diff --git a/en/java/resources/beta/index.md b/en/java/resources/beta/index.md index 16e4d5f9..f9f1def1 100644 --- a/en/java/resources/beta/index.md +++ b/en/java/resources/beta/index.md @@ -1,12041 +1,10787 @@ # Beta -# ChatKit +# Responses -## Domain Types +## Create a model response -### ChatKit Workflow +`BetaResponse beta().responses().create(ResponseCreateParamsparams = ResponseCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` -- `class ChatKitWorkflow:` +**post** `/responses?beta=true` - Workflow metadata and state returned for the session. +Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or +[image](https://platform.openai.com/docs/guides/images) inputs to generate [text](https://platform.openai.com/docs/guides/text) +or [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have the model call +your own [custom code](https://platform.openai.com/docs/guides/function-calling) or use built-in +[tools](https://platform.openai.com/docs/guides/tools) like [web search](https://platform.openai.com/docs/guides/tools-web-search) +or [file search](https://platform.openai.com/docs/guides/tools-file-search) to use your own data +as input for the model's response. - - `String id` +### Parameters - Identifier of the workflow backing the session. +- `ResponseCreateParams params` - - `Optional stateVariables` + - `Optional> betas` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` - - `String` + - `Optional background` - - `boolean` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `double` + - `Optional> contextManagement` - - `Tracing tracing` + Context management configuration for this request. - Tracing settings applied to the workflow. + - `String type` - - `boolean enabled` + The context management entry type. Currently only 'compaction' is supported. - Indicates whether tracing is enabled. + - `Optional compactThreshold` - - `Optional version` + Token threshold at which compaction should be triggered for this entry. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `Optional conversation` -# Sessions + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. -## Cancel chat session + - `String` -`ChatSession beta().chatkit().sessions().cancel(SessionCancelParamsparams = SessionCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `class BetaResponseConversationParam:` -**post** `/chatkit/sessions/{session_id}/cancel` + The conversation that this response belongs to. -Cancel chat session + - `String id` -### Parameters + The unique ID of the conversation. -- `SessionCancelParams params` + - `Optional> include` - - `Optional sessionId` + Specify additional output data to include in the model response. Currently supported values are: -### Returns + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). -- `class ChatSession:` + - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` - Represents a ChatKit session and its resolved configuration. + - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` - - `String id` + - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` - Identifier for the ChatKit session. + - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` - - `ChatSessionChatKitConfiguration chatkitConfiguration` + - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` - Resolved ChatKit feature configuration for the session. + - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` - - `ChatSessionAutomaticThreadTitling automaticThreadTitling` + - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` - Automatic thread titling preferences. + - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` - - `boolean enabled` + - `Optional input` - Whether automatic thread titling is enabled. + Text, image, or file inputs to the model, used to generate a response. - - `ChatSessionFileUpload fileUpload` + Learn more: - Upload settings for the session. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) - - `boolean enabled` + - `String` - Indicates if uploads are enabled for the session. + - `List` - - `Optional maxFileSize` + - `class BetaEasyInputMessage:` - Maximum upload size in megabytes. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `Optional maxFiles` + - `Content content` - Maximum number of uploads allowed during the session. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `ChatSessionHistory history` + - `String` - History retention configuration. + - `List` - - `boolean enabled` + - `class BetaResponseInputText:` - Indicates if chat history is persisted for the session. + A text input to the model. - - `Optional recentThreads` + - `String text` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + The text input to the model. - - `String clientSecret` + - `JsonValue; type "input_text"constant` - Ephemeral client secret that authenticates session requests. + The type of the input item. Always `input_text`. - - `long expiresAt` + - `INPUT_TEXT("input_text")` - Unix timestamp (in seconds) for when the session expires. + - `Optional promptCacheBreakpoint` - - `long maxRequestsPer1Minute` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Convenience copy of the per-minute request limit. + - `JsonValue; mode "explicit"constant` - - `JsonValue; object_ "chatkit.session"constant` + The breakpoint mode. Always `explicit`. - Type discriminator that is always `chatkit.session`. + - `EXPLICIT("explicit")` - - `CHATKIT_SESSION("chatkit.session")` + - `class BetaResponseInputImage:` - - `ChatSessionRateLimits rateLimits` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Resolved rate limit values. + - `Detail detail` - - `long maxRequestsPer1Minute` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Maximum allowed requests per one-minute window. + - `LOW("low")` - - `ChatSessionStatus status` + - `HIGH("high")` - Current lifecycle state of the session. + - `AUTO("auto")` - - `ACTIVE("active")` + - `ORIGINAL("original")` - - `EXPIRED("expired")` + - `JsonValue; type "input_image"constant` - - `CANCELLED("cancelled")` + The type of the input item. Always `input_image`. - - `String user` + - `INPUT_IMAGE("input_image")` - User identifier associated with the session. + - `Optional fileId` - - `ChatKitWorkflow workflow` + The ID of the file to be sent to the model. - Workflow metadata for the session. + - `Optional imageUrl` - - `String id` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Identifier of the workflow backing the session. + - `Optional promptCacheBreakpoint` - - `Optional stateVariables` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `JsonValue; mode "explicit"constant` - - `String` + The breakpoint mode. Always `explicit`. - - `boolean` + - `EXPLICIT("explicit")` - - `double` + - `class BetaResponseInputFile:` - - `Tracing tracing` + A file input to the model. - Tracing settings applied to the workflow. + - `JsonValue; type "input_file"constant` - - `boolean enabled` + The type of the input item. Always `input_file`. - Indicates whether tracing is enabled. + - `INPUT_FILE("input_file")` - - `Optional version` + - `Optional detail` - Specific workflow version used for the session. Defaults to null when using the latest deployment. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. -### Example + - `AUTO("auto")` -```java -package com.openai.example; + - `LOW("low")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.sessions.SessionCancelParams; -import com.openai.models.beta.chatkit.threads.ChatSession; + - `HIGH("high")` -public final class Main { - private Main() {} + - `Optional fileData` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The content of the file to be sent to the model. - ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123"); - } -} -``` + - `Optional fileId` -#### Response + The ID of the file to be sent to the model. -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` + - `Optional fileUrl` -### Example + The URL of the file to be sent to the model. -```java -package com.openai.example; + - `Optional filename` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.sessions.SessionCancelParams; -import com.openai.models.beta.chatkit.threads.ChatSession; + The name of the file to be sent to the model. -public final class Main { - private Main() {} + - `Optional promptCacheBreakpoint` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123"); - } -} -``` + - `JsonValue; mode "explicit"constant` -#### Response + The breakpoint mode. Always `explicit`. -```json -{ - "id": "cksess_123", - "object": "chatkit.session", - "workflow": { - "id": "workflow_alpha", - "version": "1" - }, - "scope": { - "customer_id": "cust_456" - }, - "max_requests_per_1_minute": 30, - "ttl_seconds": 900, - "status": "cancelled", - "cancelled_at": 1712345678 -} -``` + - `EXPLICIT("explicit")` -## Create ChatKit session + - `Role role` -`ChatSession beta().chatkit().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. -**post** `/chatkit/sessions` + - `USER("user")` -Create ChatKit session + - `ASSISTANT("assistant")` -### Parameters + - `SYSTEM("system")` -- `SessionCreateParams params` + - `DEVELOPER("developer")` - - `String user` + - `Optional phase` - A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. + 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. - - `ChatSessionWorkflowParam workflow` + - `COMMENTARY("commentary")` - Workflow that powers the session. + - `FINAL_ANSWER("final_answer")` - - `Optional chatkitConfiguration` + - `Optional type` - Optional overrides for ChatKit runtime configuration features + The type of the message input. Always `message`. - - `Optional expiresAfter` + - `MESSAGE("message")` - Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. + - `Message` - - `Optional rateLimits` + - `List content` - Optional override for per-minute request limits. When omitted, defaults to 10. + A list of one or many input items to the model, containing different content + types. -### Returns + - `class BetaResponseInputText:` -- `class ChatSession:` + A text input to the model. - Represents a ChatKit session and its resolved configuration. + - `class BetaResponseInputImage:` - - `String id` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Identifier for the ChatKit session. + - `class BetaResponseInputFile:` - - `ChatSessionChatKitConfiguration chatkitConfiguration` + A file input to the model. - Resolved ChatKit feature configuration for the session. + - `Role role` - - `ChatSessionAutomaticThreadTitling automaticThreadTitling` + The role of the message input. One of `user`, `system`, or `developer`. - Automatic thread titling preferences. + - `USER("user")` - - `boolean enabled` + - `SYSTEM("system")` - Whether automatic thread titling is enabled. + - `DEVELOPER("developer")` - - `ChatSessionFileUpload fileUpload` + - `Optional agent` - Upload settings for the session. + The agent that produced this item. - - `boolean enabled` + - `String agentName` - Indicates if uploads are enabled for the session. + The canonical name of the agent that produced this item. - - `Optional maxFileSize` + - `Optional status` - Maximum upload size in megabytes. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional maxFiles` + - `IN_PROGRESS("in_progress")` - Maximum number of uploads allowed during the session. + - `COMPLETED("completed")` - - `ChatSessionHistory history` + - `INCOMPLETE("incomplete")` - History retention configuration. + - `Optional type` - - `boolean enabled` + The type of the message input. Always set to `message`. - Indicates if chat history is persisted for the session. + - `MESSAGE("message")` - - `Optional recentThreads` + - `class BetaResponseOutputMessage:` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + An output message from the model. - - `String clientSecret` + - `String id` - Ephemeral client secret that authenticates session requests. + The unique ID of the output message. - - `long expiresAt` + - `List content` - Unix timestamp (in seconds) for when the session expires. + The content of the output message. - - `long maxRequestsPer1Minute` + - `class BetaResponseOutputText:` - Convenience copy of the per-minute request limit. + A text output from the model. - - `JsonValue; object_ "chatkit.session"constant` + - `List annotations` - Type discriminator that is always `chatkit.session`. + The annotations of the text output. - - `CHATKIT_SESSION("chatkit.session")` + - `class FileCitation:` - - `ChatSessionRateLimits rateLimits` + A citation to a file. - Resolved rate limit values. + - `String fileId` - - `long maxRequestsPer1Minute` + The ID of the file. - Maximum allowed requests per one-minute window. + - `String filename` - - `ChatSessionStatus status` + The filename of the file cited. - Current lifecycle state of the session. + - `long index` - - `ACTIVE("active")` + The index of the file in the list of files. - - `EXPIRED("expired")` + - `JsonValue; type "file_citation"constant` - - `CANCELLED("cancelled")` + The type of the file citation. Always `file_citation`. - - `String user` + - `FILE_CITATION("file_citation")` - User identifier associated with the session. + - `class UrlCitation:` - - `ChatKitWorkflow workflow` + A citation for a web resource used to generate a model response. - Workflow metadata for the session. + - `long endIndex` - - `String id` + The index of the last character of the URL citation in the message. - Identifier of the workflow backing the session. + - `long startIndex` - - `Optional stateVariables` + The index of the first character of the URL citation in the message. - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `String title` - - `String` + The title of the web resource. - - `boolean` + - `JsonValue; type "url_citation"constant` - - `double` + The type of the URL citation. Always `url_citation`. - - `Tracing tracing` + - `URL_CITATION("url_citation")` - Tracing settings applied to the workflow. + - `String url` - - `boolean enabled` + The URL of the web resource. - Indicates whether tracing is enabled. + - `class ContainerFileCitation:` - - `Optional version` + A citation for a container file used to generate a model response. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `String containerId` -### Example + The ID of the container file. -```java -package com.openai.example; + - `long endIndex` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.sessions.SessionCreateParams; -import com.openai.models.beta.chatkit.threads.ChatSession; -import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam; + The index of the last character of the container file citation in the message. -public final class Main { - private Main() {} + - `String fileId` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The ID of the file. - SessionCreateParams params = SessionCreateParams.builder() - .user("x") - .workflow(ChatSessionWorkflowParam.builder() - .id("id") - .build()) - .build(); - ChatSession chatSession = client.beta().chatkit().sessions().create(params); - } -} -``` + - `String filename` -#### Response + The filename of the container file cited. -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` + - `long startIndex` -### Example + The index of the first character of the container file citation in the message. -```java -package com.openai.example; + - `JsonValue; type "container_file_citation"constant` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.sessions.SessionCreateParams; -import com.openai.models.beta.chatkit.threads.ChatSession; -import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam; + The type of the container file citation. Always `container_file_citation`. -public final class Main { - private Main() {} + - `CONTAINER_FILE_CITATION("container_file_citation")` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `class FilePath:` - SessionCreateParams params = SessionCreateParams.builder() - .user("user") - .workflow(ChatSessionWorkflowParam.builder() - .id("id") - .build()) - .build(); - ChatSession chatSession = client.beta().chatkit().sessions().create(params); - } -} -``` + A path to a file. -#### Response + - `String fileId` -```json -{ - "client_secret": "chatkit_token_123", - "expires_at": 1735689600, - "workflow": { - "id": "workflow_alpha", - "version": "2024-10-01" - }, - "scope": { - "project": "alpha", - "environment": "staging" - }, - "max_requests_per_1_minute": 60, - "max_requests_per_session": 500, - "status": "active" -} -``` + The ID of the file. -# Threads + - `long index` -## List ChatKit thread items + The index of the file in the list of files. -`ThreadListItemsPage beta().chatkit().threads().listItems(ThreadListItemsParamsparams = ThreadListItemsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `JsonValue; type "file_path"constant` -**get** `/chatkit/threads/{thread_id}/items` + The type of the file path. Always `file_path`. -List ChatKit thread items + - `FILE_PATH("file_path")` -### Parameters + - `String text` -- `ThreadListItemsParams params` + The text output from the model. - - `Optional threadId` + - `JsonValue; type "output_text"constant` - - `Optional after` + The type of the output text. Always `output_text`. - List items created after this thread item ID. Defaults to null for the first page. + - `OUTPUT_TEXT("output_text")` - - `Optional before` + - `Optional> logprobs` - List items created before this thread item ID. Defaults to null for the newest results. + - `String token` - - `Optional limit` + - `List bytes` - Maximum number of thread items to return. Defaults to 20. + - `double logprob` - - `Optional order` + - `List topLogprobs` - Sort order for results by creation time. Defaults to `desc`. + - `String token` - - `ASC("asc")` + - `List bytes` - - `DESC("desc")` + - `double logprob` -### Returns + - `class BetaResponseOutputRefusal:` -- `class Data: A class that can be one of several variants.union` + A refusal from the model. - User-authored messages within a thread. + - `String refusal` - - `class ChatKitThreadUserMessageItem:` + The refusal explanation from the model. - User-authored messages within a thread. + - `JsonValue; type "refusal"constant` - - `String id` + The type of the refusal. Always `refusal`. - Identifier of the thread item. + - `REFUSAL("refusal")` - - `List attachments` + - `JsonValue; role "assistant"constant` - Attachments associated with the user message. Defaults to an empty list. + The role of the output message. Always `assistant`. - - `String id` + - `ASSISTANT("assistant")` - Identifier for the attachment. + - `Status status` - - `String mimeType` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - MIME type of the attachment. + - `IN_PROGRESS("in_progress")` - - `String name` + - `COMPLETED("completed")` - Original display name for the attachment. + - `INCOMPLETE("incomplete")` - - `Optional previewUrl` + - `JsonValue; type "message"constant` - Preview URL for rendering the attachment inline. + The type of the output message. Always `message`. - - `Type type` + - `MESSAGE("message")` - Attachment discriminator. + - `Optional agent` - - `IMAGE("image")` + The agent that produced this item. - - `FILE("file")` + - `String agentName` - - `List content` + The canonical name of the agent that produced this item. - Ordered content elements supplied by the user. + - `Optional phase` - - `class InputText:` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Text block that a user contributed to the thread. + - `COMMENTARY("commentary")` - - `String text` + - `FINAL_ANSWER("final_answer")` - Plain-text content supplied by the user. + - `class BetaResponseFileSearchToolCall:` - - `JsonValue; type "input_text"constant` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - Type discriminator that is always `input_text`. + - `String id` - - `INPUT_TEXT("input_text")` + The unique ID of the file search tool call. - - `class QuotedText:` + - `List queries` - Quoted snippet that the user referenced in their message. + The queries used to search for files. - - `String text` + - `Status status` - Quoted text content. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `JsonValue; type "quoted_text"constant` + - `IN_PROGRESS("in_progress")` - Type discriminator that is always `quoted_text`. + - `SEARCHING("searching")` - - `QUOTED_TEXT("quoted_text")` + - `COMPLETED("completed")` - - `long createdAt` + - `INCOMPLETE("incomplete")` - Unix timestamp (in seconds) for when the item was created. + - `FAILED("failed")` - - `Optional inferenceOptions` + - `JsonValue; type "file_search_call"constant` - Inference overrides applied to the message. Defaults to null when unset. + The type of the file search tool call. Always `file_search_call`. - - `Optional model` + - `FILE_SEARCH_CALL("file_search_call")` - Model name that generated the response. Defaults to null when using the session default. + - `Optional agent` - - `Optional toolChoice` + The agent that produced this item. - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - Identifier of the requested tool. + - `Optional> results` - - `JsonValue; object_ "chatkit.thread_item"constant` + The results of the file search tool call. - Type discriminator that is always `chatkit.thread_item`. + - `Optional attributes` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `String threadId` + - `String` - Identifier of the parent thread. + - `double` - - `JsonValue; type "chatkit.user_message"constant` + - `boolean` - - `CHATKIT_USER_MESSAGE("chatkit.user_message")` + - `Optional fileId` - - `class ChatKitThreadAssistantMessageItem:` + The unique ID of the file. - Assistant-authored message within a thread. + - `Optional filename` - - `String id` + The name of the file. - Identifier of the thread item. + - `Optional score` - - `List content` + The relevance score of the file - a value between 0 and 1. - Ordered assistant response segments. + - `Optional text` - - `List annotations` + The text that was retrieved from the file. - Ordered list of annotations attached to the response text. + - `class BetaResponseComputerToolCall:` - - `class File:` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - Annotation that references an uploaded file. + - `String id` - - `Source source` + The unique ID of the computer call. - File attachment referenced by the annotation. + - `String callId` - - `String filename` + An identifier used when responding to the tool call with output. - Filename referenced by the annotation. + - `List pendingSafetyChecks` - - `JsonValue; type "file"constant` + The pending safety checks for the computer call. - Type discriminator that is always `file`. + - `String id` - - `FILE("file")` + The ID of the pending safety check. - - `JsonValue; type "file"constant` + - `Optional code` - Type discriminator that is always `file` for this annotation. + The type of the pending safety check. - - `FILE("file")` + - `Optional message` - - `class Url:` + Details about the pending safety check. - Annotation that references a URL. + - `Status status` - - `Source source` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - URL referenced by the annotation. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "url"constant` + - `COMPLETED("completed")` - Type discriminator that is always `url`. + - `INCOMPLETE("incomplete")` - - `URL("url")` + - `Type type` - - `String url` + The type of the computer call. Always `computer_call`. - URL referenced by the annotation. + - `COMPUTER_CALL("computer_call")` - - `JsonValue; type "url"constant` + - `Optional action` - Type discriminator that is always `url` for this annotation. + A click action. - - `URL("url")` + - `Click` - - `String text` + - `Button button` - Assistant generated text. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `JsonValue; type "output_text"constant` + - `LEFT("left")` - Type discriminator that is always `output_text`. + - `RIGHT("right")` - - `OUTPUT_TEXT("output_text")` + - `WHEEL("wheel")` - - `long createdAt` + - `BACK("back")` - Unix timestamp (in seconds) for when the item was created. + - `FORWARD("forward")` - - `JsonValue; object_ "chatkit.thread_item"constant` + - `JsonValue; type "click"constant` - Type discriminator that is always `chatkit.thread_item`. + Specifies the event type. For a click action, this property is always `click`. - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `CLICK("click")` - - `String threadId` + - `long x` - Identifier of the parent thread. + The x-coordinate where the click occurred. - - `JsonValue; type "chatkit.assistant_message"constant` + - `long y` - Type discriminator that is always `chatkit.assistant_message`. + The y-coordinate where the click occurred. - - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")` + - `Optional> keys` - - `class ChatKitWidgetItem:` + The keys being held while clicking. - Thread item that renders a widget payload. + - `DoubleClick` - - `String id` + - `Optional> keys` - Identifier of the thread item. + The keys being held while double-clicking. - - `long createdAt` + - `JsonValue; type "double_click"constant` - Unix timestamp (in seconds) for when the item was created. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `JsonValue; object_ "chatkit.thread_item"constant` + - `DOUBLE_CLICK("double_click")` - Type discriminator that is always `chatkit.thread_item`. + - `long x` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + The x-coordinate where the double click occurred. - - `String threadId` + - `long y` - Identifier of the parent thread. + The y-coordinate where the double click occurred. - - `JsonValue; type "chatkit.widget"constant` + - `Drag` - Type discriminator that is always `chatkit.widget`. + - `List path` - - `CHATKIT_WIDGET("chatkit.widget")` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `String widget` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Serialized widget payload rendered in the UI. + - `long x` - - `class ChatKitClientToolCall:` + The x-coordinate. - Record of a client side tool invocation initiated by the assistant. + - `long y` - - `String id` + The y-coordinate. - Identifier of the thread item. + - `JsonValue; type "drag"constant` - - `String arguments` + Specifies the event type. For a drag action, this property is always set to `drag`. - JSON-encoded arguments that were sent to the tool. + - `DRAG("drag")` - - `String callId` + - `Optional> keys` - Identifier for the client tool call. + The keys being held while dragging the mouse. - - `long createdAt` + - `Keypress` - Unix timestamp (in seconds) for when the item was created. + - `List keys` - - `String name` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Tool name that was invoked. + - `JsonValue; type "keypress"constant` - - `JsonValue; object_ "chatkit.thread_item"constant` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Type discriminator that is always `chatkit.thread_item`. + - `KEYPRESS("keypress")` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `Move` - - `Optional output` + - `JsonValue; type "move"constant` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + Specifies the event type. For a move action, this property is always set to `move`. - - `Status status` + - `MOVE("move")` - Execution status for the tool call. + - `long x` - - `IN_PROGRESS("in_progress")` + The x-coordinate to move to. - - `COMPLETED("completed")` + - `long y` - - `String threadId` + The y-coordinate to move to. - Identifier of the parent thread. + - `Optional> keys` - - `JsonValue; type "chatkit.client_tool_call"constant` + The keys being held while moving the mouse. - Type discriminator that is always `chatkit.client_tool_call`. + - `JsonValue;` - - `CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")` + - `JsonValue; type "screenshot"constant` - - `class ChatKitTask:` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Task emitted by the workflow to show progress and status updates. + - `SCREENSHOT("screenshot")` - - `String id` + - `Scroll` - Identifier of the thread item. + - `long scrollX` - - `long createdAt` + The horizontal scroll distance. - Unix timestamp (in seconds) for when the item was created. + - `long scrollY` - - `Optional heading` + The vertical scroll distance. - Optional heading for the task. Defaults to null when not provided. + - `JsonValue; type "scroll"constant` - - `JsonValue; object_ "chatkit.thread_item"constant` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Type discriminator that is always `chatkit.thread_item`. + - `SCROLL("scroll")` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `long x` - - `Optional summary` + The x-coordinate where the scroll occurred. - Optional summary that describes the task. Defaults to null when omitted. + - `long y` - - `TaskType taskType` + The y-coordinate where the scroll occurred. - Subtype for the task. + - `Optional> keys` - - `CUSTOM("custom")` + The keys being held while scrolling. - - `THOUGHT("thought")` + - `Type` - - `String threadId` + - `String text` - Identifier of the parent thread. + The text to type. - - `JsonValue; type "chatkit.task"constant` + - `JsonValue; type "type"constant` - Type discriminator that is always `chatkit.task`. + Specifies the event type. For a type action, this property is always set to `type`. - - `CHATKIT_TASK("chatkit.task")` + - `TYPE("type")` - - `class ChatKitTaskGroup:` + - `JsonValue;` - Collection of workflow tasks grouped together in the thread. + - `JsonValue; type "wait"constant` - - `String id` + Specifies the event type. For a wait action, this property is always set to `wait`. - Identifier of the thread item. + - `WAIT("wait")` - - `long createdAt` + - `Optional> actions` - Unix timestamp (in seconds) for when the item was created. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `JsonValue; object_ "chatkit.thread_item"constant` + - `Click` - Type discriminator that is always `chatkit.thread_item`. + - `DoubleClick` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `Drag` - - `List tasks` + - `Keypress` - Tasks included in the group. + - `Move` - - `Optional heading` + - `JsonValue;` - Optional heading for the grouped task. Defaults to null when not provided. + - `Scroll` - - `Optional summary` + - `Type` - Optional summary that describes the grouped task. Defaults to null when omitted. + - `JsonValue;` - - `Type type` + - `Optional agent` - Subtype for the grouped task. + The agent that produced this item. - - `CUSTOM("custom")` + - `String agentName` - - `THOUGHT("thought")` + The canonical name of the agent that produced this item. - - `String threadId` + - `ComputerCallOutput` - Identifier of the parent thread. + - `String callId` - - `JsonValue; type "chatkit.task_group"constant` + The ID of the computer tool call that produced the output. - Type discriminator that is always `chatkit.task_group`. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `CHATKIT_TASK_GROUP("chatkit.task_group")` + A computer screenshot image used with the computer use tool. -### Example + - `JsonValue; type "computer_screenshot"constant` -```java -package com.openai.example; + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.threads.ThreadListItemsPage; -import com.openai.models.beta.chatkit.threads.ThreadListItemsParams; + - `COMPUTER_SCREENSHOT("computer_screenshot")` -public final class Main { - private Main() {} + - `Optional fileId` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The identifier of an uploaded file that contains the screenshot. - ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123"); - } -} -``` + - `Optional imageUrl` -#### Response + The URL of the screenshot image. -```json -{ - "data": [ - { - "id": "id", - "attachments": [ - { - "id": "id", - "mime_type": "mime_type", - "name": "name", - "preview_url": "https://example.com", - "type": "image" - } - ], - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "created_at": 0, - "inference_options": { - "model": "model", - "tool_choice": { - "id": "id" - } - }, - "object": "chatkit.thread_item", - "thread_id": "thread_id", - "type": "chatkit.user_message" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `JsonValue; type "computer_call_output"constant` -### Example + The type of the computer tool call output. Always `computer_call_output`. -```java -package com.openai.example; + - `COMPUTER_CALL_OUTPUT("computer_call_output")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.threads.ThreadListItemsPage; -import com.openai.models.beta.chatkit.threads.ThreadListItemsParams; + - `Optional id` -public final class Main { - private Main() {} + The ID of the computer tool call output. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Optional> acknowledgedSafetyChecks` - ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123"); - } -} -``` + The safety checks reported by the API that have been acknowledged by the developer. -#### Response + - `String id` -```json -{ - "data": [ - { - "id": "cthi_user_001", - "object": "chatkit.thread_item", - "type": "user_message", - "content": [ - { - "type": "input_text", - "text": "I need help debugging an onboarding issue." - } - ], - "attachments": [] - }, - { - "id": "cthi_assistant_002", - "object": "chatkit.thread_item", - "type": "assistant_message", - "content": [ - { - "type": "output_text", - "text": "Let's start by confirming the workflow version you deployed." - } - ] - } - ], - "has_more": false, - "object": "list" -} -``` + The ID of the pending safety check. -## Retrieve ChatKit thread + - `Optional code` -`ChatKitThread beta().chatkit().threads().retrieve(ThreadRetrieveParamsparams = ThreadRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The type of the pending safety check. -**get** `/chatkit/threads/{thread_id}` + - `Optional message` -Retrieve ChatKit thread + Details about the pending safety check. -### Parameters + - `Optional agent` -- `ThreadRetrieveParams params` + The agent that produced this item. - - `Optional threadId` + - `String agentName` -### Returns + The canonical name of the agent that produced this item. -- `class ChatKitThread:` + - `Optional status` - Represents a ChatKit thread and its current status. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `String id` + - `IN_PROGRESS("in_progress")` - Identifier of the thread. + - `COMPLETED("completed")` - - `long createdAt` + - `INCOMPLETE("incomplete")` - Unix timestamp (in seconds) for when the thread was created. + - `class BetaResponseFunctionWebSearch:` - - `JsonValue; object_ "chatkit.thread"constant` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - Type discriminator that is always `chatkit.thread`. + - `String id` - - `CHATKIT_THREAD("chatkit.thread")` + The unique ID of the web search tool call. - - `Status status` + - `Action action` - Current status for the thread. Defaults to `active` for newly created threads. + 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). - - `JsonValue;` + - `class Search:` - - `JsonValue; type "active"constant` + Action type "search" - Performs a web search query. - Status discriminator that is always `active`. + - `JsonValue; type "search"constant` - - `ACTIVE("active")` + The action type. - - `class Locked:` + - `SEARCH("search")` - Indicates that a thread is locked and cannot accept new input. + - `Optional> queries` - - `Optional reason` + The search queries. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `Optional query` - - `JsonValue; type "locked"constant` + The search query. - Status discriminator that is always `locked`. + - `Optional> sources` - - `LOCKED("locked")` + The sources used in the search. - - `class Closed:` + - `JsonValue; type "url"constant` - Indicates that a thread has been closed. + The type of source. Always `url`. - - `Optional reason` + - `URL("url")` - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `String url` - - `JsonValue; type "closed"constant` + The URL of the source. - Status discriminator that is always `closed`. + - `class OpenPage:` - - `CLOSED("closed")` + Action type "open_page" - Opens a specific URL from search results. - - `Optional title` + - `JsonValue; type "open_page"constant` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + The action type. - - `String user` + - `OPEN_PAGE("open_page")` - Free-form string that identifies your end user who owns the thread. + - `Optional url` -### Example + The URL opened by the model. -```java -package com.openai.example; + - `class FindInPage:` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.threads.ChatKitThread; -import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams; + Action type "find_in_page": Searches for a pattern within a loaded page. -public final class Main { - private Main() {} + - `String pattern` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The pattern or text to search for within the page. - ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123"); - } -} -``` + - `JsonValue; type "find_in_page"constant` -#### Response + The action type. -```json -{ - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" -} -``` + - `FIND_IN_PAGE("find_in_page")` -### Example + - `String url` -```java -package com.openai.example; + The URL of the page searched for the pattern. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.threads.ChatKitThread; -import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams; + - `Status status` -public final class Main { - private Main() {} + The status of the web search tool call. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `IN_PROGRESS("in_progress")` - ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123"); - } -} -``` + - `SEARCHING("searching")` -#### Response + - `COMPLETED("completed")` -```json -{ - "id": "cthr_abc123", - "object": "chatkit.thread", - "title": "Customer escalation", - "items": { - "data": [ - { - "id": "cthi_user_001", - "object": "chatkit.thread_item", - "type": "user_message", - "content": [ - { - "type": "input_text", - "text": "I need help debugging an onboarding issue." - } - ], - "attachments": [] - }, - { - "id": "cthi_assistant_002", - "object": "chatkit.thread_item", - "type": "assistant_message", - "content": [ - { - "type": "output_text", - "text": "Let's start by confirming the workflow version you deployed." - } - ] - } - ], - "has_more": false - } -} -``` + - `FAILED("failed")` -## Delete ChatKit thread + - `JsonValue; type "web_search_call"constant` -`ThreadDeleteResponse beta().chatkit().threads().delete(ThreadDeleteParamsparams = ThreadDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The type of the web search tool call. Always `web_search_call`. -**delete** `/chatkit/threads/{thread_id}` + - `WEB_SEARCH_CALL("web_search_call")` -Delete ChatKit thread + - `Optional agent` -### Parameters + The agent that produced this item. -- `ThreadDeleteParams params` + - `String agentName` - - `Optional threadId` + The canonical name of the agent that produced this item. -### Returns + - `class BetaResponseFunctionToolCall:` -- `class ThreadDeleteResponse:` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Confirmation payload returned after deleting a thread. + - `String arguments` - - `String id` + A JSON string of the arguments to pass to the function. - Identifier of the deleted thread. + - `String callId` - - `boolean deleted` + The unique ID of the function tool call generated by the model. - Indicates that the thread has been deleted. + - `String name` - - `JsonValue; object_ "chatkit.thread.deleted"constant` + The name of the function to run. - Type discriminator that is always `chatkit.thread.deleted`. + - `JsonValue; type "function_call"constant` - - `CHATKIT_THREAD_DELETED("chatkit.thread.deleted")` + The type of the function tool call. Always `function_call`. -### Example + - `FUNCTION_CALL("function_call")` -```java -package com.openai.example; + - `Optional id` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.threads.ThreadDeleteParams; -import com.openai.models.beta.chatkit.threads.ThreadDeleteResponse; + The unique ID of the function tool call. -public final class Main { - private Main() {} + - `Optional agent` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The agent that produced this item. - ThreadDeleteResponse thread = client.beta().chatkit().threads().delete("cthr_123"); - } -} -``` + - `String agentName` -#### Response + The canonical name of the agent that produced this item. -```json -{ - "id": "id", - "deleted": true, - "object": "chatkit.thread.deleted" -} -``` + - `Optional caller` -### Example + The execution context that produced this tool call. -```java -package com.openai.example; + - `JsonValue;` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chat_kit.threads.ThreadDeleteParams; -import com.openai.models.beta.chat_kit.threads.ThreadDeleteResponse; + - `JsonValue; type "direct"constant` -public final class Main { - private Main() {} + - `DIRECT("direct")` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `class Program:` - ThreadDeleteResponse thread = client.beta().chat_kit().threads().delete("cthr_123"); - } -} -``` + - `String callerId` -## List ChatKit threads + The call ID of the program item that produced this tool call. -`ThreadListPage beta().chatkit().threads().list(ThreadListParamsparams = ThreadListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `JsonValue; type "program"constant` -**get** `/chatkit/threads` + - `PROGRAM("program")` -List ChatKit threads + - `Optional namespace` -### Parameters + The namespace of the function to run. -- `ThreadListParams params` + - `Optional status` - - `Optional after` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - List items created after this thread item ID. Defaults to null for the first page. + - `IN_PROGRESS("in_progress")` - - `Optional before` + - `COMPLETED("completed")` - List items created before this thread item ID. Defaults to null for the newest results. + - `INCOMPLETE("incomplete")` - - `Optional limit` + - `FunctionCallOutput` - Maximum number of thread items to return. Defaults to 20. + - `String callId` - - `Optional order` + The unique ID of the function tool call generated by the model. - Sort order for results by creation time. Defaults to `desc`. + - `Output output` - - `ASC("asc")` + Text, image, or file output of the function tool call. - - `DESC("desc")` + - `String` - - `Optional user` + - `List` - Filter threads that belong to this user identifier. Defaults to null to return all users. + - `class BetaResponseInputTextContent:` -### Returns + A text input to the model. -- `class ChatKitThread:` + - `String text` - Represents a ChatKit thread and its current status. + The text input to the model. - - `String id` + - `JsonValue; type "input_text"constant` - Identifier of the thread. + The type of the input item. Always `input_text`. - - `long createdAt` + - `INPUT_TEXT("input_text")` - Unix timestamp (in seconds) for when the thread was created. + - `Optional promptCacheBreakpoint` - - `JsonValue; object_ "chatkit.thread"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Type discriminator that is always `chatkit.thread`. + - `JsonValue; mode "explicit"constant` - - `CHATKIT_THREAD("chatkit.thread")` + The breakpoint mode. Always `explicit`. - - `Status status` + - `EXPLICIT("explicit")` - Current status for the thread. Defaults to `active` for newly created threads. + - `class BetaResponseInputImageContent:` - - `JsonValue;` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `JsonValue; type "active"constant` + - `JsonValue; type "input_image"constant` - Status discriminator that is always `active`. + The type of the input item. Always `input_image`. - - `ACTIVE("active")` + - `INPUT_IMAGE("input_image")` - - `class Locked:` + - `Optional detail` - Indicates that a thread is locked and cannot accept new input. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Optional reason` + - `LOW("low")` - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `HIGH("high")` - - `JsonValue; type "locked"constant` + - `AUTO("auto")` - Status discriminator that is always `locked`. + - `ORIGINAL("original")` - - `LOCKED("locked")` + - `Optional fileId` - - `class Closed:` + The ID of the file to be sent to the model. - Indicates that a thread has been closed. + - `Optional imageUrl` - - `Optional reason` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `Optional promptCacheBreakpoint` - - `JsonValue; type "closed"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Status discriminator that is always `closed`. + - `JsonValue; mode "explicit"constant` - - `CLOSED("closed")` + The breakpoint mode. Always `explicit`. - - `Optional title` + - `EXPLICIT("explicit")` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `class BetaResponseInputFileContent:` - - `String user` + A file input to the model. - Free-form string that identifies your end user who owns the thread. + - `JsonValue; type "input_file"constant` -### Example + The type of the input item. Always `input_file`. -```java -package com.openai.example; + - `INPUT_FILE("input_file")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.threads.ThreadListPage; -import com.openai.models.beta.chatkit.threads.ThreadListParams; + - `Optional detail` -public final class Main { - private Main() {} + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `AUTO("auto")` - ThreadListPage page = client.beta().chatkit().threads().list(); - } -} -``` + - `LOW("low")` -#### Response + - `HIGH("high")` -```json -{ - "data": [ - { - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `Optional fileData` -### Example + The base64-encoded data of the file to be sent to the model. -```java -package com.openai.example; + - `Optional fileId` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.chatkit.threads.ThreadListPage; -import com.openai.models.beta.chatkit.threads.ThreadListParams; + The ID of the file to be sent to the model. -public final class Main { - private Main() {} + - `Optional fileUrl` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The URL of the file to be sent to the model. - ThreadListPage page = client.beta().chatkit().threads().list(); - } -} -``` + - `Optional filename` -#### Response + The name of the file to be sent to the model. -```json -{ - "data": [ - { - "id": "cthr_abc123", - "object": "chatkit.thread", - "title": "Customer escalation" - }, - { - "id": "cthr_def456", - "object": "chatkit.thread", - "title": "Demo feedback" - } - ], - "has_more": false, - "object": "list" -} -``` + - `Optional promptCacheBreakpoint` -## Domain Types + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. -### Chat Session + - `JsonValue; mode "explicit"constant` -- `class ChatSession:` + The breakpoint mode. Always `explicit`. - Represents a ChatKit session and its resolved configuration. + - `EXPLICIT("explicit")` - - `String id` + - `JsonValue; type "function_call_output"constant` - Identifier for the ChatKit session. + The type of the function tool call output. Always `function_call_output`. - - `ChatSessionChatKitConfiguration chatkitConfiguration` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - Resolved ChatKit feature configuration for the session. + - `Optional id` - - `ChatSessionAutomaticThreadTitling automaticThreadTitling` + The unique ID of the function tool call output. Populated when this item is returned via API. - Automatic thread titling preferences. + - `Optional agent` - - `boolean enabled` + The agent that produced this item. - Whether automatic thread titling is enabled. + - `String agentName` - - `ChatSessionFileUpload fileUpload` + The canonical name of the agent that produced this item. - Upload settings for the session. + - `Optional caller` - - `boolean enabled` + The execution context that produced this tool call. - Indicates if uploads are enabled for the session. + - `JsonValue;` - - `Optional maxFileSize` + - `JsonValue; type "direct"constant` - Maximum upload size in megabytes. + The caller type. Always `direct`. - - `Optional maxFiles` + - `DIRECT("direct")` - Maximum number of uploads allowed during the session. + - `class Program:` - - `ChatSessionHistory history` + - `String callerId` - History retention configuration. + The call ID of the program item that produced this tool call. - - `boolean enabled` + - `JsonValue; type "program"constant` - Indicates if chat history is persisted for the session. + The caller type. Always `program`. - - `Optional recentThreads` + - `PROGRAM("program")` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `Optional status` - - `String clientSecret` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - Ephemeral client secret that authenticates session requests. + - `IN_PROGRESS("in_progress")` - - `long expiresAt` + - `COMPLETED("completed")` - Unix timestamp (in seconds) for when the session expires. + - `INCOMPLETE("incomplete")` - - `long maxRequestsPer1Minute` + - `AgentMessage` - Convenience copy of the per-minute request limit. + - `String author` - - `JsonValue; object_ "chatkit.session"constant` + The sending agent identity. - Type discriminator that is always `chatkit.session`. + - `List content` - - `CHATKIT_SESSION("chatkit.session")` + Plaintext, image, or encrypted content sent between agents. - - `ChatSessionRateLimits rateLimits` + - `class BetaResponseInputTextContent:` - Resolved rate limit values. + A text input to the model. - - `long maxRequestsPer1Minute` + - `class BetaResponseInputImageContent:` - Maximum allowed requests per one-minute window. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `ChatSessionStatus status` + - `class EncryptedContent:` - Current lifecycle state of the session. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `ACTIVE("active")` + - `String encryptedContent` - - `EXPIRED("expired")` + Opaque encrypted content. - - `CANCELLED("cancelled")` + - `JsonValue; type "encrypted_content"constant` - - `String user` + The type of the input item. Always `encrypted_content`. - User identifier associated with the session. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `ChatKitWorkflow workflow` + - `String recipient` - Workflow metadata for the session. + The destination agent identity. - - `String id` + - `JsonValue; type "agent_message"constant` - Identifier of the workflow backing the session. + The item type. Always `agent_message`. - - `Optional stateVariables` + - `AGENT_MESSAGE("agent_message")` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `Optional id` - - `String` + The unique ID of this agent message item. - - `boolean` + - `Optional agent` - - `double` + The agent that produced this item. - - `Tracing tracing` + - `String agentName` - Tracing settings applied to the workflow. + The canonical name of the agent that produced this item. - - `boolean enabled` + - `MultiAgentCall` - Indicates whether tracing is enabled. + - `Action action` - - `Optional version` + The multi-agent action that was executed. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `SPAWN_AGENT("spawn_agent")` -### Chat Session Automatic Thread Titling + - `INTERRUPT_AGENT("interrupt_agent")` -- `class ChatSessionAutomaticThreadTitling:` + - `LIST_AGENTS("list_agents")` - Automatic thread title preferences for the session. + - `SEND_MESSAGE("send_message")` - - `boolean enabled` + - `FOLLOWUP_TASK("followup_task")` - Whether automatic thread titling is enabled. + - `WAIT_AGENT("wait_agent")` -### Chat Session ChatKit Configuration + - `String arguments` -- `class ChatSessionChatKitConfiguration:` + The action arguments as a JSON string. - ChatKit configuration for the session. + - `String callId` - - `ChatSessionAutomaticThreadTitling automaticThreadTitling` + The unique ID linking this call to its output. - Automatic thread titling preferences. + - `JsonValue; type "multi_agent_call"constant` - - `boolean enabled` + The item type. Always `multi_agent_call`. - Whether automatic thread titling is enabled. + - `MULTI_AGENT_CALL("multi_agent_call")` - - `ChatSessionFileUpload fileUpload` + - `Optional id` - Upload settings for the session. + The unique ID of this multi-agent call. - - `boolean enabled` + - `Optional agent` - Indicates if uploads are enabled for the session. + The agent that produced this item. - - `Optional maxFileSize` + - `String agentName` - Maximum upload size in megabytes. + The canonical name of the agent that produced this item. - - `Optional maxFiles` + - `MultiAgentCallOutput` - Maximum number of uploads allowed during the session. + - `Action action` - - `ChatSessionHistory history` + The multi-agent action that produced this result. - History retention configuration. + - `SPAWN_AGENT("spawn_agent")` - - `boolean enabled` + - `INTERRUPT_AGENT("interrupt_agent")` - Indicates if chat history is persisted for the session. + - `LIST_AGENTS("list_agents")` - - `Optional recentThreads` + - `SEND_MESSAGE("send_message")` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `FOLLOWUP_TASK("followup_task")` -### Chat Session ChatKit Configuration Param + - `WAIT_AGENT("wait_agent")` -- `class ChatSessionChatKitConfigurationParam:` + - `String callId` - Optional per-session configuration settings for ChatKit behavior. + The unique ID of the multi-agent call. - - `Optional automaticThreadTitling` + - `List output` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + Text output returned by the multi-agent action. - - `Optional enabled` + - `String text` - Enable automatic thread title generation. Defaults to true. + The text content. - - `Optional fileUpload` + - `JsonValue; type "output_text"constant` - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + The content type. Always `output_text`. - - `Optional enabled` + - `OUTPUT_TEXT("output_text")` - Enable uploads for this session. Defaults to false. + - `Optional annotations` - - `Optional maxFileSize` + Citations associated with the text content. - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + - `List` - - `Optional maxFiles` + - `String fileId` - Maximum number of files that can be uploaded to the session. Defaults to 10. + The ID of the file. - - `Optional history` + - `String filename` - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + The filename of the file cited. - - `Optional enabled` + - `long index` - Enables chat users to access previous ChatKit threads. Defaults to true. + The index of the file in the list of files. - - `Optional recentThreads` + - `JsonValue; type "file_citation"constant` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + The citation type. Always `file_citation`. -### Chat Session Expires After Param + - `FILE_CITATION("file_citation")` -- `class ChatSessionExpiresAfterParam:` + - `List` - Controls when the session expires relative to an anchor timestamp. + - `long endIndex` - - `JsonValue; anchor "created_at"constant` + The index of the last character of the citation in the message. - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `long startIndex` - - `CREATED_AT("created_at")` + The index of the first character of the citation in the message. - - `long seconds` + - `String title` - Number of seconds after the anchor when the session expires. + The title of the cited resource. -### Chat Session File Upload + - `JsonValue; type "url_citation"constant` -- `class ChatSessionFileUpload:` + The citation type. Always `url_citation`. - Upload permissions and limits applied to the session. + - `URL_CITATION("url_citation")` - - `boolean enabled` + - `String url` - Indicates if uploads are enabled for the session. + The URL of the cited resource. - - `Optional maxFileSize` + - `List` - Maximum upload size in megabytes. + - `String containerId` - - `Optional maxFiles` + The ID of the container. - Maximum number of uploads allowed during the session. + - `long endIndex` -### Chat Session History + The index of the last character of the citation in the message. -- `class ChatSessionHistory:` + - `String fileId` - History retention preferences returned for the session. + The ID of the container file. - - `boolean enabled` + - `String filename` - Indicates if chat history is persisted for the session. + The filename of the container file cited. - - `Optional recentThreads` + - `long startIndex` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + The index of the first character of the citation in the message. -### Chat Session Rate Limits + - `JsonValue; type "container_file_citation"constant` -- `class ChatSessionRateLimits:` + The citation type. Always `container_file_citation`. - Active per-minute request limit for the session. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `long maxRequestsPer1Minute` + - `JsonValue; type "multi_agent_call_output"constant` - Maximum allowed requests per one-minute window. + The item type. Always `multi_agent_call_output`. -### Chat Session Rate Limits Param + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` -- `class ChatSessionRateLimitsParam:` + - `Optional id` - Controls request rate limits for the session. + The unique ID of this multi-agent call output. - - `Optional maxRequestsPer1Minute` + - `Optional agent` - Maximum number of requests allowed per minute for the session. Defaults to 10. + The agent that produced this item. -### Chat Session Status + - `String agentName` -- `enum ChatSessionStatus:` + The canonical name of the agent that produced this item. - - `ACTIVE("active")` + - `ToolSearchCall` - - `EXPIRED("expired")` + - `JsonValue arguments` - - `CANCELLED("cancelled")` + The arguments supplied to the tool search call. -### Chat Session Workflow Param + - `JsonValue; type "tool_search_call"constant` -- `class ChatSessionWorkflowParam:` + The item type. Always `tool_search_call`. - Workflow reference and overrides applied to the chat session. + - `TOOL_SEARCH_CALL("tool_search_call")` - - `String id` + - `Optional id` - Identifier for the workflow invoked by the session. + The unique ID of this tool search call. - - `Optional stateVariables` + - `Optional agent` - State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. + The agent that produced this item. - - `String` + - `String agentName` - - `boolean` + The canonical name of the agent that produced this item. - - `double` + - `Optional callId` - - `Optional tracing` + The unique ID of the tool search call generated by the model. - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + - `Optional execution` - - `Optional enabled` + Whether tool search was executed by the server or by the client. - Whether tracing is enabled during the session. Defaults to true. + - `SERVER("server")` - - `Optional version` + - `CLIENT("client")` - Specific workflow version to run. Defaults to the latest deployed version. + - `Optional status` -### ChatKit Attachment + The status of the tool search call. -- `class ChatKitAttachment:` + - `IN_PROGRESS("in_progress")` - Attachment metadata included on thread items. + - `COMPLETED("completed")` - - `String id` + - `INCOMPLETE("incomplete")` - Identifier for the attachment. + - `class BetaResponseToolSearchOutputItemParam:` - - `String mimeType` + - `List tools` - MIME type of the attachment. + The loaded tool definitions returned by the tool search output. - - `String name` + - `class BetaFunctionTool:` - Original display name for the attachment. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `Optional previewUrl` + - `String name` - Preview URL for rendering the attachment inline. + The name of the function to call. - - `Type type` + - `Optional parameters` - Attachment discriminator. + A JSON schema object describing the parameters of the function. - - `IMAGE("image")` + - `Optional strict` - - `FILE("file")` + Whether strict parameter validation is enforced for this function tool. -### ChatKit Response Output Text + - `JsonValue; type "function"constant` -- `class ChatKitResponseOutputText:` + The type of the function tool. Always `function`. - Assistant response text accompanied by optional annotations. + - `FUNCTION("function")` - - `List annotations` + - `Optional> allowedCallers` - Ordered list of annotations attached to the response text. + The tool invocation context(s). - - `class File:` + - `DIRECT("direct")` - Annotation that references an uploaded file. + - `PROGRAMMATIC("programmatic")` - - `Source source` + - `Optional deferLoading` - File attachment referenced by the annotation. + Whether this function is deferred and loaded via tool search. - - `String filename` + - `Optional description` - Filename referenced by the annotation. + A description of the function. Used by the model to determine whether or not to call the function. - - `JsonValue; type "file"constant` + - `Optional outputSchema` - Type discriminator that is always `file`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `FILE("file")` + - `class BetaFileSearchTool:` - - `JsonValue; type "file"constant` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Type discriminator that is always `file` for this annotation. + - `JsonValue; type "file_search"constant` - - `FILE("file")` + The type of the file search tool. Always `file_search`. - - `class Url:` + - `FILE_SEARCH("file_search")` - Annotation that references a URL. + - `List vectorStoreIds` - - `Source source` + The IDs of the vector stores to search. - URL referenced by the annotation. + - `Optional filters` - - `JsonValue; type "url"constant` + A filter to apply. - Type discriminator that is always `url`. + - `class ComparisonFilter:` - - `URL("url")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `String url` + - `String key` - URL referenced by the annotation. + The key to compare against the value. - - `JsonValue; type "url"constant` + - `Type type` - Type discriminator that is always `url` for this annotation. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `URL("url")` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `String text` + - `EQ("eq")` - Assistant generated text. + - `NE("ne")` - - `JsonValue; type "output_text"constant` + - `GT("gt")` - Type discriminator that is always `output_text`. + - `GTE("gte")` - - `OUTPUT_TEXT("output_text")` + - `LT("lt")` -### ChatKit Thread + - `LTE("lte")` -- `class ChatKitThread:` + - `IN("in")` - Represents a ChatKit thread and its current status. + - `NIN("nin")` - - `String id` + - `Value value` - Identifier of the thread. + The value to compare against the attribute key; supports string, number, or boolean types. - - `long createdAt` + - `String` - Unix timestamp (in seconds) for when the thread was created. + - `double` - - `JsonValue; object_ "chatkit.thread"constant` + - `boolean` - Type discriminator that is always `chatkit.thread`. + - `List` - - `CHATKIT_THREAD("chatkit.thread")` + - `String` - - `Status status` + - `double` - Current status for the thread. Defaults to `active` for newly created threads. + - `class CompoundFilter:` - - `JsonValue;` + Combine multiple filters using `and` or `or`. - - `JsonValue; type "active"constant` + - `List filters` - Status discriminator that is always `active`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `ACTIVE("active")` + - `class ComparisonFilter:` - - `class Locked:` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Indicates that a thread is locked and cannot accept new input. + - `String key` - - `Optional reason` + The key to compare against the value. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `Type type` - - `JsonValue; type "locked"constant` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Status discriminator that is always `locked`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `LOCKED("locked")` + - `EQ("eq")` - - `class Closed:` + - `NE("ne")` - Indicates that a thread has been closed. + - `GT("gt")` - - `Optional reason` + - `GTE("gte")` - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `LT("lt")` - - `JsonValue; type "closed"constant` + - `LTE("lte")` - Status discriminator that is always `closed`. + - `IN("in")` - - `CLOSED("closed")` + - `NIN("nin")` - - `Optional title` + - `Value value` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + The value to compare against the attribute key; supports string, number, or boolean types. - - `String user` + - `String` - Free-form string that identifies your end user who owns the thread. + - `double` -### ChatKit Thread Assistant Message Item + - `boolean` -- `class ChatKitThreadAssistantMessageItem:` + - `List` - Assistant-authored message within a thread. + - `String` - - `String id` + - `double` - Identifier of the thread item. + - `JsonValue` - - `List content` + - `Type type` - Ordered assistant response segments. + Type of operation: `and` or `or`. - - `List annotations` + - `AND("and")` - Ordered list of annotations attached to the response text. + - `OR("or")` - - `class File:` + - `Optional maxNumResults` - Annotation that references an uploaded file. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `Source source` + - `Optional rankingOptions` - File attachment referenced by the annotation. + Ranking options for search. - - `String filename` + - `Optional hybridSearch` - Filename referenced by the annotation. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `JsonValue; type "file"constant` + - `double embeddingWeight` - Type discriminator that is always `file`. + The weight of the embedding in the reciprocal ranking fusion. - - `FILE("file")` + - `double textWeight` - - `JsonValue; type "file"constant` + The weight of the text in the reciprocal ranking fusion. - Type discriminator that is always `file` for this annotation. + - `Optional ranker` - - `FILE("file")` + The ranker to use for the file search. - - `class Url:` + - `AUTO("auto")` - Annotation that references a URL. + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `Source source` + - `Optional scoreThreshold` - URL referenced by the annotation. + 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. - - `JsonValue; type "url"constant` + - `class BetaComputerTool:` - Type discriminator that is always `url`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `URL("url")` + - `JsonValue; type "computer"constant` - - `String url` + The type of the computer tool. Always `computer`. - URL referenced by the annotation. + - `COMPUTER("computer")` - - `JsonValue; type "url"constant` + - `class BetaComputerUsePreviewTool:` - Type discriminator that is always `url` for this annotation. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `URL("url")` + - `long displayHeight` - - `String text` + The height of the computer display. - Assistant generated text. + - `long displayWidth` - - `JsonValue; type "output_text"constant` + The width of the computer display. - Type discriminator that is always `output_text`. + - `Environment environment` - - `OUTPUT_TEXT("output_text")` + The type of computer environment to control. - - `long createdAt` + - `WINDOWS("windows")` - Unix timestamp (in seconds) for when the item was created. + - `MAC("mac")` - - `JsonValue; object_ "chatkit.thread_item"constant` + - `LINUX("linux")` - Type discriminator that is always `chatkit.thread_item`. + - `UBUNTU("ubuntu")` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `BROWSER("browser")` - - `String threadId` + - `JsonValue; type "computer_use_preview"constant` - Identifier of the parent thread. + The type of the computer use tool. Always `computer_use_preview`. - - `JsonValue; type "chatkit.assistant_message"constant` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - Type discriminator that is always `chatkit.assistant_message`. + - `class BetaWebSearchTool:` - - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -### ChatKit Thread Item List + - `Type type` -- `class ChatKitThreadItemList:` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - A paginated list of thread items rendered for the ChatKit API. + - `WEB_SEARCH("web_search")` - - `List data` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - A list of items + - `Optional filters` - - `class ChatKitThreadUserMessageItem:` + Filters for the search. - User-authored messages within a thread. + - `Optional> allowedDomains` - - `String id` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Identifier of the thread item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `List attachments` + - `Optional searchContextSize` - Attachments associated with the user message. Defaults to an empty list. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `String id` + - `LOW("low")` - Identifier for the attachment. + - `MEDIUM("medium")` - - `String mimeType` + - `HIGH("high")` - MIME type of the attachment. + - `Optional userLocation` - - `String name` + The approximate location of the user. - Original display name for the attachment. + - `Optional city` - - `Optional previewUrl` + Free text input for the city of the user, e.g. `San Francisco`. - Preview URL for rendering the attachment inline. + - `Optional country` - - `Type type` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Attachment discriminator. + - `Optional region` - - `IMAGE("image")` + Free text input for the region of the user, e.g. `California`. - - `FILE("file")` + - `Optional timezone` - - `List content` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Ordered content elements supplied by the user. + - `Optional type` - - `class InputText:` + The type of location approximation. Always `approximate`. - Text block that a user contributed to the thread. + - `APPROXIMATE("approximate")` - - `String text` + - `Mcp` - Plain-text content supplied by the user. + - `String serverLabel` - - `JsonValue; type "input_text"constant` + A label for this MCP server, used to identify it in tool calls. - Type discriminator that is always `input_text`. + - `JsonValue; type "mcp"constant` - - `INPUT_TEXT("input_text")` + The type of the MCP tool. Always `mcp`. - - `class QuotedText:` + - `MCP("mcp")` - Quoted snippet that the user referenced in their message. + - `Optional> allowedCallers` - - `String text` + The tool invocation context(s). - Quoted text content. + - `DIRECT("direct")` - - `JsonValue; type "quoted_text"constant` + - `PROGRAMMATIC("programmatic")` - Type discriminator that is always `quoted_text`. + - `Optional allowedTools` - - `QUOTED_TEXT("quoted_text")` + List of allowed tool names or a filter object. - - `long createdAt` + - `List` - Unix timestamp (in seconds) for when the item was created. + - `class McpToolFilter:` - - `Optional inferenceOptions` + A filter object to specify which tools are allowed. - Inference overrides applied to the message. Defaults to null when unset. + - `Optional readOnly` - - `Optional model` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Model name that generated the response. Defaults to null when using the session default. + - `Optional> toolNames` - - `Optional toolChoice` + List of allowed tool names. - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `Optional authorization` - - `String id` + 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. - Identifier of the requested tool. + - `Optional connectorId` - - `JsonValue; object_ "chatkit.thread_item"constant` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - Type discriminator that is always `chatkit.thread_item`. + Currently supported `connector_id` values are: - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `String threadId` + - `CONNECTOR_DROPBOX("connector_dropbox")` - Identifier of the parent thread. + - `CONNECTOR_GMAIL("connector_gmail")` - - `JsonValue; type "chatkit.user_message"constant` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `CHATKIT_USER_MESSAGE("chatkit.user_message")` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `class ChatKitThreadAssistantMessageItem:` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - Assistant-authored message within a thread. + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `String id` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - Identifier of the thread item. + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `List content` + - `Optional deferLoading` - Ordered assistant response segments. + Whether this MCP tool is deferred and discovered via tool search. - - `List annotations` + - `Optional headers` - Ordered list of annotations attached to the response text. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `class File:` + - `Optional requireApproval` - Annotation that references an uploaded file. + Specify which of the MCP server's tools require approval. - - `Source source` + - `class McpToolApprovalFilter:` - File attachment referenced by the annotation. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `String filename` + - `Optional always` - Filename referenced by the annotation. + A filter object to specify which tools are allowed. - - `JsonValue; type "file"constant` + - `Optional readOnly` - Type discriminator that is always `file`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `FILE("file")` + - `Optional> toolNames` - - `JsonValue; type "file"constant` + List of allowed tool names. - Type discriminator that is always `file` for this annotation. + - `Optional never` - - `FILE("file")` + A filter object to specify which tools are allowed. - - `class Url:` + - `Optional readOnly` - Annotation that references a URL. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `Source source` + - `Optional> toolNames` - URL referenced by the annotation. + List of allowed tool names. - - `JsonValue; type "url"constant` + - `enum McpToolApprovalSetting:` - Type discriminator that is always `url`. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `URL("url")` + - `ALWAYS("always")` - - `String url` + - `NEVER("never")` - URL referenced by the annotation. + - `Optional serverDescription` - - `JsonValue; type "url"constant` + Optional description of the MCP server, used to provide more context. - Type discriminator that is always `url` for this annotation. + - `Optional serverUrl` - - `URL("url")` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `String text` + - `Optional tunnelId` - Assistant generated text. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `JsonValue; type "output_text"constant` + - `CodeInterpreter` - Type discriminator that is always `output_text`. + - `Container container` - - `OUTPUT_TEXT("output_text")` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `long createdAt` + - `String` - Unix timestamp (in seconds) for when the item was created. + - `class CodeInterpreterToolAuto:` - - `JsonValue; object_ "chatkit.thread_item"constant` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Type discriminator that is always `chatkit.thread_item`. + - `JsonValue; type "auto"constant` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + Always `auto`. - - `String threadId` + - `AUTO("auto")` - Identifier of the parent thread. + - `Optional> fileIds` - - `JsonValue; type "chatkit.assistant_message"constant` + An optional list of uploaded files to make available to your code. - Type discriminator that is always `chatkit.assistant_message`. + - `Optional memoryLimit` - - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")` + The memory limit for the code interpreter container. - - `class ChatKitWidgetItem:` + - `_1G("1g")` - Thread item that renders a widget payload. + - `_4G("4g")` - - `String id` + - `_16G("16g")` - Identifier of the thread item. + - `_64G("64g")` - - `long createdAt` + - `Optional networkPolicy` - Unix timestamp (in seconds) for when the item was created. + Network access policy for the container. - - `JsonValue; object_ "chatkit.thread_item"constant` + - `class BetaContainerNetworkPolicyDisabled:` - Type discriminator that is always `chatkit.thread_item`. + - `JsonValue; type "disabled"constant` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + Disable outbound network access. Always `disabled`. - - `String threadId` + - `DISABLED("disabled")` - Identifier of the parent thread. + - `class BetaContainerNetworkPolicyAllowlist:` - - `JsonValue; type "chatkit.widget"constant` + - `List allowedDomains` - Type discriminator that is always `chatkit.widget`. + A list of allowed domains when type is `allowlist`. - - `CHATKIT_WIDGET("chatkit.widget")` + - `JsonValue; type "allowlist"constant` - - `String widget` + Allow outbound network access only to specified domains. Always `allowlist`. - Serialized widget payload rendered in the UI. + - `ALLOWLIST("allowlist")` - - `class ChatKitClientToolCall:` + - `Optional> domainSecrets` - Record of a client side tool invocation initiated by the assistant. + Optional domain-scoped secrets for allowlisted domains. - - `String id` + - `String domain` - Identifier of the thread item. + The domain associated with the secret. - - `String arguments` + - `String name` - JSON-encoded arguments that were sent to the tool. + The name of the secret to inject for the domain. - - `String callId` + - `String value` - Identifier for the client tool call. + The secret value to inject for the domain. - - `long createdAt` + - `JsonValue; type "code_interpreter"constant` - Unix timestamp (in seconds) for when the item was created. + The type of the code interpreter tool. Always `code_interpreter`. - - `String name` + - `CODE_INTERPRETER("code_interpreter")` - Tool name that was invoked. + - `Optional> allowedCallers` - - `JsonValue; object_ "chatkit.thread_item"constant` + The tool invocation context(s). - Type discriminator that is always `chatkit.thread_item`. + - `DIRECT("direct")` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `PROGRAMMATIC("programmatic")` - - `Optional output` + - `JsonValue;` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `JsonValue; type "programmatic_tool_calling"constant` - - `Status status` + The type of the tool. Always `programmatic_tool_calling`. - Execution status for the tool call. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `IN_PROGRESS("in_progress")` + - `ImageGeneration` - - `COMPLETED("completed")` + - `JsonValue; type "image_generation"constant` - - `String threadId` + The type of the image generation tool. Always `image_generation`. - Identifier of the parent thread. + - `IMAGE_GENERATION("image_generation")` - - `JsonValue; type "chatkit.client_tool_call"constant` + - `Optional action` - Type discriminator that is always `chatkit.client_tool_call`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")` + - `GENERATE("generate")` - - `class ChatKitTask:` + - `EDIT("edit")` - Task emitted by the workflow to show progress and status updates. + - `AUTO("auto")` - - `String id` + - `Optional background` - Identifier of the thread item. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `long createdAt` + `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. - Unix timestamp (in seconds) for when the item was created. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `Optional heading` + - `TRANSPARENT("transparent")` - Optional heading for the task. Defaults to null when not provided. + - `OPAQUE("opaque")` - - `JsonValue; object_ "chatkit.thread_item"constant` + - `AUTO("auto")` - Type discriminator that is always `chatkit.thread_item`. + - `Optional inputFidelity` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `Optional summary` + - `HIGH("high")` - Optional summary that describes the task. Defaults to null when omitted. + - `LOW("low")` - - `TaskType taskType` + - `Optional inputImageMask` - Subtype for the task. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `CUSTOM("custom")` + - `Optional fileId` - - `THOUGHT("thought")` + File ID for the mask image. - - `String threadId` + - `Optional imageUrl` - Identifier of the parent thread. + Base64-encoded mask image. - - `JsonValue; type "chatkit.task"constant` + - `Optional model` - Type discriminator that is always `chatkit.task`. + The image generation model to use. Default: `gpt-image-1`. - - `CHATKIT_TASK("chatkit.task")` + - `GPT_IMAGE_1("gpt-image-1")` - - `class ChatKitTaskGroup:` + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - Collection of workflow tasks grouped together in the thread. + - `GPT_IMAGE_2("gpt-image-2")` - - `String id` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - Identifier of the thread item. + - `GPT_IMAGE_1_5("gpt-image-1.5")` - - `long createdAt` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - Unix timestamp (in seconds) for when the item was created. + - `Optional moderation` - - `JsonValue; object_ "chatkit.thread_item"constant` + Moderation level for the generated image. Default: `auto`. - Type discriminator that is always `chatkit.thread_item`. + - `AUTO("auto")` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `LOW("low")` - - `List tasks` + - `Optional outputCompression` - Tasks included in the group. + Compression level for the output image. Default: 100. - - `Optional heading` + - `Optional outputFormat` - Optional heading for the grouped task. Defaults to null when not provided. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `Optional summary` + - `PNG("png")` - Optional summary that describes the grouped task. Defaults to null when omitted. + - `WEBP("webp")` - - `Type type` + - `JPEG("jpeg")` - Subtype for the grouped task. + - `Optional partialImages` - - `CUSTOM("custom")` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `THOUGHT("thought")` + - `Optional quality` - - `String threadId` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Identifier of the parent thread. + - `LOW("low")` - - `JsonValue; type "chatkit.task_group"constant` + - `MEDIUM("medium")` - Type discriminator that is always `chatkit.task_group`. + - `HIGH("high")` - - `CHATKIT_TASK_GROUP("chatkit.task_group")` + - `AUTO("auto")` - - `Optional firstId` + - `Optional size` - The ID of the first item in the list. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `boolean hasMore` + - `_1024X1024("1024x1024")` - Whether there are more items available. + - `_1024X1536("1024x1536")` - - `Optional lastId` + - `_1536X1024("1536x1024")` - The ID of the last item in the list. + - `AUTO("auto")` - - `JsonValue; object_ "list"constant` + - `JsonValue;` - The type of object returned, must be `list`. + - `JsonValue; type "local_shell"constant` - - `LIST("list")` + The type of the local shell tool. Always `local_shell`. -### ChatKit Thread User Message Item + - `LOCAL_SHELL("local_shell")` -- `class ChatKitThreadUserMessageItem:` + - `class BetaFunctionShellTool:` - User-authored messages within a thread. + A tool that allows the model to execute shell commands. - - `String id` + - `JsonValue; type "shell"constant` - Identifier of the thread item. + The type of the shell tool. Always `shell`. - - `List attachments` + - `SHELL("shell")` - Attachments associated with the user message. Defaults to an empty list. + - `Optional> allowedCallers` - - `String id` + The tool invocation context(s). - Identifier for the attachment. + - `DIRECT("direct")` - - `String mimeType` + - `PROGRAMMATIC("programmatic")` - MIME type of the attachment. + - `Optional environment` - - `String name` + - `class BetaContainerAuto:` - Original display name for the attachment. + - `JsonValue; type "container_auto"constant` - - `Optional previewUrl` + Automatically creates a container for this request - Preview URL for rendering the attachment inline. + - `CONTAINER_AUTO("container_auto")` - - `Type type` + - `Optional> fileIds` - Attachment discriminator. + An optional list of uploaded files to make available to your code. - - `IMAGE("image")` + - `Optional memoryLimit` - - `FILE("file")` + The memory limit for the container. - - `List content` + - `_1G("1g")` - Ordered content elements supplied by the user. + - `_4G("4g")` - - `class InputText:` + - `_16G("16g")` - Text block that a user contributed to the thread. + - `_64G("64g")` - - `String text` + - `Optional networkPolicy` - Plain-text content supplied by the user. + Network access policy for the container. - - `JsonValue; type "input_text"constant` + - `class BetaContainerNetworkPolicyDisabled:` - Type discriminator that is always `input_text`. + - `class BetaContainerNetworkPolicyAllowlist:` - - `INPUT_TEXT("input_text")` + - `Optional> skills` - - `class QuotedText:` + An optional list of skills referenced by id or inline data. - Quoted snippet that the user referenced in their message. + - `class BetaSkillReference:` - - `String text` + - `String skillId` - Quoted text content. + The ID of the referenced skill. - - `JsonValue; type "quoted_text"constant` + - `JsonValue; type "skill_reference"constant` - Type discriminator that is always `quoted_text`. + References a skill created with the /v1/skills endpoint. - - `QUOTED_TEXT("quoted_text")` + - `SKILL_REFERENCE("skill_reference")` - - `long createdAt` + - `Optional version` - Unix timestamp (in seconds) for when the item was created. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `Optional inferenceOptions` + - `class BetaInlineSkill:` - Inference overrides applied to the message. Defaults to null when unset. + - `String description` - - `Optional model` + The description of the skill. - Model name that generated the response. Defaults to null when using the session default. + - `String name` - - `Optional toolChoice` + The name of the skill. - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `BetaInlineSkillSource source` - - `String id` + Inline skill payload - Identifier of the requested tool. + - `String data` - - `JsonValue; object_ "chatkit.thread_item"constant` + Base64-encoded skill zip bundle. - Type discriminator that is always `chatkit.thread_item`. + - `JsonValue; mediaType "application/zip"constant` - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + The media type of the inline skill payload. Must be `application/zip`. - - `String threadId` + - `APPLICATION_ZIP("application/zip")` - Identifier of the parent thread. + - `JsonValue; type "base64"constant` - - `JsonValue; type "chatkit.user_message"constant` + The type of the inline skill source. Must be `base64`. - - `CHATKIT_USER_MESSAGE("chatkit.user_message")` + - `BASE64("base64")` -### ChatKit Widget Item + - `JsonValue; type "inline"constant` -- `class ChatKitWidgetItem:` + Defines an inline skill for this request. - Thread item that renders a widget payload. + - `INLINE("inline")` - - `String id` + - `class BetaLocalEnvironment:` - Identifier of the thread item. + - `JsonValue; type "local"constant` - - `long createdAt` + Use a local computer environment. - Unix timestamp (in seconds) for when the item was created. + - `LOCAL("local")` - - `JsonValue; object_ "chatkit.thread_item"constant` + - `Optional> skills` - Type discriminator that is always `chatkit.thread_item`. + An optional list of skills. - - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` + - `String description` - - `String threadId` + The description of the skill. - Identifier of the parent thread. + - `String name` - - `JsonValue; type "chatkit.widget"constant` + The name of the skill. - Type discriminator that is always `chatkit.widget`. + - `String path` - - `CHATKIT_WIDGET("chatkit.widget")` + The path to the directory containing the skill. - - `String widget` + - `class BetaContainerReference:` - Serialized widget payload rendered in the UI. + - `String containerId` -# Assistants + The ID of the referenced container. -## List assistants + - `JsonValue; type "container_reference"constant` -`AssistantListPage beta().assistants().list(AssistantListParamsparams = AssistantListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + References a container created with the /v1/containers endpoint -**get** `/assistants` + - `CONTAINER_REFERENCE("container_reference")` -List assistants + - `class BetaCustomTool:` -### Parameters + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) -- `AssistantListParams params` + - `String name` - - `Optional after` + The name of the custom tool, used to identify it in tool calls. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `JsonValue; type "custom"constant` - - `Optional before` + The type of the custom tool. Always `custom`. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `CUSTOM("custom")` - - `Optional limit` + - `Optional> allowedCallers` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The tool invocation context(s). - - `Optional order` + - `DIRECT("direct")` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `PROGRAMMATIC("programmatic")` - - `ASC("asc")` + - `Optional deferLoading` - - `DESC("desc")` + Whether this tool should be deferred and discovered via tool search. -### Returns + - `Optional description` -- `class Assistant:` + Optional description of the custom tool, used to provide more context. - Represents an `assistant` that can call the model and use tools. + - `Optional format` - - `String id` + The input format for the custom tool. Default is unconstrained text. - The identifier, which can be referenced in API endpoints. + - `JsonValue;` - - `long createdAt` + - `JsonValue; type "text"constant` - The Unix timestamp (in seconds) for when the assistant was created. + Unconstrained text format. Always `text`. - - `Optional description` + - `TEXT("text")` - The description of the assistant. The maximum length is 512 characters. + - `class Grammar:` - - `Optional instructions` + A grammar defined by the user. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `String definition` - - `Optional metadata` + The grammar definition. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Syntax syntax` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The syntax of the grammar definition. One of `lark` or `regex`. - - `String model` + - `LARK("lark")` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `REGEX("regex")` - - `Optional name` + - `JsonValue; type "grammar"constant` - The name of the assistant. The maximum length is 256 characters. + Grammar format. Always `grammar`. - - `JsonValue; object_ "assistant"constant` + - `GRAMMAR("grammar")` - The object type, which is always `assistant`. + - `class BetaNamespaceTool:` - - `ASSISTANT("assistant")` + Groups function/custom tools under a shared namespace. - - `List tools` + - `String description` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + A description of the namespace shown to the model. - - `Optional responseFormat` + - `String name` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The namespace name used in tool calls (for example, `crm`). - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `List tools` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The function/custom tools available inside this namespace. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `class Function:` - - `JsonValue;` + - `String name` - - `AUTO("auto")` + - `JsonValue; type "function"constant` - - `class ResponseFormatText:` + - `FUNCTION("function")` - Default response format. Used to generate text responses. + - `Optional> allowedCallers` - - `JsonValue; type "text"constant` + The tool invocation context(s). - The type of response format being defined. Always `text`. + - `DIRECT("direct")` - - `TEXT("text")` + - `PROGRAMMATIC("programmatic")` - - `class ResponseFormatJsonObject:` + - `Optional deferLoading` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Whether this function should be deferred and discovered via tool search. - - `JsonValue; type "json_object"constant` + - `Optional description` - The type of response format being defined. Always `json_object`. + - `Optional outputSchema` - - `JSON_OBJECT("json_object")` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class ResponseFormatJsonSchema:` + - `Optional parameters` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional strict` - - `JsonSchema jsonSchema` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - Structured Outputs configuration options, including a JSON Schema. + - `class BetaCustomTool:` - - `String name` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `JsonValue; type "namespace"constant` - - `Optional description` + The type of the tool. Always `namespace`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `NAMESPACE("namespace")` - - `Optional schema` + - `class BetaToolSearchTool:` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Hosted or BYOT tool search configuration for deferred tools. - - `Optional strict` + - `JsonValue; type "tool_search"constant` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The type of the tool. Always `tool_search`. - - `JsonValue; type "json_schema"constant` + - `TOOL_SEARCH("tool_search")` - The type of response format being defined. Always `json_schema`. + - `Optional description` - - `JSON_SCHEMA("json_schema")` + Description shown to the model for a client-executed tool search tool. - - `Optional temperature` + - `Optional execution` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + Whether tool search is executed by the server or by the client. - - `Optional toolResources` + - `SERVER("server")` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `CLIENT("client")` - - `Optional codeInterpreter` + - `Optional parameters` - - `Optional> fileIds` + Parameter schema for a client-executed tool search tool. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `class BetaWebSearchPreviewTool:` - - `Optional fileSearch` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional> vectorStoreIds` + - `Type type` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `Optional topP` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - We generally recommend altering this or temperature but not both. + - `Optional> searchContentTypes` -### Example + - `TEXT("text")` -```java -package com.openai.example; + - `IMAGE("image")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.assistants.AssistantListPage; -import com.openai.models.beta.assistants.AssistantListParams; + - `Optional searchContextSize` -public final class Main { - private Main() {} + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `LOW("low")` - AssistantListPage page = client.beta().assistants().list(); - } -} -``` + - `MEDIUM("medium")` -#### Response + - `HIGH("high")` -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 - } - ], - "first_id": "asst_abc123", - "has_more": false, - "last_id": "asst_abc456", - "object": "list" -} -``` + - `Optional userLocation` -## Create assistant + The user's location. -`Assistant beta().assistants().create(AssistantCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `JsonValue; type "approximate"constant` -**post** `/assistants` + The type of location approximation. Always `approximate`. -Create assistant + - `APPROXIMATE("approximate")` -### Parameters + - `Optional city` -- `AssistantCreateParams params` + Free text input for the city of the user, e.g. `San Francisco`. - - `ChatModel model` + - `Optional country` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `Optional description` + - `Optional region` - The description of the assistant. The maximum length is 512 characters. + Free text input for the region of the user, e.g. `California`. - - `Optional instructions` + - `Optional timezone` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Optional metadata` + - `class BetaApplyPatchTool:` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Allows the assistant to create, delete, or update files using unified diffs. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `JsonValue; type "apply_patch"constant` - - `Optional name` + The type of the tool. Always `apply_patch`. - The name of the assistant. The maximum length is 256 characters. + - `APPLY_PATCH("apply_patch")` - - `Optional reasoningEffort` + - `Optional> allowedCallers` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The tool invocation context(s). - - `Optional responseFormat` + - `DIRECT("direct")` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `PROGRAMMATIC("programmatic")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `JsonValue; type "tool_search_output"constant` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The item type. Always `tool_search_output`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `Optional temperature` + - `Optional id` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + The unique ID of this tool search output. - - `Optional toolResources` + - `Optional agent` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The agent that produced this item. - - `Optional codeInterpreter` + - `String agentName` - - `Optional> fileIds` + The canonical name of the agent that produced this item. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `Optional callId` - - `Optional fileSearch` + The unique ID of the tool search call generated by the model. - - `Optional> vectorStoreIds` + - `Optional execution` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + Whether tool search was executed by the server or by the client. - - `Optional> vectorStores` + - `SERVER("server")` - A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `CLIENT("client")` - - `Optional chunkingStrategy` + - `Optional status` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + The status of the tool search output. - - `JsonValue;` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "auto"constant` + - `COMPLETED("completed")` - Always `auto`. + - `INCOMPLETE("incomplete")` - - `AUTO("auto")` + - `AdditionalTools` - - `class Static:` + - `JsonValue; role "developer"constant` - - `InnerStatic static_` + The role that provided the additional tools. Only `developer` is supported. - - `long chunkOverlapTokens` + - `DEVELOPER("developer")` - The number of tokens that overlap between chunks. The default value is `400`. + - `List tools` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + A list of additional tools made available at this item. - - `long maxChunkSizeTokens` + - `class BetaFunctionTool:` - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `JsonValue; type "static"constant` + - `class BetaFileSearchTool:` - Always `static`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `STATIC("static")` + - `class BetaComputerTool:` - - `Optional> fileIds` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. + - `class BetaComputerUsePreviewTool:` - - `Optional metadata` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `class BetaWebSearchTool:` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional> tools` + - `Mcp` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `CodeInterpreter` - - `Optional topP` + - `JsonValue;` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `ImageGeneration` - We generally recommend altering this or temperature but not both. + - `JsonValue;` -### Returns + - `class BetaFunctionShellTool:` -- `class Assistant:` + A tool that allows the model to execute shell commands. - Represents an `assistant` that can call the model and use tools. + - `class BetaCustomTool:` - - `String id` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The identifier, which can be referenced in API endpoints. + - `class BetaNamespaceTool:` - - `long createdAt` + Groups function/custom tools under a shared namespace. - The Unix timestamp (in seconds) for when the assistant was created. + - `class BetaToolSearchTool:` - - `Optional description` + Hosted or BYOT tool search configuration for deferred tools. - The description of the assistant. The maximum length is 512 characters. + - `class BetaWebSearchPreviewTool:` - - `Optional instructions` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `class BetaApplyPatchTool:` - - `Optional metadata` + Allows the assistant to create, delete, or update files using unified diffs. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `JsonValue; type "additional_tools"constant` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The item type. Always `additional_tools`. - - `String model` + - `ADDITIONAL_TOOLS("additional_tools")` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `Optional id` - - `Optional name` + The unique ID of this additional tools item. - The name of the assistant. The maximum length is 256 characters. + - `Optional agent` - - `JsonValue; object_ "assistant"constant` + The agent that produced this item. - The object type, which is always `assistant`. + - `String agentName` - - `ASSISTANT("assistant")` + The canonical name of the agent that produced this item. - - `List tools` + - `class BetaResponseReasoningItem:` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `Optional responseFormat` + - `String id` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The unique identifier of the reasoning content. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `List summary` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Reasoning summary content. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `String text` - - `JsonValue;` + A summary of the reasoning output from the model so far. - - `AUTO("auto")` + - `JsonValue; type "summary_text"constant` - - `class ResponseFormatText:` + The type of the object. Always `summary_text`. - Default response format. Used to generate text responses. + - `SUMMARY_TEXT("summary_text")` - - `JsonValue; type "text"constant` + - `JsonValue; type "reasoning"constant` - The type of response format being defined. Always `text`. + The type of the object. Always `reasoning`. - - `TEXT("text")` + - `REASONING("reasoning")` - - `class ResponseFormatJsonObject:` + - `Optional agent` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The agent that produced this item. - - `JsonValue; type "json_object"constant` + - `String agentName` - The type of response format being defined. Always `json_object`. + The canonical name of the agent that produced this item. - - `JSON_OBJECT("json_object")` + - `Optional> content` - - `class ResponseFormatJsonSchema:` + Reasoning text content. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `String text` - - `JsonSchema jsonSchema` + The reasoning text from the model. - Structured Outputs configuration options, including a JSON Schema. + - `JsonValue; type "reasoning_text"constant` - - `String name` + The type of the reasoning text. Always `reasoning_text`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `REASONING_TEXT("reasoning_text")` - - `Optional description` + - `Optional encryptedContent` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `Optional schema` + - `Optional status` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional strict` + - `IN_PROGRESS("in_progress")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `COMPLETED("completed")` - - `JsonValue; type "json_schema"constant` + - `INCOMPLETE("incomplete")` - The type of response format being defined. Always `json_schema`. + - `class BetaResponseCompactionItemParam:` - - `JSON_SCHEMA("json_schema")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `Optional temperature` + - `String encryptedContent` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + The encrypted content of the compaction summary. - - `Optional toolResources` + - `JsonValue; type "compaction"constant` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The type of the item. Always `compaction`. - - `Optional codeInterpreter` + - `COMPACTION("compaction")` - - `Optional> fileIds` + - `Optional id` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + The ID of the compaction item. - - `Optional fileSearch` + - `Optional agent` - - `Optional> vectorStoreIds` + The agent that produced this item. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `String agentName` - - `Optional topP` + The canonical name of the agent that produced this item. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `ImageGenerationCall` - We generally recommend altering this or temperature but not both. + - `String id` -### Example + The unique ID of the image generation call. -```java -package com.openai.example; + - `Optional result` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.ChatModel; -import com.openai.models.beta.assistants.Assistant; -import com.openai.models.beta.assistants.AssistantCreateParams; + The generated image encoded in base64. -public final class Main { - private Main() {} + - `Status status` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The status of the image generation call. - AssistantCreateParams params = AssistantCreateParams.builder() - .model(ChatModel.GPT_4O) - .build(); - Assistant assistant = client.beta().assistants().create(params); - } -} -``` + - `IN_PROGRESS("in_progress")` -#### Response + - `COMPLETED("completed")` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `GENERATING("generating")` -## Retrieve assistant + - `FAILED("failed")` -`Assistant beta().assistants().retrieve(AssistantRetrieveParamsparams = AssistantRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `JsonValue; type "image_generation_call"constant` -**get** `/assistants/{assistant_id}` + The type of the image generation call. Always `image_generation_call`. -Retrieve assistant + - `IMAGE_GENERATION_CALL("image_generation_call")` -### Parameters + - `Optional agent` -- `AssistantRetrieveParams params` + The agent that produced this item. - - `Optional assistantId` + - `String agentName` -### Returns + The canonical name of the agent that produced this item. -- `class Assistant:` + - `class BetaResponseCodeInterpreterToolCall:` - Represents an `assistant` that can call the model and use tools. + A tool call to run code. - `String id` - The identifier, which can be referenced in API endpoints. + The unique ID of the code interpreter tool call. - - `long createdAt` + - `Optional code` - The Unix timestamp (in seconds) for when the assistant was created. + The code to run, or null if not available. - - `Optional description` + - `String containerId` - The description of the assistant. The maximum length is 512 characters. + The ID of the container used to run the code. - - `Optional instructions` + - `Optional> outputs` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `Optional metadata` + - `class Logs:` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The logs output from the code interpreter. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `String logs` - - `String model` + The logs output from the code interpreter. - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `JsonValue; type "logs"constant` - - `Optional name` + The type of the output. Always `logs`. - The name of the assistant. The maximum length is 256 characters. + - `LOGS("logs")` - - `JsonValue; object_ "assistant"constant` + - `class Image:` - The object type, which is always `assistant`. + The image output from the code interpreter. - - `ASSISTANT("assistant")` + - `JsonValue; type "image"constant` - - `List tools` + The type of the output. Always `image`. - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `IMAGE("image")` - - `Optional responseFormat` + - `String url` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The URL of the image output from the code interpreter. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Status status` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `IN_PROGRESS("in_progress")` - - `JsonValue;` + - `COMPLETED("completed")` - - `AUTO("auto")` + - `INCOMPLETE("incomplete")` - - `class ResponseFormatText:` + - `INTERPRETING("interpreting")` - Default response format. Used to generate text responses. + - `FAILED("failed")` - - `JsonValue; type "text"constant` + - `JsonValue; type "code_interpreter_call"constant` - The type of response format being defined. Always `text`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `TEXT("text")` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `class ResponseFormatJsonObject:` + - `Optional agent` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The agent that produced this item. - - `JsonValue; type "json_object"constant` + - `String agentName` - The type of response format being defined. Always `json_object`. + The canonical name of the agent that produced this item. - - `JSON_OBJECT("json_object")` + - `LocalShellCall` - - `class ResponseFormatJsonSchema:` + - `String id` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The unique ID of the local shell call. - - `JsonSchema jsonSchema` + - `Action action` - Structured Outputs configuration options, including a JSON Schema. + Execute a shell command on the server. - - `String name` + - `List command` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The command to run. - - `Optional description` + - `Env env` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Environment variables to set for the command. - - `Optional schema` + - `JsonValue; type "exec"constant` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the local shell action. Always `exec`. - - `Optional strict` + - `EXEC("exec")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional timeoutMs` - - `JsonValue; type "json_schema"constant` + Optional timeout in milliseconds for the command. - The type of response format being defined. Always `json_schema`. + - `Optional user` - - `JSON_SCHEMA("json_schema")` + Optional user to run the command as. - - `Optional temperature` + - `Optional workingDirectory` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + Optional working directory to run the command in. - - `Optional toolResources` + - `String callId` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The unique ID of the local shell tool call generated by the model. - - `Optional codeInterpreter` + - `Status status` - - `Optional> fileIds` + The status of the local shell call. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `IN_PROGRESS("in_progress")` - - `Optional fileSearch` + - `COMPLETED("completed")` - - `Optional> vectorStoreIds` + - `INCOMPLETE("incomplete")` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `JsonValue; type "local_shell_call"constant` - - `Optional topP` + The type of the local shell call. Always `local_shell_call`. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `LOCAL_SHELL_CALL("local_shell_call")` - We generally recommend altering this or temperature but not both. + - `Optional agent` -### Example + The agent that produced this item. -```java -package com.openai.example; + - `String agentName` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.assistants.Assistant; -import com.openai.models.beta.assistants.AssistantRetrieveParams; + The canonical name of the agent that produced this item. -public final class Main { - private Main() {} + - `LocalShellCallOutput` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `String id` - Assistant assistant = client.beta().assistants().retrieve("assistant_id"); - } -} -``` + The unique ID of the local shell tool call generated by the model. -#### Response + - `String output` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + A JSON string of the output of the local shell tool call. -## Modify assistant + - `JsonValue; type "local_shell_call_output"constant` -`Assistant beta().assistants().update(AssistantUpdateParamsparams = AssistantUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The type of the local shell tool call output. Always `local_shell_call_output`. -**post** `/assistants/{assistant_id}` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` -Modify assistant + - `Optional agent` -### Parameters + The agent that produced this item. -- `AssistantUpdateParams params` + - `String agentName` - - `Optional assistantId` + The canonical name of the agent that produced this item. - - `Optional description` + - `Optional status` - The description of the assistant. The maximum length is 512 characters. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `Optional instructions` + - `IN_PROGRESS("in_progress")` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `COMPLETED("completed")` - - `Optional metadata` + - `INCOMPLETE("incomplete")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `ShellCall` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Action action` - - `Optional model` + The shell commands and limits that describe how to run the tool call. - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `List commands` - - `GPT_5("gpt-5")` + Ordered shell commands for the execution environment to run. - - `GPT_5_MINI("gpt-5-mini")` + - `Optional maxOutputLength` - - `GPT_5_NANO("gpt-5-nano")` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + - `Optional timeoutMs` - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `String callId` - - `GPT_4_1("gpt-4.1")` + The unique ID of the shell tool call generated by the model. - - `GPT_4_1_MINI("gpt-4.1-mini")` + - `JsonValue; type "shell_call"constant` - - `GPT_4_1_NANO("gpt-4.1-nano")` + The type of the item. Always `shell_call`. - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `SHELL_CALL("shell_call")` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + - `Optional id` - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `O3_MINI("o3-mini")` + - `Optional agent` - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + The agent that produced this item. - - `O1("o1")` + - `String agentName` - - `O1_2024_12_17("o1-2024-12-17")` + The canonical name of the agent that produced this item. - - `GPT_4O("gpt-4o")` + - `Optional caller` - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + The execution context that produced this tool call. - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + - `JsonValue;` - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + - `JsonValue; type "direct"constant` - - `GPT_4O_MINI("gpt-4o-mini")` + The caller type. Always `direct`. - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + - `DIRECT("direct")` - - `GPT_4_5_PREVIEW("gpt-4.5-preview")` + - `class Program:` - - `GPT_4_5_PREVIEW_2025_02_27("gpt-4.5-preview-2025-02-27")` + - `String callerId` - - `GPT_4_TURBO("gpt-4-turbo")` + The call ID of the program item that produced this tool call. - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `JsonValue; type "program"constant` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + The caller type. Always `program`. - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + - `PROGRAM("program")` - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `Optional environment` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + The environment to execute the shell commands in. - - `GPT_4("gpt-4")` + - `class BetaLocalEnvironment:` - - `GPT_4_0314("gpt-4-0314")` + - `class BetaContainerReference:` - - `GPT_4_0613("gpt-4-0613")` + - `Optional status` - - `GPT_4_32K("gpt-4-32k")` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `GPT_4_32K_0314("gpt-4-32k-0314")` + - `IN_PROGRESS("in_progress")` - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `COMPLETED("completed")` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `INCOMPLETE("incomplete")` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `ShellCallOutput` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `String callId` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + The unique ID of the shell tool call generated by the model. - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `List output` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `Optional name` + - `Outcome outcome` - The name of the assistant. The maximum length is 256 characters. + The exit or timeout outcome associated with this shell call. - - `Optional reasoningEffort` + - `JsonValue;` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `JsonValue; type "timeout"constant` - - `Optional responseFormat` + The outcome type. Always `timeout`. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `TIMEOUT("timeout")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `class Exit:` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Indicates that the shell commands finished and returned an exit code. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `long exitCode` - - `Optional temperature` + The exit code returned by the shell process. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `JsonValue; type "exit"constant` - - `Optional toolResources` + The outcome type. Always `exit`. - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `EXIT("exit")` - - `Optional codeInterpreter` + - `String stderr` - - `Optional> fileIds` + Captured stderr output for the shell call. - Overrides the list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `String stdout` - - `Optional fileSearch` + Captured stdout output for the shell call. - - `Optional> vectorStoreIds` + - `JsonValue; type "shell_call_output"constant` - Overrides the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + The type of the item. Always `shell_call_output`. - - `Optional> tools` + - `SHELL_CALL_OUTPUT("shell_call_output")` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `Optional id` - - `Optional topP` + The unique ID of the shell tool call output. Populated when this item is returned via API. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `Optional agent` - We generally recommend altering this or temperature but not both. + The agent that produced this item. -### Returns + - `String agentName` -- `class Assistant:` + The canonical name of the agent that produced this item. - Represents an `assistant` that can call the model and use tools. + - `Optional caller` - - `String id` + The execution context that produced this tool call. - The identifier, which can be referenced in API endpoints. + - `JsonValue;` - - `long createdAt` + - `JsonValue; type "direct"constant` - The Unix timestamp (in seconds) for when the assistant was created. + The caller type. Always `direct`. - - `Optional description` + - `DIRECT("direct")` - The description of the assistant. The maximum length is 512 characters. + - `class Program:` - - `Optional instructions` + - `String callerId` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The call ID of the program item that produced this tool call. - - `Optional metadata` + - `JsonValue; type "program"constant` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The caller type. Always `program`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `PROGRAM("program")` - - `String model` + - `Optional maxOutputLength` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `Optional name` + - `Optional status` - The name of the assistant. The maximum length is 256 characters. + The status of the shell call output. - - `JsonValue; object_ "assistant"constant` + - `IN_PROGRESS("in_progress")` - The object type, which is always `assistant`. + - `COMPLETED("completed")` - - `ASSISTANT("assistant")` + - `INCOMPLETE("incomplete")` - - `List tools` + - `ApplyPatchCall` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `String callId` - - `Optional responseFormat` + The unique ID of the apply patch tool call generated by the model. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `Operation operation` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The specific create, delete, or update instruction for the apply_patch tool call. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class CreateFile:` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + Instruction for creating a new file via the apply_patch tool. - - `JsonValue;` + - `String diff` - - `AUTO("auto")` + Unified diff content to apply when creating the file. - - `class ResponseFormatText:` + - `String path` - Default response format. Used to generate text responses. + Path of the file to create relative to the workspace root. - - `JsonValue; type "text"constant` + - `JsonValue; type "create_file"constant` - The type of response format being defined. Always `text`. + The operation type. Always `create_file`. - - `TEXT("text")` + - `CREATE_FILE("create_file")` - - `class ResponseFormatJsonObject:` + - `class DeleteFile:` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Instruction for deleting an existing file via the apply_patch tool. - - `JsonValue; type "json_object"constant` + - `String path` - The type of response format being defined. Always `json_object`. + Path of the file to delete relative to the workspace root. - - `JSON_OBJECT("json_object")` + - `JsonValue; type "delete_file"constant` - - `class ResponseFormatJsonSchema:` + The operation type. Always `delete_file`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `DELETE_FILE("delete_file")` - - `JsonSchema jsonSchema` + - `class UpdateFile:` - Structured Outputs configuration options, including a JSON Schema. + Instruction for updating an existing file via the apply_patch tool. - - `String name` + - `String diff` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + Unified diff content to apply to the existing file. - - `Optional description` + - `String path` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Path of the file to update relative to the workspace root. - - `Optional schema` + - `JsonValue; type "update_file"constant` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The operation type. Always `update_file`. - - `Optional strict` + - `UPDATE_FILE("update_file")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Status status` - - `JsonValue; type "json_schema"constant` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The type of response format being defined. Always `json_schema`. + - `IN_PROGRESS("in_progress")` - - `JSON_SCHEMA("json_schema")` + - `COMPLETED("completed")` - - `Optional temperature` + - `JsonValue; type "apply_patch_call"constant` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + The type of the item. Always `apply_patch_call`. - - `Optional toolResources` + - `APPLY_PATCH_CALL("apply_patch_call")` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `Optional id` - - `Optional codeInterpreter` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `Optional> fileIds` + - `Optional agent` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + The agent that produced this item. - - `Optional fileSearch` + - `String agentName` - - `Optional> vectorStoreIds` + The canonical name of the agent that produced this item. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `Optional caller` - - `Optional topP` + The execution context that produced this tool call. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `JsonValue;` - We generally recommend altering this or temperature but not both. + - `JsonValue; type "direct"constant` -### Example + The caller type. Always `direct`. -```java -package com.openai.example; + - `DIRECT("direct")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.assistants.Assistant; -import com.openai.models.beta.assistants.AssistantUpdateParams; + - `class Program:` -public final class Main { - private Main() {} + - `String callerId` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The call ID of the program item that produced this tool call. - Assistant assistant = client.beta().assistants().update("assistant_id"); - } -} -``` + - `JsonValue; type "program"constant` -#### Response + The caller type. Always `program`. -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `PROGRAM("program")` -## Delete assistant + - `ApplyPatchCallOutput` -`AssistantDeleted beta().assistants().delete(AssistantDeleteParamsparams = AssistantDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `String callId` -**delete** `/assistants/{assistant_id}` + The unique ID of the apply patch tool call generated by the model. -Delete assistant + - `Status status` -### Parameters + The status of the apply patch tool call output. One of `completed` or `failed`. -- `AssistantDeleteParams params` + - `COMPLETED("completed")` - - `Optional assistantId` + - `FAILED("failed")` -### Returns + - `JsonValue; type "apply_patch_call_output"constant` -- `class AssistantDeleted:` + The type of the item. Always `apply_patch_call_output`. - - `String id` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `boolean deleted` + - `Optional id` - - `JsonValue; object_ "assistant.deleted"constant` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `ASSISTANT_DELETED("assistant.deleted")` + - `Optional agent` -### Example + The agent that produced this item. -```java -package com.openai.example; + - `String agentName` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.assistants.AssistantDeleteParams; -import com.openai.models.beta.assistants.AssistantDeleted; + The canonical name of the agent that produced this item. -public final class Main { - private Main() {} + - `Optional caller` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The execution context that produced this tool call. - AssistantDeleted assistantDeleted = client.beta().assistants().delete("assistant_id"); - } -} -``` + - `JsonValue;` -#### Response + - `JsonValue; type "direct"constant` -```json -{ - "id": "id", - "deleted": true, - "object": "assistant.deleted" -} -``` + The caller type. Always `direct`. -## Domain Types + - `DIRECT("direct")` -### Assistant + - `class Program:` -- `class Assistant:` + - `String callerId` - Represents an `assistant` that can call the model and use tools. + The call ID of the program item that produced this tool call. - - `String id` + - `JsonValue; type "program"constant` - The identifier, which can be referenced in API endpoints. + The caller type. Always `program`. - - `long createdAt` + - `PROGRAM("program")` - The Unix timestamp (in seconds) for when the assistant was created. + - `Optional output` - - `Optional description` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The description of the assistant. The maximum length is 512 characters. + - `McpListTools` - - `Optional instructions` + - `String id` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The unique ID of the list. - - `Optional metadata` + - `String serverLabel` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The label of the MCP server. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `List tools` - - `String model` + The tools available on the server. - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `JsonValue inputSchema` - - `Optional name` + The JSON schema describing the tool's input. - The name of the assistant. The maximum length is 256 characters. + - `String name` - - `JsonValue; object_ "assistant"constant` + The name of the tool. - The object type, which is always `assistant`. + - `Optional annotations` - - `ASSISTANT("assistant")` + Additional annotations about the tool. - - `List tools` + - `Optional description` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + The description of the tool. - - `Optional responseFormat` + - `JsonValue; type "mcp_list_tools"constant` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The type of the item. Always `mcp_list_tools`. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `MCP_LIST_TOOLS("mcp_list_tools")` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `Optional agent` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The agent that produced this item. - - `JsonValue;` + - `String agentName` - - `AUTO("auto")` + The canonical name of the agent that produced this item. - - `class ResponseFormatText:` + - `Optional error` - Default response format. Used to generate text responses. + Error message if the server could not list tools. - - `JsonValue; type "text"constant` + - `McpApprovalRequest` - The type of response format being defined. Always `text`. + - `String id` - - `TEXT("text")` + The unique ID of the approval request. - - `class ResponseFormatJsonObject:` + - `String arguments` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + A JSON string of arguments for the tool. - - `JsonValue; type "json_object"constant` + - `String name` - The type of response format being defined. Always `json_object`. + The name of the tool to run. - - `JSON_OBJECT("json_object")` + - `String serverLabel` - - `class ResponseFormatJsonSchema:` + The label of the MCP server making the request. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `JsonValue; type "mcp_approval_request"constant` - - `JsonSchema jsonSchema` + The type of the item. Always `mcp_approval_request`. - Structured Outputs configuration options, including a JSON Schema. + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `String name` + - `Optional agent` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The agent that produced this item. - - `Optional description` + - `String agentName` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The canonical name of the agent that produced this item. - - `Optional schema` + - `McpApprovalResponse` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `String approvalRequestId` - - `Optional strict` + The ID of the approval request being answered. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `boolean approve` - - `JsonValue; type "json_schema"constant` + Whether the request was approved. - The type of response format being defined. Always `json_schema`. + - `JsonValue; type "mcp_approval_response"constant` - - `JSON_SCHEMA("json_schema")` + The type of the item. Always `mcp_approval_response`. - - `Optional temperature` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `Optional id` - - `Optional toolResources` + The unique ID of the approval response - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `Optional agent` - - `Optional codeInterpreter` + The agent that produced this item. - - `Optional> fileIds` + - `String agentName` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + The canonical name of the agent that produced this item. - - `Optional fileSearch` + - `Optional reason` - - `Optional> vectorStoreIds` + Optional reason for the decision. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `McpCall` - - `Optional topP` + - `String id` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + The unique ID of the tool call. - We generally recommend altering this or temperature but not both. + - `String arguments` -### Assistant Deleted + A JSON string of the arguments passed to the tool. -- `class AssistantDeleted:` + - `String name` - - `String id` + The name of the tool that was run. - - `boolean deleted` + - `String serverLabel` - - `JsonValue; object_ "assistant.deleted"constant` + The label of the MCP server running the tool. - - `ASSISTANT_DELETED("assistant.deleted")` + - `JsonValue; type "mcp_call"constant` -### Assistant Stream Event + The type of the item. Always `mcp_call`. -- `class AssistantStreamEvent: A class that can be one of several variants.union` + - `MCP_CALL("mcp_call")` - Represents an event emitted when streaming a Run. + - `Optional agent` - Each event in a server-sent events stream has an `event` and `data` property: + The agent that produced this item. - ``` - event: thread.created - data: {"id": "thread_123", "object": "thread", ...} - ``` + - `String agentName` - We emit events whenever a new object is created, transitions to a new state, or is being - streamed in parts (deltas). For example, we emit `thread.run.created` when a new run - is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses - to create a message during a run, we emit a `thread.message.created event`, a - `thread.message.in_progress` event, many `thread.message.delta` events, and finally a - `thread.message.completed` event. + The canonical name of the agent that produced this item. - We may add additional events over time, so we recommend handling unknown events gracefully - in your code. See the [Assistants API quickstart](https://platform.openai.com/docs/assistants/overview) to learn how to - integrate the Assistants API with streaming. + - `Optional approvalRequestId` - - `ThreadCreated` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `Thread data` + - `Optional error` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The error from the tool call, if any. - - `String id` + - `Optional output` - The identifier, which can be referenced in API endpoints. + The output from the tool call. - - `long createdAt` + - `Optional status` - The Unix timestamp (in seconds) for when the thread was created. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `Optional metadata` + - `IN_PROGRESS("in_progress")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `COMPLETED("completed")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `INCOMPLETE("incomplete")` - - `JsonValue; object_ "thread"constant` + - `CALLING("calling")` - The object type, which is always `thread`. + - `FAILED("failed")` - - `THREAD("thread")` + - `class BetaResponseCustomToolCallOutput:` - - `Optional toolResources` + The output of a custom tool call from your code, being sent back to the model. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `String callId` - - `Optional codeInterpreter` + The call ID, used to map this custom tool call output to a custom tool call. - - `Optional> fileIds` + - `Output output` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `Optional fileSearch` + - `String` - - `Optional> vectorStoreIds` + - `List` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `class BetaResponseInputText:` - - `JsonValue; event "thread.created"constant` + A text input to the model. - - `THREAD_CREATED("thread.created")` + - `class BetaResponseInputImage:` - - `Optional enabled` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Whether to enable input audio transcription. + - `class BetaResponseInputFile:` - - `ThreadRunCreated` + A file input to the model. - - `Run data` + - `JsonValue; type "custom_tool_call_output"constant` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The type of the custom tool call output. Always `custom_tool_call_output`. - - `String id` + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - The identifier, which can be referenced in API endpoints. + - `Optional id` - - `String assistantId` + The unique ID of the custom tool call output in the OpenAI platform. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `Optional agent` - - `Optional cancelledAt` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was cancelled. + - `String agentName` - - `Optional completedAt` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was completed. + - `Optional caller` - - `long createdAt` + The execution context that produced this tool call. - The Unix timestamp (in seconds) for when the run was created. + - `JsonValue;` - - `Optional expiresAt` + - `JsonValue; type "direct"constant` - The Unix timestamp (in seconds) for when the run will expire. + The caller type. Always `direct`. - - `Optional failedAt` + - `DIRECT("direct")` - The Unix timestamp (in seconds) for when the run failed. + - `class Program:` - - `Optional incompleteDetails` + - `String callerId` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The call ID of the program item that produced this tool call. - - `Optional reason` + - `JsonValue; type "program"constant` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The caller type. Always `program`. - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + - `PROGRAM("program")` - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `class BetaResponseCustomToolCall:` - - `String instructions` + A call to a custom tool created by the model. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `String callId` - - `Optional lastError` + An identifier used to map this custom tool call to a tool call output. - The last error associated with this run. Will be `null` if there are no errors. + - `String input` - - `Code code` + The input for the custom tool call generated by the model. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `String name` - - `SERVER_ERROR("server_error")` + The name of the custom tool being called. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `JsonValue; type "custom_tool_call"constant` - - `INVALID_PROMPT("invalid_prompt")` + The type of the custom tool call. Always `custom_tool_call`. - - `String message` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - A human-readable description of the error. + - `Optional id` - - `Optional maxCompletionTokens` + The unique ID of the custom tool call in the OpenAI platform. - The maximum number of completion tokens specified to have been used over the course of the run. + - `Optional agent` - - `Optional maxPromptTokens` + The agent that produced this item. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `String agentName` - - `Optional metadata` + The canonical name of the agent that produced this item. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional caller` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The execution context that produced this tool call. - - `String model` + - `JsonValue;` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `JsonValue; type "direct"constant` - - `JsonValue; object_ "thread.run"constant` + - `DIRECT("direct")` - The object type, which is always `thread.run`. + - `class Program:` - - `THREAD_RUN("thread.run")` + - `String callerId` - - `boolean parallelToolCalls` + The call ID of the program item that produced this tool call. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `JsonValue; type "program"constant` - - `Optional requiredAction` + - `PROGRAM("program")` - Details on the action required to continue the run. Will be `null` if no action is required. + - `Optional namespace` - - `SubmitToolOutputs submitToolOutputs` + The namespace of the custom tool being called. - Details on the tool outputs needed for this run to continue. + - `CompactionTrigger` - - `List toolCalls` + - `JsonValue; type "compaction_trigger"constant` - A list of the relevant tool calls. + The type of the item. Always `compaction_trigger`. - - `String id` + - `COMPACTION_TRIGGER("compaction_trigger")` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `Optional agent` - - `Function function` + The agent that produced this item. - The function definition. + - `String agentName` - - `String arguments` + The canonical name of the agent that produced this item. - The arguments that the model expects you to pass to the function. + - `ItemReference` - - `String name` + - `String id` - The name of the function. + The ID of the item to reference. - - `JsonValue; type "function"constant` + - `Optional agent` - The type of tool call the output is required for. For now, this is always `function`. + The agent that produced this item. - - `FUNCTION("function")` + - `String agentName` - - `JsonValue; type "submit_tool_outputs"constant` + The canonical name of the agent that produced this item. - For now, this is always `submit_tool_outputs`. + - `Optional type` - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + The type of item to reference. Always `item_reference`. - - `Optional responseFormat` + - `ITEM_REFERENCE("item_reference")` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `Program` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `String id` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The unique ID of this program item. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `String callId` - - `JsonValue;` + The stable call ID of the program item. - - `AUTO("auto")` + - `String code` - - `class ResponseFormatText:` + The JavaScript source executed by programmatic tool calling. - Default response format. Used to generate text responses. + - `String fingerprint` - - `JsonValue; type "text"constant` + Opaque program replay fingerprint that must be round-tripped. - The type of response format being defined. Always `text`. + - `JsonValue; type "program"constant` - - `TEXT("text")` + The item type. Always `program`. - - `class ResponseFormatJsonObject:` + - `PROGRAM("program")` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `Optional agent` - - `JsonValue; type "json_object"constant` + The agent that produced this item. - The type of response format being defined. Always `json_object`. + - `String agentName` - - `JSON_OBJECT("json_object")` + The canonical name of the agent that produced this item. - - `class ResponseFormatJsonSchema:` + - `ProgramOutput` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `String id` - - `JsonSchema jsonSchema` + The unique ID of this program output item. - Structured Outputs configuration options, including a JSON Schema. + - `String callId` - - `String name` + The call ID of the program item. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `String result` - - `Optional description` + The result produced by the program item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Status status` - - `Optional schema` + The terminal status of the program output. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `COMPLETED("completed")` - - `Optional strict` + - `INCOMPLETE("incomplete")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `JsonValue; type "program_output"constant` - - `JsonValue; type "json_schema"constant` + The item type. Always `program_output`. - The type of response format being defined. Always `json_schema`. + - `PROGRAM_OUTPUT("program_output")` - - `JSON_SCHEMA("json_schema")` + - `Optional agent` - - `Optional startedAt` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was started. + - `String agentName` - - `JsonValue status` + The canonical name of the agent that produced this item. - - `String threadId` + - `Optional instructions` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + A system (or developer) message inserted into the model's context. - - `Optional toolChoice` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `Optional maxOutputTokens` - - `Auto` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `NONE("none")` + - `Optional maxToolCalls` - - `AUTO("auto")` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `REQUIRED("required")` + - `Optional metadata` - - `class AssistantToolChoice:` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Specifies a tool the model should use. Use to force the model to call a specific tool. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Type type` + - `Optional model` - The type of the tool. If type is `function`, the function name must be set + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `FUNCTION("function")` + - `GPT_5_6_SOL("gpt-5.6-sol")` - - `CODE_INTERPRETER("code_interpreter")` + - `GPT_5_6_TERRA("gpt-5.6-terra")` - - `FILE_SEARCH("file_search")` + - `GPT_5_6_LUNA("gpt-5.6-luna")` - - `Optional function` + - `GPT_5_4("gpt-5.4")` - - `String name` + - `GPT_5_4_MINI("gpt-5.4-mini")` - The name of the function to call. + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `List tools` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - `Optional truncationStrategy` + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `GPT_5_2("gpt-5.2")` - - `Type type` + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - `AUTO("auto")` + - `GPT_5_2_PRO("gpt-5.2-pro")` - - `LAST_MESSAGES("last_messages")` + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `Optional lastMessages` + - `GPT_5_1("gpt-5.1")` - The number of most recent messages from the thread when constructing the context for the run. + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - `Optional usage` + - `GPT_5_1_CODEX("gpt-5.1-codex")` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `GPT_5_1_MINI("gpt-5.1-mini")` - - `long completionTokens` + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - Number of completion tokens used over the course of the run. + - `GPT_5("gpt-5")` - - `long promptTokens` + - `GPT_5_MINI("gpt-5-mini")` - Number of prompt tokens used over the course of the run. + - `GPT_5_NANO("gpt-5-nano")` - - `long totalTokens` + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - Total number of tokens used (prompt + completion). + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `Optional temperature` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - The sampling temperature used for this run. If not set, defaults to 1. + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `Optional topP` + - `GPT_4_1("gpt-4.1")` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `GPT_4_1_MINI("gpt-4.1-mini")` - - `JsonValue; event "thread.run.created"constant` + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `THREAD_RUN_CREATED("thread.run.created")` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - `ThreadRunQueued` + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `Run data` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `O4_MINI("o4-mini")` - - `JsonValue; event "thread.run.queued"constant` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - - `THREAD_RUN_QUEUED("thread.run.queued")` + - `O3("o3")` - - `ThreadRunInProgress` + - `O3_2025_04_16("o3-2025-04-16")` - - `Run data` + - `O3_MINI("o3-mini")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - `JsonValue; event "thread.run.in_progress"constant` + - `O1("o1")` - - `THREAD_RUN_IN_PROGRESS("thread.run.in_progress")` + - `O1_2024_12_17("o1-2024-12-17")` - - `ThreadRunRequiresAction` + - `O1_PREVIEW("o1-preview")` - - `Run data` + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `O1_MINI("o1-mini")` - - `JsonValue; event "thread.run.requires_action"constant` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - - `THREAD_RUN_REQUIRES_ACTION("thread.run.requires_action")` + - `GPT_4O("gpt-4o")` - - `ThreadRunCompleted` + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - - `Run data` + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - - `JsonValue; event "thread.run.completed"constant` + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - `THREAD_RUN_COMPLETED("thread.run.completed")` + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - `ThreadRunIncomplete` + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - - `Run data` + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - - `JsonValue; event "thread.run.incomplete"constant` + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - `THREAD_RUN_INCOMPLETE("thread.run.incomplete")` + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `ThreadRunFailed` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `Run data` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - `JsonValue; event "thread.run.failed"constant` + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - `THREAD_RUN_FAILED("thread.run.failed")` + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `ThreadRunCancelling` + - `GPT_4O_MINI("gpt-4o-mini")` - - `Run data` + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `GPT_4_TURBO("gpt-4-turbo")` - - `JsonValue; event "thread.run.cancelling"constant` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - - `THREAD_RUN_CANCELLING("thread.run.cancelling")` + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `ThreadRunCancelled` + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `Run data` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - - `JsonValue; event "thread.run.cancelled"constant` + - `GPT_4("gpt-4")` - - `THREAD_RUN_CANCELLED("thread.run.cancelled")` + - `GPT_4_0314("gpt-4-0314")` - - `ThreadRunExpired` + - `GPT_4_0613("gpt-4-0613")` - - `Run data` + - `GPT_4_32K("gpt-4-32k")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `JsonValue; event "thread.run.expired"constant` + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `THREAD_RUN_EXPIRED("thread.run.expired")` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - - `ThreadRunStepCreated` + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `RunStep data` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - Represents a step in execution of a run. + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `String id` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - The identifier of the run step, which can be referenced in API endpoints. + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - `String assistantId` + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `O1_PRO("o1-pro")` - - `Optional cancelledAt` + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `O3_PRO("o3-pro")` - - `Optional completedAt` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - The Unix timestamp (in seconds) for when the run step completed. + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `long createdAt` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - The Unix timestamp (in seconds) for when the run step was created. + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - - `Optional expiredAt` + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - `Optional failedAt` + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - The Unix timestamp (in seconds) for when the run step failed. + - `GPT_5_CODEX("gpt-5-codex")` - - `Optional lastError` + - `GPT_5_PRO("gpt-5-pro")` - The last error associated with this run step. Will be `null` if there are no errors. + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - - `Code code` + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - One of `server_error` or `rate_limit_exceeded`. + - `Optional moderation` - - `SERVER_ERROR("server_error")` + Configuration for running moderation on the input and output of this response. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `String model` - - `String message` + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - A human-readable description of the error. + - `Optional policy` - - `Optional metadata` + The policy to apply to moderated response input and output. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional input` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The moderation policy for the response input. - - `JsonValue; object_ "thread.run.step"constant` + - `Mode mode` - The object type, which is always `thread.run.step`. + - `SCORE("score")` - - `THREAD_RUN_STEP("thread.run.step")` + - `BLOCK("block")` - - `String runId` + - `Optional output` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + The moderation policy for the response output. - - `Status status` + - `Mode mode` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `SCORE("score")` - - `IN_PROGRESS("in_progress")` + - `BLOCK("block")` - - `CANCELLED("cancelled")` + - `Optional multiAgent` - - `FAILED("failed")` + Configuration for server-hosted multi-agent execution. - - `COMPLETED("completed")` + - `boolean enabled` - - `EXPIRED("expired")` + Whether to enable server-hosted multi-agent execution for this response. - - `StepDetails stepDetails` + - `Optional maxConcurrentSubagents` - The details of the run step. + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. - - `class MessageCreationStepDetails:` + - `Optional parallelToolCalls` - Details of the message creation by the run step. + Whether to allow the model to run tool calls in parallel. - - `MessageCreation messageCreation` + - `Optional previousResponseId` - - `String messageId` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The ID of the message that was created by this run step. + - `Optional prompt` - - `JsonValue; type "message_creation"constant` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - Always `message_creation`. + - `Optional promptCacheKey` - - `MESSAGE_CREATION("message_creation")` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `class ToolCallsStepDetails:` + - `Optional promptCacheOptions` - Details of the tool call. + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. - - `List toolCalls` + - `Optional mode` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - - `JsonValue; type "tool_calls"constant` + - `IMPLICIT("implicit")` - Always `tool_calls`. + - `EXPLICIT("explicit")` - - `TOOL_CALLS("tool_calls")` + - `Optional ttl` - - `String threadId` + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `_30M("30m")` - - `Type type` + - `Optional promptCacheRetention` - The type of run step, which can be either `message_creation` or `tool_calls`. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `MESSAGE_CREATION("message_creation")` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `TOOL_CALLS("tool_calls")` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `Optional usage` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `IN_MEMORY("in_memory")` - - `long completionTokens` + - `_24H("24h")` - Number of completion tokens used over the course of the run step. + - `Optional reasoning` - - `long promptTokens` + **gpt-5 and o-series models only** - Number of prompt tokens used over the course of the run step. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `long totalTokens` + - `Optional context` - Total number of tokens used (prompt + completion). + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `JsonValue; event "thread.run.step.created"constant` + - `AUTO("auto")` - - `THREAD_RUN_STEP_CREATED("thread.run.step.created")` + - `CURRENT_TURN("current_turn")` - - `ThreadRunStepInProgress` + - `ALL_TURNS("all_turns")` - - `RunStep data` + - `Optional effort` - Represents a step in execution of a run. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `JsonValue; event "thread.run.step.in_progress"constant` + - `NONE("none")` - - `THREAD_RUN_STEP_IN_PROGRESS("thread.run.step.in_progress")` + - `MINIMAL("minimal")` - - `ThreadRunStepDelta` + - `LOW("low")` - - `RunStepDeltaEvent data` + - `MEDIUM("medium")` - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `HIGH("high")` - - `String id` + - `XHIGH("xhigh")` - The identifier of the run step, which can be referenced in API endpoints. + - `MAX("max")` - - `JsonValue delta` + - `Optional generateSummary` - - `JsonValue; object_ "thread.run.step.delta"constant` + **Deprecated:** use `summary` instead. - The object type, which is always `thread.run.step.delta`. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` + - `AUTO("auto")` - - `JsonValue; event "thread.run.step.delta"constant` + - `CONCISE("concise")` - - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` + - `DETAILED("detailed")` - - `ThreadRunStepCompleted` + - `Optional mode` - - `RunStep data` + Controls the reasoning execution mode for the request. - Represents a step in execution of a run. + When returned on a response, this is the effective execution mode. - - `JsonValue; event "thread.run.step.completed"constant` + - `STANDARD("standard")` - - `THREAD_RUN_STEP_COMPLETED("thread.run.step.completed")` + - `PRO("pro")` - - `ThreadRunStepFailed` + - `Optional summary` - - `RunStep data` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - Represents a step in execution of a run. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `JsonValue; event "thread.run.step.failed"constant` + - `AUTO("auto")` - - `THREAD_RUN_STEP_FAILED("thread.run.step.failed")` + - `CONCISE("concise")` - - `ThreadRunStepCancelled` + - `DETAILED("detailed")` - - `RunStep data` + - `Optional safetyIdentifier` - Represents a step in execution of a run. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `JsonValue; event "thread.run.step.cancelled"constant` + - `Optional serviceTier` - - `THREAD_RUN_STEP_CANCELLED("thread.run.step.cancelled")` + Specifies the processing type used for serving the request. - - `ThreadRunStepExpired` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `RunStep data` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - Represents a step in execution of a run. + - `AUTO("auto")` - - `JsonValue; event "thread.run.step.expired"constant` + - `DEFAULT("default")` - - `THREAD_RUN_STEP_EXPIRED("thread.run.step.expired")` + - `FLEX("flex")` - - `ThreadMessageCreated` + - `SCALE("scale")` - - `Message data` + - `PRIORITY("priority")` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `Optional store` - - `String id` + Whether to store the generated model response for later retrieval via + API. - The identifier, which can be referenced in API endpoints. + - `Optional streamOptions` - - `Optional assistantId` + Options for streaming responses. Only set this when you set `stream: true`. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `Optional includeObfuscation` - - `Optional> attachments` + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. - A list of files attached to the message, and the tools they were added to. + - `Optional temperature` - - `Optional fileId` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The ID of the file to attach to the message. + - `Optional text` - - `Optional> tools` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The tools to add this file to. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `class CodeInterpreterTool:` + - `Optional toolChoice` - - `JsonValue; type "code_interpreter"constant` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The type of tool being defined: `code_interpreter` + - `enum BetaToolChoiceOptions:` - - `CODE_INTERPRETER("code_interpreter")` + Controls which (if any) tool is called by the model. - - `JsonValue;` + `none` means the model will not call any tool and instead generates a message. - - `JsonValue; type "file_search"constant` + `auto` means the model can pick between generating a message or calling one or + more tools. - The type of tool being defined: `file_search` + `required` means the model must call one or more tools. - - `FILE_SEARCH("file_search")` + - `NONE("none")` - - `Optional completedAt` + - `AUTO("auto")` - The Unix timestamp (in seconds) for when the message was completed. + - `REQUIRED("required")` - - `List content` + - `class BetaToolChoiceAllowed:` - The content of the message in array of text and/or images. + Constrains the tools available to the model to a pre-defined set. - - `long createdAt` + - `Mode mode` - The Unix timestamp (in seconds) for when the message was created. + Constrains the tools available to the model to a pre-defined set. - - `Optional incompleteAt` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + `required` requires the model to call one or more of the allowed tools. - - `Optional incompleteDetails` + - `AUTO("auto")` - On an incomplete message, details about why the message is incomplete. + - `REQUIRED("required")` - - `Reason reason` + - `List tools` - The reason the message is incomplete. + A list of tool definitions that the model should be allowed to call. - - `CONTENT_FILTER("content_filter")` + For the Responses API, the list of tool definitions might look like: - - `MAX_TOKENS("max_tokens")` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `RUN_CANCELLED("run_cancelled")` + - `JsonValue; type "allowed_tools"constant` - - `RUN_EXPIRED("run_expired")` + Allowed tool configuration type. Always `allowed_tools`. - - `RUN_FAILED("run_failed")` + - `ALLOWED_TOOLS("allowed_tools")` - - `Optional metadata` + - `class BetaToolChoiceTypes:` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Type type` - - `JsonValue; object_ "thread.message"constant` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The object type, which is always `thread.message`. + Allowed values are: - - `THREAD_MESSAGE("thread.message")` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `Role role` + - `FILE_SEARCH("file_search")` - The entity that produced the message. One of `user` or `assistant`. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `USER("user")` + - `COMPUTER("computer")` - - `ASSISTANT("assistant")` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `Optional runId` + - `COMPUTER_USE("computer_use")` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `Status status` + - `IMAGE_GENERATION("image_generation")` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `CODE_INTERPRETER("code_interpreter")` - - `IN_PROGRESS("in_progress")` + - `class BetaToolChoiceFunction:` - - `INCOMPLETE("incomplete")` + Use this option to force the model to call a specific function. - - `COMPLETED("completed")` + - `String name` - - `String threadId` + The name of the function to call. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `JsonValue; type "function"constant` - - `JsonValue; event "thread.message.created"constant` + For function calling, the type is always `function`. - - `THREAD_MESSAGE_CREATED("thread.message.created")` + - `FUNCTION("function")` - - `ThreadMessageInProgress` + - `class BetaToolChoiceMcp:` - - `Message data` + Use this option to force the model to call a specific tool on a remote MCP server. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `String serverLabel` - - `JsonValue; event "thread.message.in_progress"constant` + The label of the MCP server to use. - - `THREAD_MESSAGE_IN_PROGRESS("thread.message.in_progress")` + - `JsonValue; type "mcp"constant` - - `ThreadMessageDelta` + For MCP tools, the type is always `mcp`. - - `MessageDeltaEvent data` + - `MCP("mcp")` - Represents a message delta i.e. any changed fields on a message during streaming. + - `Optional name` - - `String id` + The name of the tool to call on the server. - The identifier of the message, which can be referenced in API endpoints. + - `class BetaToolChoiceCustom:` - - `MessageDelta delta` + Use this option to force the model to call a specific custom tool. - The delta containing the fields that have changed on the Message. + - `String name` - - `Optional> content` + The name of the custom tool to call. - The content of the message in array of text and/or images. + - `JsonValue; type "custom"constant` - - `Optional role` + For custom tool calling, the type is always `custom`. - The entity that produced the message. One of `user` or `assistant`. + - `CUSTOM("custom")` - - `USER("user")` + - `JsonValue;` - - `ASSISTANT("assistant")` + - `JsonValue; type "programmatic_tool_calling"constant` - - `JsonValue; object_ "thread.message.delta"constant` + The tool to call. Always `programmatic_tool_calling`. - The object type, which is always `thread.message.delta`. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `THREAD_MESSAGE_DELTA("thread.message.delta")` + - `class BetaToolChoiceApplyPatch:` - - `JsonValue; event "thread.message.delta"constant` + Forces the model to call the apply_patch tool when executing a tool call. - - `THREAD_MESSAGE_DELTA("thread.message.delta")` + - `JsonValue; type "apply_patch"constant` - - `ThreadMessageCompleted` + The tool to call. Always `apply_patch`. - - `Message data` + - `APPLY_PATCH("apply_patch")` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `class BetaToolChoiceShell:` - - `JsonValue; event "thread.message.completed"constant` + Forces the model to call the shell tool when a tool call is required. - - `THREAD_MESSAGE_COMPLETED("thread.message.completed")` + - `JsonValue; type "shell"constant` - - `ThreadMessageIncomplete` + The tool to call. Always `shell`. - - `Message data` + - `SHELL("shell")` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `Optional> tools` - - `JsonValue; event "thread.message.incomplete"constant` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `THREAD_MESSAGE_INCOMPLETE("thread.message.incomplete")` + We support the following categories of tools: - - `ErrorEvent` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `ErrorObject data` + - `class BetaFunctionTool:` - - `Optional code` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String message` + - `class BetaFileSearchTool:` - - `Optional param` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `String type` + - `class BetaComputerTool:` - - `JsonValue; event "error"constant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `ERROR("error")` + - `class BetaComputerUsePreviewTool:` -### Assistant Tool + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -- `class AssistantTool:` + - `class BetaWebSearchTool:` -### Code Interpreter Tool + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -- `class CodeInterpreterTool:` + - `Mcp` - - `JsonValue; type "code_interpreter"constant` + - `CodeInterpreter` - The type of tool being defined: `code_interpreter` + - `JsonValue;` - - `CODE_INTERPRETER("code_interpreter")` + - `ImageGeneration` -### File Search Tool + - `JsonValue;` -- `class FileSearchTool:` + - `class BetaFunctionShellTool:` - - `JsonValue; type "file_search"constant` + A tool that allows the model to execute shell commands. - The type of tool being defined: `file_search` + - `class BetaCustomTool:` - - `FILE_SEARCH("file_search")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional fileSearch` + - `class BetaNamespaceTool:` - Overrides for the file search tool. + Groups function/custom tools under a shared namespace. - - `Optional maxNumResults` + - `class BetaToolSearchTool:` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + Hosted or BYOT tool search configuration for deferred tools. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `class BetaWebSearchPreviewTool:` - - `Optional rankingOptions` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `class BetaApplyPatchTool:` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Allows the assistant to create, delete, or update files using unified diffs. - - `double scoreThreshold` + - `Optional topLogprobs` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `Optional ranker` + - `Optional topP` - The ranker to use for the file search. If not specified will use the `auto` ranker. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `Optional truncation` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - `AUTO("auto")` - - `DEFAULT_2024_08_21("default_2024_08_21")` + - `DISABLED("disabled")` -### Function Tool + - `Optional user` -- `class FunctionTool:` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `FunctionDefinition function` +### Returns - - `String name` +- `class BetaResponse:` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `String id` - - `Optional description` + Unique identifier for this Response. - A description of what the function does, used by the model to choose when and how to call the function. + - `double createdAt` - - `Optional parameters` + Unix timestamp (in seconds) of when this Response was created. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `Optional error` - Omitting `parameters` defines a function with an empty parameter list. + An error object returned when the model fails to generate a Response. - - `Optional strict` + - `Code code` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + The error code for the response. - - `JsonValue; type "function"constant` + - `SERVER_ERROR("server_error")` - The type of tool being defined: `function` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `FUNCTION("function")` + - `INVALID_PROMPT("invalid_prompt")` -### Message Stream Event + - `BIO_POLICY("bio_policy")` -- `class MessageStreamEvent: A class that can be one of several variants.union` + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `INVALID_IMAGE("invalid_image")` - - `ThreadMessageCreated` + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - - `Message data` + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `INVALID_IMAGE_URL("invalid_image_url")` - - `String id` + - `IMAGE_TOO_LARGE("image_too_large")` - The identifier, which can be referenced in API endpoints. + - `IMAGE_TOO_SMALL("image_too_small")` - - `Optional assistantId` + - `IMAGE_PARSE_ERROR("image_parse_error")` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - - `Optional> attachments` + - `INVALID_IMAGE_MODE("invalid_image_mode")` - A list of files attached to the message, and the tools they were added to. + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `Optional fileId` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - The ID of the file to attach to the message. + - `EMPTY_IMAGE_FILE("empty_image_file")` - - `Optional> tools` + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - The tools to add this file to. + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - - `class CodeInterpreterTool:` + - `String message` - - `JsonValue; type "code_interpreter"constant` + A human-readable description of the error. - The type of tool being defined: `code_interpreter` + - `Optional incompleteDetails` - - `CODE_INTERPRETER("code_interpreter")` + Details about why the response is incomplete. - - `JsonValue;` + - `Optional reason` - - `JsonValue; type "file_search"constant` + The reason why the response is incomplete. - The type of tool being defined: `file_search` + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - - `FILE_SEARCH("file_search")` + - `CONTENT_FILTER("content_filter")` - - `Optional completedAt` + - `Optional instructions` - The Unix timestamp (in seconds) for when the message was completed. + A system (or developer) message inserted into the model's context. - - `List content` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - The content of the message in array of text and/or images. + - `String` - - `long createdAt` + - `List` - The Unix timestamp (in seconds) for when the message was created. + - `class BetaEasyInputMessage:` - - `Optional incompleteAt` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `Content content` - - `Optional incompleteDetails` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - On an incomplete message, details about why the message is incomplete. + - `String` - - `Reason reason` + - `List` - The reason the message is incomplete. + - `class BetaResponseInputText:` - - `CONTENT_FILTER("content_filter")` + A text input to the model. - - `MAX_TOKENS("max_tokens")` + - `String text` - - `RUN_CANCELLED("run_cancelled")` + The text input to the model. - - `RUN_EXPIRED("run_expired")` + - `JsonValue; type "input_text"constant` - - `RUN_FAILED("run_failed")` + The type of the input item. Always `input_text`. - - `Optional metadata` + - `INPUT_TEXT("input_text")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional promptCacheBreakpoint` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; object_ "thread.message"constant` + - `JsonValue; mode "explicit"constant` - The object type, which is always `thread.message`. + The breakpoint mode. Always `explicit`. - - `THREAD_MESSAGE("thread.message")` + - `EXPLICIT("explicit")` - - `Role role` + - `class BetaResponseInputImage:` - The entity that produced the message. One of `user` or `assistant`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `USER("user")` + - `Detail detail` - - `ASSISTANT("assistant")` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Optional runId` + - `LOW("low")` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `HIGH("high")` - - `Status status` + - `AUTO("auto")` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `ORIGINAL("original")` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "input_image"constant` - - `INCOMPLETE("incomplete")` + The type of the input item. Always `input_image`. - - `COMPLETED("completed")` + - `INPUT_IMAGE("input_image")` - - `String threadId` + - `Optional fileId` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The ID of the file to be sent to the model. - - `JsonValue; event "thread.message.created"constant` + - `Optional imageUrl` - - `THREAD_MESSAGE_CREATED("thread.message.created")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ThreadMessageInProgress` + - `Optional promptCacheBreakpoint` - - `Message data` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `JsonValue; mode "explicit"constant` - - `JsonValue; event "thread.message.in_progress"constant` + The breakpoint mode. Always `explicit`. - - `THREAD_MESSAGE_IN_PROGRESS("thread.message.in_progress")` + - `EXPLICIT("explicit")` - - `ThreadMessageDelta` + - `class BetaResponseInputFile:` - - `MessageDeltaEvent data` + A file input to the model. - Represents a message delta i.e. any changed fields on a message during streaming. + - `JsonValue; type "input_file"constant` - - `String id` + The type of the input item. Always `input_file`. - The identifier of the message, which can be referenced in API endpoints. + - `INPUT_FILE("input_file")` - - `MessageDelta delta` + - `Optional detail` - The delta containing the fields that have changed on the Message. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `Optional> content` + - `AUTO("auto")` - The content of the message in array of text and/or images. + - `LOW("low")` - - `Optional role` + - `HIGH("high")` - The entity that produced the message. One of `user` or `assistant`. + - `Optional fileData` - - `USER("user")` + The content of the file to be sent to the model. - - `ASSISTANT("assistant")` + - `Optional fileId` - - `JsonValue; object_ "thread.message.delta"constant` + The ID of the file to be sent to the model. - The object type, which is always `thread.message.delta`. + - `Optional fileUrl` - - `THREAD_MESSAGE_DELTA("thread.message.delta")` + The URL of the file to be sent to the model. - - `JsonValue; event "thread.message.delta"constant` + - `Optional filename` - - `THREAD_MESSAGE_DELTA("thread.message.delta")` + The name of the file to be sent to the model. - - `ThreadMessageCompleted` + - `Optional promptCacheBreakpoint` - - `Message data` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `JsonValue; mode "explicit"constant` - - `JsonValue; event "thread.message.completed"constant` + The breakpoint mode. Always `explicit`. - - `THREAD_MESSAGE_COMPLETED("thread.message.completed")` + - `EXPLICIT("explicit")` - - `ThreadMessageIncomplete` + - `Role role` - - `Message data` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `USER("user")` - - `JsonValue; event "thread.message.incomplete"constant` + - `ASSISTANT("assistant")` - - `THREAD_MESSAGE_INCOMPLETE("thread.message.incomplete")` + - `SYSTEM("system")` -### Run Step Stream Event + - `DEVELOPER("developer")` -- `class RunStepStreamEvent: A class that can be one of several variants.union` + - `Optional phase` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + 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. - - `ThreadRunStepCreated` + - `COMMENTARY("commentary")` - - `RunStep data` + - `FINAL_ANSWER("final_answer")` - Represents a step in execution of a run. + - `Optional type` - - `String id` + The type of the message input. Always `message`. - The identifier of the run step, which can be referenced in API endpoints. + - `MESSAGE("message")` - - `String assistantId` + - `Message` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `List content` - - `Optional cancelledAt` + A list of one or many input items to the model, containing different content + types. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `class BetaResponseInputText:` - - `Optional completedAt` + A text input to the model. - The Unix timestamp (in seconds) for when the run step completed. + - `class BetaResponseInputImage:` - - `long createdAt` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The Unix timestamp (in seconds) for when the run step was created. + - `class BetaResponseInputFile:` - - `Optional expiredAt` + A file input to the model. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `Role role` - - `Optional failedAt` + The role of the message input. One of `user`, `system`, or `developer`. - The Unix timestamp (in seconds) for when the run step failed. + - `USER("user")` - - `Optional lastError` + - `SYSTEM("system")` - The last error associated with this run step. Will be `null` if there are no errors. + - `DEVELOPER("developer")` - - `Code code` + - `Optional agent` - One of `server_error` or `rate_limit_exceeded`. + The agent that produced this item. - - `SERVER_ERROR("server_error")` + - `String agentName` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The canonical name of the agent that produced this item. - - `String message` + - `Optional status` - A human-readable description of the error. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional metadata` + - `IN_PROGRESS("in_progress")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `COMPLETED("completed")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `INCOMPLETE("incomplete")` - - `JsonValue; object_ "thread.run.step"constant` + - `Optional type` - The object type, which is always `thread.run.step`. + The type of the message input. Always set to `message`. - - `THREAD_RUN_STEP("thread.run.step")` + - `MESSAGE("message")` - - `String runId` + - `class BetaResponseOutputMessage:` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + An output message from the model. - - `Status status` + - `String id` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + The unique ID of the output message. - - `IN_PROGRESS("in_progress")` + - `List content` - - `CANCELLED("cancelled")` + The content of the output message. - - `FAILED("failed")` + - `class BetaResponseOutputText:` - - `COMPLETED("completed")` + A text output from the model. - - `EXPIRED("expired")` + - `List annotations` - - `StepDetails stepDetails` + The annotations of the text output. - The details of the run step. + - `class FileCitation:` - - `class MessageCreationStepDetails:` + A citation to a file. - Details of the message creation by the run step. + - `String fileId` - - `MessageCreation messageCreation` + The ID of the file. - - `String messageId` + - `String filename` - The ID of the message that was created by this run step. + The filename of the file cited. - - `JsonValue; type "message_creation"constant` + - `long index` - Always `message_creation`. + The index of the file in the list of files. - - `MESSAGE_CREATION("message_creation")` + - `JsonValue; type "file_citation"constant` - - `class ToolCallsStepDetails:` + The type of the file citation. Always `file_citation`. - Details of the tool call. + - `FILE_CITATION("file_citation")` - - `List toolCalls` + - `class UrlCitation:` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + A citation for a web resource used to generate a model response. - - `JsonValue; type "tool_calls"constant` + - `long endIndex` - Always `tool_calls`. + The index of the last character of the URL citation in the message. - - `TOOL_CALLS("tool_calls")` + - `long startIndex` - - `String threadId` + The index of the first character of the URL citation in the message. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `String title` - - `Type type` + The title of the web resource. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `JsonValue; type "url_citation"constant` - - `MESSAGE_CREATION("message_creation")` + The type of the URL citation. Always `url_citation`. - - `TOOL_CALLS("tool_calls")` + - `URL_CITATION("url_citation")` - - `Optional usage` + - `String url` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The URL of the web resource. - - `long completionTokens` + - `class ContainerFileCitation:` - Number of completion tokens used over the course of the run step. + A citation for a container file used to generate a model response. - - `long promptTokens` + - `String containerId` - Number of prompt tokens used over the course of the run step. + The ID of the container file. - - `long totalTokens` + - `long endIndex` - Total number of tokens used (prompt + completion). + The index of the last character of the container file citation in the message. - - `JsonValue; event "thread.run.step.created"constant` + - `String fileId` - - `THREAD_RUN_STEP_CREATED("thread.run.step.created")` + The ID of the file. - - `ThreadRunStepInProgress` + - `String filename` - - `RunStep data` + The filename of the container file cited. - Represents a step in execution of a run. + - `long startIndex` - - `JsonValue; event "thread.run.step.in_progress"constant` + The index of the first character of the container file citation in the message. - - `THREAD_RUN_STEP_IN_PROGRESS("thread.run.step.in_progress")` + - `JsonValue; type "container_file_citation"constant` - - `ThreadRunStepDelta` + The type of the container file citation. Always `container_file_citation`. - - `RunStepDeltaEvent data` + - `CONTAINER_FILE_CITATION("container_file_citation")` - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `class FilePath:` - - `String id` + A path to a file. - The identifier of the run step, which can be referenced in API endpoints. + - `String fileId` - - `JsonValue delta` + The ID of the file. - - `JsonValue; object_ "thread.run.step.delta"constant` + - `long index` - The object type, which is always `thread.run.step.delta`. + The index of the file in the list of files. - - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` + - `JsonValue; type "file_path"constant` - - `JsonValue; event "thread.run.step.delta"constant` + The type of the file path. Always `file_path`. - - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` + - `FILE_PATH("file_path")` - - `ThreadRunStepCompleted` + - `String text` - - `RunStep data` + The text output from the model. - Represents a step in execution of a run. + - `JsonValue; type "output_text"constant` - - `JsonValue; event "thread.run.step.completed"constant` + The type of the output text. Always `output_text`. - - `THREAD_RUN_STEP_COMPLETED("thread.run.step.completed")` + - `OUTPUT_TEXT("output_text")` - - `ThreadRunStepFailed` + - `Optional> logprobs` - - `RunStep data` + - `String token` - Represents a step in execution of a run. + - `List bytes` - - `JsonValue; event "thread.run.step.failed"constant` + - `double logprob` - - `THREAD_RUN_STEP_FAILED("thread.run.step.failed")` + - `List topLogprobs` - - `ThreadRunStepCancelled` + - `String token` - - `RunStep data` + - `List bytes` - Represents a step in execution of a run. + - `double logprob` - - `JsonValue; event "thread.run.step.cancelled"constant` + - `class BetaResponseOutputRefusal:` - - `THREAD_RUN_STEP_CANCELLED("thread.run.step.cancelled")` + A refusal from the model. - - `ThreadRunStepExpired` + - `String refusal` - - `RunStep data` + The refusal explanation from the model. - Represents a step in execution of a run. + - `JsonValue; type "refusal"constant` - - `JsonValue; event "thread.run.step.expired"constant` + The type of the refusal. Always `refusal`. - - `THREAD_RUN_STEP_EXPIRED("thread.run.step.expired")` + - `REFUSAL("refusal")` -### Run Stream Event + - `JsonValue; role "assistant"constant` -- `class RunStreamEvent: A class that can be one of several variants.union` + The role of the output message. Always `assistant`. - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + - `ASSISTANT("assistant")` - - `ThreadRunCreated` + - `Status status` - - `Run data` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `IN_PROGRESS("in_progress")` - - `String id` + - `COMPLETED("completed")` - The identifier, which can be referenced in API endpoints. + - `INCOMPLETE("incomplete")` - - `String assistantId` + - `JsonValue; type "message"constant` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The type of the output message. Always `message`. - - `Optional cancelledAt` + - `MESSAGE("message")` - The Unix timestamp (in seconds) for when the run was cancelled. + - `Optional agent` - - `Optional completedAt` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was completed. + - `String agentName` - - `long createdAt` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was created. + - `Optional phase` - - `Optional expiresAt` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The Unix timestamp (in seconds) for when the run will expire. + - `COMMENTARY("commentary")` - - `Optional failedAt` + - `FINAL_ANSWER("final_answer")` - The Unix timestamp (in seconds) for when the run failed. + - `class BetaResponseFileSearchToolCall:` - - `Optional incompleteDetails` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `String id` - - `Optional reason` + The unique ID of the file search tool call. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `List queries` - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + The queries used to search for files. - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `Status status` - - `String instructions` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `IN_PROGRESS("in_progress")` - - `Optional lastError` + - `SEARCHING("searching")` - The last error associated with this run. Will be `null` if there are no errors. + - `COMPLETED("completed")` - - `Code code` + - `INCOMPLETE("incomplete")` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `FAILED("failed")` - - `SERVER_ERROR("server_error")` + - `JsonValue; type "file_search_call"constant` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The type of the file search tool call. Always `file_search_call`. - - `INVALID_PROMPT("invalid_prompt")` + - `FILE_SEARCH_CALL("file_search_call")` - - `String message` + - `Optional agent` - A human-readable description of the error. + The agent that produced this item. - - `Optional maxCompletionTokens` + - `String agentName` - The maximum number of completion tokens specified to have been used over the course of the run. + The canonical name of the agent that produced this item. - - `Optional maxPromptTokens` + - `Optional> results` - The maximum number of prompt tokens specified to have been used over the course of the run. + The results of the file search tool call. - - `Optional metadata` + - `Optional 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. + 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 model` + - `String` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `double` - - `JsonValue; object_ "thread.run"constant` + - `boolean` - The object type, which is always `thread.run`. + - `Optional fileId` - - `THREAD_RUN("thread.run")` + The unique ID of the file. - - `boolean parallelToolCalls` + - `Optional filename` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The name of the file. - - `Optional requiredAction` + - `Optional score` - Details on the action required to continue the run. Will be `null` if no action is required. + The relevance score of the file - a value between 0 and 1. - - `SubmitToolOutputs submitToolOutputs` + - `Optional text` - Details on the tool outputs needed for this run to continue. + The text that was retrieved from the file. - - `List toolCalls` + - `class BetaResponseComputerToolCall:` - A list of the relevant tool calls. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `String id` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - - `Function function` + The unique ID of the computer call. - The function definition. + - `String callId` - - `String arguments` + An identifier used when responding to the tool call with output. - The arguments that the model expects you to pass to the function. + - `List pendingSafetyChecks` - - `String name` + The pending safety checks for the computer call. - The name of the function. + - `String id` - - `JsonValue; type "function"constant` + The ID of the pending safety check. - The type of tool call the output is required for. For now, this is always `function`. + - `Optional code` - - `FUNCTION("function")` + The type of the pending safety check. - - `JsonValue; type "submit_tool_outputs"constant` + - `Optional message` - For now, this is always `submit_tool_outputs`. + Details about the pending safety check. - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + - `Status status` - - `Optional responseFormat` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `IN_PROGRESS("in_progress")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `COMPLETED("completed")` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `INCOMPLETE("incomplete")` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `Type type` - - `JsonValue;` + The type of the computer call. Always `computer_call`. - - `AUTO("auto")` + - `COMPUTER_CALL("computer_call")` - - `class ResponseFormatText:` + - `Optional action` - Default response format. Used to generate text responses. + A click action. - - `JsonValue; type "text"constant` + - `Click` - The type of response format being defined. Always `text`. + - `Button button` - - `TEXT("text")` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `class ResponseFormatJsonObject:` + - `LEFT("left")` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `RIGHT("right")` - - `JsonValue; type "json_object"constant` + - `WHEEL("wheel")` - The type of response format being defined. Always `json_object`. + - `BACK("back")` - - `JSON_OBJECT("json_object")` + - `FORWARD("forward")` - - `class ResponseFormatJsonSchema:` + - `JsonValue; type "click"constant` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Specifies the event type. For a click action, this property is always `click`. - - `JsonSchema jsonSchema` + - `CLICK("click")` - Structured Outputs configuration options, including a JSON Schema. + - `long x` - - `String name` + The x-coordinate where the click occurred. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `long y` - - `Optional description` + The y-coordinate where the click occurred. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Optional> keys` - - `Optional schema` + The keys being held while clicking. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `DoubleClick` - - `Optional strict` + - `Optional> keys` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The keys being held while double-clicking. - - `JsonValue; type "json_schema"constant` + - `JsonValue; type "double_click"constant` - The type of response format being defined. Always `json_schema`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `JSON_SCHEMA("json_schema")` + - `DOUBLE_CLICK("double_click")` - - `Optional startedAt` + - `long x` - The Unix timestamp (in seconds) for when the run was started. + The x-coordinate where the double click occurred. - - `JsonValue status` + - `long y` - - `String threadId` + The y-coordinate where the double click occurred. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `Drag` - - `Optional toolChoice` + - `List path` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `Auto` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `NONE("none")` + - `long x` - - `AUTO("auto")` + The x-coordinate. - - `REQUIRED("required")` + - `long y` - - `class AssistantToolChoice:` + The y-coordinate. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `JsonValue; type "drag"constant` - - `Type type` + Specifies the event type. For a drag action, this property is always set to `drag`. - The type of the tool. If type is `function`, the function name must be set + - `DRAG("drag")` - - `FUNCTION("function")` + - `Optional> keys` - - `CODE_INTERPRETER("code_interpreter")` + The keys being held while dragging the mouse. - - `FILE_SEARCH("file_search")` + - `Keypress` - - `Optional function` + - `List keys` - - `String name` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The name of the function to call. + - `JsonValue; type "keypress"constant` - - `List tools` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `KEYPRESS("keypress")` - - `Optional truncationStrategy` + - `Move` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `JsonValue; type "move"constant` - - `Type type` + Specifies the event type. For a move action, this property is always set to `move`. - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `MOVE("move")` - - `AUTO("auto")` + - `long x` - - `LAST_MESSAGES("last_messages")` + The x-coordinate to move to. - - `Optional lastMessages` + - `long y` - The number of most recent messages from the thread when constructing the context for the run. + The y-coordinate to move to. - - `Optional usage` + - `Optional> keys` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The keys being held while moving the mouse. - - `long completionTokens` + - `JsonValue;` - Number of completion tokens used over the course of the run. + - `JsonValue; type "screenshot"constant` - - `long promptTokens` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Number of prompt tokens used over the course of the run. + - `SCREENSHOT("screenshot")` - - `long totalTokens` + - `Scroll` - Total number of tokens used (prompt + completion). + - `long scrollX` - - `Optional temperature` + The horizontal scroll distance. - The sampling temperature used for this run. If not set, defaults to 1. + - `long scrollY` - - `Optional topP` + The vertical scroll distance. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `JsonValue; type "scroll"constant` - - `JsonValue; event "thread.run.created"constant` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `THREAD_RUN_CREATED("thread.run.created")` + - `SCROLL("scroll")` - - `ThreadRunQueued` + - `long x` - - `Run data` + The x-coordinate where the scroll occurred. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `long y` - - `JsonValue; event "thread.run.queued"constant` + The y-coordinate where the scroll occurred. - - `THREAD_RUN_QUEUED("thread.run.queued")` + - `Optional> keys` - - `ThreadRunInProgress` + The keys being held while scrolling. - - `Run data` + - `Type` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `String text` - - `JsonValue; event "thread.run.in_progress"constant` + The text to type. - - `THREAD_RUN_IN_PROGRESS("thread.run.in_progress")` + - `JsonValue; type "type"constant` - - `ThreadRunRequiresAction` + Specifies the event type. For a type action, this property is always set to `type`. - - `Run data` + - `TYPE("type")` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `JsonValue;` - - `JsonValue; event "thread.run.requires_action"constant` + - `JsonValue; type "wait"constant` - - `THREAD_RUN_REQUIRES_ACTION("thread.run.requires_action")` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `ThreadRunCompleted` + - `WAIT("wait")` - - `Run data` + - `Optional> actions` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `JsonValue; event "thread.run.completed"constant` + - `Click` - - `THREAD_RUN_COMPLETED("thread.run.completed")` + - `DoubleClick` - - `ThreadRunIncomplete` + - `Drag` - - `Run data` + - `Keypress` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `Move` - - `JsonValue; event "thread.run.incomplete"constant` + - `JsonValue;` - - `THREAD_RUN_INCOMPLETE("thread.run.incomplete")` + - `Scroll` - - `ThreadRunFailed` + - `Type` - - `Run data` + - `JsonValue;` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `Optional agent` - - `JsonValue; event "thread.run.failed"constant` + The agent that produced this item. - - `THREAD_RUN_FAILED("thread.run.failed")` + - `String agentName` - - `ThreadRunCancelling` + The canonical name of the agent that produced this item. - - `Run data` + - `ComputerCallOutput` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `String callId` - - `JsonValue; event "thread.run.cancelling"constant` + The ID of the computer tool call that produced the output. - - `THREAD_RUN_CANCELLING("thread.run.cancelling")` + - `BetaResponseComputerToolCallOutputScreenshot output` - - `ThreadRunCancelled` + A computer screenshot image used with the computer use tool. - - `Run data` + - `JsonValue; type "computer_screenshot"constant` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `JsonValue; event "thread.run.cancelled"constant` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `THREAD_RUN_CANCELLED("thread.run.cancelled")` + - `Optional fileId` - - `ThreadRunExpired` + The identifier of an uploaded file that contains the screenshot. - - `Run data` + - `Optional imageUrl` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The URL of the screenshot image. - - `JsonValue; event "thread.run.expired"constant` + - `JsonValue; type "computer_call_output"constant` - - `THREAD_RUN_EXPIRED("thread.run.expired")` + The type of the computer tool call output. Always `computer_call_output`. -### Thread Stream Event + - `COMPUTER_CALL_OUTPUT("computer_call_output")` -- `class ThreadStreamEvent:` + - `Optional id` - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + The ID of the computer tool call output. - - `Thread data` + - `Optional> acknowledgedSafetyChecks` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The safety checks reported by the API that have been acknowledged by the developer. - `String id` - The identifier, which can be referenced in API endpoints. + The ID of the pending safety check. - - `long createdAt` + - `Optional code` - The Unix timestamp (in seconds) for when the thread was created. + The type of the pending safety check. - - `Optional metadata` + - `Optional message` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Details about the pending safety check. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Optional agent` - - `JsonValue; object_ "thread"constant` + The agent that produced this item. - The object type, which is always `thread`. + - `String agentName` - - `THREAD("thread")` + The canonical name of the agent that produced this item. - - `Optional toolResources` + - `Optional status` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `Optional codeInterpreter` + - `IN_PROGRESS("in_progress")` - - `Optional> fileIds` + - `COMPLETED("completed")` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `INCOMPLETE("incomplete")` - - `Optional fileSearch` + - `class BetaResponseFunctionWebSearch:` - - `Optional> vectorStoreIds` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `String id` - - `JsonValue; event "thread.created"constant` + The unique ID of the web search tool call. - - `THREAD_CREATED("thread.created")` + - `Action action` - - `Optional enabled` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - Whether to enable input audio transcription. + - `class Search:` -# Threads + Action type "search" - Performs a web search query. -## Create thread + - `JsonValue; type "search"constant` -`Thread beta().threads().create(ThreadCreateParamsparams = ThreadCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The action type. -**post** `/threads` + - `SEARCH("search")` -Create thread + - `Optional> queries` -### Parameters + The search queries. -- `ThreadCreateParams params` + - `Optional query` - - `Optional> messages` + The search query. - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + - `Optional> sources` - - `Content content` + The sources used in the search. - The text contents of the message. + - `JsonValue; type "url"constant` - - `String` + The type of source. Always `url`. - - `List` + - `URL("url")` - - `class ImageFileContentBlock:` + - `String url` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The URL of the source. - - `ImageFile imageFile` + - `class OpenPage:` - - `String fileId` + Action type "open_page" - Opens a specific URL from search results. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `JsonValue; type "open_page"constant` - - `Optional detail` + The action type. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `OPEN_PAGE("open_page")` - - `AUTO("auto")` + - `Optional url` - - `LOW("low")` + The URL opened by the model. - - `HIGH("high")` + - `class FindInPage:` - - `JsonValue; type "image_file"constant` + Action type "find_in_page": Searches for a pattern within a loaded page. - Always `image_file`. + - `String pattern` - - `IMAGE_FILE("image_file")` + The pattern or text to search for within the page. - - `class ImageUrlContentBlock:` + - `JsonValue; type "find_in_page"constant` - References an image URL in the content of a message. + The action type. - - `ImageUrl imageUrl` + - `FIND_IN_PAGE("find_in_page")` - `String url` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The URL of the page searched for the pattern. - - `Optional detail` + - `Status status` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The status of the web search tool call. - - `AUTO("auto")` + - `IN_PROGRESS("in_progress")` - - `LOW("low")` + - `SEARCHING("searching")` - - `HIGH("high")` + - `COMPLETED("completed")` - - `JsonValue; type "image_url"constant` + - `FAILED("failed")` - The type of the content part. + - `JsonValue; type "web_search_call"constant` - - `IMAGE_URL("image_url")` + The type of the web search tool call. Always `web_search_call`. - - `class TextContentBlockParam:` + - `WEB_SEARCH_CALL("web_search_call")` - The text content that is part of a message. + - `Optional agent` - - `String text` + The agent that produced this item. - Text content to be sent to the model + - `String agentName` - - `JsonValue; type "text"constant` + The canonical name of the agent that produced this item. - Always `text`. + - `class BetaResponseFunctionToolCall:` - - `TEXT("text")` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `Role role` + - `String arguments` - The role of the entity that is creating the message. Allowed values include: + A JSON string of the arguments to pass to the function. - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `String callId` - - `USER("user")` + The unique ID of the function tool call generated by the model. - - `ASSISTANT("assistant")` + - `String name` - - `Optional> attachments` + The name of the function to run. - A list of files attached to the message, and the tools they should be added to. + - `JsonValue; type "function_call"constant` - - `Optional fileId` + The type of the function tool call. Always `function_call`. - The ID of the file to attach to the message. + - `FUNCTION_CALL("function_call")` - - `Optional> tools` + - `Optional id` - The tools to add this file to. + The unique ID of the function tool call. - - `class CodeInterpreterTool:` + - `Optional agent` - - `JsonValue; type "code_interpreter"constant` + The agent that produced this item. - The type of tool being defined: `code_interpreter` + - `String agentName` - - `CODE_INTERPRETER("code_interpreter")` + The canonical name of the agent that produced this item. - - `JsonValue;` + - `Optional caller` - - `JsonValue; type "file_search"constant` + The execution context that produced this tool call. - The type of tool being defined: `file_search` + - `JsonValue;` - - `FILE_SEARCH("file_search")` + - `JsonValue; type "direct"constant` - - `Optional metadata` + - `DIRECT("direct")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `class Program:` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `String callerId` - - `Optional metadata` + The call ID of the program item that produced this tool call. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `JsonValue; type "program"constant` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `PROGRAM("program")` - - `Optional toolResources` + - `Optional namespace` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The namespace of the function to run. - - `Optional codeInterpreter` + - `Optional status` - - `Optional> fileIds` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `IN_PROGRESS("in_progress")` - - `Optional fileSearch` + - `COMPLETED("completed")` - - `Optional> vectorStoreIds` + - `INCOMPLETE("incomplete")` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `FunctionCallOutput` - - `Optional> vectorStores` + - `String callId` - A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. + The unique ID of the function tool call generated by the model. - - `Optional chunkingStrategy` + - `Output output` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + Text, image, or file output of the function tool call. - - `JsonValue;` + - `String` - - `JsonValue; type "auto"constant` + - `List` - Always `auto`. + - `class BetaResponseInputTextContent:` - - `AUTO("auto")` + A text input to the model. - - `class Static:` + - `String text` - - `InnerStatic static_` + The text input to the model. - - `long chunkOverlapTokens` + - `JsonValue; type "input_text"constant` - The number of tokens that overlap between chunks. The default value is `400`. + The type of the input item. Always `input_text`. - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `INPUT_TEXT("input_text")` - - `long maxChunkSizeTokens` + - `Optional promptCacheBreakpoint` - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "static"constant` + - `JsonValue; mode "explicit"constant` - Always `static`. + The breakpoint mode. Always `explicit`. - - `STATIC("static")` + - `EXPLICIT("explicit")` - - `Optional> fileIds` + - `class BetaResponseInputImageContent:` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `Optional metadata` + - `JsonValue; type "input_image"constant` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The type of the input item. Always `input_image`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `INPUT_IMAGE("input_image")` -### Returns + - `Optional detail` -- `class Thread:` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `LOW("low")` - - `String id` + - `HIGH("high")` - The identifier, which can be referenced in API endpoints. + - `AUTO("auto")` - - `long createdAt` + - `ORIGINAL("original")` - The Unix timestamp (in seconds) for when the thread was created. + - `Optional fileId` - - `Optional metadata` + The ID of the file to be sent to the model. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional imageUrl` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `JsonValue; object_ "thread"constant` + - `Optional promptCacheBreakpoint` - The object type, which is always `thread`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `THREAD("thread")` + - `JsonValue; mode "explicit"constant` - - `Optional toolResources` + The breakpoint mode. Always `explicit`. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `EXPLICIT("explicit")` - - `Optional codeInterpreter` + - `class BetaResponseInputFileContent:` - - `Optional> fileIds` + A file input to the model. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `JsonValue; type "input_file"constant` - - `Optional fileSearch` + The type of the input item. Always `input_file`. - - `Optional> vectorStoreIds` + - `INPUT_FILE("input_file")` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `Optional detail` -### Example + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. -```java -package com.openai.example; + - `AUTO("auto")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.Thread; -import com.openai.models.beta.threads.ThreadCreateParams; + - `LOW("low")` -public final class Main { - private Main() {} + - `HIGH("high")` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Optional fileData` - Thread thread = client.beta().threads().create(); - } -} -``` + The base64-encoded data of the file to be sent to the model. -#### Response + - `Optional fileId` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + The ID of the file to be sent to the model. -## Create thread and run + - `Optional fileUrl` -`Run beta().threads().createAndRun(ThreadCreateAndRunParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + The URL of the file to be sent to the model. -**post** `/threads/runs` + - `Optional filename` -Create thread and run + The name of the file to be sent to the model. -### Parameters + - `Optional promptCacheBreakpoint` -- `ThreadCreateAndRunParams params` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String assistantId` + - `JsonValue; mode "explicit"constant` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + The breakpoint mode. Always `explicit`. - - `Optional instructions` + - `EXPLICIT("explicit")` - Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. + - `JsonValue; type "function_call_output"constant` - - `Optional maxCompletionTokens` + The type of the function tool call output. Always `function_call_output`. - The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `Optional maxPromptTokens` + - `Optional id` - The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `Optional metadata` + - `Optional agent` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The agent that produced this item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `String agentName` - - `Optional model` + The canonical name of the agent that produced this item. - The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + - `Optional caller` - - `Optional parallelToolCalls` + The execution context that produced this tool call. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `JsonValue;` - - `Optional responseFormat` + - `JsonValue; type "direct"constant` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The caller type. Always `direct`. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `DIRECT("direct")` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class Program:` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `String callerId` - - `Optional temperature` + The call ID of the program item that produced this tool call. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `JsonValue; type "program"constant` - - `Optional thread` + The caller type. Always `program`. - Options to create a new thread. If no thread is provided when running a - request, an empty thread will be created. + - `PROGRAM("program")` - - `Optional> messages` + - `Optional status` - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `Content content` + - `IN_PROGRESS("in_progress")` - The text contents of the message. + - `COMPLETED("completed")` - - `String` + - `INCOMPLETE("incomplete")` - - `List` + - `AgentMessage` - - `class ImageFileContentBlock:` + - `String author` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The sending agent identity. - - `ImageFile imageFile` + - `List content` - - `String fileId` + Plaintext, image, or encrypted content sent between agents. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `class BetaResponseInputTextContent:` - - `Optional detail` + A text input to the model. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `class BetaResponseInputImageContent:` - - `AUTO("auto")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `LOW("low")` + - `class EncryptedContent:` - - `HIGH("high")` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `JsonValue; type "image_file"constant` + - `String encryptedContent` - Always `image_file`. + Opaque encrypted content. - - `IMAGE_FILE("image_file")` + - `JsonValue; type "encrypted_content"constant` - - `class ImageUrlContentBlock:` + The type of the input item. Always `encrypted_content`. - References an image URL in the content of a message. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `ImageUrl imageUrl` + - `String recipient` - - `String url` + The destination agent identity. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `JsonValue; type "agent_message"constant` - - `Optional detail` + The item type. Always `agent_message`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `AGENT_MESSAGE("agent_message")` - - `AUTO("auto")` + - `Optional id` - - `LOW("low")` + The unique ID of this agent message item. - - `HIGH("high")` + - `Optional agent` - - `JsonValue; type "image_url"constant` + The agent that produced this item. - The type of the content part. + - `String agentName` - - `IMAGE_URL("image_url")` + The canonical name of the agent that produced this item. - - `class TextContentBlockParam:` + - `MultiAgentCall` - The text content that is part of a message. + - `Action action` - - `String text` + The multi-agent action that was executed. - Text content to be sent to the model + - `SPAWN_AGENT("spawn_agent")` - - `JsonValue; type "text"constant` + - `INTERRUPT_AGENT("interrupt_agent")` - Always `text`. + - `LIST_AGENTS("list_agents")` - - `TEXT("text")` + - `SEND_MESSAGE("send_message")` - - `Role role` + - `FOLLOWUP_TASK("followup_task")` - The role of the entity that is creating the message. Allowed values include: + - `WAIT_AGENT("wait_agent")` - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `String arguments` - - `USER("user")` + The action arguments as a JSON string. - - `ASSISTANT("assistant")` + - `String callId` - - `Optional> attachments` + The unique ID linking this call to its output. - A list of files attached to the message, and the tools they should be added to. + - `JsonValue; type "multi_agent_call"constant` - - `Optional fileId` + The item type. Always `multi_agent_call`. - The ID of the file to attach to the message. + - `MULTI_AGENT_CALL("multi_agent_call")` - - `Optional> tools` + - `Optional id` - The tools to add this file to. + The unique ID of this multi-agent call. - - `class CodeInterpreterTool:` + - `Optional agent` - - `JsonValue; type "code_interpreter"constant` + The agent that produced this item. - The type of tool being defined: `code_interpreter` + - `String agentName` - - `CODE_INTERPRETER("code_interpreter")` + The canonical name of the agent that produced this item. - - `JsonValue;` + - `MultiAgentCallOutput` - - `JsonValue; type "file_search"constant` + - `Action action` - The type of tool being defined: `file_search` + The multi-agent action that produced this result. - - `FILE_SEARCH("file_search")` + - `SPAWN_AGENT("spawn_agent")` - - `Optional metadata` + - `INTERRUPT_AGENT("interrupt_agent")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `LIST_AGENTS("list_agents")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `SEND_MESSAGE("send_message")` - - `Optional metadata` + - `FOLLOWUP_TASK("followup_task")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `WAIT_AGENT("wait_agent")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `String callId` - - `Optional toolResources` + The unique ID of the multi-agent call. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `List output` - - `Optional codeInterpreter` + Text output returned by the multi-agent action. - - `Optional> fileIds` + - `String text` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + The text content. - - `Optional fileSearch` + - `JsonValue; type "output_text"constant` - - `Optional> vectorStoreIds` + The content type. Always `output_text`. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `OUTPUT_TEXT("output_text")` - - `Optional> vectorStores` + - `Optional annotations` - A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. + Citations associated with the text content. - - `Optional chunkingStrategy` + - `List` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + - `String fileId` - - `JsonValue;` + The ID of the file. - - `JsonValue; type "auto"constant` + - `String filename` - Always `auto`. + The filename of the file cited. - - `AUTO("auto")` + - `long index` - - `class Static:` + The index of the file in the list of files. - - `InnerStatic static_` + - `JsonValue; type "file_citation"constant` - - `long chunkOverlapTokens` + The citation type. Always `file_citation`. - The number of tokens that overlap between chunks. The default value is `400`. + - `FILE_CITATION("file_citation")` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + - `List` - - `long maxChunkSizeTokens` + - `long endIndex` - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + The index of the last character of the citation in the message. - - `JsonValue; type "static"constant` + - `long startIndex` - Always `static`. + The index of the first character of the citation in the message. - - `STATIC("static")` + - `String title` - - `Optional> fileIds` + The title of the cited resource. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. + - `JsonValue; type "url_citation"constant` - - `Optional metadata` + The citation type. Always `url_citation`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `URL_CITATION("url_citation")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `String url` - - `Optional toolChoice` + The URL of the cited resource. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `List` - - `Optional toolResources` + - `String containerId` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The ID of the container. - - `Optional codeInterpreter` + - `long endIndex` - - `Optional> fileIds` + The index of the last character of the citation in the message. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `String fileId` - - `Optional fileSearch` + The ID of the container file. - - `Optional> vectorStoreIds` + - `String filename` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + The filename of the container file cited. - - `Optional> tools` + - `long startIndex` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + The index of the first character of the citation in the message. - - `Optional topP` + - `JsonValue; type "container_file_citation"constant` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + The citation type. Always `container_file_citation`. - We generally recommend altering this or temperature but not both. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `Optional truncationStrategy` + - `JsonValue; type "multi_agent_call_output"constant` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The item type. Always `multi_agent_call_output`. - - `Type type` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `Optional id` - - `AUTO("auto")` + The unique ID of this multi-agent call output. - - `LAST_MESSAGES("last_messages")` + - `Optional agent` - - `Optional lastMessages` + The agent that produced this item. - The number of most recent messages from the thread when constructing the context for the run. + - `String agentName` -### Returns + The canonical name of the agent that produced this item. -- `class Run:` + - `ToolSearchCall` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `JsonValue arguments` - - `String id` + The arguments supplied to the tool search call. - The identifier, which can be referenced in API endpoints. + - `JsonValue; type "tool_search_call"constant` - - `String assistantId` + The item type. Always `tool_search_call`. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `TOOL_SEARCH_CALL("tool_search_call")` - - `Optional cancelledAt` + - `Optional id` - The Unix timestamp (in seconds) for when the run was cancelled. + The unique ID of this tool search call. - - `Optional completedAt` + - `Optional agent` - The Unix timestamp (in seconds) for when the run was completed. + The agent that produced this item. - - `long createdAt` + - `String agentName` - The Unix timestamp (in seconds) for when the run was created. + The canonical name of the agent that produced this item. - - `Optional expiresAt` + - `Optional callId` - The Unix timestamp (in seconds) for when the run will expire. + The unique ID of the tool search call generated by the model. - - `Optional failedAt` + - `Optional execution` - The Unix timestamp (in seconds) for when the run failed. + Whether tool search was executed by the server or by the client. - - `Optional incompleteDetails` + - `SERVER("server")` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `CLIENT("client")` - - `Optional reason` + - `Optional status` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The status of the tool search call. - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + - `IN_PROGRESS("in_progress")` - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `COMPLETED("completed")` - - `String instructions` + - `INCOMPLETE("incomplete")` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class BetaResponseToolSearchOutputItemParam:` - - `Optional lastError` + - `List tools` - The last error associated with this run. Will be `null` if there are no errors. + The loaded tool definitions returned by the tool search output. - - `Code code` + - `class BetaFunctionTool:` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `SERVER_ERROR("server_error")` + - `String name` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The name of the function to call. - - `INVALID_PROMPT("invalid_prompt")` + - `Optional parameters` - - `String message` + A JSON schema object describing the parameters of the function. - A human-readable description of the error. + - `Optional strict` - - `Optional maxCompletionTokens` + Whether strict parameter validation is enforced for this function tool. - The maximum number of completion tokens specified to have been used over the course of the run. + - `JsonValue; type "function"constant` - - `Optional maxPromptTokens` + The type of the function tool. Always `function`. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `FUNCTION("function")` - - `Optional metadata` + - `Optional> allowedCallers` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The tool invocation context(s). - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `DIRECT("direct")` - - `String model` + - `PROGRAMMATIC("programmatic")` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `Optional deferLoading` - - `JsonValue; object_ "thread.run"constant` + Whether this function is deferred and loaded via tool search. - The object type, which is always `thread.run`. + - `Optional description` - - `THREAD_RUN("thread.run")` + A description of the function. Used by the model to determine whether or not to call the function. - - `boolean parallelToolCalls` + - `Optional outputSchema` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `Optional requiredAction` + - `class BetaFileSearchTool:` - Details on the action required to continue the run. Will be `null` if no action is required. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `SubmitToolOutputs submitToolOutputs` + - `JsonValue; type "file_search"constant` - Details on the tool outputs needed for this run to continue. + The type of the file search tool. Always `file_search`. - - `List toolCalls` + - `FILE_SEARCH("file_search")` - A list of the relevant tool calls. + - `List vectorStoreIds` - - `String id` + The IDs of the vector stores to search. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `Optional filters` - - `Function function` + A filter to apply. - The function definition. + - `class ComparisonFilter:` - - `String arguments` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The arguments that the model expects you to pass to the function. + - `String key` - - `String name` + The key to compare against the value. - The name of the function. + - `Type type` - - `JsonValue; type "function"constant` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The type of tool call the output is required for. For now, this is always `function`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `FUNCTION("function")` + - `EQ("eq")` - - `JsonValue; type "submit_tool_outputs"constant` + - `NE("ne")` - For now, this is always `submit_tool_outputs`. + - `GT("gt")` - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + - `GTE("gte")` - - `Optional responseFormat` + - `LT("lt")` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `LTE("lte")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `IN("in")` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `NIN("nin")` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `Value value` - - `JsonValue;` + The value to compare against the attribute key; supports string, number, or boolean types. - - `AUTO("auto")` + - `String` - - `class ResponseFormatText:` + - `double` - Default response format. Used to generate text responses. + - `boolean` - - `JsonValue; type "text"constant` + - `List` - The type of response format being defined. Always `text`. + - `String` - - `TEXT("text")` + - `double` - - `class ResponseFormatJsonObject:` + - `class CompoundFilter:` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Combine multiple filters using `and` or `or`. - - `JsonValue; type "json_object"constant` + - `List filters` - The type of response format being defined. Always `json_object`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `JSON_OBJECT("json_object")` + - `class ComparisonFilter:` - - `class ResponseFormatJsonSchema:` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `String key` - - `JsonSchema jsonSchema` + The key to compare against the value. - Structured Outputs configuration options, including a JSON Schema. + - `Type type` - - `String name` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Optional description` + - `EQ("eq")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `NE("ne")` - - `Optional schema` + - `GT("gt")` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `GTE("gte")` - - `Optional strict` + - `LT("lt")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `LTE("lte")` - - `JsonValue; type "json_schema"constant` + - `IN("in")` - The type of response format being defined. Always `json_schema`. + - `NIN("nin")` - - `JSON_SCHEMA("json_schema")` + - `Value value` - - `Optional startedAt` + The value to compare against the attribute key; supports string, number, or boolean types. - The Unix timestamp (in seconds) for when the run was started. + - `String` - - `JsonValue status` + - `double` - - `String threadId` + - `boolean` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `List` - - `Optional toolChoice` + - `String` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `double` - - `Auto` + - `JsonValue` - - `NONE("none")` + - `Type type` - - `AUTO("auto")` + Type of operation: `and` or `or`. - - `REQUIRED("required")` + - `AND("and")` - - `class AssistantToolChoice:` + - `OR("or")` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `Optional maxNumResults` - - `Type type` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The type of the tool. If type is `function`, the function name must be set + - `Optional rankingOptions` - - `FUNCTION("function")` + Ranking options for search. - - `CODE_INTERPRETER("code_interpreter")` + - `Optional hybridSearch` - - `FILE_SEARCH("file_search")` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `Optional function` + - `double embeddingWeight` - - `String name` + The weight of the embedding in the reciprocal ranking fusion. - The name of the function to call. + - `double textWeight` - - `List tools` + The weight of the text in the reciprocal ranking fusion. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `Optional ranker` - - `Optional truncationStrategy` + The ranker to use for the file search. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `AUTO("auto")` - - `Type type` + - `DEFAULT_2024_11_15("default-2024-11-15")` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `Optional scoreThreshold` - - `AUTO("auto")` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `LAST_MESSAGES("last_messages")` + - `class BetaComputerTool:` - - `Optional lastMessages` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The number of most recent messages from the thread when constructing the context for the run. + - `JsonValue; type "computer"constant` - - `Optional usage` + The type of the computer tool. Always `computer`. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `COMPUTER("computer")` - - `long completionTokens` + - `class BetaComputerUsePreviewTool:` - Number of completion tokens used over the course of the run. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `long promptTokens` + - `long displayHeight` - Number of prompt tokens used over the course of the run. + The height of the computer display. - - `long totalTokens` + - `long displayWidth` - Total number of tokens used (prompt + completion). + The width of the computer display. - - `Optional temperature` + - `Environment environment` - The sampling temperature used for this run. If not set, defaults to 1. + The type of computer environment to control. - - `Optional topP` + - `WINDOWS("windows")` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `MAC("mac")` -### Example + - `LINUX("linux")` -```java -package com.openai.example; + - `UBUNTU("ubuntu")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.ThreadCreateAndRunParams; -import com.openai.models.beta.threads.runs.Run; + - `BROWSER("browser")` -public final class Main { - private Main() {} + - `JsonValue; type "computer_use_preview"constant` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The type of the computer use tool. Always `computer_use_preview`. - ThreadCreateAndRunParams params = ThreadCreateAndRunParams.builder() - .assistantId("assistant_id") - .build(); - Run run = client.beta().threads().createAndRun(params); - } -} -``` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` -#### Response + - `class BetaWebSearchTool:` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -## Retrieve thread + - `Type type` -`Thread beta().threads().retrieve(ThreadRetrieveParamsparams = ThreadRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. -**get** `/threads/{thread_id}` + - `WEB_SEARCH("web_search")` -Retrieve thread + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` -### Parameters + - `Optional filters` -- `ThreadRetrieveParams params` + Filters for the search. - - `Optional threadId` + - `Optional> allowedDomains` -### Returns + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. -- `class Thread:` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `Optional searchContextSize` - - `String id` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The identifier, which can be referenced in API endpoints. + - `LOW("low")` - - `long createdAt` + - `MEDIUM("medium")` - The Unix timestamp (in seconds) for when the thread was created. + - `HIGH("high")` - - `Optional metadata` + - `Optional userLocation` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The approximate location of the user. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Optional city` - - `JsonValue; object_ "thread"constant` + Free text input for the city of the user, e.g. `San Francisco`. - The object type, which is always `thread`. + - `Optional country` - - `THREAD("thread")` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `Optional toolResources` + - `Optional region` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + Free text input for the region of the user, e.g. `California`. - - `Optional codeInterpreter` + - `Optional timezone` - - `Optional> fileIds` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `Optional type` - - `Optional fileSearch` + The type of location approximation. Always `approximate`. - - `Optional> vectorStoreIds` + - `APPROXIMATE("approximate")` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `Mcp` -### Example + - `String serverLabel` -```java -package com.openai.example; + A label for this MCP server, used to identify it in tool calls. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.Thread; -import com.openai.models.beta.threads.ThreadRetrieveParams; + - `JsonValue; type "mcp"constant` -public final class Main { - private Main() {} + The type of the MCP tool. Always `mcp`. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `MCP("mcp")` - Thread thread = client.beta().threads().retrieve("thread_id"); - } -} -``` + - `Optional> allowedCallers` -#### Response + The tool invocation context(s). -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `DIRECT("direct")` -## Modify thread + - `PROGRAMMATIC("programmatic")` -`Thread beta().threads().update(ThreadUpdateParamsparams = ThreadUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `Optional allowedTools` -**post** `/threads/{thread_id}` + List of allowed tool names or a filter object. -Modify thread + - `List` -### Parameters + - `class McpToolFilter:` -- `ThreadUpdateParams params` + A filter object to specify which tools are allowed. - - `Optional threadId` + - `Optional readOnly` - - `Optional metadata` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional> toolNames` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + List of allowed tool names. - - `Optional toolResources` + - `Optional authorization` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + 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 codeInterpreter` + - `Optional connectorId` - - `Optional> fileIds` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + Currently supported `connector_id` values are: - - `Optional fileSearch` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `Optional> vectorStoreIds` + - `CONNECTOR_DROPBOX("connector_dropbox")` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `CONNECTOR_GMAIL("connector_gmail")` -### Returns + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` -- `class Thread:` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `String id` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - The identifier, which can be referenced in API endpoints. + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `long createdAt` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - The Unix timestamp (in seconds) for when the thread was created. + - `Optional deferLoading` - - `Optional metadata` + Whether this MCP tool is deferred and discovered via tool search. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional headers` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `JsonValue; object_ "thread"constant` + - `Optional requireApproval` - The object type, which is always `thread`. + Specify which of the MCP server's tools require approval. - - `THREAD("thread")` + - `class McpToolApprovalFilter:` - - `Optional toolResources` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `Optional always` - - `Optional codeInterpreter` + A filter object to specify which tools are allowed. - - `Optional> fileIds` + - `Optional readOnly` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `Optional fileSearch` + - `Optional> toolNames` - - `Optional> vectorStoreIds` + List of allowed tool names. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `Optional never` -### Example + A filter object to specify which tools are allowed. -```java -package com.openai.example; + - `Optional readOnly` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.Thread; -import com.openai.models.beta.threads.ThreadUpdateParams; + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. -public final class Main { - private Main() {} + - `Optional> toolNames` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + List of allowed tool names. - Thread thread = client.beta().threads().update("thread_id"); - } -} -``` + - `enum McpToolApprovalSetting:` -#### Response + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `ALWAYS("always")` -## Delete thread + - `NEVER("never")` -`ThreadDeleted beta().threads().delete(ThreadDeleteParamsparams = ThreadDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `Optional serverDescription` -**delete** `/threads/{thread_id}` + Optional description of the MCP server, used to provide more context. -Delete thread + - `Optional serverUrl` -### Parameters + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. -- `ThreadDeleteParams params` + - `Optional tunnelId` - - `Optional threadId` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. -### Returns + - `CodeInterpreter` -- `class ThreadDeleted:` + - `Container container` - - `String id` + 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. - - `boolean deleted` + - `String` - - `JsonValue; object_ "thread.deleted"constant` + - `class CodeInterpreterToolAuto:` - - `THREAD_DELETED("thread.deleted")` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. -### Example + - `JsonValue; type "auto"constant` -```java -package com.openai.example; + Always `auto`. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.ThreadDeleteParams; -import com.openai.models.beta.threads.ThreadDeleted; + - `AUTO("auto")` -public final class Main { - private Main() {} + - `Optional> fileIds` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + An optional list of uploaded files to make available to your code. - ThreadDeleted threadDeleted = client.beta().threads().delete("thread_id"); - } -} -``` + - `Optional memoryLimit` -#### Response + The memory limit for the code interpreter container. -```json -{ - "id": "id", - "deleted": true, - "object": "thread.deleted" -} -``` + - `_1G("1g")` -## Domain Types + - `_4G("4g")` -### Assistant Response Format Option + - `_16G("16g")` -- `class AssistantResponseFormatOption: A class that can be one of several variants.union` + - `_64G("64g")` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `Optional networkPolicy` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + Network access policy for the container. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `class BetaContainerNetworkPolicyDisabled:` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `JsonValue; type "disabled"constant` - - `JsonValue;` + Disable outbound network access. Always `disabled`. - - `AUTO("auto")` + - `DISABLED("disabled")` - - `class ResponseFormatText:` + - `class BetaContainerNetworkPolicyAllowlist:` - Default response format. Used to generate text responses. + - `List allowedDomains` - - `JsonValue; type "text"constant` + A list of allowed domains when type is `allowlist`. - The type of response format being defined. Always `text`. + - `JsonValue; type "allowlist"constant` - - `TEXT("text")` + Allow outbound network access only to specified domains. Always `allowlist`. - - `class ResponseFormatJsonObject:` + - `ALLOWLIST("allowlist")` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `Optional> domainSecrets` - - `JsonValue; type "json_object"constant` + Optional domain-scoped secrets for allowlisted domains. - The type of response format being defined. Always `json_object`. + - `String domain` - - `JSON_OBJECT("json_object")` + The domain associated with the secret. - - `class ResponseFormatJsonSchema:` + - `String name` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The name of the secret to inject for the domain. - - `JsonSchema jsonSchema` + - `String value` - Structured Outputs configuration options, including a JSON Schema. + The secret value to inject for the domain. - - `String name` + - `JsonValue; type "code_interpreter"constant` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The type of the code interpreter tool. Always `code_interpreter`. - - `Optional description` + - `CODE_INTERPRETER("code_interpreter")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Optional> allowedCallers` - - `Optional schema` + The tool invocation context(s). - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `DIRECT("direct")` - - `Optional strict` + - `PROGRAMMATIC("programmatic")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `JsonValue;` - - `JsonValue; type "json_schema"constant` + - `JsonValue; type "programmatic_tool_calling"constant` - The type of response format being defined. Always `json_schema`. + The type of the tool. Always `programmatic_tool_calling`. - - `JSON_SCHEMA("json_schema")` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` -### Assistant Tool Choice + - `ImageGeneration` -- `class AssistantToolChoice:` + - `JsonValue; type "image_generation"constant` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The type of the image generation tool. Always `image_generation`. - - `Type type` + - `IMAGE_GENERATION("image_generation")` - The type of the tool. If type is `function`, the function name must be set + - `Optional action` - - `FUNCTION("function")` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `CODE_INTERPRETER("code_interpreter")` + - `GENERATE("generate")` - - `FILE_SEARCH("file_search")` + - `EDIT("edit")` - - `Optional function` + - `AUTO("auto")` - - `String name` + - `Optional background` - The name of the function to call. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. -### Assistant Tool Choice Function + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. -- `class AssistantToolChoiceFunction:` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `String name` + - `TRANSPARENT("transparent")` - The name of the function to call. + - `OPAQUE("opaque")` -### Assistant Tool Choice Option + - `AUTO("auto")` -- `class AssistantToolChoiceOption: A class that can be one of several variants.union` + - `Optional inputFidelity` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + 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`. - - `Auto` + - `HIGH("high")` - - `NONE("none")` + - `LOW("low")` - - `AUTO("auto")` + - `Optional inputImageMask` - - `REQUIRED("required")` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `class AssistantToolChoice:` + - `Optional fileId` - Specifies a tool the model should use. Use to force the model to call a specific tool. + File ID for the mask image. - - `Type type` + - `Optional imageUrl` - The type of the tool. If type is `function`, the function name must be set + Base64-encoded mask image. - - `FUNCTION("function")` + - `Optional model` - - `CODE_INTERPRETER("code_interpreter")` + The image generation model to use. Default: `gpt-image-1`. - - `FILE_SEARCH("file_search")` + - `GPT_IMAGE_1("gpt-image-1")` - - `Optional function` + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `String name` + - `GPT_IMAGE_2("gpt-image-2")` - The name of the function to call. + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` -### Thread + - `GPT_IMAGE_1_5("gpt-image-1.5")` -- `class Thread:` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `Optional moderation` - - `String id` + Moderation level for the generated image. Default: `auto`. - The identifier, which can be referenced in API endpoints. + - `AUTO("auto")` - - `long createdAt` + - `LOW("low")` - The Unix timestamp (in seconds) for when the thread was created. + - `Optional outputCompression` - - `Optional metadata` + Compression level for the output image. Default: 100. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional outputFormat` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `JsonValue; object_ "thread"constant` + - `PNG("png")` - The object type, which is always `thread`. + - `WEBP("webp")` - - `THREAD("thread")` + - `JPEG("jpeg")` - - `Optional toolResources` + - `Optional partialImages` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `Optional codeInterpreter` + - `Optional quality` - - `Optional> fileIds` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `LOW("low")` - - `Optional fileSearch` + - `MEDIUM("medium")` - - `Optional> vectorStoreIds` + - `HIGH("high")` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `AUTO("auto")` -### Thread Deleted + - `Optional size` -- `class ThreadDeleted:` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `String id` + - `_1024X1024("1024x1024")` - - `boolean deleted` + - `_1024X1536("1024x1536")` - - `JsonValue; object_ "thread.deleted"constant` + - `_1536X1024("1536x1024")` - - `THREAD_DELETED("thread.deleted")` + - `AUTO("auto")` -# Runs + - `JsonValue;` -## List runs + - `JsonValue; type "local_shell"constant` -`RunListPage beta().threads().runs().list(RunListParamsparams = RunListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The type of the local shell tool. Always `local_shell`. -**get** `/threads/{thread_id}/runs` + - `LOCAL_SHELL("local_shell")` -List runs + - `class BetaFunctionShellTool:` -### Parameters + A tool that allows the model to execute shell commands. -- `RunListParams params` + - `JsonValue; type "shell"constant` - - `Optional threadId` + The type of the shell tool. Always `shell`. - - `Optional after` + - `SHELL("shell")` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `Optional> allowedCallers` - - `Optional before` + The tool invocation context(s). - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `DIRECT("direct")` - - `Optional limit` + - `PROGRAMMATIC("programmatic")` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `Optional environment` - - `Optional order` + - `class BetaContainerAuto:` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `JsonValue; type "container_auto"constant` - - `ASC("asc")` + Automatically creates a container for this request - - `DESC("desc")` + - `CONTAINER_AUTO("container_auto")` -### Returns + - `Optional> fileIds` -- `class Run:` + An optional list of uploaded files to make available to your code. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `Optional memoryLimit` - - `String id` + The memory limit for the container. - The identifier, which can be referenced in API endpoints. + - `_1G("1g")` - - `String assistantId` + - `_4G("4g")` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `_16G("16g")` - - `Optional cancelledAt` + - `_64G("64g")` - The Unix timestamp (in seconds) for when the run was cancelled. + - `Optional networkPolicy` - - `Optional completedAt` + Network access policy for the container. - The Unix timestamp (in seconds) for when the run was completed. + - `class BetaContainerNetworkPolicyDisabled:` - - `long createdAt` + - `class BetaContainerNetworkPolicyAllowlist:` - The Unix timestamp (in seconds) for when the run was created. + - `Optional> skills` - - `Optional expiresAt` + An optional list of skills referenced by id or inline data. - The Unix timestamp (in seconds) for when the run will expire. + - `class BetaSkillReference:` - - `Optional failedAt` + - `String skillId` - The Unix timestamp (in seconds) for when the run failed. + The ID of the referenced skill. - - `Optional incompleteDetails` + - `JsonValue; type "skill_reference"constant` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + References a skill created with the /v1/skills endpoint. - - `Optional reason` + - `SKILL_REFERENCE("skill_reference")` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `Optional version` - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `class BetaInlineSkill:` - - `String instructions` + - `String description` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The description of the skill. - - `Optional lastError` + - `String name` - The last error associated with this run. Will be `null` if there are no errors. + The name of the skill. - - `Code code` + - `BetaInlineSkillSource source` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + Inline skill payload - - `SERVER_ERROR("server_error")` + - `String data` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + Base64-encoded skill zip bundle. - - `INVALID_PROMPT("invalid_prompt")` + - `JsonValue; mediaType "application/zip"constant` - - `String message` + The media type of the inline skill payload. Must be `application/zip`. - A human-readable description of the error. + - `APPLICATION_ZIP("application/zip")` - - `Optional maxCompletionTokens` + - `JsonValue; type "base64"constant` - The maximum number of completion tokens specified to have been used over the course of the run. + The type of the inline skill source. Must be `base64`. - - `Optional maxPromptTokens` + - `BASE64("base64")` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `JsonValue; type "inline"constant` - - `Optional metadata` + Defines an inline skill for this request. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `INLINE("inline")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class BetaLocalEnvironment:` - - `String model` + - `JsonValue; type "local"constant` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Use a local computer environment. - - `JsonValue; object_ "thread.run"constant` + - `LOCAL("local")` - The object type, which is always `thread.run`. + - `Optional> skills` - - `THREAD_RUN("thread.run")` + An optional list of skills. - - `boolean parallelToolCalls` + - `String description` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The description of the skill. - - `Optional requiredAction` + - `String name` - Details on the action required to continue the run. Will be `null` if no action is required. + The name of the skill. - - `SubmitToolOutputs submitToolOutputs` + - `String path` - Details on the tool outputs needed for this run to continue. + The path to the directory containing the skill. - - `List toolCalls` + - `class BetaContainerReference:` - A list of the relevant tool calls. + - `String containerId` - - `String id` + The ID of the referenced container. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `JsonValue; type "container_reference"constant` - - `Function function` + References a container created with the /v1/containers endpoint - The function definition. + - `CONTAINER_REFERENCE("container_reference")` - - `String arguments` + - `class BetaCustomTool:` - The arguments that the model expects you to pass to the function. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `String name` - The name of the function. - - - `JsonValue; type "function"constant` + The name of the custom tool, used to identify it in tool calls. - The type of tool call the output is required for. For now, this is always `function`. + - `JsonValue; type "custom"constant` - - `FUNCTION("function")` + The type of the custom tool. Always `custom`. - - `JsonValue; type "submit_tool_outputs"constant` + - `CUSTOM("custom")` - For now, this is always `submit_tool_outputs`. + - `Optional> allowedCallers` - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + The tool invocation context(s). - - `Optional responseFormat` + - `DIRECT("direct")` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `PROGRAMMATIC("programmatic")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional deferLoading` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Whether this tool should be deferred and discovered via tool search. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `Optional description` - - `JsonValue;` + Optional description of the custom tool, used to provide more context. - - `AUTO("auto")` + - `Optional format` - - `class ResponseFormatText:` + The input format for the custom tool. Default is unconstrained text. - Default response format. Used to generate text responses. + - `JsonValue;` - `JsonValue; type "text"constant` - The type of response format being defined. Always `text`. + Unconstrained text format. Always `text`. - `TEXT("text")` - - `class ResponseFormatJsonObject:` + - `class Grammar:` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + A grammar defined by the user. - - `JsonValue; type "json_object"constant` + - `String definition` - The type of response format being defined. Always `json_object`. + The grammar definition. - - `JSON_OBJECT("json_object")` + - `Syntax syntax` - - `class ResponseFormatJsonSchema:` + The syntax of the grammar definition. One of `lark` or `regex`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `LARK("lark")` - - `JsonSchema jsonSchema` + - `REGEX("regex")` - Structured Outputs configuration options, including a JSON Schema. + - `JsonValue; type "grammar"constant` - - `String name` + Grammar format. Always `grammar`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `GRAMMAR("grammar")` - - `Optional description` + - `class BetaNamespaceTool:` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Groups function/custom tools under a shared namespace. - - `Optional schema` + - `String description` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A description of the namespace shown to the model. - - `Optional strict` + - `String name` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The namespace name used in tool calls (for example, `crm`). - - `JsonValue; type "json_schema"constant` + - `List tools` - The type of response format being defined. Always `json_schema`. + The function/custom tools available inside this namespace. - - `JSON_SCHEMA("json_schema")` + - `class Function:` - - `Optional startedAt` + - `String name` - The Unix timestamp (in seconds) for when the run was started. + - `JsonValue; type "function"constant` - - `JsonValue status` + - `FUNCTION("function")` - - `String threadId` + - `Optional> allowedCallers` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The tool invocation context(s). - - `Optional toolChoice` + - `DIRECT("direct")` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `PROGRAMMATIC("programmatic")` - - `Auto` + - `Optional deferLoading` - - `NONE("none")` + Whether this function should be deferred and discovered via tool search. - - `AUTO("auto")` + - `Optional description` - - `REQUIRED("required")` + - `Optional outputSchema` - - `class AssistantToolChoice:` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `Optional parameters` - - `Type type` + - `Optional strict` - The type of the tool. If type is `function`, the function name must be set + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `FUNCTION("function")` + - `class BetaCustomTool:` - - `CODE_INTERPRETER("code_interpreter")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `FILE_SEARCH("file_search")` + - `JsonValue; type "namespace"constant` - - `Optional function` + The type of the tool. Always `namespace`. - - `String name` + - `NAMESPACE("namespace")` - The name of the function to call. + - `class BetaToolSearchTool:` - - `List tools` + Hosted or BYOT tool search configuration for deferred tools. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `JsonValue; type "tool_search"constant` - - `Optional truncationStrategy` + The type of the tool. Always `tool_search`. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `TOOL_SEARCH("tool_search")` - - `Type type` + - `Optional description` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + Description shown to the model for a client-executed tool search tool. - - `AUTO("auto")` + - `Optional execution` - - `LAST_MESSAGES("last_messages")` + Whether tool search is executed by the server or by the client. - - `Optional lastMessages` + - `SERVER("server")` - The number of most recent messages from the thread when constructing the context for the run. + - `CLIENT("client")` - - `Optional usage` + - `Optional parameters` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + Parameter schema for a client-executed tool search tool. - - `long completionTokens` + - `class BetaWebSearchPreviewTool:` - Number of completion tokens used over the course of the run. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `long promptTokens` + - `Type type` - Number of prompt tokens used over the course of the run. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `long totalTokens` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - Total number of tokens used (prompt + completion). + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `Optional temperature` + - `Optional> searchContentTypes` - The sampling temperature used for this run. If not set, defaults to 1. + - `TEXT("text")` - - `Optional topP` + - `IMAGE("image")` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `Optional searchContextSize` -### Example + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. -```java -package com.openai.example; + - `LOW("low")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.RunListPage; -import com.openai.models.beta.threads.runs.RunListParams; + - `MEDIUM("medium")` -public final class Main { - private Main() {} + - `HIGH("high")` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Optional userLocation` - RunListPage page = client.beta().threads().runs().list("thread_id"); - } -} -``` + The user's location. -#### Response + - `JsonValue; type "approximate"constant` -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 - } - ], - "first_id": "run_abc123", - "has_more": false, - "last_id": "run_abc456", - "object": "list" -} -``` + The type of location approximation. Always `approximate`. -## Create run + - `APPROXIMATE("approximate")` -`Run beta().threads().runs().create(RunCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `Optional city` -**post** `/threads/{thread_id}/runs` + Free text input for the city of the user, e.g. `San Francisco`. -Create run + - `Optional country` -### Parameters + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. -- `RunCreateParams params` + - `Optional region` - - `Optional threadId` + Free text input for the region of the user, e.g. `California`. - - `Optional> include` + - `Optional timezone` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `class BetaApplyPatchTool:` - - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` + Allows the assistant to create, delete, or update files using unified diffs. - - `String assistantId` + - `JsonValue; type "apply_patch"constant` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + The type of the tool. Always `apply_patch`. - - `Optional additionalInstructions` + - `APPLY_PATCH("apply_patch")` - Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. + - `Optional> allowedCallers` - - `Optional> additionalMessages` + The tool invocation context(s). - Adds additional messages to the thread before creating the run. + - `DIRECT("direct")` - - `Content content` + - `PROGRAMMATIC("programmatic")` - The text contents of the message. + - `JsonValue; type "tool_search_output"constant` - - `String` + The item type. Always `tool_search_output`. - - `List` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `class ImageFileContentBlock:` + - `Optional id` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The unique ID of this tool search output. - - `ImageFile imageFile` + - `Optional agent` - - `String fileId` + The agent that produced this item. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `String agentName` - - `Optional detail` + The canonical name of the agent that produced this item. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `Optional callId` - - `AUTO("auto")` + The unique ID of the tool search call generated by the model. - - `LOW("low")` + - `Optional execution` - - `HIGH("high")` + Whether tool search was executed by the server or by the client. - - `JsonValue; type "image_file"constant` + - `SERVER("server")` - Always `image_file`. + - `CLIENT("client")` - - `IMAGE_FILE("image_file")` + - `Optional status` - - `class ImageUrlContentBlock:` + The status of the tool search output. - References an image URL in the content of a message. + - `IN_PROGRESS("in_progress")` - - `ImageUrl imageUrl` + - `COMPLETED("completed")` - - `String url` + - `INCOMPLETE("incomplete")` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `AdditionalTools` - - `Optional detail` + - `JsonValue; role "developer"constant` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The role that provided the additional tools. Only `developer` is supported. - - `AUTO("auto")` + - `DEVELOPER("developer")` - - `LOW("low")` + - `List tools` - - `HIGH("high")` + A list of additional tools made available at this item. - - `JsonValue; type "image_url"constant` + - `class BetaFunctionTool:` - The type of the content part. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `IMAGE_URL("image_url")` + - `class BetaFileSearchTool:` - - `class TextContentBlockParam:` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The text content that is part of a message. + - `class BetaComputerTool:` - - `String text` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Text content to be sent to the model + - `class BetaComputerUsePreviewTool:` - - `JsonValue; type "text"constant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Always `text`. + - `class BetaWebSearchTool:` - - `TEXT("text")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Role role` + - `Mcp` - The role of the entity that is creating the message. Allowed values include: + - `CodeInterpreter` - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `JsonValue;` - - `USER("user")` + - `ImageGeneration` - - `ASSISTANT("assistant")` + - `JsonValue;` - - `Optional> attachments` + - `class BetaFunctionShellTool:` - A list of files attached to the message, and the tools they should be added to. + A tool that allows the model to execute shell commands. - - `Optional fileId` + - `class BetaCustomTool:` - The ID of the file to attach to the message. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional> tools` + - `class BetaNamespaceTool:` - The tools to add this file to. + Groups function/custom tools under a shared namespace. - - `class CodeInterpreterTool:` + - `class BetaToolSearchTool:` - - `JsonValue; type "code_interpreter"constant` + Hosted or BYOT tool search configuration for deferred tools. - The type of tool being defined: `code_interpreter` + - `class BetaWebSearchPreviewTool:` - - `CODE_INTERPRETER("code_interpreter")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue;` + - `class BetaApplyPatchTool:` - - `JsonValue; type "file_search"constant` + Allows the assistant to create, delete, or update files using unified diffs. - The type of tool being defined: `file_search` + - `JsonValue; type "additional_tools"constant` - - `FILE_SEARCH("file_search")` + The item type. Always `additional_tools`. - - `Optional metadata` + - `ADDITIONAL_TOOLS("additional_tools")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional id` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The unique ID of this additional tools item. - - `Optional instructions` + - `Optional agent` - Overrides the [instructions](https://platform.openai.com/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. + The agent that produced this item. - - `Optional maxCompletionTokens` + - `String agentName` - The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + The canonical name of the agent that produced this item. - - `Optional maxPromptTokens` + - `class BetaResponseReasoningItem:` - The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `Optional metadata` + - `String id` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The unique identifier of the reasoning content. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `List summary` - - `Optional model` + Reasoning summary content. - The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + - `String text` - - `Optional parallelToolCalls` + A summary of the reasoning output from the model so far. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `JsonValue; type "summary_text"constant` - - `Optional reasoningEffort` + The type of the object. Always `summary_text`. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `SUMMARY_TEXT("summary_text")` - - `Optional responseFormat` + - `JsonValue; type "reasoning"constant` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The type of the object. Always `reasoning`. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `REASONING("reasoning")` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `Optional agent` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The agent that produced this item. - - `Optional temperature` + - `String agentName` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + The canonical name of the agent that produced this item. - - `Optional toolChoice` + - `Optional> content` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + Reasoning text content. - - `Optional> tools` + - `String text` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + The reasoning text from the model. - - `Optional topP` + - `JsonValue; type "reasoning_text"constant` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + The type of the reasoning text. Always `reasoning_text`. - We generally recommend altering this or temperature but not both. + - `REASONING_TEXT("reasoning_text")` - - `Optional truncationStrategy` + - `Optional encryptedContent` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `Type type` + - `Optional status` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `AUTO("auto")` + - `IN_PROGRESS("in_progress")` - - `LAST_MESSAGES("last_messages")` + - `COMPLETED("completed")` - - `Optional lastMessages` + - `INCOMPLETE("incomplete")` - The number of most recent messages from the thread when constructing the context for the run. + - `class BetaResponseCompactionItemParam:` -### Returns + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). -- `class Run:` + - `String encryptedContent` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The encrypted content of the compaction summary. - - `String id` + - `JsonValue; type "compaction"constant` - The identifier, which can be referenced in API endpoints. + The type of the item. Always `compaction`. - - `String assistantId` + - `COMPACTION("compaction")` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `Optional id` - - `Optional cancelledAt` + The ID of the compaction item. - The Unix timestamp (in seconds) for when the run was cancelled. + - `Optional agent` - - `Optional completedAt` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was completed. + - `String agentName` - - `long createdAt` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was created. + - `ImageGenerationCall` - - `Optional expiresAt` + - `String id` - The Unix timestamp (in seconds) for when the run will expire. + The unique ID of the image generation call. - - `Optional failedAt` + - `Optional result` - The Unix timestamp (in seconds) for when the run failed. + The generated image encoded in base64. - - `Optional incompleteDetails` + - `Status status` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The status of the image generation call. - - `Optional reason` + - `IN_PROGRESS("in_progress")` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `COMPLETED("completed")` - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + - `GENERATING("generating")` - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `FAILED("failed")` - - `String instructions` + - `JsonValue; type "image_generation_call"constant` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the image generation call. Always `image_generation_call`. - - `Optional lastError` + - `IMAGE_GENERATION_CALL("image_generation_call")` - The last error associated with this run. Will be `null` if there are no errors. + - `Optional agent` - - `Code code` + The agent that produced this item. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `String agentName` - - `SERVER_ERROR("server_error")` + The canonical name of the agent that produced this item. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `class BetaResponseCodeInterpreterToolCall:` - - `INVALID_PROMPT("invalid_prompt")` + A tool call to run code. - - `String message` + - `String id` - A human-readable description of the error. + The unique ID of the code interpreter tool call. - - `Optional maxCompletionTokens` + - `Optional code` - The maximum number of completion tokens specified to have been used over the course of the run. + The code to run, or null if not available. - - `Optional maxPromptTokens` + - `String containerId` - The maximum number of prompt tokens specified to have been used over the course of the run. + The ID of the container used to run the code. - - `Optional metadata` + - `Optional> outputs` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `class Logs:` - - `String model` + The logs output from the code interpreter. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `String logs` - - `JsonValue; object_ "thread.run"constant` + The logs output from the code interpreter. - The object type, which is always `thread.run`. + - `JsonValue; type "logs"constant` - - `THREAD_RUN("thread.run")` + The type of the output. Always `logs`. - - `boolean parallelToolCalls` + - `LOGS("logs")` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `class Image:` - - `Optional requiredAction` + The image output from the code interpreter. - Details on the action required to continue the run. Will be `null` if no action is required. + - `JsonValue; type "image"constant` - - `SubmitToolOutputs submitToolOutputs` + The type of the output. Always `image`. - Details on the tool outputs needed for this run to continue. + - `IMAGE("image")` - - `List toolCalls` + - `String url` - A list of the relevant tool calls. + The URL of the image output from the code interpreter. - - `String id` + - `Status status` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `Function function` + - `IN_PROGRESS("in_progress")` - The function definition. + - `COMPLETED("completed")` - - `String arguments` + - `INCOMPLETE("incomplete")` - The arguments that the model expects you to pass to the function. + - `INTERPRETING("interpreting")` - - `String name` + - `FAILED("failed")` - The name of the function. + - `JsonValue; type "code_interpreter_call"constant` - - `JsonValue; type "function"constant` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The type of tool call the output is required for. For now, this is always `function`. + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `FUNCTION("function")` + - `Optional agent` - - `JsonValue; type "submit_tool_outputs"constant` + The agent that produced this item. - For now, this is always `submit_tool_outputs`. + - `String agentName` - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + The canonical name of the agent that produced this item. - - `Optional responseFormat` + - `LocalShellCall` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `String id` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The unique ID of the local shell call. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `Action action` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + Execute a shell command on the server. - - `JsonValue;` + - `List command` - - `AUTO("auto")` + The command to run. - - `class ResponseFormatText:` + - `Env env` - Default response format. Used to generate text responses. + Environment variables to set for the command. - - `JsonValue; type "text"constant` + - `JsonValue; type "exec"constant` - The type of response format being defined. Always `text`. + The type of the local shell action. Always `exec`. - - `TEXT("text")` + - `EXEC("exec")` - - `class ResponseFormatJsonObject:` + - `Optional timeoutMs` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Optional timeout in milliseconds for the command. - - `JsonValue; type "json_object"constant` + - `Optional user` - The type of response format being defined. Always `json_object`. + Optional user to run the command as. - - `JSON_OBJECT("json_object")` + - `Optional workingDirectory` - - `class ResponseFormatJsonSchema:` + Optional working directory to run the command in. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `String callId` - - `JsonSchema jsonSchema` + The unique ID of the local shell tool call generated by the model. - Structured Outputs configuration options, including a JSON Schema. + - `Status status` - - `String name` + The status of the local shell call. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `IN_PROGRESS("in_progress")` - - `Optional description` + - `COMPLETED("completed")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `INCOMPLETE("incomplete")` - - `Optional schema` + - `JsonValue; type "local_shell_call"constant` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the local shell call. Always `local_shell_call`. - - `Optional strict` + - `LOCAL_SHELL_CALL("local_shell_call")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional agent` - - `JsonValue; type "json_schema"constant` + The agent that produced this item. - The type of response format being defined. Always `json_schema`. + - `String agentName` - - `JSON_SCHEMA("json_schema")` + The canonical name of the agent that produced this item. - - `Optional startedAt` + - `LocalShellCallOutput` - The Unix timestamp (in seconds) for when the run was started. + - `String id` - - `JsonValue status` + The unique ID of the local shell tool call generated by the model. - - `String threadId` + - `String output` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + A JSON string of the output of the local shell tool call. - - `Optional toolChoice` + - `JsonValue; type "local_shell_call_output"constant` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `Auto` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `NONE("none")` + - `Optional agent` - - `AUTO("auto")` + The agent that produced this item. - - `REQUIRED("required")` + - `String agentName` - - `class AssistantToolChoice:` + The canonical name of the agent that produced this item. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `Optional status` - - `Type type` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The type of the tool. If type is `function`, the function name must be set + - `IN_PROGRESS("in_progress")` - - `FUNCTION("function")` + - `COMPLETED("completed")` - - `CODE_INTERPRETER("code_interpreter")` + - `INCOMPLETE("incomplete")` - - `FILE_SEARCH("file_search")` + - `ShellCall` - - `Optional function` + - `Action action` - - `String name` + The shell commands and limits that describe how to run the tool call. - The name of the function to call. + - `List commands` - - `List tools` + Ordered shell commands for the execution environment to run. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `Optional maxOutputLength` - - `Optional truncationStrategy` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `Optional timeoutMs` - - `Type type` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `String callId` - - `AUTO("auto")` + The unique ID of the shell tool call generated by the model. - - `LAST_MESSAGES("last_messages")` + - `JsonValue; type "shell_call"constant` - - `Optional lastMessages` + The type of the item. Always `shell_call`. - The number of most recent messages from the thread when constructing the context for the run. + - `SHELL_CALL("shell_call")` - - `Optional usage` + - `Optional id` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The unique ID of the shell tool call. Populated when this item is returned via API. - - `long completionTokens` + - `Optional agent` - Number of completion tokens used over the course of the run. + The agent that produced this item. - - `long promptTokens` + - `String agentName` - Number of prompt tokens used over the course of the run. + The canonical name of the agent that produced this item. - - `long totalTokens` + - `Optional caller` - Total number of tokens used (prompt + completion). + The execution context that produced this tool call. - - `Optional temperature` + - `JsonValue;` - The sampling temperature used for this run. If not set, defaults to 1. + - `JsonValue; type "direct"constant` - - `Optional topP` + The caller type. Always `direct`. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `DIRECT("direct")` -### Example + - `class Program:` -```java -package com.openai.example; + - `String callerId` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.Run; -import com.openai.models.beta.threads.runs.RunCreateParams; + The call ID of the program item that produced this tool call. -public final class Main { - private Main() {} + - `JsonValue; type "program"constant` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The caller type. Always `program`. - RunCreateParams params = RunCreateParams.builder() - .threadId("thread_id") - .assistantId("assistant_id") - .build(); - Run run = client.beta().threads().runs().create(params); - } -} -``` + - `PROGRAM("program")` -#### Response + - `Optional environment` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The environment to execute the shell commands in. -## Retrieve run + - `class BetaLocalEnvironment:` -`Run beta().threads().runs().retrieve(RunRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `class BetaContainerReference:` -**get** `/threads/{thread_id}/runs/{run_id}` + - `Optional status` -Retrieve run + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. -### Parameters + - `IN_PROGRESS("in_progress")` -- `RunRetrieveParams params` + - `COMPLETED("completed")` - - `String threadId` + - `INCOMPLETE("incomplete")` - - `Optional runId` + - `ShellCallOutput` -### Returns + - `String callId` -- `class Run:` + The unique ID of the shell tool call generated by the model. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `List output` - - `String id` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The identifier, which can be referenced in API endpoints. + - `Outcome outcome` - - `String assistantId` + The exit or timeout outcome associated with this shell call. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `JsonValue;` - - `Optional cancelledAt` + - `JsonValue; type "timeout"constant` - The Unix timestamp (in seconds) for when the run was cancelled. + The outcome type. Always `timeout`. - - `Optional completedAt` + - `TIMEOUT("timeout")` - The Unix timestamp (in seconds) for when the run was completed. + - `class Exit:` - - `long createdAt` + Indicates that the shell commands finished and returned an exit code. - The Unix timestamp (in seconds) for when the run was created. + - `long exitCode` - - `Optional expiresAt` + The exit code returned by the shell process. - The Unix timestamp (in seconds) for when the run will expire. + - `JsonValue; type "exit"constant` - - `Optional failedAt` + The outcome type. Always `exit`. - The Unix timestamp (in seconds) for when the run failed. + - `EXIT("exit")` - - `Optional incompleteDetails` + - `String stderr` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + Captured stderr output for the shell call. - - `Optional reason` + - `String stdout` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + Captured stdout output for the shell call. - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + - `JsonValue; type "shell_call_output"constant` - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + The type of the item. Always `shell_call_output`. - - `String instructions` + - `SHELL_CALL_OUTPUT("shell_call_output")` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `Optional id` - - `Optional lastError` + The unique ID of the shell tool call output. Populated when this item is returned via API. - The last error associated with this run. Will be `null` if there are no errors. + - `Optional agent` - - `Code code` + The agent that produced this item. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `String agentName` - - `SERVER_ERROR("server_error")` + The canonical name of the agent that produced this item. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `Optional caller` - - `INVALID_PROMPT("invalid_prompt")` + The execution context that produced this tool call. - - `String message` + - `JsonValue;` - A human-readable description of the error. + - `JsonValue; type "direct"constant` - - `Optional maxCompletionTokens` + The caller type. Always `direct`. - The maximum number of completion tokens specified to have been used over the course of the run. + - `DIRECT("direct")` - - `Optional maxPromptTokens` + - `class Program:` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `String callerId` - - `Optional metadata` + The call ID of the program item that produced this tool call. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `JsonValue; type "program"constant` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The caller type. Always `program`. - - `String model` + - `PROGRAM("program")` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `Optional maxOutputLength` - - `JsonValue; object_ "thread.run"constant` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The object type, which is always `thread.run`. + - `Optional status` - - `THREAD_RUN("thread.run")` + The status of the shell call output. - - `boolean parallelToolCalls` + - `IN_PROGRESS("in_progress")` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `COMPLETED("completed")` - - `Optional requiredAction` + - `INCOMPLETE("incomplete")` - Details on the action required to continue the run. Will be `null` if no action is required. + - `ApplyPatchCall` - - `SubmitToolOutputs submitToolOutputs` + - `String callId` - Details on the tool outputs needed for this run to continue. + The unique ID of the apply patch tool call generated by the model. - - `List toolCalls` + - `Operation operation` - A list of the relevant tool calls. + The specific create, delete, or update instruction for the apply_patch tool call. - - `String id` + - `class CreateFile:` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + Instruction for creating a new file via the apply_patch tool. - - `Function function` + - `String diff` - The function definition. + Unified diff content to apply when creating the file. - - `String arguments` + - `String path` - The arguments that the model expects you to pass to the function. + Path of the file to create relative to the workspace root. - - `String name` + - `JsonValue; type "create_file"constant` - The name of the function. + The operation type. Always `create_file`. - - `JsonValue; type "function"constant` + - `CREATE_FILE("create_file")` - The type of tool call the output is required for. For now, this is always `function`. + - `class DeleteFile:` - - `FUNCTION("function")` + Instruction for deleting an existing file via the apply_patch tool. - - `JsonValue; type "submit_tool_outputs"constant` + - `String path` - For now, this is always `submit_tool_outputs`. + Path of the file to delete relative to the workspace root. - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + - `JsonValue; type "delete_file"constant` - - `Optional responseFormat` + The operation type. Always `delete_file`. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `DELETE_FILE("delete_file")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `class UpdateFile:` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Instruction for updating an existing file via the apply_patch tool. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `String diff` - - `JsonValue;` + Unified diff content to apply to the existing file. - - `AUTO("auto")` + - `String path` - - `class ResponseFormatText:` + Path of the file to update relative to the workspace root. - Default response format. Used to generate text responses. + - `JsonValue; type "update_file"constant` - - `JsonValue; type "text"constant` + The operation type. Always `update_file`. - The type of response format being defined. Always `text`. + - `UPDATE_FILE("update_file")` - - `TEXT("text")` + - `Status status` - - `class ResponseFormatJsonObject:` + The status of the apply patch tool call. One of `in_progress` or `completed`. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "json_object"constant` + - `COMPLETED("completed")` - The type of response format being defined. Always `json_object`. + - `JsonValue; type "apply_patch_call"constant` - - `JSON_OBJECT("json_object")` + The type of the item. Always `apply_patch_call`. - - `class ResponseFormatJsonSchema:` + - `APPLY_PATCH_CALL("apply_patch_call")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional id` - - `JsonSchema jsonSchema` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Structured Outputs configuration options, including a JSON Schema. + - `Optional agent` - - `String name` + The agent that produced this item. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `String agentName` - - `Optional description` + The canonical name of the agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Optional caller` - - `Optional schema` + The execution context that produced this tool call. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `JsonValue;` - - `Optional strict` + - `JsonValue; type "direct"constant` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The caller type. Always `direct`. - - `JsonValue; type "json_schema"constant` + - `DIRECT("direct")` - The type of response format being defined. Always `json_schema`. + - `class Program:` - - `JSON_SCHEMA("json_schema")` + - `String callerId` - - `Optional startedAt` + The call ID of the program item that produced this tool call. - The Unix timestamp (in seconds) for when the run was started. + - `JsonValue; type "program"constant` - - `JsonValue status` + The caller type. Always `program`. - - `String threadId` + - `PROGRAM("program")` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `ApplyPatchCallOutput` - - `Optional toolChoice` + - `String callId` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The unique ID of the apply patch tool call generated by the model. - - `Auto` + - `Status status` - - `NONE("none")` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `AUTO("auto")` + - `COMPLETED("completed")` - - `REQUIRED("required")` + - `FAILED("failed")` - - `class AssistantToolChoice:` + - `JsonValue; type "apply_patch_call_output"constant` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The type of the item. Always `apply_patch_call_output`. - - `Type type` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - The type of the tool. If type is `function`, the function name must be set + - `Optional id` - - `FUNCTION("function")` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `CODE_INTERPRETER("code_interpreter")` + - `Optional agent` - - `FILE_SEARCH("file_search")` + The agent that produced this item. - - `Optional function` + - `String agentName` - - `String name` + The canonical name of the agent that produced this item. - The name of the function to call. + - `Optional caller` - - `List tools` + The execution context that produced this tool call. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `JsonValue;` - - `Optional truncationStrategy` + - `JsonValue; type "direct"constant` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The caller type. Always `direct`. - - `Type type` + - `DIRECT("direct")` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `class Program:` - - `AUTO("auto")` + - `String callerId` - - `LAST_MESSAGES("last_messages")` + The call ID of the program item that produced this tool call. - - `Optional lastMessages` + - `JsonValue; type "program"constant` - The number of most recent messages from the thread when constructing the context for the run. + The caller type. Always `program`. - - `Optional usage` + - `PROGRAM("program")` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `Optional output` - - `long completionTokens` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - Number of completion tokens used over the course of the run. + - `McpListTools` - - `long promptTokens` + - `String id` - Number of prompt tokens used over the course of the run. + The unique ID of the list. - - `long totalTokens` + - `String serverLabel` - Total number of tokens used (prompt + completion). + The label of the MCP server. - - `Optional temperature` + - `List tools` - The sampling temperature used for this run. If not set, defaults to 1. + The tools available on the server. - - `Optional topP` + - `JsonValue inputSchema` - The nucleus sampling value used for this run. If not set, defaults to 1. + The JSON schema describing the tool's input. -### Example + - `String name` -```java -package com.openai.example; + The name of the tool. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.Run; -import com.openai.models.beta.threads.runs.RunRetrieveParams; + - `Optional annotations` -public final class Main { - private Main() {} + Additional annotations about the tool. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Optional description` - RunRetrieveParams params = RunRetrieveParams.builder() - .threadId("thread_id") - .runId("run_id") - .build(); - Run run = client.beta().threads().runs().retrieve(params); - } -} -``` + The description of the tool. -#### Response + - `JsonValue; type "mcp_list_tools"constant` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The type of the item. Always `mcp_list_tools`. -## Modify run + - `MCP_LIST_TOOLS("mcp_list_tools")` -`Run beta().threads().runs().update(RunUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `Optional agent` -**post** `/threads/{thread_id}/runs/{run_id}` + The agent that produced this item. -Modify run + - `String agentName` -### Parameters + The canonical name of the agent that produced this item. -- `RunUpdateParams params` + - `Optional error` - - `String threadId` + Error message if the server could not list tools. - - `Optional runId` + - `McpApprovalRequest` - - `Optional metadata` + - `String id` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The unique ID of the approval request. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `String arguments` -### Returns + A JSON string of arguments for the tool. -- `class Run:` + - `String name` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The name of the tool to run. - - `String id` + - `String serverLabel` - The identifier, which can be referenced in API endpoints. + The label of the MCP server making the request. - - `String assistantId` + - `JsonValue; type "mcp_approval_request"constant` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The type of the item. Always `mcp_approval_request`. - - `Optional cancelledAt` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - The Unix timestamp (in seconds) for when the run was cancelled. + - `Optional agent` - - `Optional completedAt` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was completed. + - `String agentName` - - `long createdAt` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was created. + - `McpApprovalResponse` - - `Optional expiresAt` + - `String approvalRequestId` - The Unix timestamp (in seconds) for when the run will expire. + The ID of the approval request being answered. - - `Optional failedAt` + - `boolean approve` - The Unix timestamp (in seconds) for when the run failed. + Whether the request was approved. - - `Optional incompleteDetails` + - `JsonValue; type "mcp_approval_response"constant` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The type of the item. Always `mcp_approval_response`. - - `Optional reason` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `Optional id` - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + The unique ID of the approval response - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `Optional agent` - - `String instructions` + The agent that produced this item. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `String agentName` - - `Optional lastError` + The canonical name of the agent that produced this item. - The last error associated with this run. Will be `null` if there are no errors. + - `Optional reason` - - `Code code` + Optional reason for the decision. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `McpCall` - - `SERVER_ERROR("server_error")` + - `String id` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The unique ID of the tool call. - - `INVALID_PROMPT("invalid_prompt")` + - `String arguments` - - `String message` + A JSON string of the arguments passed to the tool. - A human-readable description of the error. + - `String name` - - `Optional maxCompletionTokens` + The name of the tool that was run. - The maximum number of completion tokens specified to have been used over the course of the run. + - `String serverLabel` - - `Optional maxPromptTokens` + The label of the MCP server running the tool. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `JsonValue; type "mcp_call"constant` - - `Optional metadata` + The type of the item. Always `mcp_call`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `MCP_CALL("mcp_call")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Optional agent` - - `String model` + The agent that produced this item. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `String agentName` - - `JsonValue; object_ "thread.run"constant` + The canonical name of the agent that produced this item. - The object type, which is always `thread.run`. + - `Optional approvalRequestId` - - `THREAD_RUN("thread.run")` + 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. - - `boolean parallelToolCalls` + - `Optional error` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The error from the tool call, if any. - - `Optional requiredAction` + - `Optional output` - Details on the action required to continue the run. Will be `null` if no action is required. + The output from the tool call. - - `SubmitToolOutputs submitToolOutputs` + - `Optional status` - Details on the tool outputs needed for this run to continue. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `List toolCalls` + - `IN_PROGRESS("in_progress")` - A list of the relevant tool calls. + - `COMPLETED("completed")` - - `String id` + - `INCOMPLETE("incomplete")` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `CALLING("calling")` - - `Function function` + - `FAILED("failed")` - The function definition. + - `class BetaResponseCustomToolCallOutput:` - - `String arguments` + The output of a custom tool call from your code, being sent back to the model. - The arguments that the model expects you to pass to the function. + - `String callId` - - `String name` + The call ID, used to map this custom tool call output to a custom tool call. - The name of the function. + - `Output output` - - `JsonValue; type "function"constant` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The type of tool call the output is required for. For now, this is always `function`. + - `String` - - `FUNCTION("function")` + - `List` - - `JsonValue; type "submit_tool_outputs"constant` + - `class BetaResponseInputText:` - For now, this is always `submit_tool_outputs`. + A text input to the model. - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + - `class BetaResponseInputImage:` - - `Optional responseFormat` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `class BetaResponseInputFile:` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + A file input to the model. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `JsonValue; type "custom_tool_call_output"constant` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `JsonValue;` + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - - `AUTO("auto")` + - `Optional id` - - `class ResponseFormatText:` + The unique ID of the custom tool call output in the OpenAI platform. - Default response format. Used to generate text responses. + - `Optional agent` - - `JsonValue; type "text"constant` + The agent that produced this item. - The type of response format being defined. Always `text`. + - `String agentName` - - `TEXT("text")` + The canonical name of the agent that produced this item. - - `class ResponseFormatJsonObject:` + - `Optional caller` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The execution context that produced this tool call. - - `JsonValue; type "json_object"constant` + - `JsonValue;` - The type of response format being defined. Always `json_object`. + - `JsonValue; type "direct"constant` - - `JSON_OBJECT("json_object")` + The caller type. Always `direct`. - - `class ResponseFormatJsonSchema:` + - `DIRECT("direct")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `class Program:` - - `JsonSchema jsonSchema` + - `String callerId` - Structured Outputs configuration options, including a JSON Schema. + The call ID of the program item that produced this tool call. - - `String name` + - `JsonValue; type "program"constant` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The caller type. Always `program`. - - `Optional description` + - `PROGRAM("program")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `class BetaResponseCustomToolCall:` - - `Optional schema` + A call to a custom tool created by the model. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `String callId` - - `Optional strict` + An identifier used to map this custom tool call to a tool call output. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `String input` - - `JsonValue; type "json_schema"constant` + The input for the custom tool call generated by the model. - The type of response format being defined. Always `json_schema`. + - `String name` - - `JSON_SCHEMA("json_schema")` + The name of the custom tool being called. - - `Optional startedAt` + - `JsonValue; type "custom_tool_call"constant` - The Unix timestamp (in seconds) for when the run was started. + The type of the custom tool call. Always `custom_tool_call`. - - `JsonValue status` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - - `String threadId` + - `Optional id` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The unique ID of the custom tool call in the OpenAI platform. - - `Optional toolChoice` + - `Optional agent` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The agent that produced this item. - - `Auto` + - `String agentName` - - `NONE("none")` + The canonical name of the agent that produced this item. - - `AUTO("auto")` + - `Optional caller` - - `REQUIRED("required")` + The execution context that produced this tool call. - - `class AssistantToolChoice:` + - `JsonValue;` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `JsonValue; type "direct"constant` - - `Type type` + - `DIRECT("direct")` - The type of the tool. If type is `function`, the function name must be set + - `class Program:` - - `FUNCTION("function")` + - `String callerId` - - `CODE_INTERPRETER("code_interpreter")` + The call ID of the program item that produced this tool call. - - `FILE_SEARCH("file_search")` + - `JsonValue; type "program"constant` - - `Optional function` + - `PROGRAM("program")` - - `String name` + - `Optional namespace` - The name of the function to call. + The namespace of the custom tool being called. - - `List tools` + - `CompactionTrigger` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `JsonValue; type "compaction_trigger"constant` - - `Optional truncationStrategy` + The type of the item. Always `compaction_trigger`. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `COMPACTION_TRIGGER("compaction_trigger")` - - `Type type` + - `Optional agent` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + The agent that produced this item. - - `AUTO("auto")` + - `String agentName` - - `LAST_MESSAGES("last_messages")` + The canonical name of the agent that produced this item. - - `Optional lastMessages` + - `ItemReference` - The number of most recent messages from the thread when constructing the context for the run. + - `String id` - - `Optional usage` + The ID of the item to reference. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `Optional agent` - - `long completionTokens` + The agent that produced this item. - Number of completion tokens used over the course of the run. + - `String agentName` - - `long promptTokens` + The canonical name of the agent that produced this item. - Number of prompt tokens used over the course of the run. + - `Optional type` - - `long totalTokens` + The type of item to reference. Always `item_reference`. - Total number of tokens used (prompt + completion). + - `ITEM_REFERENCE("item_reference")` - - `Optional temperature` + - `Program` - The sampling temperature used for this run. If not set, defaults to 1. + - `String id` - - `Optional topP` + The unique ID of this program item. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `String callId` -### Example + The stable call ID of the program item. -```java -package com.openai.example; + - `String code` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.Run; -import com.openai.models.beta.threads.runs.RunUpdateParams; + The JavaScript source executed by programmatic tool calling. -public final class Main { - private Main() {} + - `String fingerprint` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + Opaque program replay fingerprint that must be round-tripped. - RunUpdateParams params = RunUpdateParams.builder() - .threadId("thread_id") - .runId("run_id") - .build(); - Run run = client.beta().threads().runs().update(params); - } -} -``` + - `JsonValue; type "program"constant` -#### Response + The item type. Always `program`. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `PROGRAM("program")` -## Submit tool outputs to run + - `Optional agent` -`Run beta().threads().runs().submitToolOutputs(RunSubmitToolOutputsParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + The agent that produced this item. -**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` + - `String agentName` -Submit tool outputs to run + The canonical name of the agent that produced this item. -### Parameters + - `ProgramOutput` -- `RunSubmitToolOutputsParams params` + - `String id` - - `String threadId` + The unique ID of this program output item. - - `Optional runId` + - `String callId` - - `List toolOutputs` + The call ID of the program item. - A list of tools for which the outputs are being submitted. + - `String result` - - `Optional output` + The result produced by the program item. - The output of the tool call to be submitted to continue the run. + - `Status status` - - `Optional toolCallId` + The terminal status of the program output. - The ID of the tool call in the `required_action` object within the run object the output is being submitted for. + - `COMPLETED("completed")` -### Returns + - `INCOMPLETE("incomplete")` -- `class Run:` + - `JsonValue; type "program_output"constant` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The item type. Always `program_output`. - - `String id` + - `PROGRAM_OUTPUT("program_output")` - The identifier, which can be referenced in API endpoints. + - `Optional agent` - - `String assistantId` + The agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `String agentName` - - `Optional cancelledAt` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was cancelled. + - `Optional metadata` - - `Optional completedAt` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The Unix timestamp (in seconds) for when the run was completed. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `long createdAt` + - `Model model` - The Unix timestamp (in seconds) for when the run was created. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `Optional expiresAt` + - `GPT_5_6_SOL("gpt-5.6-sol")` - The Unix timestamp (in seconds) for when the run will expire. + - `GPT_5_6_TERRA("gpt-5.6-terra")` - - `Optional failedAt` + - `GPT_5_6_LUNA("gpt-5.6-luna")` - The Unix timestamp (in seconds) for when the run failed. + - `GPT_5_4("gpt-5.4")` - - `Optional incompleteDetails` + - `GPT_5_4_MINI("gpt-5.4-mini")` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `Optional reason` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `GPT_5_2("gpt-5.2")` - - `String instructions` + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - `Optional lastError` + - `GPT_5_2_PRO("gpt-5.2-pro")` - The last error associated with this run. Will be `null` if there are no errors. + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `Code code` + - `GPT_5_1("gpt-5.1")` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - `SERVER_ERROR("server_error")` + - `GPT_5_1_CODEX("gpt-5.1-codex")` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `GPT_5_1_MINI("gpt-5.1-mini")` - - `INVALID_PROMPT("invalid_prompt")` + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - `String message` + - `GPT_5("gpt-5")` - A human-readable description of the error. + - `GPT_5_MINI("gpt-5-mini")` - - `Optional maxCompletionTokens` + - `GPT_5_NANO("gpt-5-nano")` - The maximum number of completion tokens specified to have been used over the course of the run. + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - `Optional maxPromptTokens` + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - `Optional metadata` + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `GPT_4_1("gpt-4.1")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `GPT_4_1_MINI("gpt-4.1-mini")` - - `String model` + - `GPT_4_1_NANO("gpt-4.1-nano")` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - `JsonValue; object_ "thread.run"constant` + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - The object type, which is always `thread.run`. + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - - `THREAD_RUN("thread.run")` + - `O4_MINI("o4-mini")` - - `boolean parallelToolCalls` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `O3("o3")` - - `Optional requiredAction` + - `O3_2025_04_16("o3-2025-04-16")` - Details on the action required to continue the run. Will be `null` if no action is required. + - `O3_MINI("o3-mini")` - - `SubmitToolOutputs submitToolOutputs` + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - Details on the tool outputs needed for this run to continue. + - `O1("o1")` - - `List toolCalls` + - `O1_2024_12_17("o1-2024-12-17")` - A list of the relevant tool calls. + - `O1_PREVIEW("o1-preview")` - - `String id` + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `O1_MINI("o1-mini")` - - `Function function` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - The function definition. + - `GPT_4O("gpt-4o")` - - `String arguments` + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - The arguments that the model expects you to pass to the function. + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - `String name` + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - The name of the function. + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - `JsonValue; type "function"constant` + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - The type of tool call the output is required for. For now, this is always `function`. + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - - `FUNCTION("function")` + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - - `JsonValue; type "submit_tool_outputs"constant` + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - For now, this is always `submit_tool_outputs`. + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `Optional responseFormat` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `JsonValue;` + - `GPT_4O_MINI("gpt-4o-mini")` - - `AUTO("auto")` + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - - `class ResponseFormatText:` + - `GPT_4_TURBO("gpt-4-turbo")` - Default response format. Used to generate text responses. + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - - `JsonValue; type "text"constant` + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - The type of response format being defined. Always `text`. + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `TEXT("text")` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - - `class ResponseFormatJsonObject:` + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `GPT_4("gpt-4")` - - `JsonValue; type "json_object"constant` + - `GPT_4_0314("gpt-4-0314")` - The type of response format being defined. Always `json_object`. + - `GPT_4_0613("gpt-4-0613")` - - `JSON_OBJECT("json_object")` + - `GPT_4_32K("gpt-4-32k")` - - `class ResponseFormatJsonSchema:` + - `GPT_4_32K_0314("gpt-4-32k-0314")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `JsonSchema jsonSchema` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - Structured Outputs configuration options, including a JSON Schema. + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `String name` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `Optional description` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - `Optional schema` + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `O1_PRO("o1-pro")` - - `Optional strict` + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `O3_PRO("o3-pro")` - - `JsonValue; type "json_schema"constant` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - The type of response format being defined. Always `json_schema`. + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `JSON_SCHEMA("json_schema")` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - - `Optional startedAt` + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - The Unix timestamp (in seconds) for when the run was started. + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - - `JsonValue status` + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - `String threadId` + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `GPT_5_CODEX("gpt-5-codex")` - - `Optional toolChoice` + - `GPT_5_PRO("gpt-5-pro")` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - - `Auto` + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - - `NONE("none")` + - `JsonValue; object_ "response"constant` - - `AUTO("auto")` + The object type of this resource - always set to `response`. - - `REQUIRED("required")` + - `RESPONSE("response")` - - `class AssistantToolChoice:` + - `List output` - Specifies a tool the model should use. Use to force the model to call a specific tool. + An array of content items generated by the model. - - `Type type` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - The type of the tool. If type is `function`, the function name must be set + - `class BetaResponseOutputMessage:` - - `FUNCTION("function")` + An output message from the model. - - `CODE_INTERPRETER("code_interpreter")` + - `class BetaResponseFileSearchToolCall:` - - `FILE_SEARCH("file_search")` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `Optional function` + - `class BetaResponseFunctionToolCall:` - - `String name` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The name of the function to call. + - `class BetaResponseFunctionToolCallOutputItem:` - - `List tools` + - `String id` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID of the function call tool output. - - `Optional truncationStrategy` + - `String callId` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The unique ID of the function tool call generated by the model. - - `Type type` + - `Output output` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `AUTO("auto")` + - `String` - - `LAST_MESSAGES("last_messages")` + - `List` - - `Optional lastMessages` + - `class BetaResponseInputText:` - The number of most recent messages from the thread when constructing the context for the run. + A text input to the model. - - `Optional usage` + - `class BetaResponseInputImage:` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `long completionTokens` + - `class BetaResponseInputFile:` - Number of completion tokens used over the course of the run. + A file input to the model. - - `long promptTokens` + - `Status status` - Number of prompt tokens used over the course of the run. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `long totalTokens` + - `IN_PROGRESS("in_progress")` - Total number of tokens used (prompt + completion). + - `COMPLETED("completed")` - - `Optional temperature` + - `INCOMPLETE("incomplete")` - The sampling temperature used for this run. If not set, defaults to 1. + - `JsonValue; type "function_call_output"constant` - - `Optional topP` + The type of the function tool call output. Always `function_call_output`. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `FUNCTION_CALL_OUTPUT("function_call_output")` -### Example + - `Optional agent` -```java -package com.openai.example; + The agent that produced this item. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.Run; -import com.openai.models.beta.threads.runs.RunSubmitToolOutputsParams; + - `String agentName` -public final class Main { - private Main() {} + The canonical name of the agent that produced this item. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Optional caller` - RunSubmitToolOutputsParams params = RunSubmitToolOutputsParams.builder() - .threadId("thread_id") - .runId("run_id") - .addToolOutput(RunSubmitToolOutputsParams.ToolOutput.builder().build()) - .build(); - Run run = client.beta().threads().runs().submitToolOutputs(params); - } -} -``` + The execution context that produced this tool call. -#### Response + - `JsonValue;` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `JsonValue; type "direct"constant` -## Cancel a run + The caller type. Always `direct`. -`Run beta().threads().runs().cancel(RunCancelParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `DIRECT("direct")` -**post** `/threads/{thread_id}/runs/{run_id}/cancel` + - `class Program:` -Cancel a run + - `String callerId` -### Parameters + The call ID of the program item that produced this tool call. -- `RunCancelParams params` + - `JsonValue; type "program"constant` - - `String threadId` + The caller type. Always `program`. - - `Optional runId` + - `PROGRAM("program")` -### Returns + - `Optional createdBy` -- `class Run:` + The identifier of the actor that created the item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `AgentMessage` - `String id` - The identifier, which can be referenced in API endpoints. + The unique ID of the agent message. - - `String assistantId` + - `String author` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The sending agent identity. - - `Optional cancelledAt` + - `List content` - The Unix timestamp (in seconds) for when the run was cancelled. + Encrypted content sent between agents. - - `Optional completedAt` + - `class BetaResponseInputText:` - The Unix timestamp (in seconds) for when the run was completed. + A text input to the model. - - `long createdAt` + - `class BetaResponseOutputText:` - The Unix timestamp (in seconds) for when the run was created. + A text output from the model. - - `Optional expiresAt` + - `class Text:` - The Unix timestamp (in seconds) for when the run will expire. + A text content. - - `Optional failedAt` + - `String text` - The Unix timestamp (in seconds) for when the run failed. + - `JsonValue; type "text"constant` - - `Optional incompleteDetails` + - `TEXT("text")` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `class SummaryText:` - - `Optional reason` + A summary text from the model. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `String text` - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + A summary of the reasoning output from the model so far. - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `JsonValue; type "summary_text"constant` - - `String instructions` + The type of the object. Always `summary_text`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `SUMMARY_TEXT("summary_text")` - - `Optional lastError` + - `class ReasoningText:` - The last error associated with this run. Will be `null` if there are no errors. + Reasoning text from the model. - - `Code code` + - `String text` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The reasoning text from the model. - - `SERVER_ERROR("server_error")` + - `JsonValue; type "reasoning_text"constant` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The type of the reasoning text. Always `reasoning_text`. - - `INVALID_PROMPT("invalid_prompt")` + - `REASONING_TEXT("reasoning_text")` - - `String message` + - `class BetaResponseOutputRefusal:` - A human-readable description of the error. + A refusal from the model. - - `Optional maxCompletionTokens` + - `class BetaResponseInputImage:` - The maximum number of completion tokens specified to have been used over the course of the run. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional maxPromptTokens` + - `class ComputerScreenshot:` - The maximum number of prompt tokens specified to have been used over the course of the run. + A screenshot of a computer. - - `Optional metadata` + - `Detail detail` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `LOW("low")` - - `String model` + - `HIGH("high")` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `AUTO("auto")` - - `JsonValue; object_ "thread.run"constant` + - `ORIGINAL("original")` - The object type, which is always `thread.run`. + - `Optional fileId` - - `THREAD_RUN("thread.run")` + The identifier of an uploaded file that contains the screenshot. - - `boolean parallelToolCalls` + - `Optional imageUrl` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The URL of the screenshot image. - - `Optional requiredAction` + - `JsonValue; type "computer_screenshot"constant` - Details on the action required to continue the run. Will be `null` if no action is required. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `SubmitToolOutputs submitToolOutputs` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - Details on the tool outputs needed for this run to continue. + - `Optional promptCacheBreakpoint` - - `List toolCalls` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A list of the relevant tool calls. + - `JsonValue; mode "explicit"constant` - - `String id` + The breakpoint mode. Always `explicit`. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `EXPLICIT("explicit")` - - `Function function` + - `class BetaResponseInputFile:` - The function definition. + A file input to the model. - - `String arguments` + - `class EncryptedContent:` - The arguments that the model expects you to pass to the function. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `String name` + - `String encryptedContent` - The name of the function. + Opaque encrypted content. - - `JsonValue; type "function"constant` + - `JsonValue; type "encrypted_content"constant` - The type of tool call the output is required for. For now, this is always `function`. + The type of the input item. Always `encrypted_content`. - - `FUNCTION("function")` + - `ENCRYPTED_CONTENT("encrypted_content")` - - `JsonValue; type "submit_tool_outputs"constant` + - `String recipient` - For now, this is always `submit_tool_outputs`. + The destination agent identity. - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + - `JsonValue; type "agent_message"constant` - - `Optional responseFormat` + The type of the item. Always `agent_message`. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `AGENT_MESSAGE("agent_message")` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional agent` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The agent that produced this item. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `String agentName` - - `JsonValue;` + The canonical name of the agent that produced this item. - - `AUTO("auto")` + - `MultiAgentCall` - - `class ResponseFormatText:` + - `String id` - Default response format. Used to generate text responses. + The unique ID of the multi-agent call item. - - `JsonValue; type "text"constant` + - `Action action` - The type of response format being defined. Always `text`. + The multi-agent action to execute. - - `TEXT("text")` + - `SPAWN_AGENT("spawn_agent")` - - `class ResponseFormatJsonObject:` + - `INTERRUPT_AGENT("interrupt_agent")` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `LIST_AGENTS("list_agents")` - - `JsonValue; type "json_object"constant` + - `SEND_MESSAGE("send_message")` - The type of response format being defined. Always `json_object`. + - `FOLLOWUP_TASK("followup_task")` - - `JSON_OBJECT("json_object")` + - `WAIT_AGENT("wait_agent")` - - `class ResponseFormatJsonSchema:` + - `String arguments` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The JSON string of arguments generated for the action. - - `JsonSchema jsonSchema` + - `String callId` - Structured Outputs configuration options, including a JSON Schema. + The unique ID linking this call to its output. - - `String name` + - `JsonValue; type "multi_agent_call"constant` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The type of the multi-agent call. Always `multi_agent_call`. - - `Optional description` + - `MULTI_AGENT_CALL("multi_agent_call")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Optional agent` - - `Optional schema` + The agent that produced this item. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `String agentName` - - `Optional strict` + The canonical name of the agent that produced this item. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `MultiAgentCallOutput` - - `JsonValue; type "json_schema"constant` + - `String id` - The type of response format being defined. Always `json_schema`. + The unique ID of the multi-agent call output item. - - `JSON_SCHEMA("json_schema")` + - `Action action` - - `Optional startedAt` + The multi-agent action that produced this result. - The Unix timestamp (in seconds) for when the run was started. + - `SPAWN_AGENT("spawn_agent")` - - `JsonValue status` + - `INTERRUPT_AGENT("interrupt_agent")` - - `String threadId` + - `LIST_AGENTS("list_agents")` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `SEND_MESSAGE("send_message")` - - `Optional toolChoice` + - `FOLLOWUP_TASK("followup_task")` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `WAIT_AGENT("wait_agent")` - - `Auto` + - `String callId` - - `NONE("none")` + The unique ID of the multi-agent call. - - `AUTO("auto")` + - `List output` - - `REQUIRED("required")` + Text output returned by the multi-agent action. - - `class AssistantToolChoice:` + - `List annotations` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The annotations of the text output. - - `Type type` + - `String text` - The type of the tool. If type is `function`, the function name must be set + The text output from the model. - - `FUNCTION("function")` + - `JsonValue; type "output_text"constant` - - `CODE_INTERPRETER("code_interpreter")` + The type of the output text. Always `output_text`. - - `FILE_SEARCH("file_search")` + - `Optional> logprobs` - - `Optional function` + - `JsonValue; type "multi_agent_call_output"constant` - - `String name` + The type of the multi-agent result. Always `multi_agent_call_output`. - The name of the function to call. + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `List tools` + - `Optional agent` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The agent that produced this item. - - `Optional truncationStrategy` + - `String agentName` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The canonical name of the agent that produced this item. - - `Type type` + - `class BetaResponseFunctionWebSearch:` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `AUTO("auto")` + - `class BetaResponseComputerToolCall:` - - `LAST_MESSAGES("last_messages")` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `Optional lastMessages` + - `class BetaResponseComputerToolCallOutputItem:` - The number of most recent messages from the thread when constructing the context for the run. + - `String id` - - `Optional usage` + The unique ID of the computer call tool output. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `String callId` - - `long completionTokens` + The ID of the computer tool call that produced the output. - Number of completion tokens used over the course of the run. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `long promptTokens` + A computer screenshot image used with the computer use tool. - Number of prompt tokens used over the course of the run. + - `Status status` - - `long totalTokens` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Total number of tokens used (prompt + completion). + - `COMPLETED("completed")` - - `Optional temperature` + - `INCOMPLETE("incomplete")` - The sampling temperature used for this run. If not set, defaults to 1. + - `FAILED("failed")` - - `Optional topP` + - `IN_PROGRESS("in_progress")` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `JsonValue; type "computer_call_output"constant` -### Example + The type of the computer tool call output. Always `computer_call_output`. -```java -package com.openai.example; + - `COMPUTER_CALL_OUTPUT("computer_call_output")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.Run; -import com.openai.models.beta.threads.runs.RunCancelParams; + - `Optional> acknowledgedSafetyChecks` -public final class Main { - private Main() {} + The safety checks reported by the API that have been acknowledged by the + developer. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `String id` - RunCancelParams params = RunCancelParams.builder() - .threadId("thread_id") - .runId("run_id") - .build(); - Run run = client.beta().threads().runs().cancel(params); - } -} -``` + The ID of the pending safety check. -#### Response + - `Optional code` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The type of the pending safety check. -## Domain Types + - `Optional message` -### Required Action Function Tool Call + Details about the pending safety check. -- `class RequiredActionFunctionToolCall:` + - `Optional agent` - Tool call objects + The agent that produced this item. - - `String id` + - `String agentName` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The canonical name of the agent that produced this item. - - `Function function` + - `Optional createdBy` - The function definition. + The identifier of the actor that created the item. - - `String arguments` + - `class BetaResponseReasoningItem:` - The arguments that the model expects you to pass to the function. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `String name` + - `Program` - The name of the function. + - `String id` - - `JsonValue; type "function"constant` + The unique ID of the program item. - The type of tool call the output is required for. For now, this is always `function`. + - `String callId` - - `FUNCTION("function")` + The stable call ID of the program item. -### Run + - `String code` -- `class Run:` + The JavaScript source executed by programmatic tool calling. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `String fingerprint` - - `String id` + Opaque program replay fingerprint that must be round-tripped. - The identifier, which can be referenced in API endpoints. + - `JsonValue; type "program"constant` - - `String assistantId` + The type of the item. Always `program`. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `PROGRAM("program")` - - `Optional cancelledAt` + - `Optional agent` - The Unix timestamp (in seconds) for when the run was cancelled. + The agent that produced this item. - - `Optional completedAt` + - `String agentName` - The Unix timestamp (in seconds) for when the run was completed. + The canonical name of the agent that produced this item. - - `long createdAt` + - `ProgramOutput` - The Unix timestamp (in seconds) for when the run was created. + - `String id` - - `Optional expiresAt` + The unique ID of the program output item. - The Unix timestamp (in seconds) for when the run will expire. + - `String callId` - - `Optional failedAt` + The call ID of the program item. - The Unix timestamp (in seconds) for when the run failed. + - `String result` - - `Optional incompleteDetails` + The result produced by the program item. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `Status status` - - `Optional reason` + The terminal status of the program output item. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `COMPLETED("completed")` - - `MAX_COMPLETION_TOKENS("max_completion_tokens")` + - `INCOMPLETE("incomplete")` - - `MAX_PROMPT_TOKENS("max_prompt_tokens")` + - `JsonValue; type "program_output"constant` - - `String instructions` + The type of the item. Always `program_output`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `PROGRAM_OUTPUT("program_output")` - - `Optional lastError` + - `Optional agent` - The last error associated with this run. Will be `null` if there are no errors. + The agent that produced this item. - - `Code code` + - `String agentName` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The canonical name of the agent that produced this item. - - `SERVER_ERROR("server_error")` + - `class BetaResponseToolSearchCall:` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `String id` - - `INVALID_PROMPT("invalid_prompt")` + The unique ID of the tool search call item. - - `String message` + - `JsonValue arguments` - A human-readable description of the error. + Arguments used for the tool search call. - - `Optional maxCompletionTokens` + - `Optional callId` - The maximum number of completion tokens specified to have been used over the course of the run. + The unique ID of the tool search call generated by the model. - - `Optional maxPromptTokens` + - `Execution execution` - The maximum number of prompt tokens specified to have been used over the course of the run. + Whether tool search was executed by the server or by the client. - - `Optional metadata` + - `SERVER("server")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `CLIENT("client")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Status status` - - `String model` + The status of the tool search call item that was recorded. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `IN_PROGRESS("in_progress")` - - `JsonValue; object_ "thread.run"constant` + - `COMPLETED("completed")` - The object type, which is always `thread.run`. + - `INCOMPLETE("incomplete")` - - `THREAD_RUN("thread.run")` + - `JsonValue; type "tool_search_call"constant` - - `boolean parallelToolCalls` + The type of the item. Always `tool_search_call`. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `TOOL_SEARCH_CALL("tool_search_call")` - - `Optional requiredAction` + - `Optional agent` - Details on the action required to continue the run. Will be `null` if no action is required. + The agent that produced this item. - - `SubmitToolOutputs submitToolOutputs` + - `String agentName` - Details on the tool outputs needed for this run to continue. + The canonical name of the agent that produced this item. - - `List toolCalls` + - `Optional createdBy` - A list of the relevant tool calls. + The identifier of the actor that created the item. - - `String id` + - `class BetaResponseToolSearchOutputItem:` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `String id` - - `Function function` + The unique ID of the tool search output item. - The function definition. + - `Optional callId` - - `String arguments` + The unique ID of the tool search call generated by the model. - The arguments that the model expects you to pass to the function. + - `Execution execution` - - `String name` + Whether tool search was executed by the server or by the client. - The name of the function. + - `SERVER("server")` - - `JsonValue; type "function"constant` + - `CLIENT("client")` - The type of tool call the output is required for. For now, this is always `function`. + - `Status status` - - `FUNCTION("function")` + The status of the tool search output item that was recorded. - - `JsonValue; type "submit_tool_outputs"constant` + - `IN_PROGRESS("in_progress")` - For now, this is always `submit_tool_outputs`. + - `COMPLETED("completed")` - - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` + - `INCOMPLETE("incomplete")` - - `Optional responseFormat` + - `List tools` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The loaded tool definitions returned by tool search. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `class BetaFunctionTool:` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `class BetaFileSearchTool:` - - `JsonValue;` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `AUTO("auto")` + - `class BetaComputerTool:` - - `class ResponseFormatText:` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Default response format. Used to generate text responses. + - `class BetaComputerUsePreviewTool:` - - `JsonValue; type "text"constant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of response format being defined. Always `text`. + - `class BetaWebSearchTool:` - - `TEXT("text")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class ResponseFormatJsonObject:` + - `Mcp` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `CodeInterpreter` - - `JsonValue; type "json_object"constant` + - `JsonValue;` - The type of response format being defined. Always `json_object`. + - `ImageGeneration` - - `JSON_OBJECT("json_object")` + - `JsonValue;` - - `class ResponseFormatJsonSchema:` + - `class BetaFunctionShellTool:` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A tool that allows the model to execute shell commands. - - `JsonSchema jsonSchema` + - `class BetaCustomTool:` - Structured Outputs configuration options, including a JSON Schema. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `String name` + - `class BetaNamespaceTool:` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + Groups function/custom tools under a shared namespace. - - `Optional description` + - `class BetaToolSearchTool:` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Hosted or BYOT tool search configuration for deferred tools. - - `Optional schema` + - `class BetaWebSearchPreviewTool:` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional strict` + - `class BetaApplyPatchTool:` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + Allows the assistant to create, delete, or update files using unified diffs. - - `JsonValue; type "json_schema"constant` + - `JsonValue; type "tool_search_output"constant` - The type of response format being defined. Always `json_schema`. + The type of the item. Always `tool_search_output`. - - `JSON_SCHEMA("json_schema")` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `Optional startedAt` + - `Optional agent` - The Unix timestamp (in seconds) for when the run was started. + The agent that produced this item. - - `JsonValue status` + - `String agentName` - - `String threadId` + The canonical name of the agent that produced this item. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `Optional createdBy` - - `Optional toolChoice` + The identifier of the actor that created the item. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `AdditionalTools` - - `Auto` + - `String id` - - `NONE("none")` + The unique ID of the additional tools item. - - `AUTO("auto")` + - `Role role` - - `REQUIRED("required")` + The role that provided the additional tools. - - `class AssistantToolChoice:` + - `UNKNOWN("unknown")` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `USER("user")` - - `Type type` + - `ASSISTANT("assistant")` - The type of the tool. If type is `function`, the function name must be set + - `SYSTEM("system")` - - `FUNCTION("function")` + - `CRITIC("critic")` - - `CODE_INTERPRETER("code_interpreter")` + - `DISCRIMINATOR("discriminator")` - - `FILE_SEARCH("file_search")` + - `DEVELOPER("developer")` - - `Optional function` + - `TOOL("tool")` - - `String name` + - `List tools` - The name of the function to call. + The additional tool definitions made available at this item. - - `List tools` + - `class BetaFunctionTool:` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `Optional truncationStrategy` + - `class BetaFileSearchTool:` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Type type` + - `class BetaComputerTool:` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `AUTO("auto")` + - `class BetaComputerUsePreviewTool:` - - `LAST_MESSAGES("last_messages")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional lastMessages` + - `class BetaWebSearchTool:` - The number of most recent messages from the thread when constructing the context for the run. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional usage` + - `Mcp` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `CodeInterpreter` - - `long completionTokens` + - `JsonValue;` - Number of completion tokens used over the course of the run. + - `ImageGeneration` - - `long promptTokens` + - `JsonValue;` - Number of prompt tokens used over the course of the run. + - `class BetaFunctionShellTool:` - - `long totalTokens` + A tool that allows the model to execute shell commands. - Total number of tokens used (prompt + completion). + - `class BetaCustomTool:` - - `Optional temperature` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The sampling temperature used for this run. If not set, defaults to 1. + - `class BetaNamespaceTool:` - - `Optional topP` + Groups function/custom tools under a shared namespace. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `class BetaToolSearchTool:` -### Run Status + Hosted or BYOT tool search configuration for deferred tools. -- `class RunStatus:` + - `class BetaWebSearchPreviewTool:` -# Steps + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -## List run steps + - `class BetaApplyPatchTool:` -`StepListPage beta().threads().runs().steps().list(StepListParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + Allows the assistant to create, delete, or update files using unified diffs. -**get** `/threads/{thread_id}/runs/{run_id}/steps` + - `JsonValue; type "additional_tools"constant` -List run steps + The type of the item. Always `additional_tools`. -### Parameters + - `ADDITIONAL_TOOLS("additional_tools")` -- `StepListParams params` + - `Optional agent` - - `String threadId` + The agent that produced this item. - - `Optional runId` + - `String agentName` - - `Optional after` + The canonical name of the agent that produced this item. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `class BetaResponseCompactionItem:` - - `Optional before` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `String id` - - `Optional> include` + The unique ID of the compaction item. - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + - `String encryptedContent` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The encrypted content that was produced by compaction. - - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` + - `JsonValue; type "compaction"constant` - - `Optional limit` + The type of the item. Always `compaction`. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `COMPACTION("compaction")` - - `Optional order` + - `Optional agent` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + The agent that produced this item. - - `ASC("asc")` + - `String agentName` - - `DESC("desc")` + The canonical name of the agent that produced this item. -### Returns + - `Optional createdBy` -- `class RunStep:` + The identifier of the actor that created the item. - Represents a step in execution of a run. + - `ImageGenerationCall` - `String id` - The identifier of the run step, which can be referenced in API endpoints. + The unique ID of the image generation call. - - `String assistantId` + - `Optional result` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + The generated image encoded in base64. - - `Optional cancelledAt` + - `Status status` - The Unix timestamp (in seconds) for when the run step was cancelled. + The status of the image generation call. - - `Optional completedAt` + - `IN_PROGRESS("in_progress")` - The Unix timestamp (in seconds) for when the run step completed. + - `COMPLETED("completed")` - - `long createdAt` + - `GENERATING("generating")` - The Unix timestamp (in seconds) for when the run step was created. + - `FAILED("failed")` - - `Optional expiredAt` + - `JsonValue; type "image_generation_call"constant` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The type of the image generation call. Always `image_generation_call`. - - `Optional failedAt` + - `IMAGE_GENERATION_CALL("image_generation_call")` - The Unix timestamp (in seconds) for when the run step failed. + - `Optional agent` - - `Optional lastError` + The agent that produced this item. - The last error associated with this run step. Will be `null` if there are no errors. + - `String agentName` - - `Code code` + The canonical name of the agent that produced this item. - One of `server_error` or `rate_limit_exceeded`. + - `class BetaResponseCodeInterpreterToolCall:` - - `SERVER_ERROR("server_error")` + A tool call to run code. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `LocalShellCall` - - `String message` + - `String id` - A human-readable description of the error. + The unique ID of the local shell call. - - `Optional metadata` + - `Action action` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Execute a shell command on the server. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `List command` - - `JsonValue; object_ "thread.run.step"constant` + The command to run. - The object type, which is always `thread.run.step`. + - `Env env` - - `THREAD_RUN_STEP("thread.run.step")` + Environment variables to set for the command. - - `String runId` + - `JsonValue; type "exec"constant` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + The type of the local shell action. Always `exec`. - - `Status status` + - `EXEC("exec")` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `Optional timeoutMs` - - `IN_PROGRESS("in_progress")` + Optional timeout in milliseconds for the command. - - `CANCELLED("cancelled")` + - `Optional user` - - `FAILED("failed")` + Optional user to run the command as. - - `COMPLETED("completed")` + - `Optional workingDirectory` - - `EXPIRED("expired")` + Optional working directory to run the command in. - - `StepDetails stepDetails` + - `String callId` - The details of the run step. + The unique ID of the local shell tool call generated by the model. - - `class MessageCreationStepDetails:` + - `Status status` - Details of the message creation by the run step. + The status of the local shell call. - - `MessageCreation messageCreation` + - `IN_PROGRESS("in_progress")` - - `String messageId` + - `COMPLETED("completed")` - The ID of the message that was created by this run step. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "message_creation"constant` + - `JsonValue; type "local_shell_call"constant` - Always `message_creation`. + The type of the local shell call. Always `local_shell_call`. - - `MESSAGE_CREATION("message_creation")` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `class ToolCallsStepDetails:` + - `Optional agent` - Details of the tool call. + The agent that produced this item. - - `List toolCalls` + - `String agentName` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The canonical name of the agent that produced this item. - - `JsonValue; type "tool_calls"constant` + - `LocalShellCallOutput` - Always `tool_calls`. + - `String id` - - `TOOL_CALLS("tool_calls")` + The unique ID of the local shell tool call generated by the model. - - `String threadId` + - `String output` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + A JSON string of the output of the local shell tool call. - - `Type type` + - `JsonValue; type "local_shell_call_output"constant` - The type of run step, which can be either `message_creation` or `tool_calls`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `MESSAGE_CREATION("message_creation")` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `TOOL_CALLS("tool_calls")` + - `Optional agent` - - `Optional usage` + The agent that produced this item. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `String agentName` - - `long completionTokens` + The canonical name of the agent that produced this item. - Number of completion tokens used over the course of the run step. + - `Optional status` - - `long promptTokens` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Number of prompt tokens used over the course of the run step. + - `IN_PROGRESS("in_progress")` - - `long totalTokens` + - `COMPLETED("completed")` - Total number of tokens used (prompt + completion). + - `INCOMPLETE("incomplete")` -### Example + - `class BetaResponseFunctionShellToolCall:` -```java -package com.openai.example; + A tool call that executes one or more shell commands in a managed environment. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.steps.StepListPage; -import com.openai.models.beta.threads.runs.steps.StepListParams; + - `String id` -public final class Main { - private Main() {} + The unique ID of the shell tool call. Populated when this item is returned via API. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Action action` - StepListParams params = StepListParams.builder() - .threadId("thread_id") - .runId("run_id") - .build(); - StepListPage page = client.beta().threads().runs().steps().list(params); - } -} -``` + The shell commands and limits that describe how to run the tool call. -#### Response + - `List commands` -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } - } - ], - "first_id": "step_abc123", - "has_more": false, - "last_id": "step_abc456", - "object": "list" -} -``` + - `Optional maxOutputLength` -## Retrieve run step + Optional maximum number of characters to return from each command. -`RunStep beta().threads().runs().steps().retrieve(StepRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `Optional timeoutMs` -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` + Optional timeout in milliseconds for the commands. -Retrieve run step + - `String callId` -### Parameters + The unique ID of the shell tool call generated by the model. -- `StepRetrieveParams params` + - `Optional environment` - - `String threadId` + Represents the use of a local environment to perform shell actions. - - `String runId` + - `class BetaResponseLocalEnvironment:` - - `Optional stepId` + Represents the use of a local environment to perform shell actions. - - `Optional> include` + - `JsonValue; type "local"constant` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + The environment type. Always `local`. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `LOCAL("local")` - - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` + - `class BetaResponseContainerReference:` -### Returns + Represents a container created with /v1/containers. -- `class RunStep:` + - `String containerId` - Represents a step in execution of a run. + - `JsonValue; type "container_reference"constant` - - `String id` + The environment type. Always `container_reference`. - The identifier of the run step, which can be referenced in API endpoints. + - `CONTAINER_REFERENCE("container_reference")` - - `String assistantId` + - `Status status` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `Optional cancelledAt` + - `IN_PROGRESS("in_progress")` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `COMPLETED("completed")` - - `Optional completedAt` + - `INCOMPLETE("incomplete")` - The Unix timestamp (in seconds) for when the run step completed. + - `JsonValue; type "shell_call"constant` - - `long createdAt` + The type of the item. Always `shell_call`. - The Unix timestamp (in seconds) for when the run step was created. + - `SHELL_CALL("shell_call")` - - `Optional expiredAt` + - `Optional agent` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The agent that produced this item. - - `Optional failedAt` + - `String agentName` - The Unix timestamp (in seconds) for when the run step failed. + The canonical name of the agent that produced this item. - - `Optional lastError` + - `Optional caller` - The last error associated with this run step. Will be `null` if there are no errors. + The execution context that produced this tool call. - - `Code code` + - `JsonValue;` - One of `server_error` or `rate_limit_exceeded`. + - `JsonValue; type "direct"constant` - - `SERVER_ERROR("server_error")` + - `DIRECT("direct")` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `class Program:` - - `String message` + - `String callerId` - A human-readable description of the error. + The call ID of the program item that produced this tool call. - - `Optional metadata` + - `JsonValue; type "program"constant` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `PROGRAM("program")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Optional createdBy` - - `JsonValue; object_ "thread.run.step"constant` + The ID of the entity that created this tool call. - The object type, which is always `thread.run.step`. + - `class BetaResponseFunctionShellToolCallOutput:` - - `THREAD_RUN_STEP("thread.run.step")` + The output of a shell tool call that was emitted. - - `String runId` + - `String id` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + The unique ID of the shell call output. Populated when this item is returned via API. - - `Status status` + - `String callId` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + The unique ID of the shell tool call generated by the model. - - `IN_PROGRESS("in_progress")` + - `Optional maxOutputLength` - - `CANCELLED("cancelled")` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `FAILED("failed")` + - `List output` - - `COMPLETED("completed")` + An array of shell call output contents - - `EXPIRED("expired")` + - `Outcome outcome` - - `StepDetails stepDetails` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The details of the run step. + - `JsonValue;` - - `class MessageCreationStepDetails:` + - `JsonValue; type "timeout"constant` - Details of the message creation by the run step. + The outcome type. Always `timeout`. - - `MessageCreation messageCreation` + - `TIMEOUT("timeout")` - - `String messageId` + - `class Exit:` - The ID of the message that was created by this run step. + Indicates that the shell commands finished and returned an exit code. - - `JsonValue; type "message_creation"constant` + - `long exitCode` - Always `message_creation`. + Exit code from the shell process. - - `MESSAGE_CREATION("message_creation")` + - `JsonValue; type "exit"constant` - - `class ToolCallsStepDetails:` + The outcome type. Always `exit`. - Details of the tool call. + - `EXIT("exit")` - - `List toolCalls` + - `String stderr` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The standard error output that was captured. - - `JsonValue; type "tool_calls"constant` + - `String stdout` - Always `tool_calls`. + The standard output that was captured. - - `TOOL_CALLS("tool_calls")` + - `Optional createdBy` - - `String threadId` + The identifier of the actor that created the item. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `Status status` - - `Type type` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `IN_PROGRESS("in_progress")` - - `MESSAGE_CREATION("message_creation")` + - `COMPLETED("completed")` - - `TOOL_CALLS("tool_calls")` + - `INCOMPLETE("incomplete")` - - `Optional usage` + - `JsonValue; type "shell_call_output"constant` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The type of the shell call output. Always `shell_call_output`. - - `long completionTokens` + - `SHELL_CALL_OUTPUT("shell_call_output")` - Number of completion tokens used over the course of the run step. + - `Optional agent` - - `long promptTokens` + The agent that produced this item. - Number of prompt tokens used over the course of the run step. + - `String agentName` - - `long totalTokens` + The canonical name of the agent that produced this item. - Total number of tokens used (prompt + completion). + - `Optional caller` -### Example + The execution context that produced this tool call. -```java -package com.openai.example; + - `JsonValue;` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.runs.steps.RunStep; -import com.openai.models.beta.threads.runs.steps.StepRetrieveParams; + - `JsonValue; type "direct"constant` -public final class Main { - private Main() {} + - `DIRECT("direct")` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `class Program:` - StepRetrieveParams params = StepRetrieveParams.builder() - .threadId("thread_id") - .runId("run_id") - .stepId("step_id") - .build(); - RunStep runStep = client.beta().threads().runs().steps().retrieve(params); - } -} -``` + - `String callerId` -#### Response + The call ID of the program item that produced this tool call. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } -} -``` + - `JsonValue; type "program"constant` -## Domain Types + - `PROGRAM("program")` -### Code Interpreter Logs + - `Optional createdBy` -- `class CodeInterpreterLogs:` + The identifier of the actor that created the item. - Text output from the Code Interpreter tool call as part of a run step. + - `class BetaResponseApplyPatchToolCall:` - - `long index` + A tool call that applies file diffs by creating, deleting, or updating files. - The index of the output in the outputs array. + - `String id` - - `JsonValue; type "logs"constant` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Always `logs`. + - `String callId` - - `LOGS("logs")` + The unique ID of the apply patch tool call generated by the model. - - `Optional logs` + - `Operation operation` - The text output from the Code Interpreter tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. -### Code Interpreter Output Image + - `class CreateFile:` -- `class CodeInterpreterOutputImage:` + Instruction describing how to create a file via the apply_patch tool. - - `long index` + - `String diff` - The index of the output in the outputs array. + Diff to apply. - - `JsonValue; type "image"constant` + - `String path` - Always `image`. + Path of the file to create. - - `IMAGE("image")` + - `JsonValue; type "create_file"constant` - - `Optional image` + Create a new file with the provided diff. - - `Optional fileId` + - `CREATE_FILE("create_file")` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `class DeleteFile:` -### Code Interpreter Tool Call + Instruction describing how to delete a file via the apply_patch tool. -- `class CodeInterpreterToolCall:` + - `String path` - Details of the Code Interpreter tool call the run step was involved in. + Path of the file to delete. - - `String id` + - `JsonValue; type "delete_file"constant` - The ID of the tool call. + Delete the specified file. - - `CodeInterpreter codeInterpreter` + - `DELETE_FILE("delete_file")` - The Code Interpreter tool call definition. + - `class UpdateFile:` - - `String input` + Instruction describing how to update a file via the apply_patch tool. - The input to the Code Interpreter tool call. + - `String diff` - - `List outputs` + Diff to apply. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `String path` - - `class LogsOutput:` + Path of the file to update. - Text output from the Code Interpreter tool call as part of a run step. + - `JsonValue; type "update_file"constant` - - `String logs` + Update an existing file with the provided diff. - The text output from the Code Interpreter tool call. + - `UPDATE_FILE("update_file")` - - `JsonValue; type "logs"constant` + - `Status status` - Always `logs`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `LOGS("logs")` + - `IN_PROGRESS("in_progress")` - - `class ImageOutput:` + - `COMPLETED("completed")` - - `Image image` + - `JsonValue; type "apply_patch_call"constant` - - `String fileId` + The type of the item. Always `apply_patch_call`. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `APPLY_PATCH_CALL("apply_patch_call")` - - `JsonValue; type "image"constant` + - `Optional agent` - Always `image`. + The agent that produced this item. - - `IMAGE("image")` + - `String agentName` - - `JsonValue; type "code_interpreter"constant` + The canonical name of the agent that produced this item. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `Optional caller` - - `CODE_INTERPRETER("code_interpreter")` + The execution context that produced this tool call. -### Code Interpreter Tool Call Delta + - `JsonValue;` -- `class CodeInterpreterToolCallDelta:` + - `JsonValue; type "direct"constant` - Details of the Code Interpreter tool call the run step was involved in. + - `DIRECT("direct")` - - `long index` + - `class Program:` - The index of the tool call in the tool calls array. + - `String callerId` - - `JsonValue; type "code_interpreter"constant` + The call ID of the program item that produced this tool call. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `JsonValue; type "program"constant` - - `CODE_INTERPRETER("code_interpreter")` + - `PROGRAM("program")` - - `Optional id` + - `Optional createdBy` - The ID of the tool call. + The ID of the entity that created this tool call. - - `Optional codeInterpreter` + - `class BetaResponseApplyPatchToolCallOutput:` - The Code Interpreter tool call definition. + The output emitted by an apply patch tool call. - - `Optional input` + - `String id` - The input to the Code Interpreter tool call. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `Optional> outputs` + - `String callId` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + The unique ID of the apply patch tool call generated by the model. - - `class CodeInterpreterLogs:` + - `Status status` - Text output from the Code Interpreter tool call as part of a run step. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `long index` + - `COMPLETED("completed")` - The index of the output in the outputs array. + - `FAILED("failed")` - - `JsonValue; type "logs"constant` + - `JsonValue; type "apply_patch_call_output"constant` - Always `logs`. + The type of the item. Always `apply_patch_call_output`. - - `LOGS("logs")` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `Optional logs` + - `Optional agent` - The text output from the Code Interpreter tool call. + The agent that produced this item. - - `class CodeInterpreterOutputImage:` + - `String agentName` - - `long index` + The canonical name of the agent that produced this item. - The index of the output in the outputs array. + - `Optional caller` - - `JsonValue; type "image"constant` + The execution context that produced this tool call. - Always `image`. + - `JsonValue;` - - `IMAGE("image")` + - `JsonValue; type "direct"constant` - - `Optional image` + - `DIRECT("direct")` - - `Optional fileId` + - `class Program:` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `String callerId` -### File Search Tool Call + The call ID of the program item that produced this tool call. -- `class FileSearchToolCall:` + - `JsonValue; type "program"constant` - - `String id` + - `PROGRAM("program")` - The ID of the tool call object. + - `Optional createdBy` - - `FileSearch fileSearch` + The ID of the entity that created this tool call output. - For now, this is always going to be an empty object. + - `Optional output` - - `Optional rankingOptions` + Optional textual output returned by the apply patch tool. - The ranking options for the file search. + - `McpCall` - - `Ranker ranker` + - `String id` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The unique ID of the tool call. - - `AUTO("auto")` + - `String arguments` - - `DEFAULT_2024_08_21("default_2024_08_21")` + A JSON string of the arguments passed to the tool. - - `double scoreThreshold` + - `String name` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The name of the tool that was run. - - `Optional> results` + - `String serverLabel` - The results of the file search. + The label of the MCP server running the tool. - - `String fileId` + - `JsonValue; type "mcp_call"constant` - The ID of the file that result was found in. + The type of the item. Always `mcp_call`. - - `String fileName` + - `MCP_CALL("mcp_call")` - The name of the file that result was found in. + - `Optional agent` - - `double score` + The agent that produced this item. - The score of the result. All values must be a floating point number between 0 and 1. + - `String agentName` - - `Optional> content` + The canonical name of the agent that produced this item. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `Optional approvalRequestId` - - `Optional text` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The text content of the file. + - `Optional error` - - `Optional type` + The error from the tool call, if any. - The type of the content. + - `Optional output` - - `TEXT("text")` + The output from the tool call. - - `JsonValue; type "file_search"constant` + - `Optional status` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `FILE_SEARCH("file_search")` + - `IN_PROGRESS("in_progress")` -### File Search Tool Call Delta + - `COMPLETED("completed")` -- `class FileSearchToolCallDelta:` + - `INCOMPLETE("incomplete")` - - `JsonValue fileSearch` + - `CALLING("calling")` - For now, this is always going to be an empty object. + - `FAILED("failed")` - - `long index` + - `McpListTools` - The index of the tool call in the tool calls array. + - `String id` - - `JsonValue; type "file_search"constant` + The unique ID of the list. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `String serverLabel` - - `FILE_SEARCH("file_search")` + The label of the MCP server. - - `Optional id` + - `List tools` - The ID of the tool call object. + The tools available on the server. -### Function Tool Call + - `JsonValue inputSchema` -- `class FunctionToolCall:` + The JSON schema describing the tool's input. - - `String id` + - `String name` - The ID of the tool call object. + The name of the tool. - - `Function function` + - `Optional annotations` - The definition of the function that was called. + Additional annotations about the tool. - - `String arguments` + - `Optional description` - The arguments passed to the function. + The description of the tool. - - `String name` + - `JsonValue; type "mcp_list_tools"constant` - The name of the function. + The type of the item. Always `mcp_list_tools`. - - `Optional output` + - `MCP_LIST_TOOLS("mcp_list_tools")` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `Optional agent` - - `JsonValue; type "function"constant` + The agent that produced this item. - The type of tool call. This is always going to be `function` for this type of tool call. + - `String agentName` - - `FUNCTION("function")` + The canonical name of the agent that produced this item. -### Function Tool Call Delta + - `Optional error` -- `class FunctionToolCallDelta:` + Error message if the server could not list tools. - - `long index` + - `McpApprovalRequest` - The index of the tool call in the tool calls array. + - `String id` - - `JsonValue; type "function"constant` + The unique ID of the approval request. - The type of tool call. This is always going to be `function` for this type of tool call. + - `String arguments` - - `FUNCTION("function")` + A JSON string of arguments for the tool. - - `Optional id` + - `String name` - The ID of the tool call object. + The name of the tool to run. - - `Optional function` + - `String serverLabel` - The definition of the function that was called. + The label of the MCP server making the request. - - `Optional arguments` + - `JsonValue; type "mcp_approval_request"constant` - The arguments passed to the function. + The type of the item. Always `mcp_approval_request`. - - `Optional name` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - The name of the function. + - `Optional agent` - - `Optional output` + The agent that produced this item. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `String agentName` -### Message Creation Step Details + The canonical name of the agent that produced this item. -- `class MessageCreationStepDetails:` + - `McpApprovalResponse` - Details of the message creation by the run step. + - `String id` - - `MessageCreation messageCreation` + The unique ID of the approval response - - `String messageId` + - `String approvalRequestId` - The ID of the message that was created by this run step. + The ID of the approval request being answered. - - `JsonValue; type "message_creation"constant` + - `boolean approve` - Always `message_creation`. + Whether the request was approved. - - `MESSAGE_CREATION("message_creation")` + - `JsonValue; type "mcp_approval_response"constant` -### Run Step + The type of the item. Always `mcp_approval_response`. -- `class RunStep:` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - Represents a step in execution of a run. + - `Optional agent` - - `String id` + The agent that produced this item. - The identifier of the run step, which can be referenced in API endpoints. + - `String agentName` - - `String assistantId` + The canonical name of the agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `Optional reason` - - `Optional cancelledAt` + Optional reason for the decision. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `class BetaResponseCustomToolCall:` - - `Optional completedAt` + A call to a custom tool created by the model. - The Unix timestamp (in seconds) for when the run step completed. + - `class BetaResponseCustomToolCallOutputItem:` - - `long createdAt` + The output of a custom tool call from your code, being sent back to the model. - The Unix timestamp (in seconds) for when the run step was created. + - `String id` - - `Optional expiredAt` + The unique ID of the custom tool call output item. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `Status status` - - `Optional failedAt` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The Unix timestamp (in seconds) for when the run step failed. + - `IN_PROGRESS("in_progress")` - - `Optional lastError` + - `COMPLETED("completed")` - The last error associated with this run step. Will be `null` if there are no errors. + - `INCOMPLETE("incomplete")` - - `Code code` + - `Optional createdBy` - One of `server_error` or `rate_limit_exceeded`. + The identifier of the actor that created the item. - - `SERVER_ERROR("server_error")` + - `boolean parallelToolCalls` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + Whether to allow the model to run tool calls in parallel. - - `String message` + - `Optional temperature` - A human-readable description of the error. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `Optional metadata` + - `ToolChoice toolChoice` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `enum BetaToolChoiceOptions:` - - `JsonValue; object_ "thread.run.step"constant` + Controls which (if any) tool is called by the model. - The object type, which is always `thread.run.step`. + `none` means the model will not call any tool and instead generates a message. - - `THREAD_RUN_STEP("thread.run.step")` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `String runId` + `required` means the model must call one or more tools. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `NONE("none")` - - `Status status` + - `AUTO("auto")` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `REQUIRED("required")` - - `IN_PROGRESS("in_progress")` + - `class BetaToolChoiceAllowed:` - - `CANCELLED("cancelled")` + Constrains the tools available to the model to a pre-defined set. - - `FAILED("failed")` + - `Mode mode` - - `COMPLETED("completed")` + Constrains the tools available to the model to a pre-defined set. - - `EXPIRED("expired")` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `StepDetails stepDetails` + `required` requires the model to call one or more of the allowed tools. - The details of the run step. + - `AUTO("auto")` - - `class MessageCreationStepDetails:` + - `REQUIRED("required")` - Details of the message creation by the run step. + - `List tools` - - `MessageCreation messageCreation` + A list of tool definitions that the model should be allowed to call. - - `String messageId` + For the Responses API, the list of tool definitions might look like: - The ID of the message that was created by this run step. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `JsonValue; type "message_creation"constant` + - `JsonValue; type "allowed_tools"constant` - Always `message_creation`. + Allowed tool configuration type. Always `allowed_tools`. - - `MESSAGE_CREATION("message_creation")` + - `ALLOWED_TOOLS("allowed_tools")` - - `class ToolCallsStepDetails:` + - `class BetaToolChoiceTypes:` - Details of the tool call. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `List toolCalls` + - `Type type` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `JsonValue; type "tool_calls"constant` + Allowed values are: - Always `tool_calls`. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `TOOL_CALLS("tool_calls")` + - `FILE_SEARCH("file_search")` - - `String threadId` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `COMPUTER("computer")` - - `Type type` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `COMPUTER_USE("computer_use")` - - `MESSAGE_CREATION("message_creation")` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `TOOL_CALLS("tool_calls")` + - `IMAGE_GENERATION("image_generation")` - - `Optional usage` + - `CODE_INTERPRETER("code_interpreter")` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `class BetaToolChoiceFunction:` - - `long completionTokens` + Use this option to force the model to call a specific function. - Number of completion tokens used over the course of the run step. + - `String name` - - `long promptTokens` + The name of the function to call. - Number of prompt tokens used over the course of the run step. + - `JsonValue; type "function"constant` - - `long totalTokens` + For function calling, the type is always `function`. - Total number of tokens used (prompt + completion). + - `FUNCTION("function")` -### Run Step Delta + - `class BetaToolChoiceMcp:` -- `class RunStepDelta:` + Use this option to force the model to call a specific tool on a remote MCP server. -### Run Step Delta Event + - `String serverLabel` -- `class RunStepDeltaEvent:` + The label of the MCP server to use. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `JsonValue; type "mcp"constant` - - `String id` + For MCP tools, the type is always `mcp`. - The identifier of the run step, which can be referenced in API endpoints. + - `MCP("mcp")` - - `JsonValue delta` + - `Optional name` - - `JsonValue; object_ "thread.run.step.delta"constant` + The name of the tool to call on the server. - The object type, which is always `thread.run.step.delta`. + - `class BetaToolChoiceCustom:` - - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` + Use this option to force the model to call a specific custom tool. -### Run Step Delta Message Delta + - `String name` -- `class RunStepDeltaMessageDelta:` + The name of the custom tool to call. - Details of the message creation by the run step. + - `JsonValue; type "custom"constant` - - `JsonValue; type "message_creation"constant` + For custom tool calling, the type is always `custom`. - Always `message_creation`. + - `CUSTOM("custom")` - - `MESSAGE_CREATION("message_creation")` + - `JsonValue;` - - `Optional messageCreation` + - `JsonValue; type "programmatic_tool_calling"constant` - - `Optional messageId` + The tool to call. Always `programmatic_tool_calling`. - The ID of the message that was created by this run step. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` -### Run Step Include + - `class BetaToolChoiceApplyPatch:` -- `enum RunStepInclude:` + Forces the model to call the apply_patch tool when executing a tool call. - - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` + - `JsonValue; type "apply_patch"constant` -### Tool Call + The tool to call. Always `apply_patch`. -- `class ToolCall:` + - `APPLY_PATCH("apply_patch")` -### Tool Call Delta + - `class BetaToolChoiceShell:` -- `class ToolCallDelta:` + Forces the model to call the shell tool when a tool call is required. -### Tool Call Delta Object + - `JsonValue; type "shell"constant` -- `class ToolCallDeltaObject:` + The tool to call. Always `shell`. - Details of the tool call. + - `SHELL("shell")` - - `JsonValue; type "tool_calls"constant` + - `List tools` - Always `tool_calls`. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `TOOL_CALLS("tool_calls")` + We support the following categories of tools: - - `Optional> toolCalls` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `class BetaFunctionTool:` -### Tool Calls Step Details + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). -- `class ToolCallsStepDetails:` + - `class BetaFileSearchTool:` - Details of the tool call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `List toolCalls` + - `class BetaComputerTool:` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; type "tool_calls"constant` + - `class BetaComputerUsePreviewTool:` - Always `tool_calls`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `TOOL_CALLS("tool_calls")` + - `class BetaWebSearchTool:` -# Messages + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -## List messages + - `Mcp` -`MessageListPage beta().threads().messages().list(MessageListParamsparams = MessageListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `CodeInterpreter` -**get** `/threads/{thread_id}/messages` + - `JsonValue;` -List messages + - `ImageGeneration` -### Parameters + - `JsonValue;` -- `MessageListParams params` + - `class BetaFunctionShellTool:` - - `Optional threadId` + A tool that allows the model to execute shell commands. - - `Optional after` + - `class BetaCustomTool:` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional before` + - `class BetaNamespaceTool:` - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + Groups function/custom tools under a shared namespace. - - `Optional limit` + - `class BetaToolSearchTool:` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + Hosted or BYOT tool search configuration for deferred tools. - - `Optional order` + - `class BetaWebSearchPreviewTool:` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `ASC("asc")` + - `class BetaApplyPatchTool:` - - `DESC("desc")` + Allows the assistant to create, delete, or update files using unified diffs. - - `Optional runId` + - `Optional topP` - Filter messages by the run ID that generated them. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. -### Returns + We generally recommend altering this or `temperature` but not both. -- `class Message:` + - `Optional background` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `String id` + - `Optional completedAt` - The identifier, which can be referenced in API endpoints. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Optional assistantId` + - `Optional conversation` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `Optional> attachments` + - `String id` - A list of files attached to the message, and the tools they were added to. + The unique ID of the conversation that this response was associated with. - - `Optional fileId` + - `Optional maxOutputTokens` - The ID of the file to attach to the message. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `Optional> tools` + - `Optional maxToolCalls` - The tools to add this file to. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `class CodeInterpreterTool:` + - `Optional moderation` - - `JsonValue; type "code_interpreter"constant` + Moderation results for the response input and output, if moderated completions were requested. - The type of tool being defined: `code_interpreter` + - `Input input` - - `CODE_INTERPRETER("code_interpreter")` + Moderation for the response input. - - `JsonValue;` + - `class ModerationResult:` - - `JsonValue; type "file_search"constant` + A moderation result produced for the response input or output. - The type of tool being defined: `file_search` + - `Categories categories` - - `FILE_SEARCH("file_search")` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `Optional completedAt` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - The Unix timestamp (in seconds) for when the message was completed. + Which modalities of input are reflected by the score for each category. - - `List content` + - `TEXT("text")` - The content of the message in array of text and/or images. + - `IMAGE("image")` - - `long createdAt` + - `CategoryScores categoryScores` - The Unix timestamp (in seconds) for when the message was created. + A dictionary of moderation categories to scores. - - `Optional incompleteAt` + - `boolean flagged` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + A boolean indicating whether the content was flagged by any category. - - `Optional incompleteDetails` + - `String model` - On an incomplete message, details about why the message is incomplete. + The moderation model that produced this result. - - `Reason reason` + - `JsonValue; type "moderation_result"constant` - The reason the message is incomplete. + The object type, which was always `moderation_result` for successful moderation results. - - `CONTENT_FILTER("content_filter")` + - `MODERATION_RESULT("moderation_result")` - - `MAX_TOKENS("max_tokens")` + - `class Error:` - - `RUN_CANCELLED("run_cancelled")` + An error produced while attempting moderation for the response input or output. - - `RUN_EXPIRED("run_expired")` + - `String code` - - `RUN_FAILED("run_failed")` + The error code. - - `Optional metadata` + - `String message` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The error message. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `JsonValue; type "error"constant` - - `JsonValue; object_ "thread.message"constant` + The object type, which was always `error` for moderation failures. - The object type, which is always `thread.message`. + - `ERROR("error")` - - `THREAD_MESSAGE("thread.message")` + - `Output output` - - `Role role` + Moderation for the response output. - The entity that produced the message. One of `user` or `assistant`. + - `class ModerationResult:` - - `USER("user")` + A moderation result produced for the response input or output. - - `ASSISTANT("assistant")` + - `Categories categories` - - `Optional runId` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `Status status` + Which modalities of input are reflected by the score for each category. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `TEXT("text")` - - `IN_PROGRESS("in_progress")` + - `IMAGE("image")` - - `INCOMPLETE("incomplete")` + - `CategoryScores categoryScores` - - `COMPLETED("completed")` + A dictionary of moderation categories to scores. - - `String threadId` + - `boolean flagged` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + A boolean indicating whether the content was flagged by any category. -### Example + - `String model` -```java -package com.openai.example; + The moderation model that produced this result. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.messages.MessageListPage; -import com.openai.models.beta.threads.messages.MessageListParams; + - `JsonValue; type "moderation_result"constant` -public final class Main { - private Main() {} + The object type, which was always `moderation_result` for successful moderation results. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `MODERATION_RESULT("moderation_result")` - MessageListPage page = client.beta().threads().messages().list("thread_id"); - } -} -``` + - `class Error:` -#### Response + An error produced while attempting moderation for the response input or output. -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" - } - ], - "first_id": "msg_abc123", - "has_more": false, - "last_id": "msg_abc123", - "object": "list" -} -``` + - `String code` -## Create message + The error code. -`Message beta().threads().messages().create(MessageCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `String message` -**post** `/threads/{thread_id}/messages` + The error message. -Create message + - `JsonValue; type "error"constant` -### Parameters + The object type, which was always `error` for moderation failures. -- `MessageCreateParams params` + - `ERROR("error")` - - `Optional threadId` + - `Optional previousResponseId` - - `Content content` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The text contents of the message. + - `Optional prompt` - - `String` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `List` + - `String id` - - `class ImageFileContentBlock:` + The unique identifier of the prompt template to use. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `Optional variables` - - `ImageFile imageFile` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `String fileId` + - `String` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `class BetaResponseInputText:` - - `Optional detail` + A text input to the model. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `class BetaResponseInputImage:` - - `AUTO("auto")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `LOW("low")` + - `class BetaResponseInputFile:` - - `HIGH("high")` + A file input to the model. - - `JsonValue; type "image_file"constant` + - `Optional version` - Always `image_file`. + Optional version of the prompt template. - - `IMAGE_FILE("image_file")` + - `Optional promptCacheKey` - - `class ImageUrlContentBlock:` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - References an image URL in the content of a message. + - `Optional promptCacheOptions` - - `ImageUrl imageUrl` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `String url` + - `Mode mode` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Whether implicit prompt-cache breakpoints were enabled. - - `Optional detail` + - `IMPLICIT("implicit")` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `EXPLICIT("explicit")` - - `AUTO("auto")` + - `Ttl ttl` - - `LOW("low")` + The minimum lifetime applied to each cache breakpoint. - - `HIGH("high")` + - `_30M("30m")` - - `JsonValue; type "image_url"constant` + - `Optional promptCacheRetention` - The type of the content part. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `IMAGE_URL("image_url")` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `class TextContentBlockParam:` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The text content that is part of a message. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `String text` + - `IN_MEMORY("in_memory")` - Text content to be sent to the model + - `_24H("24h")` - - `JsonValue; type "text"constant` + - `Optional reasoning` - Always `text`. + **gpt-5 and o-series models only** - - `TEXT("text")` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `Role role` + - `Optional context` - The role of the entity that is creating the message. Allowed values include: + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `AUTO("auto")` - - `USER("user")` + - `CURRENT_TURN("current_turn")` - - `ASSISTANT("assistant")` + - `ALL_TURNS("all_turns")` - - `Optional> attachments` + - `Optional effort` - A list of files attached to the message, and the tools they should be added to. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `Optional fileId` + - `NONE("none")` - The ID of the file to attach to the message. + - `MINIMAL("minimal")` - - `Optional> tools` + - `LOW("low")` - The tools to add this file to. + - `MEDIUM("medium")` - - `class CodeInterpreterTool:` + - `HIGH("high")` - - `JsonValue; type "code_interpreter"constant` + - `XHIGH("xhigh")` - The type of tool being defined: `code_interpreter` + - `MAX("max")` - - `CODE_INTERPRETER("code_interpreter")` + - `Optional generateSummary` - - `JsonValue;` + **Deprecated:** use `summary` instead. - - `JsonValue; type "file_search"constant` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The type of tool being defined: `file_search` + - `AUTO("auto")` - - `FILE_SEARCH("file_search")` + - `CONCISE("concise")` - - `Optional metadata` + - `DETAILED("detailed")` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional mode` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Controls the reasoning execution mode for the request. -### Returns + When returned on a response, this is the effective execution mode. -- `class Message:` + - `STANDARD("standard")` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `PRO("pro")` - - `String id` + - `Optional summary` - The identifier, which can be referenced in API endpoints. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `Optional assistantId` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `AUTO("auto")` - - `Optional> attachments` + - `CONCISE("concise")` - A list of files attached to the message, and the tools they were added to. + - `DETAILED("detailed")` - - `Optional fileId` + - `Optional safetyIdentifier` - The ID of the file to attach to the message. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `Optional> tools` + - `Optional serviceTier` - The tools to add this file to. + Specifies the processing type used for serving the request. - - `class CodeInterpreterTool:` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `JsonValue; type "code_interpreter"constant` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The type of tool being defined: `code_interpreter` + - `AUTO("auto")` - - `CODE_INTERPRETER("code_interpreter")` + - `DEFAULT("default")` - - `JsonValue;` + - `FLEX("flex")` - - `JsonValue; type "file_search"constant` + - `SCALE("scale")` - The type of tool being defined: `file_search` + - `PRIORITY("priority")` - - `FILE_SEARCH("file_search")` + - `Optional status` - - `Optional completedAt` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The Unix timestamp (in seconds) for when the message was completed. + - `COMPLETED("completed")` - - `List content` + - `FAILED("failed")` - The content of the message in array of text and/or images. + - `IN_PROGRESS("in_progress")` - - `long createdAt` + - `CANCELLED("cancelled")` - The Unix timestamp (in seconds) for when the message was created. + - `QUEUED("queued")` - - `Optional incompleteAt` + - `INCOMPLETE("incomplete")` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `Optional text` - - `Optional incompleteDetails` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - On an incomplete message, details about why the message is incomplete. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `Reason reason` + - `Optional format` - The reason the message is incomplete. + An object specifying the format that the model must output. - - `CONTENT_FILTER("content_filter")` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `MAX_TOKENS("max_tokens")` + The default format is `{ "type": "text" }` with no additional options. - - `RUN_CANCELLED("run_cancelled")` + **Not recommended for gpt-4o and newer models:** - - `RUN_EXPIRED("run_expired")` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `RUN_FAILED("run_failed")` + - `JsonValue;` - - `Optional metadata` + - `JsonValue; type "text"constant` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The type of response format being defined. Always `text`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `TEXT("text")` - - `JsonValue; object_ "thread.message"constant` + - `class BetaResponseFormatTextJsonSchemaConfig:` - The object type, which is always `thread.message`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `THREAD_MESSAGE("thread.message")` + - `String name` - - `Role role` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The entity that produced the message. One of `user` or `assistant`. + - `Schema schema` - - `USER("user")` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `ASSISTANT("assistant")` + - `JsonValue; type "json_schema"constant` - - `Optional runId` + The type of response format being defined. Always `json_schema`. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `JSON_SCHEMA("json_schema")` - - `Status status` + - `Optional description` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `IN_PROGRESS("in_progress")` + - `Optional strict` - - `INCOMPLETE("incomplete")` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `COMPLETED("completed")` + - `JsonValue;` - - `String threadId` + - `JsonValue; type "json_object"constant` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The type of response format being defined. Always `json_object`. + + - `JSON_OBJECT("json_object")` + + - `Optional verbosity` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional topLogprobs` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `Optional truncation` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `AUTO("auto")` + + - `DISABLED("disabled")` + + - `Optional usage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `long inputTokens` + + The number of input tokens. + + - `InputTokensDetails inputTokensDetails` + + A detailed breakdown of the input tokens. + + - `long cacheWriteTokens` + + The number of input tokens that were written to the cache. + + - `long cachedTokens` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `long outputTokens` + + The number of output tokens. + + - `OutputTokensDetails outputTokensDetails` + + A detailed breakdown of the output tokens. + + - `long reasoningTokens` + + The number of reasoning tokens. + + - `long totalTokens` + + The total number of tokens used. + + - `Optional user` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). ### Example @@ -12044,8 +10790,8 @@ package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.messages.Message; -import com.openai.models.beta.threads.messages.MessageCreateParams; +import com.openai.models.beta.responses.BetaResponse; +import com.openai.models.beta.responses.ResponseCreateParams; public final class Main { private Main() {} @@ -12053,12 +10799,7 @@ public final class Main { public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - MessageCreateParams params = MessageCreateParams.builder() - .threadId("thread_id") - .content("string") - .role(MessageCreateParams.Role.USER) - .build(); - Message message = client.beta().threads().messages().create(params); + BetaResponse betaResponse = client.beta().responses().create(); } } ``` @@ -12068,1487 +10809,20814 @@ public final class Main { ```json { "id": "id", - "assistant_id": "assistant_id", - "attachments": [ + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ { "file_id": "file_id", - "tools": [ + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ { - "type": "code_interpreter" + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] } ] } ], - "completed_at": 0, - "content": [ - {} + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" }, - "metadata": { + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { "foo": "string" }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" } ``` -## Modify message +## Get a model response -`Message beta().threads().messages().update(MessageUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` +`BetaResponse beta().responses().retrieve(ResponseRetrieveParamsparams = ResponseRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` -**post** `/threads/{thread_id}/messages/{message_id}` +**get** `/responses/{response_id}?beta=true` -Modify message +Retrieves a model response with the given ID. ### Parameters -- `MessageUpdateParams params` +- `ResponseRetrieveParams params` - - `String threadId` + - `Optional responseId` - - `Optional messageId` + - `Optional> include` - - `Optional metadata` + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` -### Returns + - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` -- `class Message:` + - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `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")` + + - `Optional includeObfuscation` + + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events + to normalize payload sizes as a mitigation to certain side-channel + attacks. These obfuscation fields are included by default, but add a + small amount of overhead to the data stream. You can set + `include_obfuscation` to false to optimize for bandwidth if you trust + the network links between your application and the OpenAI API. + + - `Optional startingAfter` + + The sequence number of the event after which to start streaming. + + - `Optional> betas` + + - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + +### Returns + +- `class BetaResponse:` - `String id` - The identifier, which can be referenced in API endpoints. + Unique identifier for this Response. - - `Optional assistantId` + - `double createdAt` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + Unix timestamp (in seconds) of when this Response was created. - - `Optional> attachments` + - `Optional error` - A list of files attached to the message, and the tools they were added to. + An error object returned when the model fails to generate a Response. - - `Optional fileId` + - `Code code` - The ID of the file to attach to the message. + The error code for the response. - - `Optional> tools` + - `SERVER_ERROR("server_error")` - The tools to add this file to. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `class CodeInterpreterTool:` + - `INVALID_PROMPT("invalid_prompt")` - - `JsonValue; type "code_interpreter"constant` + - `BIO_POLICY("bio_policy")` - The type of tool being defined: `code_interpreter` + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - `CODE_INTERPRETER("code_interpreter")` + - `INVALID_IMAGE("invalid_image")` - - `JsonValue;` + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - - `JsonValue; type "file_search"constant` + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - The type of tool being defined: `file_search` + - `INVALID_IMAGE_URL("invalid_image_url")` - - `FILE_SEARCH("file_search")` + - `IMAGE_TOO_LARGE("image_too_large")` - - `Optional completedAt` + - `IMAGE_TOO_SMALL("image_too_small")` - The Unix timestamp (in seconds) for when the message was completed. + - `IMAGE_PARSE_ERROR("image_parse_error")` - - `List content` + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - The content of the message in array of text and/or images. + - `INVALID_IMAGE_MODE("invalid_image_mode")` - - `long createdAt` + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - The Unix timestamp (in seconds) for when the message was created. + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - - `Optional incompleteAt` + - `EMPTY_IMAGE_FILE("empty_image_file")` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + + - `String message` + + A human-readable description of the error. - `Optional incompleteDetails` - On an incomplete message, details about why the message is incomplete. + Details about why the response is incomplete. - - `Reason reason` + - `Optional reason` - The reason the message is incomplete. + The reason why the response is incomplete. + + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - `CONTENT_FILTER("content_filter")` - - `MAX_TOKENS("max_tokens")` + - `Optional instructions` - - `RUN_CANCELLED("run_cancelled")` + A system (or developer) message inserted into the model's context. - - `RUN_EXPIRED("run_expired")` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `RUN_FAILED("run_failed")` + - `String` - - `Optional metadata` + - `List` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `class BetaEasyInputMessage:` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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. - - `JsonValue; object_ "thread.message"constant` + - `Content content` - The object type, which is always `thread.message`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `THREAD_MESSAGE("thread.message")` + - `String` + + - `List` + + - `class BetaResponseInputText:` + + 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `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 fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + 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` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` - `Role role` - The entity that produced the message. One of `user` or `assistant`. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - `USER("user")` - `ASSISTANT("assistant")` - - `Optional runId` + - `SYSTEM("system")` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `DEVELOPER("developer")` - - `Status status` + - `Optional phase` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `COMMENTARY("commentary")` + + - `FINAL_ANSWER("final_answer")` + + - `Optional type` + + The type of the message input. Always `message`. + + - `MESSAGE("message")` + + - `Message` + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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")` - - `COMPLETED("completed")` + - `Optional type` - - `String threadId` + The type of the message input. Always set to `message`. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `MESSAGE("message")` -### Example + - `class BetaResponseOutputMessage:` -```java -package com.openai.example; + An output message from the model. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.messages.Message; -import com.openai.models.beta.threads.messages.MessageUpdateParams; + - `String id` -public final class Main { - private Main() {} + The unique ID of the output message. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `List content` - MessageUpdateParams params = MessageUpdateParams.builder() - .threadId("thread_id") - .messageId("message_id") - .build(); - Message message = client.beta().threads().messages().update(params); - } -} -``` + The content of the output message. -#### Response + - `class BetaResponseOutputText:` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + A text output from the model. -## Retrieve message + - `List annotations` -`Message beta().threads().messages().retrieve(MessageRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + The annotations of the text output. -**get** `/threads/{thread_id}/messages/{message_id}` + - `class FileCitation:` -Retrieve message + A citation to a file. -### Parameters + - `String fileId` -- `MessageRetrieveParams params` + The ID of the file. - - `String threadId` + - `String filename` - - `Optional messageId` + The filename of the file cited. -### Returns + - `long index` -- `class Message:` + The index of the file in the list of files. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `JsonValue; type "file_citation"constant` - - `String id` + The type of the file citation. Always `file_citation`. - The identifier, which can be referenced in API endpoints. + - `FILE_CITATION("file_citation")` - - `Optional assistantId` + - `class UrlCitation:` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + A citation for a web resource used to generate a model response. - - `Optional> attachments` + - `long endIndex` - A list of files attached to the message, and the tools they were added to. + The index of the last character of the URL citation in the message. - - `Optional fileId` + - `long startIndex` - The ID of the file to attach to the message. + The index of the first character of the URL citation in the message. - - `Optional> tools` + - `String title` - The tools to add this file to. + The title of the web resource. - - `class CodeInterpreterTool:` + - `JsonValue; type "url_citation"constant` - - `JsonValue; type "code_interpreter"constant` + The type of the URL citation. Always `url_citation`. - The type of tool being defined: `code_interpreter` + - `URL_CITATION("url_citation")` - - `CODE_INTERPRETER("code_interpreter")` + - `String url` - - `JsonValue;` + The URL of the web resource. - - `JsonValue; type "file_search"constant` + - `class ContainerFileCitation:` - The type of tool being defined: `file_search` + A citation for a container file used to generate a model response. - - `FILE_SEARCH("file_search")` + - `String containerId` - - `Optional completedAt` + The ID of the container file. - The Unix timestamp (in seconds) for when the message was completed. + - `long endIndex` - - `List content` + The index of the last character of the container file citation in the message. - The content of the message in array of text and/or images. + - `String fileId` - - `long createdAt` + The ID of the file. - The Unix timestamp (in seconds) for when the message was created. + - `String filename` - - `Optional incompleteAt` + The filename of the container file cited. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `long startIndex` - - `Optional incompleteDetails` + The index of the first character of the container file citation in the message. - On an incomplete message, details about why the message is incomplete. + - `JsonValue; type "container_file_citation"constant` - - `Reason reason` + The type of the container file citation. Always `container_file_citation`. - The reason the message is incomplete. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `CONTENT_FILTER("content_filter")` + - `class FilePath:` - - `MAX_TOKENS("max_tokens")` + A path to a file. - - `RUN_CANCELLED("run_cancelled")` + - `String fileId` - - `RUN_EXPIRED("run_expired")` + The ID of the file. - - `RUN_FAILED("run_failed")` + - `long index` - - `Optional metadata` + The index of the file in the list of files. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `JsonValue; type "file_path"constant` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the file path. Always `file_path`. - - `JsonValue; object_ "thread.message"constant` + - `FILE_PATH("file_path")` - The object type, which is always `thread.message`. + - `String text` - - `THREAD_MESSAGE("thread.message")` + The text output from the model. - - `Role role` + - `JsonValue; type "output_text"constant` - The entity that produced the message. One of `user` or `assistant`. + The type of the output text. Always `output_text`. - - `USER("user")` + - `OUTPUT_TEXT("output_text")` - - `ASSISTANT("assistant")` + - `Optional> logprobs` - - `Optional runId` + - `String token` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `class BetaResponseOutputRefusal:` + + 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, which can be either `in_progress`, `incomplete`, or `completed`. + 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `String id` + + The unique ID of the file search tool call. + + - `List 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")` - - `String threadId` + - `INCOMPLETE("incomplete")` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `FAILED("failed")` -### Example + - `JsonValue; type "file_search_call"constant` -```java -package com.openai.example; + The type of the file search tool call. Always `file_search_call`. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.messages.Message; -import com.openai.models.beta.threads.messages.MessageRetrieveParams; + - `FILE_SEARCH_CALL("file_search_call")` -public final class Main { - private Main() {} + - `Optional agent` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The agent that produced this item. - MessageRetrieveParams params = MessageRetrieveParams.builder() - .threadId("thread_id") - .messageId("message_id") - .build(); - Message message = client.beta().threads().messages().retrieve(params); - } -} -``` + - `String agentName` -#### Response + The canonical name of the agent that produced this item. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `Optional> results` -## Delete message + The results of the file search tool call. -`MessageDeleted beta().threads().messages().delete(MessageDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `Optional attributes` -**delete** `/threads/{thread_id}/messages/{message_id}` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. -Delete message + - `String` -### Parameters + - `double` -- `MessageDeleteParams params` + - `boolean` - - `String threadId` + - `Optional fileId` - - `Optional messageId` + The unique ID of the file. -### Returns + - `Optional filename` -- `class MessageDeleted:` + The name of the file. + + - `Optional score` + + The relevance score of the file - a value between 0 and 1. + + - `Optional text` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `String id` - - `boolean deleted` + The unique ID of the computer call. - - `JsonValue; object_ "thread.message.deleted"constant` + - `String callId` - - `THREAD_MESSAGE_DELETED("thread.message.deleted")` + An identifier used when responding to the tool call with output. -### Example + - `List pendingSafetyChecks` -```java -package com.openai.example; + The pending safety checks for the computer call. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.threads.messages.MessageDeleteParams; -import com.openai.models.beta.threads.messages.MessageDeleted; + - `String id` -public final class Main { - private Main() {} + The ID of the pending safety check. - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Optional code` - MessageDeleteParams params = MessageDeleteParams.builder() - .threadId("thread_id") - .messageId("message_id") - .build(); - MessageDeleted messageDeleted = client.beta().threads().messages().delete(params); - } -} -``` + The type of the pending safety check. -#### Response + - `Optional 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` + + A click action. + + - `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> keys` + + The keys being held while clicking. + + - `DoubleClick` + + - `Optional> 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` + + 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> keys` + + The keys being held while dragging the mouse. + + - `Keypress` + + - `List 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> 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> 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")` + + - `Optional> actions` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click` + + - `DoubleClick` + + - `Drag` + + - `Keypress` + + - `Move` + + - `JsonValue;` + + - `Scroll` + + - `Type` + + - `JsonValue;` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ComputerCallOutput` + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot 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 fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional 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 id` + + The ID of the computer tool call output. + + - `Optional> 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 code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `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. + + - `JsonValue; type "search"constant` + + The action type. + + - `SEARCH("search")` + + - `Optional> queries` + + The search queries. + + - `Optional query` + + The search query. + + - `Optional> 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 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `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 id` + + The unique ID of the function tool call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the function to run. + + - `Optional 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` + + - `class BetaResponseInputTextContent:` + + 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional 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 fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFileContent:` + + 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` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The base64-encoded data of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `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 id` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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")` + + - `AgentMessage` + + - `String author` + + The sending agent identity. + + - `List content` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent:` + + A text input to the model. + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The item type. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional id` + + The unique ID of this agent message item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `Action action` + + The multi-agent action that was executed. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The action arguments as a JSON string. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The item type. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional id` + + The unique ID of this multi-agent call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `String text` + + The text content. + + - `JsonValue; type "output_text"constant` + + The content type. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional annotations` + + Citations associated with the text content. + + - `List` + + - `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 citation type. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `List` + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `String title` + + The title of the cited resource. + + - `JsonValue; type "url_citation"constant` + + The citation type. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the cited resource. + + - `List` + + - `String containerId` + + The ID of the container. + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `String fileId` + + The ID of the container file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The citation type. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 id` + + The unique ID of this tool search call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseToolSearchOutputItemParam:` + + - `List tools` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `String name` + + The name of the function to call. + + - `Optional parameters` + + A JSON schema object describing the parameters of the function. + + - `Optional strict` + + Whether strict parameter validation is enforced for this function tool. + + - `JsonValue; type "function"constant` + + The type of the function tool. Always `function`. + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function is deferred and loaded via tool search. + + - `Optional description` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `Optional outputSchema` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `JsonValue; type "file_search"constant` + + The type of the file search tool. Always `file_search`. + + - `FILE_SEARCH("file_search")` + + - `List vectorStoreIds` + + The IDs of the vector stores to search. + + - `Optional 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` + + - `String` + + - `double` + + - `class CompoundFilter:` + + Combine multiple filters using `and` or `or`. + + - `List 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. + + - `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` + + - `String` + + - `double` + + - `JsonValue` + + - `Type type` + + Type of operation: `and` or `or`. + + - `AND("and")` + + - `OR("or")` + + - `Optional maxNumResults` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `Optional rankingOptions` + + Ranking options for search. + + - `Optional 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` + + The ranker to use for the file search. + + - `AUTO("auto")` + + - `DEFAULT_2024_11_15("default-2024-11-15")` + + - `Optional 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 BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `JsonValue; type "computer"constant` + + The type of the computer tool. Always `computer`. + + - `COMPUTER("computer")` + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `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 BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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 for the search. + + - `Optional> 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` + + High 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` + + The approximate location of the user. + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `Optional 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional allowedTools` + + List of allowed tool names or a filter object. + + - `List` + + - `class McpToolFilter:` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional 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` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `CONNECTOR_DROPBOX("connector_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 deferLoading` + + Whether this MCP tool is deferred and discovered via tool search. + + - `Optional headers` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `Optional 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` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional never` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> 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 serverDescription` + + Optional description of the MCP server, used to provide more context. + + - `Optional serverUrl` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `Optional tunnelId` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter` + + - `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> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the code interpreter container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `JsonValue; type "disabled"constant` + + Disable outbound network access. Always `disabled`. + + - `DISABLED("disabled")` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `List 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> 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")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The type of the tool. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `ImageGeneration` + + - `JsonValue; type "image_generation"constant` + + The type of the image generation tool. Always `image_generation`. + + - `IMAGE_GENERATION("image_generation")` + + - `Optional action` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `GENERATE("generate")` + + - `EDIT("edit")` + + - `AUTO("auto")` + + - `Optional 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` + + 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` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `Optional fileId` + + File ID for the mask image. + + - `Optional imageUrl` + + Base64-encoded mask image. + + - `Optional 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 level for the generated image. Default: `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `Optional outputCompression` + + Compression level for the output image. Default: 100. + + - `Optional outputFormat` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `PNG("png")` + + - `WEBP("webp")` + + - `JPEG("jpeg")` + + - `Optional partialImages` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `Optional 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 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`. + + - `_1024X1024("1024x1024")` + + - `_1024X1536("1024x1536")` + + - `_1536X1024("1536x1024")` + + - `AUTO("auto")` + + - `JsonValue;` + + - `JsonValue; type "local_shell"constant` + + The type of the local shell tool. Always `local_shell`. + + - `LOCAL_SHELL("local_shell")` + + - `class BetaFunctionShellTool:` + + 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional environment` + + - `class BetaContainerAuto:` + + - `JsonValue; type "container_auto"constant` + + Automatically creates a container for this request + + - `CONTAINER_AUTO("container_auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `Optional> skills` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference:` + + - `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 version` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill:` + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `BetaInlineSkillSource 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 BetaLocalEnvironment:` + + - `JsonValue; type "local"constant` + + Use a local computer environment. + + - `LOCAL("local")` + + - `Optional> 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 BetaContainerReference:` + + - `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 BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this tool should be deferred and discovered via tool search. + + - `Optional description` + + Optional description of the custom tool, used to provide more context. + + - `Optional format` + + The input format for the custom tool. Default is unconstrained text. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + Unconstrained text format. Always `text`. + + - `TEXT("text")` + + - `class Grammar:` + + A grammar defined by the user. + + - `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 BetaNamespaceTool:` + + 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 tools` + + The function/custom tools available inside this namespace. + + - `class Function:` + + - `String name` + + - `JsonValue; type "function"constant` + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function should be deferred and discovered via tool search. + + - `Optional description` + + - `Optional outputSchema` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `Optional parameters` + + - `Optional strict` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `JsonValue; type "namespace"constant` + + The type of the tool. Always `namespace`. + + - `NAMESPACE("namespace")` + + - `class BetaToolSearchTool:` + + 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 description` + + Description shown to the model for a client-executed tool search tool. + + - `Optional execution` + + Whether tool search is executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional parameters` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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> searchContentTypes` + + - `TEXT("text")` + + - `IMAGE("image")` + + - `Optional 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` + + The user's location. + + - `JsonValue; type "approximate"constant` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "apply_patch"constant` + + The type of the tool. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue; type "tool_search_output"constant` + + The item type. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional id` + + The unique ID of this tool search output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search output. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `AdditionalTools` + + - `JsonValue; role "developer"constant` + + The role that provided the additional tools. Only `developer` is supported. + + - `DEVELOPER("developer")` + + - `List tools` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "additional_tools"constant` + + The item type. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional id` + + The unique ID of this additional tools item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `String id` + + The unique identifier of the reasoning content. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> 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 encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional 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 BetaResponseCompactionItemParam:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `String encryptedContent` + + The encrypted content of the compaction summary. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional id` + + The ID of the compaction item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall:` + + A tool call to run code. + + - `String id` + + The unique ID of the code interpreter tool call. + + - `Optional code` + + The code to run, or null if not available. + + - `String containerId` + + The ID of the container used to run the code. + + - `Optional> 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. + + - `Action action` + + Execute a shell command on the server. + + - `List 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 timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` + + Optional user to run the command as. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 commands` + + Ordered shell commands for the execution environment to run. + + - `Optional maxOutputLength` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `Optional 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 id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional environment` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment:` + + - `class BetaContainerReference:` + + - `Optional 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 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 id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional maxOutputLength` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `Optional 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 id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `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 id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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 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 annotations` + + Additional annotations about the tool. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 id` + + The unique ID of the approval response + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 error` + + The error from the tool call, if any. + + - `Optional output` + + The output from the tool call. + + - `Optional 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 BetaResponseCustomToolCallOutput:` + + 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` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `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 id` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `class BetaResponseCustomToolCall:` + + 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 id` + + The unique ID of the custom tool call in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the custom tool being called. + + - `CompactionTrigger` + + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` + + - `String id` + + The ID of the item to reference. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional type` + + The type of item to reference. Always `item_reference`. + + - `ITEM_REFERENCE("item_reference")` + + - `Program` + + - `String id` + + The unique ID of this program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The item type. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of this program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The item type. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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. + + - `Model model` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. + + - `GPT_5_6_SOL("gpt-5.6-sol")` + + - `GPT_5_6_TERRA("gpt-5.6-terra")` + + - `GPT_5_6_LUNA("gpt-5.6-luna")` + + - `GPT_5_4("gpt-5.4")` + + - `GPT_5_4_MINI("gpt-5.4-mini")` + + - `GPT_5_4_NANO("gpt-5.4-nano")` + + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + + - `GPT_5_2("gpt-5.2")` + + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + + - `GPT_5_2_PRO("gpt-5.2-pro")` + + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + + - `GPT_5_1("gpt-5.1")` + + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + + - `GPT_5_1_CODEX("gpt-5.1-codex")` + + - `GPT_5_1_MINI("gpt-5.1-mini")` + + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + + - `GPT_5("gpt-5")` + + - `GPT_5_MINI("gpt-5-mini")` + + - `GPT_5_NANO("gpt-5-nano")` + + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + + - `GPT_4_1("gpt-4.1")` + + - `GPT_4_1_MINI("gpt-4.1-mini")` + + - `GPT_4_1_NANO("gpt-4.1-nano")` + + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + + - `O4_MINI("o4-mini")` + + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + + - `O3("o3")` + + - `O3_2025_04_16("o3-2025-04-16")` + + - `O3_MINI("o3-mini")` + + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + + - `O1("o1")` + + - `O1_2024_12_17("o1-2024-12-17")` + + - `O1_PREVIEW("o1-preview")` + + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + + - `O1_MINI("o1-mini")` + + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + + - `GPT_4O("gpt-4o")` + + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + + - `CODEX_MINI_LATEST("codex-mini-latest")` + + - `GPT_4O_MINI("gpt-4o-mini")` + + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + + - `GPT_4_TURBO("gpt-4-turbo")` + + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + + - `GPT_4("gpt-4")` + + - `GPT_4_0314("gpt-4-0314")` + + - `GPT_4_0613("gpt-4-0613")` + + - `GPT_4_32K("gpt-4-32k")` + + - `GPT_4_32K_0314("gpt-4-32k-0314")` + + - `GPT_4_32K_0613("gpt-4-32k-0613")` + + - `GPT_3_5_TURBO("gpt-3.5-turbo")` + + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + + - `O1_PRO("o1-pro")` + + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + + - `O3_PRO("o3-pro")` + + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + + - `O3_DEEP_RESEARCH("o3-deep-research")` + + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + + - `COMPUTER_USE_PREVIEW("computer-use-preview")` + + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + + - `GPT_5_CODEX("gpt-5-codex")` + + - `GPT_5_PRO("gpt-5-pro")` + + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + + - `JsonValue; object_ "response"constant` + + The object type of this resource - always set to `response`. + + - `RESPONSE("response")` + + - `List output` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem:` + + - `String id` + + The unique ID of the function call tool output. + + - `String callId` + + The unique ID of the function tool call generated by the model. + + - `Output output` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Status 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")` + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AgentMessage` + + - `String id` + + The unique ID of the agent message. + + - `String author` + + The sending agent identity. + + - `List content` + + Encrypted content sent between agents. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `class Text:` + + A text content. + + - `String text` + + - `JsonValue; type "text"constant` + + - `TEXT("text")` + + - `class SummaryText:` + + 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 BetaResponseOutputRefusal:` + + A refusal from the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot:` + + A screenshot of a computer. + + - `Detail 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 fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The type of the item. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `String id` + + The unique ID of the multi-agent call item. + + - `Action action` + + The multi-agent action to execute. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The JSON string of arguments generated for the action. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `String id` + + The unique ID of the multi-agent call output item. + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `List annotations` + + The annotations of the text output. + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `Optional> logprobs` + + - `JsonValue; type "multi_agent_call_output"constant` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `class BetaResponseComputerToolCallOutputItem:` + + - `String id` + + The unique ID of the computer call tool output. + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot output` + + A computer screenshot image used with the computer use tool. + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + + - `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> 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 code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `Program` + + - `String id` + + The unique ID of the program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The type of the item. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of the program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output item. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The type of the item. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall:` + + - `String id` + + The unique ID of the tool search call item. + + - `JsonValue arguments` + + Arguments used for the tool search call. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search call item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "tool_search_call"constant` + + The type of the item. Always `tool_search_call`. + + - `TOOL_SEARCH_CALL("tool_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem:` + + - `String id` + + The unique ID of the tool search output item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search output item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `List tools` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "tool_search_output"constant` + + The type of the item. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AdditionalTools` + + - `String id` + + The unique ID of the additional tools item. + + - `Role role` + + The role that provided the additional tools. + + - `UNKNOWN("unknown")` + + - `USER("user")` + + - `ASSISTANT("assistant")` + + - `SYSTEM("system")` + + - `CRITIC("critic")` + + - `DISCRIMINATOR("discriminator")` + + - `DEVELOPER("developer")` + + - `TOOL("tool")` + + - `List tools` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "additional_tools"constant` + + The type of the item. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `String id` + + The unique ID of the compaction item. + + - `String encryptedContent` + + The encrypted content that was produced by compaction. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall:` + + A tool call to run code. + + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. + + - `Action action` + + Execute a shell command on the server. + + - `List 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 timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` + + Optional user to run the command as. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseFunctionShellToolCall:` + + A tool call that executes one or more shell commands in a managed environment. + + - `String id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `Action action` + + The shell commands and limits that describe how to run the tool call. + + - `List commands` + + - `Optional maxOutputLength` + + Optional maximum number of characters to return from each command. + + - `Optional timeoutMs` + + Optional timeout in milliseconds for the commands. + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `Optional environment` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment:` + + Represents the use of a local environment to perform shell actions. + + - `JsonValue; type "local"constant` + + The environment type. Always `local`. + + - `LOCAL("local")` + + - `class BetaResponseContainerReference:` + + Represents a container created with /v1/containers. + + - `String containerId` + + - `JsonValue; type "container_reference"constant` + + The environment type. Always `container_reference`. + + - `CONTAINER_REFERENCE("container_reference")` + + - `Status status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call"constant` + + The type of the item. Always `shell_call`. + + - `SHELL_CALL("shell_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput:` + + The output of a shell tool call that was emitted. + + - `String id` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `Optional maxOutputLength` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `List output` + + An array of shell call output contents + + - `Outcome outcome` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `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` + + Exit code from the shell process. + + - `JsonValue; type "exit"constant` + + The outcome type. Always `exit`. + + - `EXIT("exit")` + + - `String stderr` + + The standard error output that was captured. + + - `String stdout` + + The standard output that was captured. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `Status status` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call_output"constant` + + The type of the shell call output. Always `shell_call_output`. + + - `SHELL_CALL_OUTPUT("shell_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseApplyPatchToolCall:` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `String id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the apply patch tool call generated by the model. + + - `Operation operation` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `class CreateFile:` + + Instruction describing how to create a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to create. + + - `JsonValue; type "create_file"constant` + + Create a new file with the provided diff. + + - `CREATE_FILE("create_file")` + + - `class DeleteFile:` + + Instruction describing how to delete a file via the apply_patch tool. + + - `String path` + + Path of the file to delete. + + - `JsonValue; type "delete_file"constant` + + Delete the specified file. + + - `DELETE_FILE("delete_file")` + + - `class UpdateFile:` + + Instruction describing how to update a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to update. + + - `JsonValue; type "update_file"constant` + + Update an existing file with the provided diff. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput:` + + The output emitted by an apply patch tool call. + + - `String id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call output. + + - `Optional output` + + Optional textual output returned by the apply patch tool. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 error` + + The error from the tool call, if any. + + - `Optional output` + + The output from the tool call. + + - `Optional 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")` + + - `McpListTools` + + - `String id` + + The unique ID of the list. + + - `String serverLabel` + + The label of the MCP server. + + - `List 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 annotations` + + Additional annotations about the tool. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `McpApprovalResponse` + + - `String id` + + The unique ID of the approval response + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional reason` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall:` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem:` + + The output of a custom tool call from your code, being sent back to the model. + + - `String id` + + The unique ID of the custom tool call output item. + + - `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")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `boolean parallelToolCalls` + + Whether to allow the model to run tool calls in parallel. + + - `Optional temperature` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + + - `ToolChoice toolChoice` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `enum BetaToolChoiceOptions:` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `NONE("none")` + + - `AUTO("auto")` + + - `REQUIRED("required")` + + - `class BetaToolChoiceAllowed:` + + Constrains the tools available to the model to a pre-defined set. + + - `Mode mode` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `AUTO("auto")` + + - `REQUIRED("required")` + + - `List tools` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `JsonValue; type "allowed_tools"constant` + + Allowed tool configuration type. Always `allowed_tools`. + + - `ALLOWED_TOOLS("allowed_tools")` + + - `class BetaToolChoiceTypes:` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `Type type` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `FILE_SEARCH("file_search")` + + - `WEB_SEARCH_PREVIEW("web_search_preview")` + + - `COMPUTER("computer")` + + - `COMPUTER_USE_PREVIEW("computer_use_preview")` + + - `COMPUTER_USE("computer_use")` + + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + + - `IMAGE_GENERATION("image_generation")` + + - `CODE_INTERPRETER("code_interpreter")` + + - `class BetaToolChoiceFunction:` + + Use this option to force the model to call a specific function. + + - `String name` + + The name of the function to call. + + - `JsonValue; type "function"constant` + + For function calling, the type is always `function`. + + - `FUNCTION("function")` + + - `class BetaToolChoiceMcp:` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `String serverLabel` + + The label of the MCP server to use. + + - `JsonValue; type "mcp"constant` + + For MCP tools, the type is always `mcp`. + + - `MCP("mcp")` + + - `Optional name` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom:` + + Use this option to force the model to call a specific custom tool. + + - `String name` + + The name of the custom tool to call. + + - `JsonValue; type "custom"constant` + + For custom tool calling, the type is always `custom`. + + - `CUSTOM("custom")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The tool to call. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `class BetaToolChoiceApplyPatch:` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `JsonValue; type "apply_patch"constant` + + The tool to call. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `class BetaToolChoiceShell:` + + Forces the model to call the shell tool when a tool call is required. + + - `JsonValue; type "shell"constant` + + The tool to call. Always `shell`. + + - `SHELL("shell")` + + - `List tools` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `Optional topP` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `Optional background` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `Optional completedAt` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `Optional conversation` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `String id` + + The unique ID of the conversation that this response was associated with. + + - `Optional maxOutputTokens` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `Optional maxToolCalls` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `Optional moderation` + + Moderation results for the response input and output, if moderated completions were requested. + + - `Input input` + + Moderation for the response input. + + - `class ModerationResult:` + + A moderation result produced for the response input or output. + + - `Categories categories` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `CategoryAppliedInputTypes categoryAppliedInputTypes` + + Which modalities of input are reflected by the score for each category. + + - `TEXT("text")` + + - `IMAGE("image")` + + - `CategoryScores categoryScores` + + A dictionary of moderation categories to scores. + + - `boolean flagged` + + A boolean indicating whether the content was flagged by any category. + + - `String model` + + The moderation model that produced this result. + + - `JsonValue; type "moderation_result"constant` + + The object type, which was always `moderation_result` for successful moderation results. + + - `MODERATION_RESULT("moderation_result")` + + - `class Error:` + + An error produced while attempting moderation for the response input or output. + + - `String code` + + The error code. + + - `String message` + + The error message. + + - `JsonValue; type "error"constant` + + The object type, which was always `error` for moderation failures. + + - `ERROR("error")` + + - `Output output` + + Moderation for the response output. + + - `class ModerationResult:` + + A moderation result produced for the response input or output. + + - `Categories categories` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `CategoryAppliedInputTypes categoryAppliedInputTypes` + + Which modalities of input are reflected by the score for each category. + + - `TEXT("text")` + + - `IMAGE("image")` + + - `CategoryScores categoryScores` + + A dictionary of moderation categories to scores. + + - `boolean flagged` + + A boolean indicating whether the content was flagged by any category. + + - `String model` + + The moderation model that produced this result. + + - `JsonValue; type "moderation_result"constant` + + The object type, which was always `moderation_result` for successful moderation results. + + - `MODERATION_RESULT("moderation_result")` + + - `class Error:` + + An error produced while attempting moderation for the response input or output. + + - `String code` + + The error code. + + - `String message` + + The error message. + + - `JsonValue; type "error"constant` + + The object type, which was always `error` for moderation failures. + + - `ERROR("error")` + + - `Optional previousResponseId` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `Optional prompt` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `String id` + + The unique identifier of the prompt template to use. + + - `Optional variables` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `String` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Optional version` + + Optional version of the prompt template. + + - `Optional promptCacheKey` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `Optional promptCacheOptions` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `Mode mode` + + Whether implicit prompt-cache breakpoints were enabled. + + - `IMPLICIT("implicit")` + + - `EXPLICIT("explicit")` + + - `Ttl ttl` + + The minimum lifetime applied to each cache breakpoint. + + - `_30M("30m")` + + - `Optional promptCacheRetention` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `IN_MEMORY("in_memory")` + + - `_24H("24h")` + + - `Optional reasoning` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `Optional context` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `AUTO("auto")` + + - `CURRENT_TURN("current_turn")` + + - `ALL_TURNS("all_turns")` + + - `Optional effort` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `NONE("none")` + + - `MINIMAL("minimal")` + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `XHIGH("xhigh")` + + - `MAX("max")` + + - `Optional generateSummary` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `AUTO("auto")` + + - `CONCISE("concise")` + + - `DETAILED("detailed")` + + - `Optional mode` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `STANDARD("standard")` + + - `PRO("pro")` + + - `Optional summary` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `AUTO("auto")` + + - `CONCISE("concise")` + + - `DETAILED("detailed")` + + - `Optional safetyIdentifier` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `Optional serviceTier` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `AUTO("auto")` + + - `DEFAULT("default")` + + - `FLEX("flex")` + + - `SCALE("scale")` + + - `PRIORITY("priority")` + + - `Optional status` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `COMPLETED("completed")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + + - `CANCELLED("cancelled")` + + - `QUEUED("queued")` + + - `INCOMPLETE("incomplete")` + + - `Optional text` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `Optional format` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + The type of response format being defined. Always `text`. + + - `TEXT("text")` + + - `class BetaResponseFormatTextJsonSchemaConfig:` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `String name` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `Schema schema` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `JsonValue; type "json_schema"constant` + + The type of response format being defined. Always `json_schema`. + + - `JSON_SCHEMA("json_schema")` + + - `Optional description` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `Optional strict` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). + + - `JsonValue;` + + - `JsonValue; type "json_object"constant` + + The type of response format being defined. Always `json_object`. + + - `JSON_OBJECT("json_object")` + + - `Optional verbosity` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional topLogprobs` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `Optional truncation` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `AUTO("auto")` + + - `DISABLED("disabled")` + + - `Optional usage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `long inputTokens` + + The number of input tokens. + + - `InputTokensDetails inputTokensDetails` + + A detailed breakdown of the input tokens. + + - `long cacheWriteTokens` + + The number of input tokens that were written to the cache. + + - `long cachedTokens` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `long outputTokens` + + The number of output tokens. + + - `OutputTokensDetails outputTokensDetails` + + A detailed breakdown of the output tokens. + + - `long reasoningTokens` + + The number of reasoning tokens. + + - `long totalTokens` + + The total number of tokens used. + + - `Optional user` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + +### Example + +```java +package com.openai.example; + +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.responses.BetaResponse; +import com.openai.models.beta.responses.ResponseRetrieveParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + + BetaResponse betaResponse = client.beta().responses().retrieve("resp_677efb5139a88190b512bc3fef8e535d"); + } +} +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` + +## Delete a model response + +`beta().responses().delete(ResponseDeleteParamsparams = ResponseDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**delete** `/responses/{response_id}?beta=true` + +Deletes a model response with the given ID. + +### Parameters + +- `ResponseDeleteParams params` + + - `Optional responseId` + + - `Optional> betas` + + - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + +### Example + +```java +package com.openai.example; + +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.responses.ResponseDeleteParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + + client.beta().responses().delete("resp_677efb5139a88190b512bc3fef8e535d"); + } +} +``` + +## Cancel a response + +`BetaResponse beta().responses().cancel(ResponseCancelParamsparams = ResponseCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/responses/{response_id}/cancel?beta=true` + +Cancels a model response with the given ID. Only responses created with +the `background` parameter set to `true` can be cancelled. +[Learn more](https://platform.openai.com/docs/guides/background). + +### Parameters + +- `ResponseCancelParams params` + + - `Optional responseId` + + - `Optional> betas` + + - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + +### Returns + +- `class BetaResponse:` + + - `String id` + + Unique identifier for this Response. + + - `double createdAt` + + Unix timestamp (in seconds) of when this Response was created. + + - `Optional error` + + An error object returned when the model fails to generate a Response. + + - `Code code` + + The error code for the response. + + - `SERVER_ERROR("server_error")` + + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + + - `INVALID_PROMPT("invalid_prompt")` + + - `BIO_POLICY("bio_policy")` + + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + + - `INVALID_IMAGE("invalid_image")` + + - `INVALID_IMAGE_FORMAT("invalid_image_format")` + + - `INVALID_BASE64_IMAGE("invalid_base64_image")` + + - `INVALID_IMAGE_URL("invalid_image_url")` + + - `IMAGE_TOO_LARGE("image_too_large")` + + - `IMAGE_TOO_SMALL("image_too_small")` + + - `IMAGE_PARSE_ERROR("image_parse_error")` + + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + + - `INVALID_IMAGE_MODE("invalid_image_mode")` + + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + + - `EMPTY_IMAGE_FILE("empty_image_file")` + + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + + - `String message` + + A human-readable description of the error. + + - `Optional incompleteDetails` + + Details about why the response is incomplete. + + - `Optional reason` + + The reason why the response is incomplete. + + - `MAX_OUTPUT_TOKENS("max_output_tokens")` + + - `CONTENT_FILTER("content_filter")` + + - `Optional instructions` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `String` + + - `List` + + - `class BetaEasyInputMessage:` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `Content content` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `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 fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + 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` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `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` + + 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` + + The type of the message input. Always `message`. + + - `MESSAGE("message")` + + - `Message` + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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` + + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `String id` + + The unique ID of the output message. + + - `List content` + + The content of the output message. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `List 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> logprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `class BetaResponseOutputRefusal:` + + 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `String id` + + The unique ID of the file search tool call. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> results` + + The results of the file search tool call. + + - `Optional 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 fileId` + + The unique ID of the file. + + - `Optional filename` + + The name of the file. + + - `Optional score` + + The relevance score of the file - a value between 0 and 1. + + - `Optional text` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `String id` + + The unique ID of the computer call. + + - `String callId` + + An identifier used when responding to the tool call with output. + + - `List pendingSafetyChecks` + + The pending safety checks for the computer call. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional 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` + + A click action. + + - `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> keys` + + The keys being held while clicking. + + - `DoubleClick` + + - `Optional> 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` + + 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> keys` + + The keys being held while dragging the mouse. + + - `Keypress` + + - `List 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> 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> 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")` + + - `Optional> actions` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click` + + - `DoubleClick` + + - `Drag` + + - `Keypress` + + - `Move` + + - `JsonValue;` + + - `Scroll` + + - `Type` + + - `JsonValue;` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ComputerCallOutput` + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot 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 fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional 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 id` + + The ID of the computer tool call output. + + - `Optional> 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 code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `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. + + - `JsonValue; type "search"constant` + + The action type. + + - `SEARCH("search")` + + - `Optional> queries` + + The search queries. + + - `Optional query` + + The search query. + + - `Optional> 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 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `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 id` + + The unique ID of the function tool call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the function to run. + + - `Optional 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` + + - `class BetaResponseInputTextContent:` + + 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional 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 fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFileContent:` + + 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` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The base64-encoded data of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `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 id` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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")` + + - `AgentMessage` + + - `String author` + + The sending agent identity. + + - `List content` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent:` + + A text input to the model. + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The item type. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional id` + + The unique ID of this agent message item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `Action action` + + The multi-agent action that was executed. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The action arguments as a JSON string. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The item type. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional id` + + The unique ID of this multi-agent call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `String text` + + The text content. + + - `JsonValue; type "output_text"constant` + + The content type. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional annotations` + + Citations associated with the text content. + + - `List` + + - `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 citation type. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `List` + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `String title` + + The title of the cited resource. + + - `JsonValue; type "url_citation"constant` + + The citation type. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the cited resource. + + - `List` + + - `String containerId` + + The ID of the container. + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `String fileId` + + The ID of the container file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The citation type. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 id` + + The unique ID of this tool search call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseToolSearchOutputItemParam:` + + - `List tools` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `String name` + + The name of the function to call. + + - `Optional parameters` + + A JSON schema object describing the parameters of the function. + + - `Optional strict` + + Whether strict parameter validation is enforced for this function tool. + + - `JsonValue; type "function"constant` + + The type of the function tool. Always `function`. + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function is deferred and loaded via tool search. + + - `Optional description` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `Optional outputSchema` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `JsonValue; type "file_search"constant` + + The type of the file search tool. Always `file_search`. + + - `FILE_SEARCH("file_search")` + + - `List vectorStoreIds` + + The IDs of the vector stores to search. + + - `Optional 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` + + - `String` + + - `double` + + - `class CompoundFilter:` + + Combine multiple filters using `and` or `or`. + + - `List 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. + + - `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` + + - `String` + + - `double` + + - `JsonValue` + + - `Type type` + + Type of operation: `and` or `or`. + + - `AND("and")` + + - `OR("or")` + + - `Optional maxNumResults` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `Optional rankingOptions` + + Ranking options for search. + + - `Optional 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` + + The ranker to use for the file search. + + - `AUTO("auto")` + + - `DEFAULT_2024_11_15("default-2024-11-15")` + + - `Optional 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 BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `JsonValue; type "computer"constant` + + The type of the computer tool. Always `computer`. + + - `COMPUTER("computer")` + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `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 BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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 for the search. + + - `Optional> 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` + + High 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` + + The approximate location of the user. + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `Optional 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional allowedTools` + + List of allowed tool names or a filter object. + + - `List` + + - `class McpToolFilter:` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional 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` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `CONNECTOR_DROPBOX("connector_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 deferLoading` + + Whether this MCP tool is deferred and discovered via tool search. + + - `Optional headers` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `Optional 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` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional never` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> 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 serverDescription` + + Optional description of the MCP server, used to provide more context. + + - `Optional serverUrl` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `Optional tunnelId` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter` + + - `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> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the code interpreter container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `JsonValue; type "disabled"constant` + + Disable outbound network access. Always `disabled`. + + - `DISABLED("disabled")` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `List 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> 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")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The type of the tool. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `ImageGeneration` + + - `JsonValue; type "image_generation"constant` + + The type of the image generation tool. Always `image_generation`. + + - `IMAGE_GENERATION("image_generation")` + + - `Optional action` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `GENERATE("generate")` + + - `EDIT("edit")` + + - `AUTO("auto")` + + - `Optional 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` + + 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` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `Optional fileId` + + File ID for the mask image. + + - `Optional imageUrl` + + Base64-encoded mask image. + + - `Optional 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 level for the generated image. Default: `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `Optional outputCompression` + + Compression level for the output image. Default: 100. + + - `Optional outputFormat` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `PNG("png")` + + - `WEBP("webp")` + + - `JPEG("jpeg")` + + - `Optional partialImages` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `Optional 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 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`. + + - `_1024X1024("1024x1024")` + + - `_1024X1536("1024x1536")` + + - `_1536X1024("1536x1024")` + + - `AUTO("auto")` + + - `JsonValue;` + + - `JsonValue; type "local_shell"constant` + + The type of the local shell tool. Always `local_shell`. + + - `LOCAL_SHELL("local_shell")` + + - `class BetaFunctionShellTool:` + + 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional environment` + + - `class BetaContainerAuto:` + + - `JsonValue; type "container_auto"constant` + + Automatically creates a container for this request + + - `CONTAINER_AUTO("container_auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `Optional> skills` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference:` + + - `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 version` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill:` + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `BetaInlineSkillSource 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 BetaLocalEnvironment:` + + - `JsonValue; type "local"constant` + + Use a local computer environment. + + - `LOCAL("local")` + + - `Optional> 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 BetaContainerReference:` + + - `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 BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this tool should be deferred and discovered via tool search. + + - `Optional description` + + Optional description of the custom tool, used to provide more context. + + - `Optional format` + + The input format for the custom tool. Default is unconstrained text. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + Unconstrained text format. Always `text`. + + - `TEXT("text")` + + - `class Grammar:` + + A grammar defined by the user. + + - `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 BetaNamespaceTool:` + + 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 tools` + + The function/custom tools available inside this namespace. + + - `class Function:` + + - `String name` + + - `JsonValue; type "function"constant` + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function should be deferred and discovered via tool search. + + - `Optional description` + + - `Optional outputSchema` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `Optional parameters` + + - `Optional strict` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `JsonValue; type "namespace"constant` + + The type of the tool. Always `namespace`. + + - `NAMESPACE("namespace")` + + - `class BetaToolSearchTool:` + + 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 description` + + Description shown to the model for a client-executed tool search tool. + + - `Optional execution` + + Whether tool search is executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional parameters` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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> searchContentTypes` + + - `TEXT("text")` + + - `IMAGE("image")` + + - `Optional 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` + + The user's location. + + - `JsonValue; type "approximate"constant` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "apply_patch"constant` + + The type of the tool. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue; type "tool_search_output"constant` + + The item type. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional id` + + The unique ID of this tool search output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search output. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `AdditionalTools` + + - `JsonValue; role "developer"constant` + + The role that provided the additional tools. Only `developer` is supported. + + - `DEVELOPER("developer")` + + - `List tools` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "additional_tools"constant` + + The item type. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional id` + + The unique ID of this additional tools item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `String id` + + The unique identifier of the reasoning content. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> 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 encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional 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 BetaResponseCompactionItemParam:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `String encryptedContent` + + The encrypted content of the compaction summary. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional id` + + The ID of the compaction item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall:` + + A tool call to run code. + + - `String id` + + The unique ID of the code interpreter tool call. + + - `Optional code` + + The code to run, or null if not available. + + - `String containerId` + + The ID of the container used to run the code. + + - `Optional> 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. + + - `Action action` + + Execute a shell command on the server. + + - `List 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 timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` + + Optional user to run the command as. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 commands` + + Ordered shell commands for the execution environment to run. + + - `Optional maxOutputLength` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `Optional 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 id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional environment` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment:` + + - `class BetaContainerReference:` + + - `Optional 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 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 id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional maxOutputLength` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `Optional 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 id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `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 id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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 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 annotations` + + Additional annotations about the tool. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 id` + + The unique ID of the approval response + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 error` + + The error from the tool call, if any. + + - `Optional output` + + The output from the tool call. + + - `Optional 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 BetaResponseCustomToolCallOutput:` + + 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` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `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 id` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `class BetaResponseCustomToolCall:` + + 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 id` + + The unique ID of the custom tool call in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the custom tool being called. + + - `CompactionTrigger` + + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` + + - `String id` + + The ID of the item to reference. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional type` + + The type of item to reference. Always `item_reference`. + + - `ITEM_REFERENCE("item_reference")` + + - `Program` + + - `String id` + + The unique ID of this program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The item type. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of this program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The item type. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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. + + - `Model model` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. + + - `GPT_5_6_SOL("gpt-5.6-sol")` + + - `GPT_5_6_TERRA("gpt-5.6-terra")` + + - `GPT_5_6_LUNA("gpt-5.6-luna")` + + - `GPT_5_4("gpt-5.4")` + + - `GPT_5_4_MINI("gpt-5.4-mini")` + + - `GPT_5_4_NANO("gpt-5.4-nano")` + + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + + - `GPT_5_2("gpt-5.2")` + + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + + - `GPT_5_2_PRO("gpt-5.2-pro")` + + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + + - `GPT_5_1("gpt-5.1")` + + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + + - `GPT_5_1_CODEX("gpt-5.1-codex")` + + - `GPT_5_1_MINI("gpt-5.1-mini")` + + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + + - `GPT_5("gpt-5")` + + - `GPT_5_MINI("gpt-5-mini")` + + - `GPT_5_NANO("gpt-5-nano")` + + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + + - `GPT_4_1("gpt-4.1")` + + - `GPT_4_1_MINI("gpt-4.1-mini")` + + - `GPT_4_1_NANO("gpt-4.1-nano")` + + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + + - `O4_MINI("o4-mini")` + + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + + - `O3("o3")` + + - `O3_2025_04_16("o3-2025-04-16")` + + - `O3_MINI("o3-mini")` + + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + + - `O1("o1")` + + - `O1_2024_12_17("o1-2024-12-17")` + + - `O1_PREVIEW("o1-preview")` + + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + + - `O1_MINI("o1-mini")` + + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + + - `GPT_4O("gpt-4o")` + + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + + - `CODEX_MINI_LATEST("codex-mini-latest")` + + - `GPT_4O_MINI("gpt-4o-mini")` + + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + + - `GPT_4_TURBO("gpt-4-turbo")` + + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + + - `GPT_4("gpt-4")` + + - `GPT_4_0314("gpt-4-0314")` + + - `GPT_4_0613("gpt-4-0613")` + + - `GPT_4_32K("gpt-4-32k")` + + - `GPT_4_32K_0314("gpt-4-32k-0314")` + + - `GPT_4_32K_0613("gpt-4-32k-0613")` + + - `GPT_3_5_TURBO("gpt-3.5-turbo")` + + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + + - `O1_PRO("o1-pro")` + + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + + - `O3_PRO("o3-pro")` + + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + + - `O3_DEEP_RESEARCH("o3-deep-research")` + + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + + - `COMPUTER_USE_PREVIEW("computer-use-preview")` + + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + + - `GPT_5_CODEX("gpt-5-codex")` + + - `GPT_5_PRO("gpt-5-pro")` + + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + + - `JsonValue; object_ "response"constant` + + The object type of this resource - always set to `response`. + + - `RESPONSE("response")` + + - `List output` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `class BetaResponseFunctionToolCallOutputItem:` + + - `String id` + + The unique ID of the function call tool output. + + - `String callId` + + The unique ID of the function tool call generated by the model. + + - `Output output` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Status 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")` + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AgentMessage` + + - `String id` + + The unique ID of the agent message. + + - `String author` + + The sending agent identity. + + - `List content` + + Encrypted content sent between agents. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `class Text:` + + A text content. + + - `String text` + + - `JsonValue; type "text"constant` + + - `TEXT("text")` + + - `class SummaryText:` + + 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 BetaResponseOutputRefusal:` + + A refusal from the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot:` + + A screenshot of a computer. + + - `Detail 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 fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The type of the item. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `String id` + + The unique ID of the multi-agent call item. + + - `Action action` + + The multi-agent action to execute. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The JSON string of arguments generated for the action. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `String id` + + The unique ID of the multi-agent call output item. + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `List annotations` + + The annotations of the text output. + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `Optional> logprobs` + + - `JsonValue; type "multi_agent_call_output"constant` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `class BetaResponseComputerToolCallOutputItem:` + + - `String id` + + The unique ID of the computer call tool output. + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot output` + + A computer screenshot image used with the computer use tool. + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + + - `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> 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 code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `Program` + + - `String id` + + The unique ID of the program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The type of the item. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of the program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output item. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The type of the item. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall:` + + - `String id` + + The unique ID of the tool search call item. + + - `JsonValue arguments` + + Arguments used for the tool search call. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search call item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "tool_search_call"constant` + + The type of the item. Always `tool_search_call`. + + - `TOOL_SEARCH_CALL("tool_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem:` + + - `String id` + + The unique ID of the tool search output item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search output item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `List tools` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "tool_search_output"constant` + + The type of the item. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AdditionalTools` + + - `String id` + + The unique ID of the additional tools item. + + - `Role role` + + The role that provided the additional tools. + + - `UNKNOWN("unknown")` + + - `USER("user")` + + - `ASSISTANT("assistant")` + + - `SYSTEM("system")` + + - `CRITIC("critic")` + + - `DISCRIMINATOR("discriminator")` + + - `DEVELOPER("developer")` + + - `TOOL("tool")` + + - `List tools` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "additional_tools"constant` + + The type of the item. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `String id` + + The unique ID of the compaction item. + + - `String encryptedContent` + + The encrypted content that was produced by compaction. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall:` + + A tool call to run code. + + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. + + - `Action action` + + Execute a shell command on the server. + + - `List 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 timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` + + Optional user to run the command as. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseFunctionShellToolCall:` + + A tool call that executes one or more shell commands in a managed environment. + + - `String id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `Action action` + + The shell commands and limits that describe how to run the tool call. + + - `List commands` + + - `Optional maxOutputLength` + + Optional maximum number of characters to return from each command. + + - `Optional timeoutMs` + + Optional timeout in milliseconds for the commands. + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `Optional environment` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment:` + + Represents the use of a local environment to perform shell actions. + + - `JsonValue; type "local"constant` + + The environment type. Always `local`. + + - `LOCAL("local")` + + - `class BetaResponseContainerReference:` + + Represents a container created with /v1/containers. + + - `String containerId` + + - `JsonValue; type "container_reference"constant` + + The environment type. Always `container_reference`. + + - `CONTAINER_REFERENCE("container_reference")` + + - `Status status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call"constant` + + The type of the item. Always `shell_call`. + + - `SHELL_CALL("shell_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput:` + + The output of a shell tool call that was emitted. + + - `String id` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the shell tool call generated by the model. + + - `Optional maxOutputLength` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `List output` + + An array of shell call output contents + + - `Outcome outcome` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `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` + + Exit code from the shell process. + + - `JsonValue; type "exit"constant` + + The outcome type. Always `exit`. + + - `EXIT("exit")` + + - `String stderr` + + The standard error output that was captured. + + - `String stdout` + + The standard output that was captured. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `Status status` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call_output"constant` + + The type of the shell call output. Always `shell_call_output`. + + - `SHELL_CALL_OUTPUT("shell_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseApplyPatchToolCall:` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `String id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the apply patch tool call generated by the model. + + - `Operation operation` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `class CreateFile:` + + Instruction describing how to create a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to create. + + - `JsonValue; type "create_file"constant` + + Create a new file with the provided diff. + + - `CREATE_FILE("create_file")` + + - `class DeleteFile:` + + Instruction describing how to delete a file via the apply_patch tool. + + - `String path` + + Path of the file to delete. + + - `JsonValue; type "delete_file"constant` + + Delete the specified file. + + - `DELETE_FILE("delete_file")` + + - `class UpdateFile:` + + Instruction describing how to update a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to update. + + - `JsonValue; type "update_file"constant` + + Update an existing file with the provided diff. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput:` + + The output emitted by an apply patch tool call. + + - `String id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call output. + + - `Optional output` + + Optional textual output returned by the apply patch tool. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 error` + + The error from the tool call, if any. + + - `Optional output` + + The output from the tool call. + + - `Optional 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")` + + - `McpListTools` + + - `String id` + + The unique ID of the list. + + - `String serverLabel` + + The label of the MCP server. + + - `List 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 annotations` + + Additional annotations about the tool. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `McpApprovalResponse` + + - `String id` + + The unique ID of the approval response + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional reason` + + Optional reason for the decision. + + - `class BetaResponseCustomToolCall:` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem:` + + The output of a custom tool call from your code, being sent back to the model. + + - `String id` + + The unique ID of the custom tool call output item. + + - `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")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `boolean parallelToolCalls` + + Whether to allow the model to run tool calls in parallel. + + - `Optional temperature` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + + - `ToolChoice toolChoice` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `enum BetaToolChoiceOptions:` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `NONE("none")` + + - `AUTO("auto")` + + - `REQUIRED("required")` + + - `class BetaToolChoiceAllowed:` + + Constrains the tools available to the model to a pre-defined set. + + - `Mode mode` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `AUTO("auto")` + + - `REQUIRED("required")` + + - `List tools` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `JsonValue; type "allowed_tools"constant` + + Allowed tool configuration type. Always `allowed_tools`. + + - `ALLOWED_TOOLS("allowed_tools")` + + - `class BetaToolChoiceTypes:` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `Type type` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `FILE_SEARCH("file_search")` + + - `WEB_SEARCH_PREVIEW("web_search_preview")` + + - `COMPUTER("computer")` + + - `COMPUTER_USE_PREVIEW("computer_use_preview")` + + - `COMPUTER_USE("computer_use")` + + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + + - `IMAGE_GENERATION("image_generation")` + + - `CODE_INTERPRETER("code_interpreter")` + + - `class BetaToolChoiceFunction:` + + Use this option to force the model to call a specific function. + + - `String name` + + The name of the function to call. + + - `JsonValue; type "function"constant` + + For function calling, the type is always `function`. + + - `FUNCTION("function")` + + - `class BetaToolChoiceMcp:` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `String serverLabel` + + The label of the MCP server to use. + + - `JsonValue; type "mcp"constant` + + For MCP tools, the type is always `mcp`. + + - `MCP("mcp")` + + - `Optional name` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom:` + + Use this option to force the model to call a specific custom tool. + + - `String name` + + The name of the custom tool to call. + + - `JsonValue; type "custom"constant` + + For custom tool calling, the type is always `custom`. + + - `CUSTOM("custom")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The tool to call. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `class BetaToolChoiceApplyPatch:` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `JsonValue; type "apply_patch"constant` + + The tool to call. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `class BetaToolChoiceShell:` + + Forces the model to call the shell tool when a tool call is required. + + - `JsonValue; type "shell"constant` + + The tool to call. Always `shell`. + + - `SHELL("shell")` + + - `List tools` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `Optional topP` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `Optional background` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `Optional completedAt` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `Optional conversation` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `String id` + + The unique ID of the conversation that this response was associated with. + + - `Optional maxOutputTokens` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `Optional maxToolCalls` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `Optional moderation` + + Moderation results for the response input and output, if moderated completions were requested. + + - `Input input` + + Moderation for the response input. + + - `class ModerationResult:` + + A moderation result produced for the response input or output. + + - `Categories categories` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `CategoryAppliedInputTypes categoryAppliedInputTypes` + + Which modalities of input are reflected by the score for each category. + + - `TEXT("text")` + + - `IMAGE("image")` + + - `CategoryScores categoryScores` + + A dictionary of moderation categories to scores. + + - `boolean flagged` + + A boolean indicating whether the content was flagged by any category. + + - `String model` + + The moderation model that produced this result. + + - `JsonValue; type "moderation_result"constant` + + The object type, which was always `moderation_result` for successful moderation results. + + - `MODERATION_RESULT("moderation_result")` + + - `class Error:` + + An error produced while attempting moderation for the response input or output. + + - `String code` + + The error code. + + - `String message` + + The error message. + + - `JsonValue; type "error"constant` + + The object type, which was always `error` for moderation failures. + + - `ERROR("error")` + + - `Output output` + + Moderation for the response output. + + - `class ModerationResult:` + + A moderation result produced for the response input or output. + + - `Categories categories` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `CategoryAppliedInputTypes categoryAppliedInputTypes` + + Which modalities of input are reflected by the score for each category. + + - `TEXT("text")` + + - `IMAGE("image")` + + - `CategoryScores categoryScores` + + A dictionary of moderation categories to scores. + + - `boolean flagged` + + A boolean indicating whether the content was flagged by any category. + + - `String model` + + The moderation model that produced this result. + + - `JsonValue; type "moderation_result"constant` + + The object type, which was always `moderation_result` for successful moderation results. + + - `MODERATION_RESULT("moderation_result")` + + - `class Error:` + + An error produced while attempting moderation for the response input or output. + + - `String code` + + The error code. + + - `String message` + + The error message. + + - `JsonValue; type "error"constant` + + The object type, which was always `error` for moderation failures. + + - `ERROR("error")` + + - `Optional previousResponseId` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `Optional prompt` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `String id` + + The unique identifier of the prompt template to use. + + - `Optional variables` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `String` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Optional version` + + Optional version of the prompt template. + + - `Optional promptCacheKey` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `Optional promptCacheOptions` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `Mode mode` + + Whether implicit prompt-cache breakpoints were enabled. + + - `IMPLICIT("implicit")` + + - `EXPLICIT("explicit")` + + - `Ttl ttl` + + The minimum lifetime applied to each cache breakpoint. + + - `_30M("30m")` + + - `Optional promptCacheRetention` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `IN_MEMORY("in_memory")` + + - `_24H("24h")` + + - `Optional reasoning` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `Optional context` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `AUTO("auto")` + + - `CURRENT_TURN("current_turn")` + + - `ALL_TURNS("all_turns")` + + - `Optional effort` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `NONE("none")` + + - `MINIMAL("minimal")` + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `XHIGH("xhigh")` + + - `MAX("max")` + + - `Optional generateSummary` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `AUTO("auto")` + + - `CONCISE("concise")` + + - `DETAILED("detailed")` + + - `Optional mode` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `STANDARD("standard")` + + - `PRO("pro")` + + - `Optional summary` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `AUTO("auto")` + + - `CONCISE("concise")` + + - `DETAILED("detailed")` + + - `Optional safetyIdentifier` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `Optional serviceTier` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `AUTO("auto")` + + - `DEFAULT("default")` + + - `FLEX("flex")` + + - `SCALE("scale")` + + - `PRIORITY("priority")` + + - `Optional status` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `COMPLETED("completed")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + + - `CANCELLED("cancelled")` + + - `QUEUED("queued")` + + - `INCOMPLETE("incomplete")` + + - `Optional text` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `Optional format` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + The type of response format being defined. Always `text`. + + - `TEXT("text")` + + - `class BetaResponseFormatTextJsonSchemaConfig:` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `String name` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `Schema schema` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `JsonValue; type "json_schema"constant` + + The type of response format being defined. Always `json_schema`. + + - `JSON_SCHEMA("json_schema")` + + - `Optional description` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `Optional strict` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). + + - `JsonValue;` + + - `JsonValue; type "json_object"constant` + + The type of response format being defined. Always `json_object`. + + - `JSON_OBJECT("json_object")` + + - `Optional verbosity` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional topLogprobs` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `Optional truncation` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `AUTO("auto")` + + - `DISABLED("disabled")` + + - `Optional usage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `long inputTokens` + + The number of input tokens. + + - `InputTokensDetails inputTokensDetails` + + A detailed breakdown of the input tokens. + + - `long cacheWriteTokens` + + The number of input tokens that were written to the cache. + + - `long cachedTokens` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `long outputTokens` + + The number of output tokens. + + - `OutputTokensDetails outputTokensDetails` + + A detailed breakdown of the output tokens. + + - `long reasoningTokens` + + The number of reasoning tokens. + + - `long totalTokens` + + The total number of tokens used. + + - `Optional user` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + +### Example + +```java +package com.openai.example; + +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.responses.BetaResponse; +import com.openai.models.beta.responses.ResponseCancelParams; + +public final class Main { + private Main() {} + + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + + BetaResponse betaResponse = client.beta().responses().cancel("resp_677efb5139a88190b512bc3fef8e535d"); + } +} +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` + +## Compact a response + +`BetaCompactedResponse beta().responses().compact(ResponseCompactParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + +**post** `/responses/compact?beta=true` + +Compact a conversation. Returns a compacted response object. + +Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced). + +### Parameters + +- `ResponseCompactParams params` + + - `Optional> betas` + + - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + + - `Optional model` + + Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. + + - `GPT_5_6_SOL("gpt-5.6-sol")` + + - `GPT_5_6_TERRA("gpt-5.6-terra")` + + - `GPT_5_6_LUNA("gpt-5.6-luna")` + + - `GPT_5_4("gpt-5.4")` + + - `GPT_5_4_MINI("gpt-5.4-mini")` + + - `GPT_5_4_NANO("gpt-5.4-nano")` + + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + + - `GPT_5_2("gpt-5.2")` + + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + + - `GPT_5_2_PRO("gpt-5.2-pro")` + + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + + - `GPT_5_1("gpt-5.1")` + + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + + - `GPT_5_1_CODEX("gpt-5.1-codex")` + + - `GPT_5_1_MINI("gpt-5.1-mini")` + + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + + - `GPT_5("gpt-5")` + + - `GPT_5_MINI("gpt-5-mini")` + + - `GPT_5_NANO("gpt-5-nano")` + + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + + - `GPT_4_1("gpt-4.1")` + + - `GPT_4_1_MINI("gpt-4.1-mini")` + + - `GPT_4_1_NANO("gpt-4.1-nano")` + + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + + - `O4_MINI("o4-mini")` + + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + + - `O3("o3")` + + - `O3_2025_04_16("o3-2025-04-16")` + + - `O3_MINI("o3-mini")` + + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + + - `O1("o1")` + + - `O1_2024_12_17("o1-2024-12-17")` + + - `O1_PREVIEW("o1-preview")` + + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + + - `O1_MINI("o1-mini")` + + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + + - `GPT_4O("gpt-4o")` + + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + + - `CODEX_MINI_LATEST("codex-mini-latest")` + + - `GPT_4O_MINI("gpt-4o-mini")` + + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + + - `GPT_4_TURBO("gpt-4-turbo")` + + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + + - `GPT_4("gpt-4")` + + - `GPT_4_0314("gpt-4-0314")` + + - `GPT_4_0613("gpt-4-0613")` + + - `GPT_4_32K("gpt-4-32k")` + + - `GPT_4_32K_0314("gpt-4-32k-0314")` + + - `GPT_4_32K_0613("gpt-4-32k-0613")` + + - `GPT_3_5_TURBO("gpt-3.5-turbo")` + + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + + - `O1_PRO("o1-pro")` + + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + + - `O3_PRO("o3-pro")` + + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + + - `O3_DEEP_RESEARCH("o3-deep-research")` + + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + + - `COMPUTER_USE_PREVIEW("computer-use-preview")` + + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + + - `GPT_5_CODEX("gpt-5-codex")` + + - `GPT_5_PRO("gpt-5-pro")` + + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + + - `Optional input` + + Text, image, or file inputs to the model, used to generate a response + + - `String` + + - `List` + + - `class BetaEasyInputMessage:` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `Content content` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `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 fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + 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` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `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` + + 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` + + The type of the message input. Always `message`. + + - `MESSAGE("message")` + + - `Message` + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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` + + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `String id` + + The unique ID of the output message. + + - `List content` + + The content of the output message. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `List 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> logprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `class BetaResponseOutputRefusal:` + + 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `String id` + + The unique ID of the file search tool call. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> results` + + The results of the file search tool call. + + - `Optional 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 fileId` + + The unique ID of the file. + + - `Optional filename` + + The name of the file. + + - `Optional score` + + The relevance score of the file - a value between 0 and 1. + + - `Optional text` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `String id` + + The unique ID of the computer call. + + - `String callId` + + An identifier used when responding to the tool call with output. + + - `List pendingSafetyChecks` + + The pending safety checks for the computer call. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional 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` + + A click action. + + - `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> keys` + + The keys being held while clicking. + + - `DoubleClick` + + - `Optional> 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` + + 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> keys` + + The keys being held while dragging the mouse. + + - `Keypress` + + - `List 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> 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> 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")` + + - `Optional> actions` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click` + + - `DoubleClick` + + - `Drag` + + - `Keypress` + + - `Move` + + - `JsonValue;` + + - `Scroll` + + - `Type` + + - `JsonValue;` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ComputerCallOutput` + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot 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 fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional 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 id` + + The ID of the computer tool call output. + + - `Optional> 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 code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `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. + + - `JsonValue; type "search"constant` + + The action type. + + - `SEARCH("search")` + + - `Optional> queries` + + The search queries. + + - `Optional query` + + The search query. + + - `Optional> 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 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `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 id` + + The unique ID of the function tool call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the function to run. + + - `Optional 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` + + - `class BetaResponseInputTextContent:` + + 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional 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 fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFileContent:` + + 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` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The base64-encoded data of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `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 id` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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")` + + - `AgentMessage` + + - `String author` + + The sending agent identity. + + - `List content` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent:` + + A text input to the model. + + - `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The item type. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional id` + + The unique ID of this agent message item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `Action action` + + The multi-agent action that was executed. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The action arguments as a JSON string. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The item type. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional id` + + The unique ID of this multi-agent call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `String text` + + The text content. + + - `JsonValue; type "output_text"constant` + + The content type. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional annotations` + + Citations associated with the text content. + + - `List` + + - `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 citation type. Always `file_citation`. + + - `FILE_CITATION("file_citation")` + + - `List` + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `String title` + + The title of the cited resource. + + - `JsonValue; type "url_citation"constant` + + The citation type. Always `url_citation`. + + - `URL_CITATION("url_citation")` + + - `String url` + + The URL of the cited resource. + + - `List` + + - `String containerId` + + The ID of the container. + + - `long endIndex` + + The index of the last character of the citation in the message. + + - `String fileId` + + The ID of the container file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The citation type. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 id` + + The unique ID of this tool search call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search call. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `class BetaResponseToolSearchOutputItemParam:` + + - `List tools` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `String name` + + The name of the function to call. + + - `Optional parameters` + + A JSON schema object describing the parameters of the function. + + - `Optional strict` + + Whether strict parameter validation is enforced for this function tool. + + - `JsonValue; type "function"constant` + + The type of the function tool. Always `function`. + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function is deferred and loaded via tool search. + + - `Optional description` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `Optional outputSchema` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `JsonValue; type "file_search"constant` + + The type of the file search tool. Always `file_search`. + + - `FILE_SEARCH("file_search")` + + - `List vectorStoreIds` + + The IDs of the vector stores to search. + + - `Optional 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` + + - `String` + + - `double` + + - `class CompoundFilter:` + + Combine multiple filters using `and` or `or`. + + - `List 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. + + - `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` + + - `String` + + - `double` + + - `JsonValue` + + - `Type type` + + Type of operation: `and` or `or`. + + - `AND("and")` + + - `OR("or")` + + - `Optional maxNumResults` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `Optional rankingOptions` + + Ranking options for search. + + - `Optional 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` + + The ranker to use for the file search. + + - `AUTO("auto")` + + - `DEFAULT_2024_11_15("default-2024-11-15")` + + - `Optional 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 BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `JsonValue; type "computer"constant` + + The type of the computer tool. Always `computer`. + + - `COMPUTER("computer")` + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `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 BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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 for the search. + + - `Optional> 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` + + High 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` + + The approximate location of the user. + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `Optional 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional allowedTools` + + List of allowed tool names or a filter object. + + - `List` + + - `class McpToolFilter:` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional 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` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `CONNECTOR_DROPBOX("connector_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 deferLoading` + + Whether this MCP tool is deferred and discovered via tool search. + + - `Optional headers` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `Optional 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` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional never` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> 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 serverDescription` + + Optional description of the MCP server, used to provide more context. + + - `Optional serverUrl` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `Optional tunnelId` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter` + + - `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> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the code interpreter container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `JsonValue; type "disabled"constant` + + Disable outbound network access. Always `disabled`. + + - `DISABLED("disabled")` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `List 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> 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")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The type of the tool. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `ImageGeneration` + + - `JsonValue; type "image_generation"constant` + + The type of the image generation tool. Always `image_generation`. + + - `IMAGE_GENERATION("image_generation")` + + - `Optional action` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `GENERATE("generate")` + + - `EDIT("edit")` + + - `AUTO("auto")` + + - `Optional 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` + + 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` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `Optional fileId` + + File ID for the mask image. + + - `Optional imageUrl` + + Base64-encoded mask image. + + - `Optional 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 level for the generated image. Default: `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `Optional outputCompression` + + Compression level for the output image. Default: 100. + + - `Optional outputFormat` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `PNG("png")` + + - `WEBP("webp")` + + - `JPEG("jpeg")` + + - `Optional partialImages` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `Optional 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 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`. + + - `_1024X1024("1024x1024")` + + - `_1024X1536("1024x1536")` + + - `_1536X1024("1536x1024")` + + - `AUTO("auto")` + + - `JsonValue;` + + - `JsonValue; type "local_shell"constant` + + The type of the local shell tool. Always `local_shell`. + + - `LOCAL_SHELL("local_shell")` + + - `class BetaFunctionShellTool:` + + 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional environment` + + - `class BetaContainerAuto:` + + - `JsonValue; type "container_auto"constant` + + Automatically creates a container for this request + + - `CONTAINER_AUTO("container_auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `Optional> skills` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference:` + + - `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 version` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill:` + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `BetaInlineSkillSource 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 BetaLocalEnvironment:` + + - `JsonValue; type "local"constant` + + Use a local computer environment. + + - `LOCAL("local")` + + - `Optional> 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 BetaContainerReference:` + + - `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 BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this tool should be deferred and discovered via tool search. + + - `Optional description` + + Optional description of the custom tool, used to provide more context. + + - `Optional format` + + The input format for the custom tool. Default is unconstrained text. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + Unconstrained text format. Always `text`. + + - `TEXT("text")` + + - `class Grammar:` + + A grammar defined by the user. + + - `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 BetaNamespaceTool:` + + 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 tools` + + The function/custom tools available inside this namespace. + + - `class Function:` + + - `String name` + + - `JsonValue; type "function"constant` + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function should be deferred and discovered via tool search. + + - `Optional description` + + - `Optional outputSchema` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `Optional parameters` + + - `Optional strict` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `JsonValue; type "namespace"constant` + + The type of the tool. Always `namespace`. + + - `NAMESPACE("namespace")` + + - `class BetaToolSearchTool:` + + 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 description` + + Description shown to the model for a client-executed tool search tool. + + - `Optional execution` + + Whether tool search is executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional parameters` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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> searchContentTypes` + + - `TEXT("text")` + + - `IMAGE("image")` + + - `Optional 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` + + The user's location. + + - `JsonValue; type "approximate"constant` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "apply_patch"constant` + + The type of the tool. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue; type "tool_search_output"constant` + + The item type. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional id` + + The unique ID of this tool search output. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Optional execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search output. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `AdditionalTools` + + - `JsonValue; role "developer"constant` + + The role that provided the additional tools. Only `developer` is supported. + + - `DEVELOPER("developer")` + + - `List tools` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "additional_tools"constant` + + The item type. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional id` + + The unique ID of this additional tools item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `String id` + + The unique identifier of the reasoning content. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> 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 encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional 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 BetaResponseCompactionItemParam:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `String encryptedContent` + + The encrypted content of the compaction summary. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional id` + + The ID of the compaction item. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall:` + + A tool call to run code. + + - `String id` + + The unique ID of the code interpreter tool call. + + - `Optional code` + + The code to run, or null if not available. + + - `String containerId` + + The ID of the container used to run the code. + + - `Optional> 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. + + - `Action action` + + Execute a shell command on the server. + + - `List 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 timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` + + Optional user to run the command as. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 commands` + + Ordered shell commands for the execution environment to run. + + - `Optional maxOutputLength` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `Optional 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 id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional environment` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment:` + + - `class BetaContainerReference:` + + - `Optional 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 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 id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional maxOutputLength` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `Optional 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 id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `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 id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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 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 annotations` + + Additional annotations about the tool. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `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 id` + + The unique ID of the approval response + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 error` + + The error from the tool call, if any. + + - `Optional output` + + The output from the tool call. + + - `Optional 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 BetaResponseCustomToolCallOutput:` + + 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` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `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 id` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `class BetaResponseCustomToolCall:` + + 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 id` + + The unique ID of the custom tool call in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the custom tool being called. + + - `CompactionTrigger` + + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` + + - `String id` + + The ID of the item to reference. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional type` + + The type of item to reference. Always `item_reference`. + + - `ITEM_REFERENCE("item_reference")` + + - `Program` + + - `String id` + + The unique ID of this program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The item type. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of this program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The item type. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional instructions` + + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + + - `Optional previousResponseId` + + The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `Optional promptCacheKey` + + A key to use when reading from or writing to the prompt cache. + + - `Optional promptCacheOptions` + + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + + - `Optional mode` + + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + + - `IMPLICIT("implicit")` + + - `EXPLICIT("explicit")` + + - `Optional ttl` + + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + + - `_30M("30m")` + + - `Optional promptCacheRetention` + + How long to retain a prompt cache entry created by this request. + + - `IN_MEMORY("in_memory")` + + - `_24H("24h")` + + - `Optional serviceTier` + + The service tier to use for this request. + + - `AUTO("auto")` + + - `DEFAULT("default")` + + - `FLEX("flex")` + + - `PRIORITY("priority")` + +### Returns + +- `class BetaCompactedResponse:` + + - `String id` + + The unique identifier for the compacted response. + + - `long createdAt` + + Unix timestamp (in seconds) when the compacted conversation was created. + + - `JsonValue; object_ "response.compaction"constant` + + The object type. Always `response.compaction`. + + - `RESPONSE_COMPACTION("response.compaction")` + + - `List output` + + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `String id` + + The unique ID of the output message. + + - `List content` + + The content of the output message. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `List 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> logprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `List topLogprobs` + + - `String token` + + - `List bytes` + + - `double logprob` + + - `class BetaResponseOutputRefusal:` + + 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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 BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `String id` + + The unique ID of the file search tool call. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> results` + + The results of the file search tool call. + + - `Optional 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 fileId` + + The unique ID of the file. + + - `Optional filename` + + The name of the file. + + - `Optional score` + + The relevance score of the file - a value between 0 and 1. + + - `Optional text` + + The text that was retrieved from the file. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `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 id` + + The unique ID of the function tool call. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the function to run. + + - `Optional 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 BetaResponseFunctionToolCallOutputItem:` + + - `String id` + + The unique ID of the function call tool output. + + - `String callId` + + The unique ID of the function tool call generated by the model. + + - `Output output` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String` + + - `List` + + - `class BetaResponseInputText:` + + 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `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 fileId` + + The ID of the file to be sent to the model. + + - `Optional imageUrl` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + 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` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `HIGH("high")` + + - `Optional fileData` + + The content of the file to be sent to the model. + + - `Optional fileId` + + The ID of the file to be sent to the model. + + - `Optional fileUrl` + + The URL of the file to be sent to the model. + + - `Optional filename` + + The name of the file to be sent to the model. + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `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")` + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + The caller type. Always `direct`. + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AgentMessage` + + - `String id` + + The unique ID of the agent message. + + - `String author` + + The sending agent identity. + + - `List content` + + Encrypted content sent between agents. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseOutputText:` + + A text output from the model. + + - `class Text:` + + A text content. + + - `String text` + + - `JsonValue; type "text"constant` + + - `TEXT("text")` + + - `class SummaryText:` + + 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 BetaResponseOutputRefusal:` + + A refusal from the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot:` + + A screenshot of a computer. + + - `Detail 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 fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional 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")` + + - `Optional promptCacheBreakpoint` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The type of the item. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` + + - `String id` + + The unique ID of the multi-agent call item. + + - `Action action` + + The multi-agent action to execute. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The JSON string of arguments generated for the action. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `String id` + + The unique ID of the multi-agent call output item. + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `List annotations` + + The annotations of the text output. + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `Optional> logprobs` + + - `JsonValue; type "multi_agent_call_output"constant` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `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. + + - `JsonValue; type "search"constant` + + The action type. + + - `SEARCH("search")` + + - `Optional> queries` + + The search queries. + + - `Optional query` + + The search query. + + - `Optional> 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 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `String id` + + The unique ID of the computer call. + + - `String callId` + + An identifier used when responding to the tool call with output. + + - `List pendingSafetyChecks` + + The pending safety checks for the computer call. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional 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` + + A click action. + + - `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> keys` + + The keys being held while clicking. + + - `DoubleClick` + + - `Optional> 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` + + 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> keys` + + The keys being held while dragging the mouse. + + - `Keypress` + + - `List 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> 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> 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")` + + - `Optional> actions` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click` + + - `DoubleClick` + + - `Drag` + + - `Keypress` + + - `Move` + + - `JsonValue;` + + - `Scroll` + + - `Type` + + - `JsonValue;` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseComputerToolCallOutputItem:` + + - `String id` + + The unique ID of the computer call tool output. + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot 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 fileId` + + The identifier of an uploaded file that contains the screenshot. + + - `Optional imageUrl` + + The URL of the screenshot image. + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + + - `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> 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 code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `String id` + + The unique identifier of the reasoning content. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> 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 encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional 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")` + + - `Program` + + - `String id` + + The unique ID of the program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The type of the item. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of the program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output item. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The type of the item. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall:` + + - `String id` + + The unique ID of the tool search call item. + + - `JsonValue arguments` + + Arguments used for the tool search call. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search call item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "tool_search_call"constant` + + The type of the item. Always `tool_search_call`. + + - `TOOL_SEARCH_CALL("tool_search_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem:` + + - `String id` + + The unique ID of the tool search output item. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search output item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `List tools` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `String name` + + The name of the function to call. + + - `Optional parameters` + + A JSON schema object describing the parameters of the function. + + - `Optional strict` + + Whether strict parameter validation is enforced for this function tool. + + - `JsonValue; type "function"constant` + + The type of the function tool. Always `function`. + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function is deferred and loaded via tool search. + + - `Optional description` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `Optional outputSchema` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `JsonValue; type "file_search"constant` + + The type of the file search tool. Always `file_search`. + + - `FILE_SEARCH("file_search")` + + - `List vectorStoreIds` + + The IDs of the vector stores to search. + + - `Optional 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` + + - `String` + + - `double` + + - `class CompoundFilter:` + + Combine multiple filters using `and` or `or`. + + - `List 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. + + - `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` + + - `String` + + - `double` + + - `JsonValue` + + - `Type type` + + Type of operation: `and` or `or`. + + - `AND("and")` + + - `OR("or")` + + - `Optional maxNumResults` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `Optional rankingOptions` + + Ranking options for search. + + - `Optional 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` + + The ranker to use for the file search. + + - `AUTO("auto")` + + - `DEFAULT_2024_11_15("default-2024-11-15")` + + - `Optional 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 BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `JsonValue; type "computer"constant` + + The type of the computer tool. Always `computer`. + + - `COMPUTER("computer")` + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `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 BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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 for the search. + + - `Optional> 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` + + High 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` + + The approximate location of the user. + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `Optional 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional allowedTools` + + List of allowed tool names or a filter object. + + - `List` + + - `class McpToolFilter:` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional 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` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `CONNECTOR_DROPBOX("connector_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 deferLoading` + + Whether this MCP tool is deferred and discovered via tool search. + + - `Optional headers` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `Optional 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` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional never` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> 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 serverDescription` + + Optional description of the MCP server, used to provide more context. + + - `Optional serverUrl` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `Optional tunnelId` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter` + + - `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> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the code interpreter container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `JsonValue; type "disabled"constant` + + Disable outbound network access. Always `disabled`. + + - `DISABLED("disabled")` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `List 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> 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")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The type of the tool. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `ImageGeneration` + + - `JsonValue; type "image_generation"constant` + + The type of the image generation tool. Always `image_generation`. + + - `IMAGE_GENERATION("image_generation")` + + - `Optional action` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `GENERATE("generate")` + + - `EDIT("edit")` + + - `AUTO("auto")` + + - `Optional 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` + + 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` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `Optional fileId` + + File ID for the mask image. + + - `Optional imageUrl` + + Base64-encoded mask image. + + - `Optional 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 level for the generated image. Default: `auto`. + + - `AUTO("auto")` + + - `LOW("low")` + + - `Optional outputCompression` + + Compression level for the output image. Default: 100. + + - `Optional outputFormat` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `PNG("png")` + + - `WEBP("webp")` + + - `JPEG("jpeg")` + + - `Optional partialImages` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `Optional 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 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`. + + - `_1024X1024("1024x1024")` + + - `_1024X1536("1024x1536")` + + - `_1536X1024("1536x1024")` + + - `AUTO("auto")` + + - `JsonValue;` + + - `JsonValue; type "local_shell"constant` + + The type of the local shell tool. Always `local_shell`. + + - `LOCAL_SHELL("local_shell")` + + - `class BetaFunctionShellTool:` + + 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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional environment` + + - `class BetaContainerAuto:` + + - `JsonValue; type "container_auto"constant` + + Automatically creates a container for this request + + - `CONTAINER_AUTO("container_auto")` + + - `Optional> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `Optional> skills` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference:` + + - `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 version` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill:` + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `BetaInlineSkillSource 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 BetaLocalEnvironment:` + + - `JsonValue; type "local"constant` + + Use a local computer environment. + + - `LOCAL("local")` + + - `Optional> 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 BetaContainerReference:` + + - `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 BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `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> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this tool should be deferred and discovered via tool search. + + - `Optional description` + + Optional description of the custom tool, used to provide more context. + + - `Optional format` + + The input format for the custom tool. Default is unconstrained text. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + Unconstrained text format. Always `text`. + + - `TEXT("text")` + + - `class Grammar:` + + A grammar defined by the user. + + - `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 BetaNamespaceTool:` + + 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 tools` + + The function/custom tools available inside this namespace. + + - `class Function:` + + - `String name` + + - `JsonValue; type "function"constant` + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function should be deferred and discovered via tool search. + + - `Optional description` + + - `Optional outputSchema` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `Optional parameters` + + - `Optional strict` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `JsonValue; type "namespace"constant` + + The type of the tool. Always `namespace`. + + - `NAMESPACE("namespace")` + + - `class BetaToolSearchTool:` + + 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 description` + + Description shown to the model for a client-executed tool search tool. + + - `Optional execution` + + Whether tool search is executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional parameters` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Type 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> searchContentTypes` + + - `TEXT("text")` + + - `IMAGE("image")` + + - `Optional 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` + + The user's location. + + - `JsonValue; type "approximate"constant` + + The type of location approximation. Always `approximate`. + + - `APPROXIMATE("approximate")` + + - `Optional city` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `Optional country` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `Optional region` + + Free text input for the region of the user, e.g. `California`. + + - `Optional timezone` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "apply_patch"constant` + + The type of the tool. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `JsonValue; type "tool_search_output"constant` + + The type of the item. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AdditionalTools` + + - `String id` + + The unique ID of the additional tools item. + + - `Role role` + + The role that provided the additional tools. + + - `UNKNOWN("unknown")` + + - `USER("user")` + + - `ASSISTANT("assistant")` + + - `SYSTEM("system")` + + - `CRITIC("critic")` + + - `DISCRIMINATOR("discriminator")` + + - `DEVELOPER("developer")` + + - `TOOL("tool")` + + - `List tools` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` + - `class BetaWebSearchPreviewTool:` -## Domain Types + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -### Annotation + - `class BetaApplyPatchTool:` -- `class Annotation:` + Allows the assistant to create, delete, or update files using unified diffs. -### Annotation Delta + - `JsonValue; type "additional_tools"constant` -- `class AnnotationDelta:` + The type of the item. Always `additional_tools`. -### File Citation Annotation + - `ADDITIONAL_TOOLS("additional_tools")` -- `class FileCitationAnnotation:` + - `Optional agent` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + The agent that produced this item. - - `long endIndex` + - `String agentName` - - `FileCitation fileCitation` + The canonical name of the agent that produced this item. - - `String fileId` + - `class BetaResponseCompactionItem:` - The ID of the specific File the citation is from. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `long startIndex` + - `String id` - - `String text` + The unique ID of the compaction item. - The text in the message content that needs to be replaced. + - `String encryptedContent` - - `JsonValue; type "file_citation"constant` + The encrypted content that was produced by compaction. - Always `file_citation`. + - `JsonValue; type "compaction"constant` - - `FILE_CITATION("file_citation")` + The type of the item. Always `compaction`. -### File Citation Delta Annotation + - `COMPACTION("compaction")` -- `class FileCitationDeltaAnnotation:` + - `Optional agent` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + The agent that produced this item. - - `long index` + - `String agentName` - The index of the annotation in the text content part. + The canonical name of the agent that produced this item. - - `JsonValue; type "file_citation"constant` + - `Optional createdBy` - Always `file_citation`. + The identifier of the actor that created the item. - - `FILE_CITATION("file_citation")` + - `ImageGenerationCall` - - `Optional endIndex` + - `String id` - - `Optional fileCitation` + The unique ID of the image generation call. - - `Optional fileId` + - `Optional result` - The ID of the specific File the citation is from. + The generated image encoded in base64. - - `Optional quote` + - `Status status` - The specific quote in the file. + The status of the image generation call. - - `Optional startIndex` + - `IN_PROGRESS("in_progress")` - - `Optional text` + - `COMPLETED("completed")` - The text in the message content that needs to be replaced. + - `GENERATING("generating")` -### File Path Annotation + - `FAILED("failed")` -- `class FilePathAnnotation:` + - `JsonValue; type "image_generation_call"constant` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The type of the image generation call. Always `image_generation_call`. - - `long endIndex` + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `FilePath filePath` + - `Optional agent` - - `String fileId` + The agent that produced this item. - The ID of the file that was generated. + - `String agentName` - - `long startIndex` + The canonical name of the agent that produced this item. - - `String text` + - `class BetaResponseCodeInterpreterToolCall:` - The text in the message content that needs to be replaced. + A tool call to run code. - - `JsonValue; type "file_path"constant` + - `String id` - Always `file_path`. + The unique ID of the code interpreter tool call. - - `FILE_PATH("file_path")` + - `Optional code` -### File Path Delta Annotation + The code to run, or null if not available. -- `class FilePathDeltaAnnotation:` + - `String containerId` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The ID of the container used to run the code. - - `long index` + - `Optional> outputs` - The index of the annotation in the text content part. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `JsonValue; type "file_path"constant` + - `class Logs:` - Always `file_path`. + The logs output from the code interpreter. - - `FILE_PATH("file_path")` + - `String logs` - - `Optional endIndex` + The logs output from the code interpreter. - - `Optional filePath` + - `JsonValue; type "logs"constant` - - `Optional fileId` + The type of the output. Always `logs`. - The ID of the file that was generated. + - `LOGS("logs")` - - `Optional startIndex` + - `class Image:` - - `Optional text` + The image output from the code interpreter. - The text in the message content that needs to be replaced. + - `JsonValue; type "image"constant` -### Image File + The type of the output. Always `image`. -- `class ImageFile:` + - `IMAGE("image")` - - `String fileId` + - `String url` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The URL of the image output from the code interpreter. - - `Optional detail` + - `Status status` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `AUTO("auto")` + - `IN_PROGRESS("in_progress")` - - `LOW("low")` + - `COMPLETED("completed")` - - `HIGH("high")` + - `INCOMPLETE("incomplete")` -### Image File Content Block + - `INTERPRETING("interpreting")` -- `class ImageFileContentBlock:` + - `FAILED("failed")` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `JsonValue; type "code_interpreter_call"constant` - - `ImageFile imageFile` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `String fileId` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `Optional agent` - - `Optional detail` + The agent that produced this item. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `String agentName` - - `AUTO("auto")` + The canonical name of the agent that produced this item. - - `LOW("low")` + - `LocalShellCall` - - `HIGH("high")` + - `String id` - - `JsonValue; type "image_file"constant` + The unique ID of the local shell call. - Always `image_file`. + - `Action action` - - `IMAGE_FILE("image_file")` + Execute a shell command on the server. -### Image File Delta + - `List command` -- `class ImageFileDelta:` + The command to run. - - `Optional detail` + - `Env env` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + Environment variables to set for the command. - - `AUTO("auto")` + - `JsonValue; type "exec"constant` - - `LOW("low")` + The type of the local shell action. Always `exec`. - - `HIGH("high")` + - `EXEC("exec")` - - `Optional fileId` + - `Optional timeoutMs` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + Optional timeout in milliseconds for the command. -### Image File Delta Block + - `Optional user` -- `class ImageFileDeltaBlock:` + Optional user to run the command as. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `Optional workingDirectory` - - `long index` + Optional working directory to run the command in. - The index of the content part in the message. + - `String callId` - - `JsonValue; type "image_file"constant` + The unique ID of the local shell tool call generated by the model. - Always `image_file`. + - `Status status` - - `IMAGE_FILE("image_file")` + The status of the local shell call. - - `Optional imageFile` + - `IN_PROGRESS("in_progress")` - - `Optional detail` + - `COMPLETED("completed")` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `INCOMPLETE("incomplete")` - - `AUTO("auto")` + - `JsonValue; type "local_shell_call"constant` - - `LOW("low")` + The type of the local shell call. Always `local_shell_call`. - - `HIGH("high")` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `Optional fileId` + - `Optional agent` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The agent that produced this item. -### Image URL + - `String agentName` -- `class ImageUrl:` + The canonical name of the agent that produced this item. - - `String url` + - `LocalShellCallOutput` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `String id` - - `Optional detail` + The unique ID of the local shell tool call generated by the model. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `String output` - - `AUTO("auto")` + A JSON string of the output of the local shell tool call. - - `LOW("low")` + - `JsonValue; type "local_shell_call_output"constant` - - `HIGH("high")` + The type of the local shell tool call output. Always `local_shell_call_output`. -### Image URL Content Block + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` -- `class ImageUrlContentBlock:` + - `Optional agent` - References an image URL in the content of a message. + The agent that produced this item. - - `ImageUrl imageUrl` + - `String agentName` - - `String url` + The canonical name of the agent that produced this item. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `Optional status` - - `Optional detail` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `IN_PROGRESS("in_progress")` - - `AUTO("auto")` + - `COMPLETED("completed")` - - `LOW("low")` + - `INCOMPLETE("incomplete")` - - `HIGH("high")` + - `class BetaResponseFunctionShellToolCall:` - - `JsonValue; type "image_url"constant` + A tool call that executes one or more shell commands in a managed environment. - The type of the content part. + - `String id` - - `IMAGE_URL("image_url")` + The unique ID of the shell tool call. Populated when this item is returned via API. -### Image URL Delta + - `Action action` -- `class ImageUrlDelta:` + The shell commands and limits that describe how to run the tool call. - - `Optional detail` + - `List commands` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `Optional maxOutputLength` - - `AUTO("auto")` + Optional maximum number of characters to return from each command. - - `LOW("low")` + - `Optional timeoutMs` - - `HIGH("high")` + Optional timeout in milliseconds for the commands. - - `Optional url` + - `String callId` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The unique ID of the shell tool call generated by the model. -### Image URL Delta Block + - `Optional environment` -- `class ImageUrlDeltaBlock:` + Represents the use of a local environment to perform shell actions. - References an image URL in the content of a message. + - `class BetaResponseLocalEnvironment:` - - `long index` + Represents the use of a local environment to perform shell actions. - The index of the content part in the message. + - `JsonValue; type "local"constant` - - `JsonValue; type "image_url"constant` + The environment type. Always `local`. - Always `image_url`. + - `LOCAL("local")` - - `IMAGE_URL("image_url")` + - `class BetaResponseContainerReference:` - - `Optional imageUrl` + Represents a container created with /v1/containers. - - `Optional detail` + - `String containerId` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `JsonValue; type "container_reference"constant` - - `AUTO("auto")` + The environment type. Always `container_reference`. - - `LOW("low")` + - `CONTAINER_REFERENCE("container_reference")` - - `HIGH("high")` + - `Status status` - - `Optional url` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `IN_PROGRESS("in_progress")` -### Message + - `COMPLETED("completed")` -- `class Message:` + - `INCOMPLETE("incomplete")` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `JsonValue; type "shell_call"constant` - - `String id` + The type of the item. Always `shell_call`. - The identifier, which can be referenced in API endpoints. + - `SHELL_CALL("shell_call")` - - `Optional assistantId` + - `Optional agent` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The agent that produced this item. - - `Optional> attachments` + - `String agentName` - A list of files attached to the message, and the tools they were added to. + The canonical name of the agent that produced this item. - - `Optional fileId` + - `Optional caller` - The ID of the file to attach to the message. + The execution context that produced this tool call. - - `Optional> tools` + - `JsonValue;` - The tools to add this file to. + - `JsonValue; type "direct"constant` - - `class CodeInterpreterTool:` + - `DIRECT("direct")` - - `JsonValue; type "code_interpreter"constant` + - `class Program:` - The type of tool being defined: `code_interpreter` + - `String callerId` - - `CODE_INTERPRETER("code_interpreter")` + The call ID of the program item that produced this tool call. - - `JsonValue;` + - `JsonValue; type "program"constant` - - `JsonValue; type "file_search"constant` + - `PROGRAM("program")` - The type of tool being defined: `file_search` + - `Optional createdBy` - - `FILE_SEARCH("file_search")` + The ID of the entity that created this tool call. - - `Optional completedAt` + - `class BetaResponseFunctionShellToolCallOutput:` - The Unix timestamp (in seconds) for when the message was completed. + The output of a shell tool call that was emitted. - - `List content` + - `String id` - The content of the message in array of text and/or images. + The unique ID of the shell call output. Populated when this item is returned via API. - - `long createdAt` + - `String callId` - The Unix timestamp (in seconds) for when the message was created. + The unique ID of the shell tool call generated by the model. - - `Optional incompleteAt` + - `Optional maxOutputLength` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `Optional incompleteDetails` + - `List output` - On an incomplete message, details about why the message is incomplete. + An array of shell call output contents - - `Reason reason` + - `Outcome outcome` - The reason the message is incomplete. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `CONTENT_FILTER("content_filter")` + - `JsonValue;` - - `MAX_TOKENS("max_tokens")` + - `JsonValue; type "timeout"constant` - - `RUN_CANCELLED("run_cancelled")` + The outcome type. Always `timeout`. - - `RUN_EXPIRED("run_expired")` + - `TIMEOUT("timeout")` - - `RUN_FAILED("run_failed")` + - `class Exit:` - - `Optional metadata` + Indicates that the shell commands finished and returned an exit code. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `long exitCode` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Exit code from the shell process. - - `JsonValue; object_ "thread.message"constant` + - `JsonValue; type "exit"constant` - The object type, which is always `thread.message`. + The outcome type. Always `exit`. - - `THREAD_MESSAGE("thread.message")` + - `EXIT("exit")` - - `Role role` + - `String stderr` - The entity that produced the message. One of `user` or `assistant`. + The standard error output that was captured. - - `USER("user")` + - `String stdout` - - `ASSISTANT("assistant")` + The standard output that was captured. - - `Optional runId` + - `Optional createdBy` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The identifier of the actor that created the item. - `Status status` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` + - `COMPLETED("completed")` + - `INCOMPLETE("incomplete")` - - `COMPLETED("completed")` + - `JsonValue; type "shell_call_output"constant` - - `String threadId` + The type of the shell call output. Always `shell_call_output`. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `SHELL_CALL_OUTPUT("shell_call_output")` -### Message Content + - `Optional agent` -- `class MessageContent:` + The agent that produced this item. -### Message Content Delta + - `String agentName` -- `class MessageContentDelta:` + The canonical name of the agent that produced this item. -### Message Content Part Param + - `Optional caller` -- `class MessageContentPartParam: A class that can be one of several variants.union` + The execution context that produced this tool call. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `JsonValue;` - - `class ImageFileContentBlock:` + - `JsonValue; type "direct"constant` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `DIRECT("direct")` - - `ImageFile imageFile` + - `class Program:` - - `String fileId` + - `String callerId` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The call ID of the program item that produced this tool call. - - `Optional detail` + - `JsonValue; type "program"constant` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `PROGRAM("program")` - - `AUTO("auto")` + - `Optional createdBy` - - `LOW("low")` + The identifier of the actor that created the item. - - `HIGH("high")` + - `class BetaResponseApplyPatchToolCall:` - - `JsonValue; type "image_file"constant` + A tool call that applies file diffs by creating, deleting, or updating files. - Always `image_file`. + - `String id` - - `IMAGE_FILE("image_file")` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `class ImageUrlContentBlock:` + - `String callId` - References an image URL in the content of a message. + The unique ID of the apply patch tool call generated by the model. - - `ImageUrl imageUrl` + - `Operation operation` - - `String url` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `class CreateFile:` - - `Optional detail` + Instruction describing how to create a file via the apply_patch tool. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `String diff` - - `AUTO("auto")` + Diff to apply. - - `LOW("low")` + - `String path` - - `HIGH("high")` + Path of the file to create. - - `JsonValue; type "image_url"constant` + - `JsonValue; type "create_file"constant` - The type of the content part. + Create a new file with the provided diff. - - `IMAGE_URL("image_url")` + - `CREATE_FILE("create_file")` - - `class TextContentBlockParam:` + - `class DeleteFile:` - The text content that is part of a message. + Instruction describing how to delete a file via the apply_patch tool. - - `String text` + - `String path` - Text content to be sent to the model + Path of the file to delete. - - `JsonValue; type "text"constant` + - `JsonValue; type "delete_file"constant` - Always `text`. + Delete the specified file. - - `TEXT("text")` + - `DELETE_FILE("delete_file")` -### Message Deleted + - `class UpdateFile:` -- `class MessageDeleted:` + Instruction describing how to update a file via the apply_patch tool. - - `String id` + - `String diff` - - `boolean deleted` + Diff to apply. - - `JsonValue; object_ "thread.message.deleted"constant` + - `String path` - - `THREAD_MESSAGE_DELETED("thread.message.deleted")` + Path of the file to update. -### Message Delta + - `JsonValue; type "update_file"constant` -- `class MessageDelta:` + Update an existing file with the provided diff. - The delta containing the fields that have changed on the Message. + - `UPDATE_FILE("update_file")` - - `Optional> content` + - `Status status` - The content of the message in array of text and/or images. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `Optional role` + - `IN_PROGRESS("in_progress")` - The entity that produced the message. One of `user` or `assistant`. + - `COMPLETED("completed")` - - `USER("user")` + - `JsonValue; type "apply_patch_call"constant` - - `ASSISTANT("assistant")` + The type of the item. Always `apply_patch_call`. -### Message Delta Event + - `APPLY_PATCH_CALL("apply_patch_call")` -- `class MessageDeltaEvent:` + - `Optional agent` - Represents a message delta i.e. any changed fields on a message during streaming. + The agent that produced this item. - - `String id` + - `String agentName` - The identifier of the message, which can be referenced in API endpoints. + The canonical name of the agent that produced this item. - - `MessageDelta delta` + - `Optional caller` - The delta containing the fields that have changed on the Message. + The execution context that produced this tool call. - - `Optional> content` + - `JsonValue;` - The content of the message in array of text and/or images. + - `JsonValue; type "direct"constant` - - `Optional role` + - `DIRECT("direct")` - The entity that produced the message. One of `user` or `assistant`. + - `class Program:` - - `USER("user")` + - `String callerId` - - `ASSISTANT("assistant")` + The call ID of the program item that produced this tool call. - - `JsonValue; object_ "thread.message.delta"constant` + - `JsonValue; type "program"constant` - The object type, which is always `thread.message.delta`. + - `PROGRAM("program")` - - `THREAD_MESSAGE_DELTA("thread.message.delta")` + - `Optional createdBy` -### Refusal Content Block + The ID of the entity that created this tool call. -- `class RefusalContentBlock:` + - `class BetaResponseApplyPatchToolCallOutput:` - The refusal content generated by the assistant. + The output emitted by an apply patch tool call. - - `String refusal` + - `String id` - - `JsonValue; type "refusal"constant` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Always `refusal`. + - `String callId` - - `REFUSAL("refusal")` + The unique ID of the apply patch tool call generated by the model. -### Refusal Delta Block + - `Status status` -- `class RefusalDeltaBlock:` + The status of the apply patch tool call output. One of `completed` or `failed`. - The refusal content that is part of a message. + - `COMPLETED("completed")` - - `long index` + - `FAILED("failed")` - The index of the refusal part in the message. + - `JsonValue; type "apply_patch_call_output"constant` - - `JsonValue; type "refusal"constant` + The type of the item. Always `apply_patch_call_output`. - Always `refusal`. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `REFUSAL("refusal")` + - `Optional agent` - - `Optional refusal` + The agent that produced this item. -### Text + - `String agentName` -- `class Text:` + The canonical name of the agent that produced this item. - - `List annotations` + - `Optional caller` - - `String value` + The execution context that produced this tool call. - The data that makes up the text. + - `JsonValue;` -### Text Content Block + - `JsonValue; type "direct"constant` -- `class TextContentBlock:` + - `DIRECT("direct")` - The text content that is part of a message. + - `class Program:` - - `Text text` + - `String callerId` - - `List annotations` + The call ID of the program item that produced this tool call. - - `String value` + - `JsonValue; type "program"constant` - The data that makes up the text. + - `PROGRAM("program")` - - `JsonValue; type "text"constant` + - `Optional createdBy` - Always `text`. + The ID of the entity that created this tool call output. - - `TEXT("text")` + - `Optional output` -### Text Content Block Param + Optional textual output returned by the apply patch tool. -- `class TextContentBlockParam:` + - `McpCall` - The text content that is part of a message. + - `String id` - - `String text` + The unique ID of the tool call. - Text content to be sent to the model + - `String arguments` - - `JsonValue; type "text"constant` + A JSON string of the arguments passed to the tool. - Always `text`. + - `String name` - - `TEXT("text")` + The name of the tool that was run. -### Text Delta + - `String serverLabel` -- `class TextDelta:` + The label of the MCP server running the tool. - - `Optional> annotations` + - `JsonValue; type "mcp_call"constant` - - `Optional value` + The type of the item. Always `mcp_call`. - The data that makes up the text. + - `MCP_CALL("mcp_call")` -### Text Delta Block + - `Optional agent` -- `class TextDeltaBlock:` + The agent that produced this item. - The text content that is part of a message. + - `String agentName` - - `long index` + The canonical name of the agent that produced this item. - The index of the content part in the message. + - `Optional approvalRequestId` - - `JsonValue; type "text"constant` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - Always `text`. + - `Optional error` - - `TEXT("text")` + The error from the tool call, if any. - - `Optional text` + - `Optional output` - - `Optional> annotations` + The output from the tool call. - - `Optional value` + - `Optional status` - The data that makes up the text. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. -# Responses + - `IN_PROGRESS("in_progress")` -## Create a model response + - `COMPLETED("completed")` -`BetaResponse beta().responses().create(ResponseCreateParamsparams = ResponseCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `INCOMPLETE("incomplete")` -**post** `/responses?beta=true` + - `CALLING("calling")` -Create a model response + - `FAILED("failed")` -### Parameters + - `McpListTools` -- `ResponseCreateParams params` + - `String id` - - `Optional> betas` + The unique ID of the list. - - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + - `String serverLabel` - - `Optional background` + The label of the MCP server. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `List tools` - - `Optional> contextManagement` + The tools available on the server. - Context management configuration for this request. + - `JsonValue inputSchema` - - `String type` + The JSON schema describing the tool's input. - The context management entry type. Currently only 'compaction' is supported. + - `String name` - - `Optional compactThreshold` + The name of the tool. - Token threshold at which compaction should be triggered for this entry. + - `Optional annotations` - - `Optional conversation` + Additional annotations about the tool. - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + - `Optional description` - - `String` + The description of the tool. - - `class BetaResponseConversationParam:` + - `JsonValue; type "mcp_list_tools"constant` - The conversation that this response belongs to. + The type of the item. Always `mcp_list_tools`. + + - `MCP_LIST_TOOLS("mcp_list_tools")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional error` + + Error message if the server could not list tools. + + - `McpApprovalRequest` - `String id` - The unique ID of the conversation. + The unique ID of the approval request. - - `Optional> include` + - `String arguments` - Specify additional output data to include in the model response. Currently supported values are: + A JSON string of arguments for the tool. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `String name` - - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` + The name of the tool to run. - - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` + - `String serverLabel` - - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` + The label of the MCP server making the request. - - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` + - `JsonValue; type "mcp_approval_request"constant` - - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` + The type of the item. Always `mcp_approval_request`. - - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` + - `Optional agent` - - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` + The agent that produced this item. - - `Optional input` + - `String agentName` - Text, image, or file inputs to the model, used to generate a response. + The canonical name of the agent that produced this item. - Learn more: + - `McpApprovalResponse` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) + - `String id` - - `String` + The unique ID of the approval response - - `List` + - `String approvalRequestId` - - `class BetaEasyInputMessage:` + The ID of the approval request being answered. - 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. + - `boolean approve` - - `Content content` + Whether the request was approved. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `JsonValue; type "mcp_approval_response"constant` - - `String` + The type of the item. Always `mcp_approval_response`. - - `List` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `class BetaResponseInputText:` + - `Optional agent` - A text input to the model. + The agent that produced this item. - - `String text` + - `String agentName` - The text input to the model. + The canonical name of the agent that produced this item. - - `JsonValue; type "input_text"constant` + - `Optional reason` - The type of the input item. Always `input_text`. + Optional reason for the decision. - - `INPUT_TEXT("input_text")` + - `class BetaResponseCustomToolCall:` - - `Optional promptCacheBreakpoint` + A call to a custom tool created by the model. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String callId` - - `JsonValue; mode "explicit"constant` + An identifier used to map this custom tool call to a tool call output. - The breakpoint mode. Always `explicit`. + - `String input` - - `EXPLICIT("explicit")` + The input for the custom tool call generated by the model. - - `class BetaResponseInputImage:` + - `String name` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The name of the custom tool being called. - - `Detail detail` + - `JsonValue; type "custom_tool_call"constant` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The type of the custom tool call. Always `custom_tool_call`. - - `LOW("low")` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - - `HIGH("high")` + - `Optional id` - - `AUTO("auto")` + The unique ID of the custom tool call in the OpenAI platform. - - `ORIGINAL("original")` + - `Optional agent` - - `JsonValue; type "input_image"constant` + The agent that produced this item. - The type of the input item. Always `input_image`. + - `String agentName` - - `INPUT_IMAGE("input_image")` + The canonical name of the agent that produced this item. - - `Optional fileId` + - `Optional caller` - The ID of the file to be sent to the model. + The execution context that produced this tool call. - - `Optional imageUrl` + - `JsonValue;` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `JsonValue; type "direct"constant` - - `Optional promptCacheBreakpoint` + - `DIRECT("direct")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class Program:` - - `JsonValue; mode "explicit"constant` + - `String callerId` - The breakpoint mode. Always `explicit`. + The call ID of the program item that produced this tool call. - - `EXPLICIT("explicit")` + - `JsonValue; type "program"constant` - - `class BetaResponseInputFile:` + - `PROGRAM("program")` - A file input to the model. + - `Optional namespace` - - `JsonValue; type "input_file"constant` + The namespace of the custom tool being called. - The type of the input item. Always `input_file`. + - `class BetaResponseCustomToolCallOutputItem:` - - `INPUT_FILE("input_file")` + The output of a custom tool call from your code, being sent back to the model. - - `Optional detail` + - `String id` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The unique ID of the custom tool call output item. - - `AUTO("auto")` + - `Status status` - - `LOW("low")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `HIGH("high")` + - `IN_PROGRESS("in_progress")` - - `Optional fileData` + - `COMPLETED("completed")` - The content of the file to be sent to the model. + - `INCOMPLETE("incomplete")` - - `Optional fileId` + - `Optional createdBy` - The ID of the file to be sent to the model. + The identifier of the actor that created the item. - - `Optional fileUrl` + - `BetaResponseUsage usage` - The URL of the file to be sent to the model. + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - - `Optional filename` + - `long inputTokens` - The name of the file to be sent to the model. + The number of input tokens. - - `Optional promptCacheBreakpoint` + - `InputTokensDetails inputTokensDetails` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A detailed breakdown of the input tokens. - - `JsonValue; mode "explicit"constant` + - `long cacheWriteTokens` - The breakpoint mode. Always `explicit`. + The number of input tokens that were written to the cache. - - `EXPLICIT("explicit")` + - `long cachedTokens` - - `Role role` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `long outputTokens` - - `USER("user")` + The number of output tokens. - - `ASSISTANT("assistant")` + - `OutputTokensDetails outputTokensDetails` - - `SYSTEM("system")` + A detailed breakdown of the output tokens. - - `DEVELOPER("developer")` + - `long reasoningTokens` - - `Optional phase` + The number of reasoning tokens. - 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. + - `long totalTokens` - - `COMMENTARY("commentary")` + The total number of tokens used. - - `Optional type` +### Example - The type of the message input. Always `message`. +```java +package com.openai.example; - - `MESSAGE("message")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.responses.BetaCompactedResponse; +import com.openai.models.beta.responses.ResponseCompactParams; - - `Message` +public final class Main { + private Main() {} - - `List content` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - A list of one or many input items to the model, containing different content - types. + ResponseCompactParams params = ResponseCompactParams.builder() + .model(ResponseCompactParams.Model.GPT_5_6_SOL) + .build(); + BetaCompactedResponse betaCompactedResponse = client.beta().responses().compact(params); + } +} +``` - - `class BetaResponseInputText:` +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "object": "response.compaction", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "text": "text", + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "phase": "commentary" + } + ], + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + } +} +``` - A text input to the model. +## Domain Types - - `class BetaResponseInputImage:` +### Beta Apply Patch Tool - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). +- `class BetaApplyPatchTool:` - - `class BetaResponseInputFile:` + Allows the assistant to create, delete, or update files using unified diffs. - A file input to the model. + - `JsonValue; type "apply_patch"constant` - - `Role role` + The type of the tool. Always `apply_patch`. - The role of the message input. One of `user`, `system`, or `developer`. + - `APPLY_PATCH("apply_patch")` - - `USER("user")` + - `Optional> allowedCallers` - - `SYSTEM("system")` + The tool invocation context(s). - - `DEVELOPER("developer")` + - `DIRECT("direct")` - - `Optional agent` + - `PROGRAMMATIC("programmatic")` - The agent that produced this item. +### Beta Compacted Response - - `String agentName` +- `class BetaCompactedResponse:` - The canonical name of the agent that produced this item. + - `String id` - - `Optional status` + The unique identifier for the compacted response. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `long createdAt` - - `IN_PROGRESS("in_progress")` + Unix timestamp (in seconds) when the compacted conversation was created. - - `COMPLETED("completed")` + - `JsonValue; object_ "response.compaction"constant` - - `INCOMPLETE("incomplete")` + The object type. Always `response.compaction`. - - `Optional type` + - `RESPONSE_COMPACTION("response.compaction")` - The type of the message input. Always set to `message`. + - `List output` - - `MESSAGE("message")` + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - `class BetaResponseOutputMessage:` @@ -13745,6 +31813,8 @@ Create a model response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -13821,36 +31891,66 @@ Create a model response The text that was retrieved from the file. - - `class BetaResponseComputerToolCall:` + - `class BetaResponseFunctionToolCall:` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `String id` + - `String arguments` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `String callId` - An identifier used when responding to the tool call with output. + The unique ID of the function tool call generated by the model. - - `List pendingSafetyChecks` + - `String name` - The pending safety checks for the computer call. + The name of the function to run. - - `String id` + - `JsonValue; type "function_call"constant` - The ID of the pending safety check. + The type of the function tool call. Always `function_call`. - - `Optional code` + - `FUNCTION_CALL("function_call")` - The type of the pending safety check. + - `Optional id` - - `Optional message` + The unique ID of the function tool call. - Details about the pending safety check. + - `Optional agent` - - `Status status` + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the function to run. + + - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -13861,236 +31961,271 @@ Create a model response - `INCOMPLETE("incomplete")` - - `Type type` + - `class BetaResponseFunctionToolCallOutputItem:` - The type of the computer call. Always `computer_call`. + - `String id` - - `COMPUTER_CALL("computer_call")` + The unique ID of the function call tool output. - - `Optional action` + - `String callId` - A click action. + The unique ID of the function tool call generated by the model. - - `Click` + - `Output output` - - `Button button` + The output from the function call generated by your code. + Can be a string or an list of output content. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `String` - - `LEFT("left")` + - `List` - - `RIGHT("right")` + - `class BetaResponseInputText:` - - `WHEEL("wheel")` + A text input to the model. - - `BACK("back")` + - `String text` - - `FORWARD("forward")` + The text input to the model. - - `JsonValue; type "click"constant` + - `JsonValue; type "input_text"constant` - Specifies the event type. For a click action, this property is always `click`. + The type of the input item. Always `input_text`. - - `CLICK("click")` + - `INPUT_TEXT("input_text")` - - `long x` + - `Optional promptCacheBreakpoint` - The x-coordinate where the click occurred. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `long y` + - `JsonValue; mode "explicit"constant` - The y-coordinate where the click occurred. + The breakpoint mode. Always `explicit`. - - `Optional> keys` + - `EXPLICIT("explicit")` - The keys being held while clicking. + - `class BetaResponseInputImage:` - - `DoubleClick` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional> keys` + - `Detail detail` - The keys being held while double-clicking. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `JsonValue; type "double_click"constant` + - `LOW("low")` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `HIGH("high")` - - `DOUBLE_CLICK("double_click")` + - `AUTO("auto")` - - `long x` + - `ORIGINAL("original")` - The x-coordinate where the double click occurred. + - `JsonValue; type "input_image"constant` - - `long y` + The type of the input item. Always `input_image`. - The y-coordinate where the double click occurred. + - `INPUT_IMAGE("input_image")` - - `Drag` + - `Optional fileId` - - `List path` + The ID of the file to be sent to the model. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `Optional imageUrl` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `long x` + - `Optional promptCacheBreakpoint` - The x-coordinate. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `long y` + - `JsonValue; mode "explicit"constant` - The y-coordinate. + The breakpoint mode. Always `explicit`. - - `JsonValue; type "drag"constant` + - `EXPLICIT("explicit")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `class BetaResponseInputFile:` - - `DRAG("drag")` + A file input to the model. - - `Optional> keys` + - `JsonValue; type "input_file"constant` - The keys being held while dragging the mouse. + The type of the input item. Always `input_file`. - - `Keypress` + - `INPUT_FILE("input_file")` - - `List keys` + - `Optional detail` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `JsonValue; type "keypress"constant` + - `AUTO("auto")` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `LOW("low")` - - `KEYPRESS("keypress")` + - `HIGH("high")` - - `Move` + - `Optional fileData` - - `JsonValue; type "move"constant` + The content of the file to be sent to the model. - Specifies the event type. For a move action, this property is always set to `move`. + - `Optional fileId` - - `MOVE("move")` + The ID of the file to be sent to the model. - - `long x` + - `Optional fileUrl` - The x-coordinate to move to. + The URL of the file to be sent to the model. - - `long y` + - `Optional filename` - The y-coordinate to move to. + The name of the file to be sent to the model. - - `Optional> keys` + - `Optional promptCacheBreakpoint` - The keys being held while moving the mouse. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `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")` + + - `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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. - `JsonValue;` - - `JsonValue; type "screenshot"constant` + - `JsonValue; type "direct"constant` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The caller type. Always `direct`. - - `SCREENSHOT("screenshot")` + - `DIRECT("direct")` - - `Scroll` + - `class Program:` - - `long scrollX` + - `String callerId` - The horizontal scroll distance. + The call ID of the program item that produced this tool call. - - `long scrollY` + - `JsonValue; type "program"constant` - The vertical scroll distance. + The caller type. Always `program`. - - `JsonValue; type "scroll"constant` + - `PROGRAM("program")` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `Optional createdBy` - - `SCROLL("scroll")` + The identifier of the actor that created the item. - - `long x` + - `AgentMessage` - The x-coordinate where the scroll occurred. + - `String id` - - `long y` + The unique ID of the agent message. - The y-coordinate where the scroll occurred. + - `String author` - - `Optional> keys` + The sending agent identity. - The keys being held while scrolling. + - `List content` - - `Type` + Encrypted content sent between agents. - - `String text` + - `class BetaResponseInputText:` - The text to type. + A text input to the model. - - `JsonValue; type "type"constant` + - `class BetaResponseOutputText:` - Specifies the event type. For a type action, this property is always set to `type`. + A text output from the model. - - `TYPE("type")` + - `class Text:` - - `JsonValue;` + A text content. - - `JsonValue; type "wait"constant` + - `String text` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `JsonValue; type "text"constant` - - `WAIT("wait")` + - `TEXT("text")` - - `Optional> actions` + - `class SummaryText:` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + A summary text from the model. - - `Click` + - `String text` - - `DoubleClick` + A summary of the reasoning output from the model so far. - - `Drag` + - `JsonValue; type "summary_text"constant` - - `Keypress` + The type of the object. Always `summary_text`. - - `Move` + - `SUMMARY_TEXT("summary_text")` - - `JsonValue;` + - `class ReasoningText:` - - `Scroll` + Reasoning text from the model. - - `Type` + - `String text` - - `JsonValue;` + The reasoning text from the model. - - `Optional agent` + - `JsonValue; type "reasoning_text"constant` - The agent that produced this item. + The type of the reasoning text. Always `reasoning_text`. - - `String agentName` + - `REASONING_TEXT("reasoning_text")` - The canonical name of the agent that produced this item. + - `class BetaResponseOutputRefusal:` - - `ComputerCallOutput` + A refusal from the model. - - `String callId` + - `class BetaResponseInputImage:` - The ID of the computer tool call that produced the output. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `BetaResponseComputerToolCallOutputScreenshot output` + - `class ComputerScreenshot:` - A computer screenshot image used with the computer use tool. + A screenshot of a computer. - - `JsonValue; type "computer_screenshot"constant` + - `Detail detail` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `LOW("low")` + + - `HIGH("high")` + + - `AUTO("auto")` + + - `ORIGINAL("original")` - `Optional fileId` @@ -14100,31 +32235,93 @@ Create a model response The URL of the screenshot image. - - `JsonValue; type "computer_call_output"constant` + - `JsonValue; type "computer_screenshot"constant` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `Optional id` + - `Optional promptCacheBreakpoint` - The ID of the computer tool call output. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional> acknowledgedSafetyChecks` + - `JsonValue; mode "explicit"constant` - The safety checks reported by the API that have been acknowledged by the developer. + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `class EncryptedContent:` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `String encryptedContent` + + Opaque encrypted content. + + - `JsonValue; type "encrypted_content"constant` + + The type of the input item. Always `encrypted_content`. + + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The type of the item. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall` - `String id` - The ID of the pending safety check. + The unique ID of the multi-agent call item. - - `Optional code` + - `Action action` - The type of the pending safety check. + The multi-agent action to execute. - - `Optional message` + - `SPAWN_AGENT("spawn_agent")` - Details about the pending safety check. + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String arguments` + + The JSON string of arguments generated for the action. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional agent` @@ -14134,15 +32331,63 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional status` + - `MultiAgentCallOutput` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `String id` - - `IN_PROGRESS("in_progress")` + The unique ID of the multi-agent call output item. - - `COMPLETED("completed")` + - `Action action` - - `INCOMPLETE("incomplete")` + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `List annotations` + + The annotations of the text output. + + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `Optional> logprobs` + + - `JsonValue; type "multi_agent_call_output"constant` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. - `class BetaResponseFunctionWebSearch:` @@ -14248,297 +32493,324 @@ Create a model response The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall:` + - `class BetaResponseComputerToolCall:` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `String arguments` + - `String id` - A JSON string of the arguments to pass to the function. + The unique ID of the computer call. - `String callId` - The unique ID of the function tool call generated by the model. + An identifier used when responding to the tool call with output. - - `String name` + - `List pendingSafetyChecks` - The name of the function to run. + The pending safety checks for the computer call. - - `JsonValue; type "function_call"constant` + - `String id` - The type of the function tool call. Always `function_call`. + The ID of the pending safety check. - - `FUNCTION_CALL("function_call")` + - `Optional code` - - `Optional id` + The type of the pending safety check. - The unique ID of the function tool call. + - `Optional message` - - `Optional agent` + Details about the pending safety check. - The agent that produced this item. + - `Status status` - - `String agentName` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The canonical name of the agent that produced this item. + - `IN_PROGRESS("in_progress")` - - `Optional caller` + - `COMPLETED("completed")` - The execution context that produced this tool call. + - `INCOMPLETE("incomplete")` - - `JsonValue;` + - `Type type` - - `JsonValue; type "direct"constant` + The type of the computer call. Always `computer_call`. - - `DIRECT("direct")` + - `COMPUTER_CALL("computer_call")` - - `class Program:` + - `Optional action` - - `String callerId` + A click action. - The call ID of the program item that produced this tool call. + - `Click` - - `JsonValue; type "program"constant` + - `Button button` - - `PROGRAM("program")` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Optional namespace` + - `LEFT("left")` - The namespace of the function to run. + - `RIGHT("right")` - - `Optional status` + - `WHEEL("wheel")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `BACK("back")` - - `IN_PROGRESS("in_progress")` + - `FORWARD("forward")` - - `COMPLETED("completed")` + - `JsonValue; type "click"constant` - - `INCOMPLETE("incomplete")` + Specifies the event type. For a click action, this property is always `click`. - - `FunctionCallOutput` + - `CLICK("click")` - - `String callId` + - `long x` - The unique ID of the function tool call generated by the model. + The x-coordinate where the click occurred. - - `Output output` + - `long y` - Text, image, or file output of the function tool call. + The y-coordinate where the click occurred. - - `String` + - `Optional> keys` - - `List` + The keys being held while clicking. - - `class BetaResponseInputTextContent:` + - `DoubleClick` - A text input to the model. + - `Optional> keys` - - `String text` + The keys being held while double-clicking. - The text input to the model. + - `JsonValue; type "double_click"constant` - - `JsonValue; type "input_text"constant` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The type of the input item. Always `input_text`. + - `DOUBLE_CLICK("double_click")` - - `INPUT_TEXT("input_text")` + - `long x` - - `Optional promptCacheBreakpoint` + The x-coordinate where the double click occurred. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `long y` - - `JsonValue; mode "explicit"constant` + The y-coordinate where the double click occurred. - The breakpoint mode. Always `explicit`. + - `Drag` - - `EXPLICIT("explicit")` + - `List path` - - `class BetaResponseInputImageContent:` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `JsonValue; type "input_image"constant` + - `long x` - The type of the input item. Always `input_image`. + The x-coordinate. - - `INPUT_IMAGE("input_image")` + - `long y` - - `Optional detail` + The y-coordinate. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `JsonValue; type "drag"constant` - - `LOW("low")` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `HIGH("high")` + - `DRAG("drag")` - - `AUTO("auto")` + - `Optional> keys` - - `ORIGINAL("original")` + The keys being held while dragging the mouse. - - `Optional fileId` + - `Keypress` - The ID of the file to be sent to the model. + - `List keys` - - `Optional imageUrl` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `JsonValue; type "keypress"constant` - - `Optional promptCacheBreakpoint` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `KEYPRESS("keypress")` - - `JsonValue; mode "explicit"constant` + - `Move` - The breakpoint mode. Always `explicit`. + - `JsonValue; type "move"constant` - - `EXPLICIT("explicit")` + Specifies the event type. For a move action, this property is always set to `move`. - - `class BetaResponseInputFileContent:` + - `MOVE("move")` - A file input to the model. + - `long x` - - `JsonValue; type "input_file"constant` + The x-coordinate to move to. - The type of the input item. Always `input_file`. + - `long y` - - `INPUT_FILE("input_file")` + The y-coordinate to move to. - - `Optional detail` + - `Optional> keys` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The keys being held while moving the mouse. - - `AUTO("auto")` + - `JsonValue;` - - `LOW("low")` + - `JsonValue; type "screenshot"constant` - - `HIGH("high")` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `Optional fileData` + - `SCREENSHOT("screenshot")` - The base64-encoded data of the file to be sent to the model. + - `Scroll` - - `Optional fileId` + - `long scrollX` - The ID of the file to be sent to the model. + The horizontal scroll distance. - - `Optional fileUrl` + - `long scrollY` - The URL of the file to be sent to the model. + The vertical scroll distance. - - `Optional filename` + - `JsonValue; type "scroll"constant` - The name of the file to be sent to the model. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `Optional promptCacheBreakpoint` + - `SCROLL("scroll")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `long x` - - `JsonValue; mode "explicit"constant` + The x-coordinate where the scroll occurred. - The breakpoint mode. Always `explicit`. + - `long y` - - `EXPLICIT("explicit")` + The y-coordinate where the scroll occurred. - - `JsonValue; type "function_call_output"constant` + - `Optional> keys` - The type of the function tool call output. Always `function_call_output`. + The keys being held while scrolling. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `Type` - - `Optional id` + - `String text` - The unique ID of the function tool call output. Populated when this item is returned via API. + The text to type. - - `Optional agent` + - `JsonValue; type "type"constant` - The agent that produced this item. + Specifies the event type. For a type action, this property is always set to `type`. - - `String agentName` + - `TYPE("type")` - The canonical name of the agent that produced this item. + - `JsonValue;` - - `Optional caller` + - `JsonValue; type "wait"constant` - The execution context that produced this tool call. + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `WAIT("wait")` + + - `Optional> actions` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click` + + - `DoubleClick` + + - `Drag` + + - `Keypress` + + - `Move` - `JsonValue;` - - `JsonValue; type "direct"constant` + - `Scroll` - The caller type. Always `direct`. + - `Type` - - `DIRECT("direct")` + - `JsonValue;` - - `class Program:` + - `Optional agent` - - `String callerId` + The agent that produced this item. - The call ID of the program item that produced this tool call. + - `String agentName` - - `JsonValue; type "program"constant` + The canonical name of the agent that produced this item. - The caller type. Always `program`. + - `class BetaResponseComputerToolCallOutputItem:` - - `PROGRAM("program")` + - `String id` - - `Optional status` + The unique ID of the computer call tool output. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `String callId` - - `IN_PROGRESS("in_progress")` + The ID of the computer tool call that produced the output. - - `COMPLETED("completed")` + - `BetaResponseComputerToolCallOutputScreenshot output` - - `INCOMPLETE("incomplete")` + A computer screenshot image used with the computer use tool. - - `AgentMessage` + - `JsonValue; type "computer_screenshot"constant` - - `String author` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The sending agent identity. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `List content` + - `Optional fileId` - Plaintext, image, or encrypted content sent between agents. + The identifier of an uploaded file that contains the screenshot. - - `class BetaResponseInputTextContent:` + - `Optional imageUrl` - A text input to the model. + The URL of the screenshot image. - - `class BetaResponseInputImageContent:` + - `Status status` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class EncryptedContent:` + - `COMPLETED("completed")` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `INCOMPLETE("incomplete")` - - `String encryptedContent` + - `FAILED("failed")` - Opaque encrypted content. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "encrypted_content"constant` + - `JsonValue; type "computer_call_output"constant` - The type of the input item. Always `encrypted_content`. + The type of the computer tool call output. Always `computer_call_output`. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `String recipient` + - `Optional> acknowledgedSafetyChecks` - The destination agent identity. + The safety checks reported by the API that have been acknowledged by the + developer. - - `JsonValue; type "agent_message"constant` + - `String id` - The item type. Always `agent_message`. + The ID of the pending safety check. - - `AGENT_MESSAGE("agent_message")` + - `Optional code` - - `Optional id` + The type of the pending safety check. - The unique ID of this agent message item. + - `Optional message` + + Details about the pending safety check. - `Optional agent` @@ -14548,41 +32820,40 @@ Create a model response The canonical name of the agent that produced this item. - - `MultiAgentCall` - - - `Action action` - - The multi-agent action that was executed. + - `Optional createdBy` - - `SPAWN_AGENT("spawn_agent")` + The identifier of the actor that created the item. - - `INTERRUPT_AGENT("interrupt_agent")` + - `class BetaResponseReasoningItem:` - - `LIST_AGENTS("list_agents")` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `SEND_MESSAGE("send_message")` + - `String id` - - `FOLLOWUP_TASK("followup_task")` + The unique identifier of the reasoning content. - - `WAIT_AGENT("wait_agent")` + - `List summary` - - `String arguments` + Reasoning summary content. - The action arguments as a JSON string. + - `String text` - - `String callId` + A summary of the reasoning output from the model so far. - The unique ID linking this call to its output. + - `JsonValue; type "summary_text"constant` - - `JsonValue; type "multi_agent_call"constant` + The type of the object. Always `summary_text`. - The item type. Always `multi_agent_call`. + - `SUMMARY_TEXT("summary_text")` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `JsonValue; type "reasoning"constant` - - `Optional id` + The type of the object. Always `reasoning`. - The unique ID of this multi-agent call. + - `REASONING("reasoning")` - `Optional agent` @@ -14592,152 +32863,142 @@ Create a model response The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `Action action` - - The multi-agent action that produced this result. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` + - `Optional> content` - - `LIST_AGENTS("list_agents")` + Reasoning text content. - - `SEND_MESSAGE("send_message")` + - `String text` - - `FOLLOWUP_TASK("followup_task")` + The reasoning text from the model. - - `WAIT_AGENT("wait_agent")` + - `JsonValue; type "reasoning_text"constant` - - `String callId` + The type of the reasoning text. Always `reasoning_text`. - The unique ID of the multi-agent call. + - `REASONING_TEXT("reasoning_text")` - - `List output` + - `Optional encryptedContent` - Text output returned by the multi-agent action. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `String text` + - `Optional status` - The text content. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue; type "output_text"constant` + - `IN_PROGRESS("in_progress")` - The content type. Always `output_text`. + - `COMPLETED("completed")` - - `OUTPUT_TEXT("output_text")` + - `INCOMPLETE("incomplete")` - - `Optional annotations` + - `Program` - Citations associated with the text content. + - `String id` - - `List` + The unique ID of the program item. - - `String fileId` + - `String callId` - The ID of the file. + The stable call ID of the program item. - - `String filename` + - `String code` - The filename of the file cited. + The JavaScript source executed by programmatic tool calling. - - `long index` + - `String fingerprint` - The index of the file in the list of files. + Opaque program replay fingerprint that must be round-tripped. - - `JsonValue; type "file_citation"constant` + - `JsonValue; type "program"constant` - The citation type. Always `file_citation`. + The type of the item. Always `program`. - - `FILE_CITATION("file_citation")` + - `PROGRAM("program")` - - `List` + - `Optional agent` - - `long endIndex` + The agent that produced this item. - The index of the last character of the citation in the message. + - `String agentName` - - `long startIndex` + The canonical name of the agent that produced this item. - The index of the first character of the citation in the message. + - `ProgramOutput` - - `String title` + - `String id` - The title of the cited resource. + The unique ID of the program output item. - - `JsonValue; type "url_citation"constant` + - `String callId` - The citation type. Always `url_citation`. + The call ID of the program item. - - `URL_CITATION("url_citation")` + - `String result` - - `String url` + The result produced by the program item. - The URL of the cited resource. + - `Status status` - - `List` + The terminal status of the program output item. - - `String containerId` + - `COMPLETED("completed")` - The ID of the container. + - `INCOMPLETE("incomplete")` - - `long endIndex` + - `JsonValue; type "program_output"constant` - The index of the last character of the citation in the message. + The type of the item. Always `program_output`. - - `String fileId` + - `PROGRAM_OUTPUT("program_output")` - The ID of the container file. + - `Optional agent` - - `String filename` + The agent that produced this item. - The filename of the container file cited. + - `String agentName` - - `long startIndex` + The canonical name of the agent that produced this item. - The index of the first character of the citation in the message. + - `class BetaResponseToolSearchCall:` - - `JsonValue; type "container_file_citation"constant` + - `String id` - The citation type. Always `container_file_citation`. + The unique ID of the tool search call item. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `JsonValue arguments` - - `JsonValue; type "multi_agent_call_output"constant` + Arguments used for the tool search call. - The item type. Always `multi_agent_call_output`. + - `Optional callId` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + The unique ID of the tool search call generated by the model. - - `Optional id` + - `Execution execution` - The unique ID of this multi-agent call output. + Whether tool search was executed by the server or by the client. - - `Optional agent` + - `SERVER("server")` - The agent that produced this item. + - `CLIENT("client")` - - `String agentName` + - `Status status` - The canonical name of the agent that produced this item. + The status of the tool search call item that was recorded. - - `ToolSearchCall` + - `IN_PROGRESS("in_progress")` - - `JsonValue arguments` + - `COMPLETED("completed")` - The arguments supplied to the tool search call. + - `INCOMPLETE("incomplete")` - `JsonValue; type "tool_search_call"constant` - The item type. Always `tool_search_call`. + The type of the item. Always `tool_search_call`. - `TOOL_SEARCH_CALL("tool_search_call")` - - `Optional id` - - The unique ID of this tool search call. - - `Optional agent` The agent that produced this item. @@ -14746,11 +33007,21 @@ Create a model response The canonical name of the agent that produced this item. + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem:` + + - `String id` + + The unique ID of the tool search output item. + - `Optional callId` The unique ID of the tool search call generated by the model. - - `Optional execution` + - `Execution execution` Whether tool search was executed by the server or by the client. @@ -14758,9 +33029,9 @@ Create a model response - `CLIENT("client")` - - `Optional status` + - `Status status` - The status of the tool search call. + The status of the tool search output item that was recorded. - `IN_PROGRESS("in_progress")` @@ -14768,11 +33039,9 @@ Create a model response - `INCOMPLETE("incomplete")` - - `class BetaResponseToolSearchOutputItemParam:` - - `List tools` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool:` @@ -14881,7 +33150,11 @@ Create a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -14938,7 +33211,11 @@ Create a model response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -15434,1397 +33711,410 @@ Create a model response - `Optional partialImages` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - - `Optional 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 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`. - - - `_1024X1024("1024x1024")` - - - `_1024X1536("1024x1536")` - - - `_1536X1024("1536x1024")` - - - `AUTO("auto")` - - - `JsonValue;` - - - `JsonValue; type "local_shell"constant` - - The type of the local shell tool. Always `local_shell`. - - - `LOCAL_SHELL("local_shell")` - - - `class BetaFunctionShellTool:` - - 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> allowedCallers` - - The tool invocation context(s). - - - `DIRECT("direct")` - - - `PROGRAMMATIC("programmatic")` - - - `Optional environment` - - - `class BetaContainerAuto:` - - - `JsonValue; type "container_auto"constant` - - Automatically creates a container for this request - - - `CONTAINER_AUTO("container_auto")` - - - `Optional> fileIds` - - An optional list of uploaded files to make available to your code. - - - `Optional memoryLimit` - - The memory limit for the container. - - - `_1G("1g")` - - - `_4G("4g")` - - - `_16G("16g")` - - - `_64G("64g")` - - - `Optional networkPolicy` - - Network access policy for the container. - - - `class BetaContainerNetworkPolicyDisabled:` - - - `class BetaContainerNetworkPolicyAllowlist:` - - - `Optional> skills` - - An optional list of skills referenced by id or inline data. - - - `class BetaSkillReference:` - - - `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 version` - - Optional skill version. Use a positive integer or 'latest'. Omit for default. - - - `class BetaInlineSkill:` - - - `String description` - - The description of the skill. - - - `String name` - - The name of the skill. - - - `BetaInlineSkillSource 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 BetaLocalEnvironment:` - - - `JsonValue; type "local"constant` - - Use a local computer environment. - - - `LOCAL("local")` - - - `Optional> 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 BetaContainerReference:` - - - `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 BetaCustomTool:` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `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> allowedCallers` - - The tool invocation context(s). - - - `DIRECT("direct")` - - - `PROGRAMMATIC("programmatic")` - - - `Optional deferLoading` - - Whether this tool should be deferred and discovered via tool search. - - - `Optional description` - - Optional description of the custom tool, used to provide more context. - - - `Optional format` - - The input format for the custom tool. Default is unconstrained text. - - - `JsonValue;` - - - `JsonValue; type "text"constant` - - Unconstrained text format. Always `text`. - - - `TEXT("text")` - - - `class Grammar:` - - A grammar defined by the user. - - - `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 BetaNamespaceTool:` - - 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 tools` - - The function/custom tools available inside this namespace. - - - `class Function:` - - - `String name` - - - `JsonValue; type "function"constant` - - - `FUNCTION("function")` - - - `Optional> allowedCallers` - - The tool invocation context(s). - - - `DIRECT("direct")` - - - `PROGRAMMATIC("programmatic")` - - - `Optional deferLoading` - - Whether this function should be deferred and discovered via tool search. - - - `Optional description` - - - `Optional outputSchema` - - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - - `Optional parameters` - - - `Optional strict` - - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - - `class BetaCustomTool:` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `JsonValue; type "namespace"constant` - - The type of the tool. Always `namespace`. - - - `NAMESPACE("namespace")` - - - `class BetaToolSearchTool:` - - 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 description` - - Description shown to the model for a client-executed tool search tool. - - - `Optional execution` - - Whether tool search is executed by the server or by the client. - - - `SERVER("server")` - - - `CLIENT("client")` - - - `Optional parameters` - - Parameter schema for a client-executed tool search tool. - - - `class BetaWebSearchPreviewTool:` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `Type 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> searchContentTypes` - - - `TEXT("text")` - - - `IMAGE("image")` - - - `Optional 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` - - The user's location. - - - `JsonValue; type "approximate"constant` - - The type of location approximation. Always `approximate`. - - - `APPROXIMATE("approximate")` - - - `Optional city` - - Free text input for the city of the user, e.g. `San Francisco`. - - - `Optional country` - - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - - `Optional region` - - Free text input for the region of the user, e.g. `California`. - - - `Optional timezone` - - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - - `class BetaApplyPatchTool:` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `JsonValue; type "apply_patch"constant` - - The type of the tool. Always `apply_patch`. - - - `APPLY_PATCH("apply_patch")` - - - `Optional> allowedCallers` - - The tool invocation context(s). - - - `DIRECT("direct")` - - - `PROGRAMMATIC("programmatic")` - - - `JsonValue; type "tool_search_output"constant` - - The item type. Always `tool_search_output`. - - - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - - `Optional id` - - The unique ID of this tool search output. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional callId` - - The unique ID of the tool search call generated by the model. - - - `Optional execution` - - Whether tool search was executed by the server or by the client. - - - `SERVER("server")` - - - `CLIENT("client")` - - - `Optional status` - - The status of the tool search output. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `AdditionalTools` - - - `JsonValue; role "developer"constant` - - The role that provided the additional tools. Only `developer` is supported. - - - `DEVELOPER("developer")` - - - `List tools` - - A list of additional tools made available at this item. - - - `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `class BetaFileSearchTool:` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class BetaComputerTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool:` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `Mcp` - - - `CodeInterpreter` - - - `JsonValue;` - - - `ImageGeneration` - - - `JsonValue;` - - - `class BetaFunctionShellTool:` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool:` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class BetaNamespaceTool:` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool:` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class BetaWebSearchPreviewTool:` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class BetaApplyPatchTool:` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `JsonValue; type "additional_tools"constant` - - The item type. Always `additional_tools`. - - - `ADDITIONAL_TOOLS("additional_tools")` - - - `Optional id` - - The unique ID of this additional tools item. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `class BetaResponseReasoningItem:` - - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). - - - `String id` - - The unique identifier of the reasoning content. - - - `List 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional> 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 encryptedContent` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `Optional 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 BetaResponseCompactionItemParam:` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `String encryptedContent` - - The encrypted content of the compaction summary. - - - `JsonValue; type "compaction"constant` - - The type of the item. Always `compaction`. - - - `COMPACTION("compaction")` - - - `Optional id` - - The ID of the compaction item. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ImageGenerationCall` - - - `String id` - - The unique ID of the image generation call. - - - `Optional 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. - - - `String id` - - The unique ID of the code interpreter tool call. - - - `Optional code` - - The code to run, or null if not available. - - - `String containerId` - - The ID of the container used to run the code. - - - `Optional> 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `LocalShellCall` - - - `String id` - - The unique ID of the local shell call. - - - `Action action` - - Execute a shell command on the server. - - - `List 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 timeoutMs` - - Optional timeout in milliseconds for the command. - - - `Optional user` - - Optional user to run the command as. - - - `Optional 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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 commands` - - Ordered shell commands for the execution environment to run. - - - `Optional maxOutputLength` - - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - - `Optional 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 id` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - The caller type. Always `program`. - - - `PROGRAM("program")` - - - `Optional environment` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment:` - - - `class BetaContainerReference:` - - - `Optional 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 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 id` - - The unique ID of the shell tool call output. Populated when this item is returned via API. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `JsonValue; type "program"constant` + - `Optional quality` - The caller type. Always `program`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `PROGRAM("program")` + - `LOW("low")` - - `Optional maxOutputLength` + - `MEDIUM("medium")` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `HIGH("high")` - - `Optional status` + - `AUTO("auto")` - The status of the shell call output. + - `Optional size` - - `IN_PROGRESS("in_progress")` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `COMPLETED("completed")` + - `_1024X1024("1024x1024")` - - `INCOMPLETE("incomplete")` + - `_1024X1536("1024x1536")` - - `ApplyPatchCall` + - `_1536X1024("1536x1024")` - - `String callId` + - `AUTO("auto")` - The unique ID of the apply patch tool call generated by the model. + - `JsonValue;` - - `Operation operation` + - `JsonValue; type "local_shell"constant` - The specific create, delete, or update instruction for the apply_patch tool call. + The type of the local shell tool. Always `local_shell`. - - `class CreateFile:` + - `LOCAL_SHELL("local_shell")` - Instruction for creating a new file via the apply_patch tool. + - `class BetaFunctionShellTool:` - - `String diff` + A tool that allows the model to execute shell commands. - Unified diff content to apply when creating the file. + - `JsonValue; type "shell"constant` - - `String path` + The type of the shell tool. Always `shell`. - Path of the file to create relative to the workspace root. + - `SHELL("shell")` - - `JsonValue; type "create_file"constant` + - `Optional> allowedCallers` - The operation type. Always `create_file`. + The tool invocation context(s). - - `CREATE_FILE("create_file")` + - `DIRECT("direct")` - - `class DeleteFile:` + - `PROGRAMMATIC("programmatic")` - Instruction for deleting an existing file via the apply_patch tool. + - `Optional environment` - - `String path` + - `class BetaContainerAuto:` - Path of the file to delete relative to the workspace root. + - `JsonValue; type "container_auto"constant` - - `JsonValue; type "delete_file"constant` + Automatically creates a container for this request - The operation type. Always `delete_file`. + - `CONTAINER_AUTO("container_auto")` - - `DELETE_FILE("delete_file")` + - `Optional> fileIds` - - `class UpdateFile:` + An optional list of uploaded files to make available to your code. - Instruction for updating an existing file via the apply_patch tool. + - `Optional memoryLimit` - - `String diff` + The memory limit for the container. - Unified diff content to apply to the existing file. + - `_1G("1g")` - - `String path` + - `_4G("4g")` - Path of the file to update relative to the workspace root. + - `_16G("16g")` - - `JsonValue; type "update_file"constant` + - `_64G("64g")` - The operation type. Always `update_file`. + - `Optional networkPolicy` - - `UPDATE_FILE("update_file")` + Network access policy for the container. - - `Status status` + - `class BetaContainerNetworkPolicyDisabled:` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `class BetaContainerNetworkPolicyAllowlist:` - - `IN_PROGRESS("in_progress")` + - `Optional> skills` - - `COMPLETED("completed")` + An optional list of skills referenced by id or inline data. - - `JsonValue; type "apply_patch_call"constant` + - `class BetaSkillReference:` - The type of the item. Always `apply_patch_call`. + - `String skillId` - - `APPLY_PATCH_CALL("apply_patch_call")` + The ID of the referenced skill. - - `Optional id` + - `JsonValue; type "skill_reference"constant` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + References a skill created with the /v1/skills endpoint. - - `Optional agent` + - `SKILL_REFERENCE("skill_reference")` - The agent that produced this item. + - `Optional version` - - `String agentName` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The canonical name of the agent that produced this item. + - `class BetaInlineSkill:` - - `Optional caller` + - `String description` - The execution context that produced this tool call. + The description of the skill. - - `JsonValue;` + - `String name` - - `JsonValue; type "direct"constant` + The name of the skill. - The caller type. Always `direct`. + - `BetaInlineSkillSource source` - - `DIRECT("direct")` + Inline skill payload - - `class Program:` + - `String data` - - `String callerId` + Base64-encoded skill zip bundle. - The call ID of the program item that produced this tool call. + - `JsonValue; mediaType "application/zip"constant` - - `JsonValue; type "program"constant` + The media type of the inline skill payload. Must be `application/zip`. - The caller type. Always `program`. + - `APPLICATION_ZIP("application/zip")` - - `PROGRAM("program")` + - `JsonValue; type "base64"constant` - - `ApplyPatchCallOutput` + The type of the inline skill source. Must be `base64`. - - `String callId` + - `BASE64("base64")` - The unique ID of the apply patch tool call generated by the model. + - `JsonValue; type "inline"constant` - - `Status status` + Defines an inline skill for this request. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `INLINE("inline")` - - `COMPLETED("completed")` + - `class BetaLocalEnvironment:` - - `FAILED("failed")` + - `JsonValue; type "local"constant` - - `JsonValue; type "apply_patch_call_output"constant` + Use a local computer environment. - The type of the item. Always `apply_patch_call_output`. + - `LOCAL("local")` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `Optional> skills` - - `Optional id` + An optional list of skills. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `String description` - - `Optional agent` + The description of the skill. - The agent that produced this item. + - `String name` - - `String agentName` + The name of the skill. - The canonical name of the agent that produced this item. + - `String path` - - `Optional caller` + The path to the directory containing the skill. - The execution context that produced this tool call. + - `class BetaContainerReference:` - - `JsonValue;` + - `String containerId` - - `JsonValue; type "direct"constant` + The ID of the referenced container. - The caller type. Always `direct`. + - `JsonValue; type "container_reference"constant` - - `DIRECT("direct")` + References a container created with the /v1/containers endpoint - - `class Program:` + - `CONTAINER_REFERENCE("container_reference")` - - `String callerId` + - `class BetaCustomTool:` - The call ID of the program item that produced this tool call. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `JsonValue; type "program"constant` + - `String name` - The caller type. Always `program`. + The name of the custom tool, used to identify it in tool calls. - - `PROGRAM("program")` + - `JsonValue; type "custom"constant` - - `Optional output` + The type of the custom tool. Always `custom`. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `CUSTOM("custom")` - - `McpListTools` + - `Optional> allowedCallers` - - `String id` + The tool invocation context(s). - The unique ID of the list. + - `DIRECT("direct")` - - `String serverLabel` + - `PROGRAMMATIC("programmatic")` - The label of the MCP server. + - `Optional deferLoading` - - `List tools` + Whether this tool should be deferred and discovered via tool search. - The tools available on the server. + - `Optional description` - - `JsonValue inputSchema` + Optional description of the custom tool, used to provide more context. - The JSON schema describing the tool's input. + - `Optional format` - - `String name` + The input format for the custom tool. Default is unconstrained text. - The name of the tool. + - `JsonValue;` - - `Optional annotations` + - `JsonValue; type "text"constant` - Additional annotations about the tool. + Unconstrained text format. Always `text`. - - `Optional description` + - `TEXT("text")` - The description of the tool. + - `class Grammar:` - - `JsonValue; type "mcp_list_tools"constant` + A grammar defined by the user. - The type of the item. Always `mcp_list_tools`. + - `String definition` - - `MCP_LIST_TOOLS("mcp_list_tools")` + The grammar definition. - - `Optional agent` + - `Syntax syntax` - The agent that produced this item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `String agentName` + - `LARK("lark")` - The canonical name of the agent that produced this item. + - `REGEX("regex")` - - `Optional error` + - `JsonValue; type "grammar"constant` - Error message if the server could not list tools. + Grammar format. Always `grammar`. - - `McpApprovalRequest` + - `GRAMMAR("grammar")` - - `String id` + - `class BetaNamespaceTool:` - The unique ID of the approval request. + Groups function/custom tools under a shared namespace. - - `String arguments` + - `String description` - A JSON string of arguments for the tool. + A description of the namespace shown to the model. - `String name` - The name of the tool to run. + The namespace name used in tool calls (for example, `crm`). - - `String serverLabel` + - `List tools` - The label of the MCP server making the request. + The function/custom tools available inside this namespace. - - `JsonValue; type "mcp_approval_request"constant` + - `class Function:` - The type of the item. Always `mcp_approval_request`. + - `String name` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `JsonValue; type "function"constant` - - `Optional agent` + - `FUNCTION("function")` - The agent that produced this item. + - `Optional> allowedCallers` - - `String agentName` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `DIRECT("direct")` - - `McpApprovalResponse` + - `PROGRAMMATIC("programmatic")` - - `String approvalRequestId` + - `Optional deferLoading` - The ID of the approval request being answered. + Whether this function should be deferred and discovered via tool search. - - `boolean approve` + - `Optional description` - Whether the request was approved. + - `Optional outputSchema` - - `JsonValue; type "mcp_approval_response"constant` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The type of the item. Always `mcp_approval_response`. + - `Optional parameters` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `Optional strict` - - `Optional id` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The unique ID of the approval response + - `class BetaCustomTool:` - - `Optional agent` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The agent that produced this item. + - `JsonValue; type "namespace"constant` - - `String agentName` + The type of the tool. Always `namespace`. - The canonical name of the agent that produced this item. + - `NAMESPACE("namespace")` - - `Optional reason` + - `class BetaToolSearchTool:` - Optional reason for the decision. + Hosted or BYOT tool search configuration for deferred tools. - - `McpCall` + - `JsonValue; type "tool_search"constant` - - `String id` + The type of the tool. Always `tool_search`. - The unique ID of the tool call. + - `TOOL_SEARCH("tool_search")` - - `String arguments` + - `Optional description` - A JSON string of the arguments passed to the tool. + Description shown to the model for a client-executed tool search tool. - - `String name` + - `Optional execution` - The name of the tool that was run. + Whether tool search is executed by the server or by the client. - - `String serverLabel` + - `SERVER("server")` - The label of the MCP server running the tool. + - `CLIENT("client")` - - `JsonValue; type "mcp_call"constant` + - `Optional parameters` - The type of the item. Always `mcp_call`. + Parameter schema for a client-executed tool search tool. - - `MCP_CALL("mcp_call")` + - `class BetaWebSearchPreviewTool:` - - `Optional agent` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The agent that produced this item. + - `Type type` - - `String agentName` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The canonical name of the agent that produced this item. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `Optional approvalRequestId` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - 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> searchContentTypes` - - `Optional error` + - `TEXT("text")` - The error from the tool call, if any. + - `IMAGE("image")` - - `Optional output` + - `Optional searchContextSize` - The output from the tool call. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Optional status` + - `LOW("low")` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `MEDIUM("medium")` - - `IN_PROGRESS("in_progress")` + - `HIGH("high")` - - `COMPLETED("completed")` + - `Optional userLocation` - - `INCOMPLETE("incomplete")` + The user's location. - - `CALLING("calling")` + - `JsonValue; type "approximate"constant` - - `FAILED("failed")` + The type of location approximation. Always `approximate`. - - `class BetaResponseCustomToolCallOutput:` + - `APPROXIMATE("approximate")` - The output of a custom tool call from your code, being sent back to the model. + - `Optional city` - - `String callId` + Free text input for the city of the user, e.g. `San Francisco`. - The call ID, used to map this custom tool call output to a custom tool call. + - `Optional country` - - `Output output` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `Optional region` - - `String` + Free text input for the region of the user, e.g. `California`. - - `List` + - `Optional timezone` - - `class BetaResponseInputText:` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A text input to the model. + - `class BetaApplyPatchTool:` - - `class BetaResponseInputImage:` + Allows the assistant to create, delete, or update files using unified diffs. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `JsonValue; type "apply_patch"constant` - - `class BetaResponseInputFile:` + The type of the tool. Always `apply_patch`. - A file input to the model. + - `APPLY_PATCH("apply_patch")` - - `JsonValue; type "custom_tool_call_output"constant` + - `Optional> allowedCallers` - The type of the custom tool call output. Always `custom_tool_call_output`. + The tool invocation context(s). - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `DIRECT("direct")` - - `Optional id` + - `PROGRAMMATIC("programmatic")` - The unique ID of the custom tool call output in the OpenAI platform. + - `JsonValue; type "tool_search_output"constant` + + The type of the item. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - `Optional agent` @@ -16834,95 +34124,100 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional caller` + - `Optional createdBy` - The execution context that produced this tool call. + The identifier of the actor that created the item. - - `JsonValue;` + - `AdditionalTools` - - `JsonValue; type "direct"constant` + - `String id` - The caller type. Always `direct`. + The unique ID of the additional tools item. - - `DIRECT("direct")` + - `Role role` - - `class Program:` + The role that provided the additional tools. - - `String callerId` + - `UNKNOWN("unknown")` - The call ID of the program item that produced this tool call. + - `USER("user")` - - `JsonValue; type "program"constant` + - `ASSISTANT("assistant")` - The caller type. Always `program`. + - `SYSTEM("system")` - - `PROGRAM("program")` + - `CRITIC("critic")` - - `class BetaResponseCustomToolCall:` + - `DISCRIMINATOR("discriminator")` - A call to a custom tool created by the model. + - `DEVELOPER("developer")` - - `String callId` + - `TOOL("tool")` - An identifier used to map this custom tool call to a tool call output. + - `List tools` - - `String input` + The additional tool definitions made available at this item. - The input for the custom tool call generated by the model. + - `class BetaFunctionTool:` - - `String name` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The name of the custom tool being called. + - `class BetaFileSearchTool:` - - `JsonValue; type "custom_tool_call"constant` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of the custom tool call. Always `custom_tool_call`. + - `class BetaComputerTool:` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional id` + - `class BetaComputerUsePreviewTool:` - The unique ID of the custom tool call in the OpenAI platform. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional agent` + - `class BetaWebSearchTool:` - The agent that produced this item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String agentName` + - `Mcp` - The canonical name of the agent that produced this item. + - `CodeInterpreter` - - `Optional caller` + - `JsonValue;` - The execution context that produced this tool call. + - `ImageGeneration` - `JsonValue;` - - `JsonValue; type "direct"constant` + - `class BetaFunctionShellTool:` - - `DIRECT("direct")` + A tool that allows the model to execute shell commands. - - `class Program:` + - `class BetaCustomTool:` - - `String callerId` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The call ID of the program item that produced this tool call. + - `class BetaNamespaceTool:` - - `JsonValue; type "program"constant` + Groups function/custom tools under a shared namespace. - - `PROGRAM("program")` + - `class BetaToolSearchTool:` - - `Optional namespace` + Hosted or BYOT tool search configuration for deferred tools. - The namespace of the custom tool being called. + - `class BetaWebSearchPreviewTool:` - - `CompactionTrigger` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue; type "compaction_trigger"constant` + - `class BetaApplyPatchTool:` - The type of the item. Always `compaction_trigger`. + Allows the assistant to create, delete, or update files using unified diffs. - - `COMPACTION_TRIGGER("compaction_trigger")` + - `JsonValue; type "additional_tools"constant` + + The type of the item. Always `additional_tools`. + + - `ADDITIONAL_TOOLS("additional_tools")` - `Optional agent` @@ -16932,11 +34227,23 @@ Create a model response The canonical name of the agent that produced this item. - - `ItemReference` + - `class BetaResponseCompactionItem:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `String id` - The ID of the item to reference. + The unique ID of the compaction item. + + - `String encryptedContent` + + The encrypted content that was produced by compaction. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` - `Optional agent` @@ -16946,35 +34253,37 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional type` - - The type of item to reference. Always `item_reference`. + - `Optional createdBy` - - `ITEM_REFERENCE("item_reference")` + The identifier of the actor that created the item. - - `Program` + - `ImageGenerationCall` - `String id` - The unique ID of this program item. + The unique ID of the image generation call. - - `String callId` + - `Optional result` - The stable call ID of the program item. + The generated image encoded in base64. - - `String code` + - `Status status` - The JavaScript source executed by programmatic tool calling. + The status of the image generation call. - - `String fingerprint` + - `IN_PROGRESS("in_progress")` - Opaque program replay fingerprint that must be round-tripped. + - `COMPLETED("completed")` - - `JsonValue; type "program"constant` + - `GENERATING("generating")` - The item type. Always `program`. + - `FAILED("failed")` - - `PROGRAM("program")` + - `JsonValue; type "image_generation_call"constant` + + The type of the image generation call. Always `image_generation_call`. + + - `IMAGE_GENERATION_CALL("image_generation_call")` - `Optional agent` @@ -16984,3517 +34293,3398 @@ Create a model response The canonical name of the agent that produced this item. - - `ProgramOutput` - - - `String id` - - The unique ID of this program output item. + - `class BetaResponseCodeInterpreterToolCall:` - - `String callId` + A tool call to run code. - The call ID of the program item. + - `String id` - - `String result` + The unique ID of the code interpreter tool call. - The result produced by the program item. + - `Optional code` - - `Status status` + The code to run, or null if not available. - The terminal status of the program output. + - `String containerId` - - `COMPLETED("completed")` + The ID of the container used to run the code. - - `INCOMPLETE("incomplete")` + - `Optional> outputs` - - `JsonValue; type "program_output"constant` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The item type. Always `program_output`. + - `class Logs:` - - `PROGRAM_OUTPUT("program_output")` + The logs output from the code interpreter. - - `Optional agent` + - `String logs` - The agent that produced this item. + The logs output from the code interpreter. - - `String agentName` + - `JsonValue; type "logs"constant` - The canonical name of the agent that produced this item. + The type of the output. Always `logs`. - - `Optional instructions` + - `LOGS("logs")` - A system (or developer) message inserted into the model's context. + - `class Image:` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + The image output from the code interpreter. - - `Optional maxOutputTokens` + - `JsonValue; type "image"constant` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The type of the output. Always `image`. - - `Optional maxToolCalls` + - `IMAGE("image")` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `String url` - - `Optional metadata` + The URL of the image output from the code interpreter. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Status status` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `Optional model` + - `IN_PROGRESS("in_progress")` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `COMPLETED("completed")` - - `GPT_5_6_SOL("gpt-5.6-sol")` + - `INCOMPLETE("incomplete")` - - `GPT_5_6_TERRA("gpt-5.6-terra")` + - `INTERPRETING("interpreting")` - - `GPT_5_6_LUNA("gpt-5.6-luna")` + - `FAILED("failed")` - - `GPT_5_4("gpt-5.4")` + - `JsonValue; type "code_interpreter_call"constant` - - `GPT_5_4_MINI("gpt-5.4-mini")` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `GPT_5_4_NANO("gpt-5.4-nano")` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `Optional agent` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + The agent that produced this item. - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `String agentName` - - `GPT_5_2("gpt-5.2")` + The canonical name of the agent that produced this item. - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + - `LocalShellCall` - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + - `String id` - - `GPT_5_2_PRO("gpt-5.2-pro")` + The unique ID of the local shell call. - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + - `Action action` - - `GPT_5_1("gpt-5.1")` + Execute a shell command on the server. - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `List command` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + The command to run. - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `Env env` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + Environment variables to set for the command. - - `GPT_5("gpt-5")` + - `JsonValue; type "exec"constant` - - `GPT_5_MINI("gpt-5-mini")` + The type of the local shell action. Always `exec`. - - `GPT_5_NANO("gpt-5-nano")` + - `EXEC("exec")` - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + - `Optional timeoutMs` - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + Optional timeout in milliseconds for the command. - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `Optional user` - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + Optional user to run the command as. - - `GPT_4_1("gpt-4.1")` + - `Optional workingDirectory` - - `GPT_4_1_MINI("gpt-4.1-mini")` + Optional working directory to run the command in. - - `GPT_4_1_NANO("gpt-4.1-nano")` + - `String callId` - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + The unique ID of the local shell tool call generated by the model. - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + - `Status status` - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + The status of the local shell call. - - `O4_MINI("o4-mini")` + - `IN_PROGRESS("in_progress")` - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + - `COMPLETED("completed")` - - `O3("o3")` + - `INCOMPLETE("incomplete")` - - `O3_2025_04_16("o3-2025-04-16")` + - `JsonValue; type "local_shell_call"constant` - - `O3_MINI("o3-mini")` + The type of the local shell call. Always `local_shell_call`. - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `O1("o1")` + - `Optional agent` - - `O1_2024_12_17("o1-2024-12-17")` + The agent that produced this item. - - `O1_PREVIEW("o1-preview")` + - `String agentName` - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + The canonical name of the agent that produced this item. - - `O1_MINI("o1-mini")` + - `LocalShellCallOutput` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + - `String id` - - `GPT_4O("gpt-4o")` + The unique ID of the local shell tool call generated by the model. - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + - `String output` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + A JSON string of the output of the local shell tool call. - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + - `JsonValue; type "local_shell_call_output"constant` - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + - `Optional agent` - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + The agent that produced this item. - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + - `String agentName` - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + The canonical name of the agent that produced this item. - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + - `Optional status` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `IN_PROGRESS("in_progress")` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + - `COMPLETED("completed")` - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `INCOMPLETE("incomplete")` - - `CODEX_MINI_LATEST("codex-mini-latest")` + - `class BetaResponseFunctionShellToolCall:` - - `GPT_4O_MINI("gpt-4o-mini")` + A tool call that executes one or more shell commands in a managed environment. - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + - `String id` - - `GPT_4_TURBO("gpt-4-turbo")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `Action action` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + The shell commands and limits that describe how to run the tool call. - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + - `List commands` - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `Optional maxOutputLength` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + Optional maximum number of characters to return from each command. - - `GPT_4("gpt-4")` + - `Optional timeoutMs` - - `GPT_4_0314("gpt-4-0314")` + Optional timeout in milliseconds for the commands. - - `GPT_4_0613("gpt-4-0613")` + - `String callId` - - `GPT_4_32K("gpt-4-32k")` + The unique ID of the shell tool call generated by the model. - - `GPT_4_32K_0314("gpt-4-32k-0314")` + - `Optional environment` - - `GPT_4_32K_0613("gpt-4-32k-0613")` + Represents the use of a local environment to perform shell actions. - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `class BetaResponseLocalEnvironment:` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + Represents the use of a local environment to perform shell actions. - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `JsonValue; type "local"constant` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + The environment type. Always `local`. - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `LOCAL("local")` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `class BetaResponseContainerReference:` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + Represents a container created with /v1/containers. - - `O1_PRO("o1-pro")` + - `String containerId` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - `JsonValue; type "container_reference"constant` - - `O3_PRO("o3-pro")` + The environment type. Always `container_reference`. - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `CONTAINER_REFERENCE("container_reference")` - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `Status status` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + - `IN_PROGRESS("in_progress")` - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `COMPLETED("completed")` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `INCOMPLETE("incomplete")` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `JsonValue; type "shell_call"constant` - - `GPT_5_CODEX("gpt-5-codex")` + The type of the item. Always `shell_call`. - - `GPT_5_PRO("gpt-5-pro")` + - `SHELL_CALL("shell_call")` - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `Optional agent` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + The agent that produced this item. - - `Optional moderation` + - `String agentName` - Configuration for running moderation on the input and output of this response. + The canonical name of the agent that produced this item. - - `String model` + - `Optional caller` - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + The execution context that produced this tool call. - - `Optional policy` + - `JsonValue;` - The policy to apply to moderated response input and output. + - `JsonValue; type "direct"constant` - - `Optional input` + - `DIRECT("direct")` - The moderation policy for the response input. + - `class Program:` - - `Mode mode` + - `String callerId` - - `SCORE("score")` + The call ID of the program item that produced this tool call. - - `BLOCK("block")` + - `JsonValue; type "program"constant` - - `Optional output` + - `PROGRAM("program")` - The moderation policy for the response output. + - `Optional createdBy` - - `Mode mode` + The ID of the entity that created this tool call. - - `SCORE("score")` + - `class BetaResponseFunctionShellToolCallOutput:` - - `BLOCK("block")` + The output of a shell tool call that was emitted. - - `Optional multiAgent` + - `String id` - Configuration for server-hosted multi-agent execution. + The unique ID of the shell call output. Populated when this item is returned via API. - - `boolean enabled` + - `String callId` - Whether to enable server-hosted multi-agent execution for this response. + The unique ID of the shell tool call generated by the model. - - `Optional maxConcurrentSubagents` + - `Optional maxOutputLength` - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `Optional parallelToolCalls` + - `List output` - Whether to allow the model to run tool calls in parallel. + An array of shell call output contents - - `Optional previousResponseId` + - `Outcome outcome` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `Optional prompt` + - `JsonValue;` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `JsonValue; type "timeout"constant` - - `Optional promptCacheKey` + The outcome type. Always `timeout`. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `TIMEOUT("timeout")` - - `Optional promptCacheOptions` + - `class Exit:` - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + Indicates that the shell commands finished and returned an exit code. - - `Optional mode` + - `long exitCode` - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + Exit code from the shell process. - - `IMPLICIT("implicit")` + - `JsonValue; type "exit"constant` - - `EXPLICIT("explicit")` + The outcome type. Always `exit`. - - `Optional ttl` + - `EXIT("exit")` - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + - `String stderr` - - `_30M("30m")` + The standard error output that was captured. - - `Optional promptCacheRetention` + - `String stdout` - Deprecated. Use `prompt_cache_options.ttl` instead. + The standard output that was captured. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `Optional createdBy` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The identifier of the actor that created the item. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `Status status` - - `IN_MEMORY("in_memory")` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `_24H("24h")` + - `IN_PROGRESS("in_progress")` - - `Optional reasoning` + - `COMPLETED("completed")` - **gpt-5 and o-series models only** + - `INCOMPLETE("incomplete")` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `JsonValue; type "shell_call_output"constant` - - `Optional context` + The type of the shell call output. Always `shell_call_output`. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `AUTO("auto")` + - `Optional agent` - - `CURRENT_TURN("current_turn")` + The agent that produced this item. - - `ALL_TURNS("all_turns")` + - `String agentName` - - `Optional effort` + The canonical name of the agent that produced this item. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `Optional caller` - - `NONE("none")` + The execution context that produced this tool call. - - `MINIMAL("minimal")` + - `JsonValue;` - - `LOW("low")` + - `JsonValue; type "direct"constant` - - `MEDIUM("medium")` + - `DIRECT("direct")` - - `HIGH("high")` + - `class Program:` - - `XHIGH("xhigh")` + - `String callerId` - - `MAX("max")` + The call ID of the program item that produced this tool call. - - `Optional generateSummary` + - `JsonValue; type "program"constant` - **Deprecated:** use `summary` instead. + - `PROGRAM("program")` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `Optional createdBy` - - `AUTO("auto")` + The identifier of the actor that created the item. - - `CONCISE("concise")` + - `class BetaResponseApplyPatchToolCall:` - - `DETAILED("detailed")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `Optional mode` + - `String id` - Controls the reasoning execution mode for the request. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - When returned on a response, this is the effective execution mode. + - `String callId` - - `STANDARD("standard")` + The unique ID of the apply patch tool call generated by the model. - - `PRO("pro")` + - `Operation operation` - - `Optional summary` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `class CreateFile:` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + Instruction describing how to create a file via the apply_patch tool. - - `AUTO("auto")` + - `String diff` - - `CONCISE("concise")` + Diff to apply. - - `DETAILED("detailed")` + - `String path` - - `Optional safetyIdentifier` + Path of the file to create. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `JsonValue; type "create_file"constant` - - `Optional serviceTier` + Create a new file with the provided diff. - Specifies the processing type used for serving the request. + - `CREATE_FILE("create_file")` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `class DeleteFile:` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + Instruction describing how to delete a file via the apply_patch tool. - - `AUTO("auto")` + - `String path` - - `DEFAULT("default")` + Path of the file to delete. - - `FLEX("flex")` + - `JsonValue; type "delete_file"constant` - - `SCALE("scale")` + Delete the specified file. - - `PRIORITY("priority")` + - `DELETE_FILE("delete_file")` - - `Optional store` + - `class UpdateFile:` - Whether to store the generated model response for later retrieval via - API. + Instruction describing how to update a file via the apply_patch tool. - - `Optional streamOptions` + - `String diff` - Options for streaming responses. Only set this when you set `stream: true`. + Diff to apply. - - `Optional includeObfuscation` + - `String path` - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. + Path of the file to update. - - `Optional temperature` + - `JsonValue; type "update_file"constant` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + Update an existing file with the provided diff. - - `Optional text` + - `UPDATE_FILE("update_file")` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `Status status` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `Optional toolChoice` + - `IN_PROGRESS("in_progress")` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `COMPLETED("completed")` - - `enum BetaToolChoiceOptions:` + - `JsonValue; type "apply_patch_call"constant` - Controls which (if any) tool is called by the model. + The type of the item. Always `apply_patch_call`. - `none` means the model will not call any tool and instead generates a message. + - `APPLY_PATCH_CALL("apply_patch_call")` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `Optional agent` - `required` means the model must call one or more tools. + The agent that produced this item. - - `NONE("none")` + - `String agentName` - - `AUTO("auto")` + The canonical name of the agent that produced this item. - - `REQUIRED("required")` + - `Optional caller` - - `class BetaToolChoiceAllowed:` + The execution context that produced this tool call. - Constrains the tools available to the model to a pre-defined set. + - `JsonValue;` - - `Mode mode` + - `JsonValue; type "direct"constant` - Constrains the tools available to the model to a pre-defined set. + - `DIRECT("direct")` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `class Program:` - `required` requires the model to call one or more of the allowed tools. + - `String callerId` - - `AUTO("auto")` + The call ID of the program item that produced this tool call. - - `REQUIRED("required")` + - `JsonValue; type "program"constant` - - `List tools` + - `PROGRAM("program")` - A list of tool definitions that the model should be allowed to call. + - `Optional createdBy` - For the Responses API, the list of tool definitions might look like: + The ID of the entity that created this tool call. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `class BetaResponseApplyPatchToolCallOutput:` - - `JsonValue; type "allowed_tools"constant` + The output emitted by an apply patch tool call. - Allowed tool configuration type. Always `allowed_tools`. + - `String id` - - `ALLOWED_TOOLS("allowed_tools")` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class BetaToolChoiceTypes:` + - `String callId` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + The unique ID of the apply patch tool call generated by the model. - - `Type type` + - `Status status` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + The status of the apply patch tool call output. One of `completed` or `failed`. - Allowed values are: + - `COMPLETED("completed")` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `FAILED("failed")` - - `FILE_SEARCH("file_search")` + - `JsonValue; type "apply_patch_call_output"constant` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + The type of the item. Always `apply_patch_call_output`. - - `COMPUTER("computer")` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `Optional agent` - - `COMPUTER_USE("computer_use")` + The agent that produced this item. - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `String agentName` - - `IMAGE_GENERATION("image_generation")` + The canonical name of the agent that produced this item. - - `CODE_INTERPRETER("code_interpreter")` + - `Optional caller` - - `class BetaToolChoiceFunction:` + The execution context that produced this tool call. - Use this option to force the model to call a specific function. + - `JsonValue;` - - `String name` + - `JsonValue; type "direct"constant` - The name of the function to call. + - `DIRECT("direct")` - - `JsonValue; type "function"constant` + - `class Program:` - For function calling, the type is always `function`. + - `String callerId` - - `FUNCTION("function")` + The call ID of the program item that produced this tool call. - - `class BetaToolChoiceMcp:` + - `JsonValue; type "program"constant` - Use this option to force the model to call a specific tool on a remote MCP server. + - `PROGRAM("program")` - - `String serverLabel` + - `Optional createdBy` - The label of the MCP server to use. + The ID of the entity that created this tool call output. - - `JsonValue; type "mcp"constant` + - `Optional output` - For MCP tools, the type is always `mcp`. + Optional textual output returned by the apply patch tool. - - `MCP("mcp")` + - `McpCall` - - `Optional name` + - `String id` - The name of the tool to call on the server. + The unique ID of the tool call. - - `class BetaToolChoiceCustom:` + - `String arguments` - Use this option to force the model to call a specific custom tool. + A JSON string of the arguments passed to the tool. - `String name` - The name of the custom tool to call. - - - `JsonValue; type "custom"constant` + The name of the tool that was run. - For custom tool calling, the type is always `custom`. + - `String serverLabel` - - `CUSTOM("custom")` + The label of the MCP server running the tool. - - `JsonValue;` + - `JsonValue; type "mcp_call"constant` - - `JsonValue; type "programmatic_tool_calling"constant` + The type of the item. Always `mcp_call`. - The tool to call. Always `programmatic_tool_calling`. + - `MCP_CALL("mcp_call")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional agent` - - `class BetaToolChoiceApplyPatch:` + The agent that produced this item. - Forces the model to call the apply_patch tool when executing a tool call. + - `String agentName` - - `JsonValue; type "apply_patch"constant` + The canonical name of the agent that produced this item. - The tool to call. Always `apply_patch`. + - `Optional approvalRequestId` - - `APPLY_PATCH("apply_patch")` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `class BetaToolChoiceShell:` + - `Optional error` - Forces the model to call the shell tool when a tool call is required. + The error from the tool call, if any. - - `JsonValue; type "shell"constant` + - `Optional output` - The tool to call. Always `shell`. + The output from the tool call. - - `SHELL("shell")` + - `Optional status` - - `Optional> tools` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `IN_PROGRESS("in_progress")` - We support the following categories of tools: + - `COMPLETED("completed")` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `INCOMPLETE("incomplete")` - - `class BetaFunctionTool:` + - `CALLING("calling")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `FAILED("failed")` - - `class BetaFileSearchTool:` + - `McpListTools` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `String id` - - `class BetaComputerTool:` + The unique ID of the list. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String serverLabel` - - `class BetaComputerUsePreviewTool:` + The label of the MCP server. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `List tools` - - `class BetaWebSearchTool:` + The tools available on the server. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue inputSchema` - - `Mcp` + The JSON schema describing the tool's input. - - `CodeInterpreter` + - `String name` - - `JsonValue;` + The name of the tool. - - `ImageGeneration` + - `Optional annotations` - - `JsonValue;` + Additional annotations about the tool. - - `class BetaFunctionShellTool:` + - `Optional description` - A tool that allows the model to execute shell commands. + The description of the tool. - - `class BetaCustomTool:` + - `JsonValue; type "mcp_list_tools"constant` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The type of the item. Always `mcp_list_tools`. - - `class BetaNamespaceTool:` + - `MCP_LIST_TOOLS("mcp_list_tools")` - Groups function/custom tools under a shared namespace. + - `Optional agent` - - `class BetaToolSearchTool:` + The agent that produced this item. - Hosted or BYOT tool search configuration for deferred tools. + - `String agentName` - - `class BetaWebSearchPreviewTool:` + The canonical name of the agent that produced this item. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional error` - - `class BetaApplyPatchTool:` + Error message if the server could not list tools. - Allows the assistant to create, delete, or update files using unified diffs. + - `McpApprovalRequest` - - `Optional topLogprobs` + - `String id` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The unique ID of the approval request. - - `Optional topP` + - `String arguments` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + A JSON string of arguments for the tool. - We generally recommend altering this or `temperature` but not both. + - `String name` - - `Optional truncation` + The name of the tool to run. - The truncation strategy to use for the model response. + - `String serverLabel` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The label of the MCP server making the request. - - `AUTO("auto")` + - `JsonValue; type "mcp_approval_request"constant` - - `DISABLED("disabled")` + The type of the item. Always `mcp_approval_request`. - - `Optional user` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `Optional agent` -### Returns + The agent that produced this item. -- `class BetaResponse:` + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - Unique identifier for this Response. + - `McpApprovalResponse` - - `double createdAt` + - `String id` - Unix timestamp (in seconds) of when this Response was created. + The unique ID of the approval response - - `Optional error` + - `String approvalRequestId` - An error object returned when the model fails to generate a Response. + The ID of the approval request being answered. - - `Code code` + - `boolean approve` - The error code for the response. + Whether the request was approved. - - `SERVER_ERROR("server_error")` + - `JsonValue; type "mcp_approval_response"constant` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The type of the item. Always `mcp_approval_response`. - - `INVALID_PROMPT("invalid_prompt")` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `BIO_POLICY("bio_policy")` + - `Optional agent` - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + The agent that produced this item. - - `INVALID_IMAGE("invalid_image")` + - `String agentName` - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + The canonical name of the agent that produced this item. - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `Optional reason` - - `INVALID_IMAGE_URL("invalid_image_url")` + Optional reason for the decision. - - `IMAGE_TOO_LARGE("image_too_large")` + - `class BetaResponseCustomToolCall:` - - `IMAGE_TOO_SMALL("image_too_small")` + A call to a custom tool created by the model. - - `IMAGE_PARSE_ERROR("image_parse_error")` + - `String callId` - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + An identifier used to map this custom tool call to a tool call output. - - `INVALID_IMAGE_MODE("invalid_image_mode")` + - `String input` - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + The input for the custom tool call generated by the model. - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + - `String name` - - `EMPTY_IMAGE_FILE("empty_image_file")` + The name of the custom tool being called. - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + - `JsonValue; type "custom_tool_call"constant` - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + The type of the custom tool call. Always `custom_tool_call`. - - `String message` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - A human-readable description of the error. + - `Optional id` - - `Optional incompleteDetails` + The unique ID of the custom tool call in the OpenAI platform. - Details about why the response is incomplete. + - `Optional agent` - - `Optional reason` + The agent that produced this item. - The reason why the response is incomplete. + - `String agentName` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + The canonical name of the agent that produced this item. - - `CONTENT_FILTER("content_filter")` + - `Optional caller` - - `Optional instructions` + The execution context that produced this tool call. - A system (or developer) message inserted into the model's context. + - `JsonValue;` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `JsonValue; type "direct"constant` - - `String` + - `DIRECT("direct")` - - `List` + - `class Program:` - - `class BetaEasyInputMessage:` + - `String callerId` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The call ID of the program item that produced this tool call. - - `Content content` + - `JsonValue; type "program"constant` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `PROGRAM("program")` - - `String` + - `Optional namespace` - - `List` + The namespace of the custom tool being called. - - `class BetaResponseInputText:` + - `class BetaResponseCustomToolCallOutputItem:` - A text input to the model. + The output of a custom tool call from your code, being sent back to the model. - - `String text` + - `String id` - The text input to the model. + The unique ID of the custom tool call output item. - - `JsonValue; type "input_text"constant` + - `Status status` - The type of the input item. Always `input_text`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `INPUT_TEXT("input_text")` + - `IN_PROGRESS("in_progress")` - - `Optional promptCacheBreakpoint` + - `COMPLETED("completed")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `INCOMPLETE("incomplete")` - - `JsonValue; mode "explicit"constant` + - `Optional createdBy` - The breakpoint mode. Always `explicit`. + The identifier of the actor that created the item. - - `EXPLICIT("explicit")` + - `BetaResponseUsage usage` - - `class BetaResponseInputImage:` + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `long inputTokens` - - `Detail detail` + The number of input tokens. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `InputTokensDetails inputTokensDetails` - - `LOW("low")` + A detailed breakdown of the input tokens. - - `HIGH("high")` + - `long cacheWriteTokens` - - `AUTO("auto")` + The number of input tokens that were written to the cache. - - `ORIGINAL("original")` + - `long cachedTokens` - - `JsonValue; type "input_image"constant` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The type of the input item. Always `input_image`. + - `long outputTokens` - - `INPUT_IMAGE("input_image")` + The number of output tokens. - - `Optional fileId` + - `OutputTokensDetails outputTokensDetails` - The ID of the file to be sent to the model. + A detailed breakdown of the output tokens. - - `Optional imageUrl` + - `long reasoningTokens` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The number of reasoning tokens. - - `Optional promptCacheBreakpoint` + - `long totalTokens` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The total number of tokens used. - - `JsonValue; mode "explicit"constant` +### Beta Computer Action - The breakpoint mode. Always `explicit`. +- `class BetaComputerAction: A class that can be one of several variants.union` - - `EXPLICIT("explicit")` + A click action. - - `class BetaResponseInputFile:` + - `Click` - A file input to the model. + - `Button button` - - `JsonValue; type "input_file"constant` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The type of the input item. Always `input_file`. + - `LEFT("left")` - - `INPUT_FILE("input_file")` + - `RIGHT("right")` - - `Optional detail` + - `WHEEL("wheel")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `BACK("back")` - - `AUTO("auto")` + - `FORWARD("forward")` - - `LOW("low")` + - `JsonValue; type "click"constant` - - `HIGH("high")` + Specifies the event type. For a click action, this property is always `click`. - - `Optional fileData` + - `CLICK("click")` - The content of the file to be sent to the model. + - `long x` - - `Optional fileId` + The x-coordinate where the click occurred. - The ID of the file to be sent to the model. + - `long y` - - `Optional fileUrl` + The y-coordinate where the click occurred. - The URL of the file to be sent to the model. + - `Optional> keys` - - `Optional filename` + The keys being held while clicking. - The name of the file to be sent to the model. + - `DoubleClick` - - `Optional promptCacheBreakpoint` + - `Optional> keys` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The keys being held while double-clicking. - - `JsonValue; mode "explicit"constant` + - `JsonValue; type "double_click"constant` - The breakpoint mode. Always `explicit`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `EXPLICIT("explicit")` + - `DOUBLE_CLICK("double_click")` - - `Role role` + - `long x` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The x-coordinate where the double click occurred. - - `USER("user")` + - `long y` - - `ASSISTANT("assistant")` + The y-coordinate where the double click occurred. - - `SYSTEM("system")` + - `Drag` - - `DEVELOPER("developer")` + - `List path` - - `Optional phase` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - 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. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `COMMENTARY("commentary")` + - `long x` - - `Optional type` + The x-coordinate. - The type of the message input. Always `message`. + - `long y` - - `MESSAGE("message")` + The y-coordinate. - - `Message` + - `JsonValue; type "drag"constant` - - `List content` + Specifies the event type. For a drag action, this property is always set to `drag`. - A list of one or many input items to the model, containing different content - types. + - `DRAG("drag")` - - `class BetaResponseInputText:` + - `Optional> keys` - A text input to the model. + The keys being held while dragging the mouse. - - `class BetaResponseInputImage:` + - `Keypress` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `List keys` - - `class BetaResponseInputFile:` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A file input to the model. + - `JsonValue; type "keypress"constant` - - `Role role` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The role of the message input. One of `user`, `system`, or `developer`. + - `KEYPRESS("keypress")` - - `USER("user")` + - `Move` - - `SYSTEM("system")` + - `JsonValue; type "move"constant` - - `DEVELOPER("developer")` + Specifies the event type. For a move action, this property is always set to `move`. - - `Optional agent` + - `MOVE("move")` - The agent that produced this item. + - `long x` - - `String agentName` + The x-coordinate to move to. - The canonical name of the agent that produced this item. + - `long y` - - `Optional status` + The y-coordinate to move to. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional> keys` - - `IN_PROGRESS("in_progress")` + The keys being held while moving the mouse. - - `COMPLETED("completed")` + - `JsonValue;` - - `INCOMPLETE("incomplete")` + - `JsonValue; type "screenshot"constant` - - `Optional type` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The type of the message input. Always set to `message`. + - `SCREENSHOT("screenshot")` - - `MESSAGE("message")` + - `Scroll` - - `class BetaResponseOutputMessage:` + - `long scrollX` - An output message from the model. + The horizontal scroll distance. - - `String id` + - `long scrollY` - The unique ID of the output message. + The vertical scroll distance. - - `List content` + - `JsonValue; type "scroll"constant` - The content of the output message. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class BetaResponseOutputText:` + - `SCROLL("scroll")` - A text output from the model. + - `long x` - - `List annotations` + The x-coordinate where the scroll occurred. - The annotations of the text output. + - `long y` - - `class FileCitation:` + The y-coordinate where the scroll occurred. - A citation to a file. + - `Optional> keys` - - `String fileId` + The keys being held while scrolling. - The ID of the file. + - `Type` - - `String filename` + - `String text` - The filename of the file cited. + The text to type. - - `long index` + - `JsonValue; type "type"constant` - The index of the file in the list of files. + Specifies the event type. For a type action, this property is always set to `type`. - - `JsonValue; type "file_citation"constant` + - `TYPE("type")` - The type of the file citation. Always `file_citation`. + - `JsonValue;` - - `FILE_CITATION("file_citation")` + - `JsonValue; type "wait"constant` - - `class UrlCitation:` + Specifies the event type. For a wait action, this property is always set to `wait`. - A citation for a web resource used to generate a model response. + - `WAIT("wait")` - - `long endIndex` +### Beta Computer Tool - The index of the last character of the URL citation in the message. +- `class BetaComputerTool:` - - `long startIndex` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The index of the first character of the URL citation in the message. + - `JsonValue; type "computer"constant` - - `String title` + The type of the computer tool. Always `computer`. - The title of the web resource. + - `COMPUTER("computer")` - - `JsonValue; type "url_citation"constant` +### Beta Computer Use Preview Tool - The type of the URL citation. Always `url_citation`. +- `class BetaComputerUsePreviewTool:` - - `URL_CITATION("url_citation")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String url` + - `long displayHeight` - The URL of the web resource. + The height of the computer display. - - `class ContainerFileCitation:` + - `long displayWidth` - A citation for a container file used to generate a model response. + The width of the computer display. - - `String containerId` + - `Environment environment` - The ID of the container file. + The type of computer environment to control. - - `long endIndex` + - `WINDOWS("windows")` - The index of the last character of the container file citation in the message. + - `MAC("mac")` - - `String fileId` + - `LINUX("linux")` - The ID of the file. + - `UBUNTU("ubuntu")` - - `String filename` + - `BROWSER("browser")` - The filename of the container file cited. + - `JsonValue; type "computer_use_preview"constant` - - `long startIndex` + The type of the computer use tool. Always `computer_use_preview`. - The index of the first character of the container file citation in the message. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `JsonValue; type "container_file_citation"constant` +### Beta Container Auto - The type of the container file citation. Always `container_file_citation`. +- `class BetaContainerAuto:` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `JsonValue; type "container_auto"constant` - - `class FilePath:` + Automatically creates a container for this request - A path to a file. + - `CONTAINER_AUTO("container_auto")` - - `String fileId` + - `Optional> fileIds` - The ID of the file. + An optional list of uploaded files to make available to your code. - - `long index` + - `Optional memoryLimit` - The index of the file in the list of files. + The memory limit for the container. - - `JsonValue; type "file_path"constant` + - `_1G("1g")` - The type of the file path. Always `file_path`. + - `_4G("4g")` - - `FILE_PATH("file_path")` + - `_16G("16g")` - - `String text` + - `_64G("64g")` - The text output from the model. + - `Optional networkPolicy` - - `JsonValue; type "output_text"constant` + Network access policy for the container. - The type of the output text. Always `output_text`. + - `class BetaContainerNetworkPolicyDisabled:` - - `OUTPUT_TEXT("output_text")` + - `JsonValue; type "disabled"constant` - - `Optional> logprobs` + Disable outbound network access. Always `disabled`. - - `String token` + - `DISABLED("disabled")` - - `List bytes` + - `class BetaContainerNetworkPolicyAllowlist:` - - `double logprob` + - `List allowedDomains` - - `List topLogprobs` + A list of allowed domains when type is `allowlist`. - - `String token` + - `JsonValue; type "allowlist"constant` - - `List bytes` + Allow outbound network access only to specified domains. Always `allowlist`. - - `double logprob` + - `ALLOWLIST("allowlist")` - - `class BetaResponseOutputRefusal:` + - `Optional> domainSecrets` - A refusal from the model. + Optional domain-scoped secrets for allowlisted domains. - - `String refusal` + - `String domain` - The refusal explanation from the model. + The domain associated with the secret. - - `JsonValue; type "refusal"constant` + - `String name` - The type of the refusal. Always `refusal`. + The name of the secret to inject for the domain. - - `REFUSAL("refusal")` + - `String value` - - `JsonValue; role "assistant"constant` + The secret value to inject for the domain. - The role of the output message. Always `assistant`. + - `Optional> skills` - - `ASSISTANT("assistant")` + An optional list of skills referenced by id or inline data. - - `Status status` + - `class BetaSkillReference:` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `String skillId` - - `IN_PROGRESS("in_progress")` + The ID of the referenced skill. - - `COMPLETED("completed")` + - `JsonValue; type "skill_reference"constant` - - `INCOMPLETE("incomplete")` + References a skill created with the /v1/skills endpoint. - - `JsonValue; type "message"constant` + - `SKILL_REFERENCE("skill_reference")` - The type of the output message. Always `message`. + - `Optional version` - - `MESSAGE("message")` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `Optional agent` + - `class BetaInlineSkill:` - The agent that produced this item. + - `String description` - - `String agentName` + The description of the skill. - The canonical name of the agent that produced this item. + - `String name` - - `Optional phase` + The name of the skill. - 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. + - `BetaInlineSkillSource source` - - `COMMENTARY("commentary")` + Inline skill payload - - `class BetaResponseFileSearchToolCall:` + - `String data` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Base64-encoded skill zip bundle. - - `String id` + - `JsonValue; mediaType "application/zip"constant` - The unique ID of the file search tool call. + The media type of the inline skill payload. Must be `application/zip`. - - `List queries` + - `APPLICATION_ZIP("application/zip")` - The queries used to search for files. + - `JsonValue; type "base64"constant` - - `Status status` + The type of the inline skill source. Must be `base64`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `BASE64("base64")` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "inline"constant` - - `SEARCHING("searching")` + Defines an inline skill for this request. - - `COMPLETED("completed")` + - `INLINE("inline")` - - `INCOMPLETE("incomplete")` +### Beta Container Network Policy Allowlist - - `FAILED("failed")` +- `class BetaContainerNetworkPolicyAllowlist:` - - `JsonValue; type "file_search_call"constant` + - `List allowedDomains` - The type of the file search tool call. Always `file_search_call`. + A list of allowed domains when type is `allowlist`. - - `FILE_SEARCH_CALL("file_search_call")` + - `JsonValue; type "allowlist"constant` - - `Optional agent` + Allow outbound network access only to specified domains. Always `allowlist`. - The agent that produced this item. + - `ALLOWLIST("allowlist")` - - `String agentName` + - `Optional> domainSecrets` - The canonical name of the agent that produced this item. + Optional domain-scoped secrets for allowlisted domains. - - `Optional> results` + - `String domain` - The results of the file search tool call. + The domain associated with the secret. - - `Optional attributes` + - `String name` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The name of the secret to inject for the domain. - - `String` + - `String value` - - `double` + The secret value to inject for the domain. - - `boolean` +### Beta Container Network Policy Disabled - - `Optional fileId` +- `class BetaContainerNetworkPolicyDisabled:` - The unique ID of the file. + - `JsonValue; type "disabled"constant` - - `Optional filename` + Disable outbound network access. Always `disabled`. - The name of the file. + - `DISABLED("disabled")` - - `Optional score` +### Beta Container Network Policy Domain Secret - The relevance score of the file - a value between 0 and 1. +- `class BetaContainerNetworkPolicyDomainSecret:` - - `Optional text` + - `String domain` - The text that was retrieved from the file. + The domain associated with the secret. - - `class BetaResponseComputerToolCall:` + - `String name` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The name of the secret to inject for the domain. - - `String id` + - `String value` - The unique ID of the computer call. + The secret value to inject for the domain. - - `String callId` +### Beta Container Reference - An identifier used when responding to the tool call with output. +- `class BetaContainerReference:` - - `List pendingSafetyChecks` + - `String containerId` - The pending safety checks for the computer call. + The ID of the referenced container. - - `String id` + - `JsonValue; type "container_reference"constant` - The ID of the pending safety check. + References a container created with the /v1/containers endpoint - - `Optional code` + - `CONTAINER_REFERENCE("container_reference")` - The type of the pending safety check. +### Beta Custom Tool - - `Optional message` +- `class BetaCustomTool:` - Details about the pending safety check. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Status status` + - `String name` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the custom tool, used to identify it in tool calls. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "custom"constant` - - `COMPLETED("completed")` + The type of the custom tool. Always `custom`. - - `INCOMPLETE("incomplete")` + - `CUSTOM("custom")` - - `Type type` + - `Optional> allowedCallers` - The type of the computer call. Always `computer_call`. + The tool invocation context(s). - - `COMPUTER_CALL("computer_call")` + - `DIRECT("direct")` - - `Optional action` + - `PROGRAMMATIC("programmatic")` - A click action. + - `Optional deferLoading` - - `Click` + Whether this tool should be deferred and discovered via tool search. - - `Button button` + - `Optional description` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Optional description of the custom tool, used to provide more context. - - `LEFT("left")` + - `Optional format` - - `RIGHT("right")` + The input format for the custom tool. Default is unconstrained text. - - `WHEEL("wheel")` + - `JsonValue;` - - `BACK("back")` + - `JsonValue; type "text"constant` - - `FORWARD("forward")` + Unconstrained text format. Always `text`. - - `JsonValue; type "click"constant` + - `TEXT("text")` - Specifies the event type. For a click action, this property is always `click`. + - `class Grammar:` - - `CLICK("click")` + A grammar defined by the user. - - `long x` + - `String definition` - The x-coordinate where the click occurred. + The grammar definition. - - `long y` + - `Syntax syntax` - The y-coordinate where the click occurred. + The syntax of the grammar definition. One of `lark` or `regex`. - - `Optional> keys` + - `LARK("lark")` - The keys being held while clicking. + - `REGEX("regex")` - - `DoubleClick` + - `JsonValue; type "grammar"constant` - - `Optional> keys` + Grammar format. Always `grammar`. - The keys being held while double-clicking. + - `GRAMMAR("grammar")` - - `JsonValue; type "double_click"constant` +### Beta Easy Input Message - Specifies the event type. For a double click action, this property is always set to `double_click`. +- `class BetaEasyInputMessage:` - - `DOUBLE_CLICK("double_click")` + 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. - - `long x` + - `Content content` - The x-coordinate where the double click occurred. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `long y` + - `String` - The y-coordinate where the double click occurred. + - `List` - - `Drag` + - `class BetaResponseInputText:` - - `List path` + A text input to the model. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `String text` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The text input to the model. - - `long x` + - `JsonValue; type "input_text"constant` - The x-coordinate. + The type of the input item. Always `input_text`. - - `long y` + - `INPUT_TEXT("input_text")` - The y-coordinate. + - `Optional promptCacheBreakpoint` - - `JsonValue; type "drag"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `JsonValue; mode "explicit"constant` - - `DRAG("drag")` + The breakpoint mode. Always `explicit`. - - `Optional> keys` + - `EXPLICIT("explicit")` - The keys being held while dragging the mouse. + - `class BetaResponseInputImage:` - - `Keypress` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `List keys` + - `Detail detail` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `JsonValue; type "keypress"constant` + - `LOW("low")` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `HIGH("high")` - - `KEYPRESS("keypress")` + - `AUTO("auto")` - - `Move` + - `ORIGINAL("original")` - - `JsonValue; type "move"constant` + - `JsonValue; type "input_image"constant` - Specifies the event type. For a move action, this property is always set to `move`. + The type of the input item. Always `input_image`. - - `MOVE("move")` + - `INPUT_IMAGE("input_image")` - - `long x` + - `Optional fileId` - The x-coordinate to move to. + The ID of the file to be sent to the model. - - `long y` + - `Optional imageUrl` - The y-coordinate to move to. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `Optional> keys` + - `Optional promptCacheBreakpoint` - The keys being held while moving the mouse. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue;` + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "screenshot"constant` + The breakpoint mode. Always `explicit`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `EXPLICIT("explicit")` - - `SCREENSHOT("screenshot")` + - `class BetaResponseInputFile:` - - `Scroll` + A file input to the model. - - `long scrollX` + - `JsonValue; type "input_file"constant` - The horizontal scroll distance. + The type of the input item. Always `input_file`. - - `long scrollY` + - `INPUT_FILE("input_file")` - The vertical scroll distance. + - `Optional detail` - - `JsonValue; type "scroll"constant` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `AUTO("auto")` - - `SCROLL("scroll")` + - `LOW("low")` - - `long x` + - `HIGH("high")` - The x-coordinate where the scroll occurred. + - `Optional fileData` - - `long y` + The content of the file to be sent to the model. - The y-coordinate where the scroll occurred. + - `Optional fileId` - - `Optional> keys` + The ID of the file to be sent to the model. - The keys being held while scrolling. + - `Optional fileUrl` - - `Type` + The URL of the file to be sent to the model. - - `String text` + - `Optional filename` - The text to type. + The name of the file to be sent to the model. - - `JsonValue; type "type"constant` + - `Optional promptCacheBreakpoint` - Specifies the event type. For a type action, this property is always set to `type`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `TYPE("type")` + - `JsonValue; mode "explicit"constant` - - `JsonValue;` + The breakpoint mode. Always `explicit`. - - `JsonValue; type "wait"constant` + - `EXPLICIT("explicit")` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `Role role` - - `WAIT("wait")` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `Optional> actions` + - `USER("user")` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `ASSISTANT("assistant")` - - `Click` + - `SYSTEM("system")` - - `DoubleClick` + - `DEVELOPER("developer")` - - `Drag` + - `Optional phase` - - `Keypress` + 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. - - `Move` + - `COMMENTARY("commentary")` - - `JsonValue;` + - `FINAL_ANSWER("final_answer")` - - `Scroll` + - `Optional type` - - `Type` + The type of the message input. Always `message`. - - `JsonValue;` + - `MESSAGE("message")` - - `Optional agent` +### Beta File Search Tool - The agent that produced this item. +- `class BetaFileSearchTool:` - - `String agentName` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The canonical name of the agent that produced this item. + - `JsonValue; type "file_search"constant` - - `ComputerCallOutput` + The type of the file search tool. Always `file_search`. - - `String callId` + - `FILE_SEARCH("file_search")` - The ID of the computer tool call that produced the output. + - `List vectorStoreIds` - - `BetaResponseComputerToolCallOutputScreenshot output` + The IDs of the vector stores to search. - A computer screenshot image used with the computer use tool. + - `Optional filters` - - `JsonValue; type "computer_screenshot"constant` + A filter to apply. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `class ComparisonFilter:` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `Optional fileId` + - `String key` - The identifier of an uploaded file that contains the screenshot. + The key to compare against the value. - - `Optional imageUrl` + - `Type type` - The URL of the screenshot image. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `JsonValue; type "computer_call_output"constant` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The type of the computer tool call output. Always `computer_call_output`. + - `EQ("eq")` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `NE("ne")` - - `Optional id` + - `GT("gt")` - The ID of the computer tool call output. + - `GTE("gte")` - - `Optional> acknowledgedSafetyChecks` + - `LT("lt")` - The safety checks reported by the API that have been acknowledged by the developer. + - `LTE("lte")` - - `String id` + - `IN("in")` - The ID of the pending safety check. + - `NIN("nin")` - - `Optional code` + - `Value value` - The type of the pending safety check. + The value to compare against the attribute key; supports string, number, or boolean types. - - `Optional message` + - `String` - Details about the pending safety check. + - `double` - - `Optional agent` + - `boolean` - The agent that produced this item. + - `List` - - `String agentName` + - `String` - The canonical name of the agent that produced this item. + - `double` - - `Optional status` + - `class CompoundFilter:` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + Combine multiple filters using `and` or `or`. - - `IN_PROGRESS("in_progress")` + - `List filters` - - `COMPLETED("completed")` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `INCOMPLETE("incomplete")` + - `class ComparisonFilter:` - - `class BetaResponseFunctionWebSearch:` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `String key` - - `String id` + The key to compare against the value. - The unique ID of the web search tool call. + - `Type type` - - `Action action` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - 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). + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `class Search:` + - `EQ("eq")` - Action type "search" - Performs a web search query. + - `NE("ne")` - - `JsonValue; type "search"constant` + - `GT("gt")` - The action type. + - `GTE("gte")` - - `SEARCH("search")` + - `LT("lt")` - - `Optional> queries` + - `LTE("lte")` - The search queries. + - `IN("in")` - - `Optional query` + - `NIN("nin")` - The search query. + - `Value value` - - `Optional> sources` + The value to compare against the attribute key; supports string, number, or boolean types. - The sources used in the search. + - `String` - - `JsonValue; type "url"constant` + - `double` - The type of source. Always `url`. + - `boolean` - - `URL("url")` + - `List` - - `String url` + - `String` - The URL of the source. + - `double` - - `class OpenPage:` + - `JsonValue` - Action type "open_page" - Opens a specific URL from search results. + - `Type type` - - `JsonValue; type "open_page"constant` + Type of operation: `and` or `or`. - The action type. + - `AND("and")` - - `OPEN_PAGE("open_page")` + - `OR("or")` - - `Optional url` + - `Optional maxNumResults` - The URL opened by the model. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `class FindInPage:` + - `Optional rankingOptions` - Action type "find_in_page": Searches for a pattern within a loaded page. + Ranking options for search. - - `String pattern` + - `Optional hybridSearch` - The pattern or text to search for within the page. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `JsonValue; type "find_in_page"constant` + - `double embeddingWeight` - The action type. + The weight of the embedding in the reciprocal ranking fusion. - - `FIND_IN_PAGE("find_in_page")` + - `double textWeight` - - `String url` + The weight of the text in the reciprocal ranking fusion. - The URL of the page searched for the pattern. + - `Optional ranker` - - `Status status` + The ranker to use for the file search. - The status of the web search tool call. + - `AUTO("auto")` - - `IN_PROGRESS("in_progress")` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `SEARCHING("searching")` + - `Optional scoreThreshold` - - `COMPLETED("completed")` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `FAILED("failed")` +### Beta Function Shell Tool - - `JsonValue; type "web_search_call"constant` +- `class BetaFunctionShellTool:` - The type of the web search tool call. Always `web_search_call`. + A tool that allows the model to execute shell commands. - - `WEB_SEARCH_CALL("web_search_call")` + - `JsonValue; type "shell"constant` - - `Optional agent` + The type of the shell tool. Always `shell`. - The agent that produced this item. + - `SHELL("shell")` - - `String agentName` + - `Optional> allowedCallers` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `class BetaResponseFunctionToolCall:` + - `DIRECT("direct")` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `PROGRAMMATIC("programmatic")` - - `String arguments` + - `Optional environment` - A JSON string of the arguments to pass to the function. + - `class BetaContainerAuto:` - - `String callId` + - `JsonValue; type "container_auto"constant` - The unique ID of the function tool call generated by the model. + Automatically creates a container for this request - - `String name` + - `CONTAINER_AUTO("container_auto")` - The name of the function to run. + - `Optional> fileIds` - - `JsonValue; type "function_call"constant` + An optional list of uploaded files to make available to your code. - The type of the function tool call. Always `function_call`. + - `Optional memoryLimit` - - `FUNCTION_CALL("function_call")` + The memory limit for the container. - - `Optional id` + - `_1G("1g")` - The unique ID of the function tool call. + - `_4G("4g")` - - `Optional agent` + - `_16G("16g")` - The agent that produced this item. + - `_64G("64g")` - - `String agentName` + - `Optional networkPolicy` - The canonical name of the agent that produced this item. + Network access policy for the container. - - `Optional caller` + - `class BetaContainerNetworkPolicyDisabled:` - The execution context that produced this tool call. + - `JsonValue; type "disabled"constant` - - `JsonValue;` + Disable outbound network access. Always `disabled`. - - `JsonValue; type "direct"constant` + - `DISABLED("disabled")` - - `DIRECT("direct")` + - `class BetaContainerNetworkPolicyAllowlist:` - - `class Program:` + - `List allowedDomains` - - `String callerId` + A list of allowed domains when type is `allowlist`. - The call ID of the program item that produced this tool call. + - `JsonValue; type "allowlist"constant` - - `JsonValue; type "program"constant` + Allow outbound network access only to specified domains. Always `allowlist`. - - `PROGRAM("program")` + - `ALLOWLIST("allowlist")` - - `Optional namespace` + - `Optional> domainSecrets` - The namespace of the function to run. + Optional domain-scoped secrets for allowlisted domains. - - `Optional status` + - `String domain` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The domain associated with the secret. - - `IN_PROGRESS("in_progress")` + - `String name` - - `COMPLETED("completed")` + The name of the secret to inject for the domain. - - `INCOMPLETE("incomplete")` + - `String value` - - `FunctionCallOutput` + The secret value to inject for the domain. - - `String callId` + - `Optional> skills` - The unique ID of the function tool call generated by the model. + An optional list of skills referenced by id or inline data. - - `Output output` + - `class BetaSkillReference:` - Text, image, or file output of the function tool call. + - `String skillId` - - `String` + The ID of the referenced skill. - - `List` + - `JsonValue; type "skill_reference"constant` - - `class BetaResponseInputTextContent:` + References a skill created with the /v1/skills endpoint. - A text input to the model. + - `SKILL_REFERENCE("skill_reference")` - - `String text` + - `Optional version` - The text input to the model. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `JsonValue; type "input_text"constant` + - `class BetaInlineSkill:` - The type of the input item. Always `input_text`. + - `String description` - - `INPUT_TEXT("input_text")` + The description of the skill. - - `Optional promptCacheBreakpoint` + - `String name` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The name of the skill. - - `JsonValue; mode "explicit"constant` + - `BetaInlineSkillSource source` - The breakpoint mode. Always `explicit`. + Inline skill payload - - `EXPLICIT("explicit")` + - `String data` - - `class BetaResponseInputImageContent:` + Base64-encoded skill zip bundle. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `JsonValue; mediaType "application/zip"constant` - - `JsonValue; type "input_image"constant` + The media type of the inline skill payload. Must be `application/zip`. - The type of the input item. Always `input_image`. + - `APPLICATION_ZIP("application/zip")` - - `INPUT_IMAGE("input_image")` + - `JsonValue; type "base64"constant` - - `Optional detail` + The type of the inline skill source. Must be `base64`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `BASE64("base64")` - - `LOW("low")` + - `JsonValue; type "inline"constant` - - `HIGH("high")` + Defines an inline skill for this request. - - `AUTO("auto")` + - `INLINE("inline")` - - `ORIGINAL("original")` + - `class BetaLocalEnvironment:` - - `Optional fileId` + - `JsonValue; type "local"constant` - The ID of the file to be sent to the model. + Use a local computer environment. - - `Optional imageUrl` + - `LOCAL("local")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `Optional> skills` - - `Optional promptCacheBreakpoint` + An optional list of skills. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String description` - - `JsonValue; mode "explicit"constant` + The description of the skill. - The breakpoint mode. Always `explicit`. + - `String name` - - `EXPLICIT("explicit")` + The name of the skill. - - `class BetaResponseInputFileContent:` + - `String path` - A file input to the model. + The path to the directory containing the skill. - - `JsonValue; type "input_file"constant` + - `class BetaContainerReference:` - The type of the input item. Always `input_file`. + - `String containerId` - - `INPUT_FILE("input_file")` + The ID of the referenced container. - - `Optional detail` + - `JsonValue; type "container_reference"constant` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + References a container created with the /v1/containers endpoint - - `AUTO("auto")` + - `CONTAINER_REFERENCE("container_reference")` - - `LOW("low")` +### Beta Function Tool - - `HIGH("high")` +- `class BetaFunctionTool:` - - `Optional fileData` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The base64-encoded data of the file to be sent to the model. + - `String name` - - `Optional fileId` + The name of the function to call. - The ID of the file to be sent to the model. + - `Optional parameters` - - `Optional fileUrl` + A JSON schema object describing the parameters of the function. - The URL of the file to be sent to the model. + - `Optional strict` - - `Optional filename` + Whether strict parameter validation is enforced for this function tool. - The name of the file to be sent to the model. + - `JsonValue; type "function"constant` - - `Optional promptCacheBreakpoint` + The type of the function tool. Always `function`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `FUNCTION("function")` - - `JsonValue; mode "explicit"constant` + - `Optional> allowedCallers` - The breakpoint mode. Always `explicit`. + The tool invocation context(s). - - `EXPLICIT("explicit")` + - `DIRECT("direct")` - - `JsonValue; type "function_call_output"constant` + - `PROGRAMMATIC("programmatic")` - The type of the function tool call output. Always `function_call_output`. + - `Optional deferLoading` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + Whether this function is deferred and loaded via tool search. - - `Optional id` + - `Optional description` - The unique ID of the function tool call output. Populated when this item is returned via API. + A description of the function. Used by the model to determine whether or not to call the function. - - `Optional agent` + - `Optional outputSchema` - The agent that produced this item. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `String agentName` +### Beta Inline Skill - The canonical name of the agent that produced this item. +- `class BetaInlineSkill:` - - `Optional caller` + - `String description` - The execution context that produced this tool call. + The description of the skill. - - `JsonValue;` + - `String name` - - `JsonValue; type "direct"constant` + The name of the skill. - The caller type. Always `direct`. + - `BetaInlineSkillSource source` - - `DIRECT("direct")` + Inline skill payload - - `class Program:` + - `String data` - - `String callerId` + Base64-encoded skill zip bundle. - The call ID of the program item that produced this tool call. + - `JsonValue; mediaType "application/zip"constant` - - `JsonValue; type "program"constant` + The media type of the inline skill payload. Must be `application/zip`. - The caller type. Always `program`. + - `APPLICATION_ZIP("application/zip")` - - `PROGRAM("program")` + - `JsonValue; type "base64"constant` - - `Optional status` + The type of the inline skill source. Must be `base64`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `BASE64("base64")` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "inline"constant` - - `COMPLETED("completed")` + Defines an inline skill for this request. - - `INCOMPLETE("incomplete")` + - `INLINE("inline")` - - `AgentMessage` +### Beta Inline Skill Source - - `String author` +- `class BetaInlineSkillSource:` - The sending agent identity. + Inline skill payload - - `List content` + - `String data` - Plaintext, image, or encrypted content sent between agents. + Base64-encoded skill zip bundle. - - `class BetaResponseInputTextContent:` + - `JsonValue; mediaType "application/zip"constant` - A text input to the model. + The media type of the inline skill payload. Must be `application/zip`. - - `class BetaResponseInputImageContent:` + - `APPLICATION_ZIP("application/zip")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `JsonValue; type "base64"constant` - - `class EncryptedContent:` + The type of the inline skill source. Must be `base64`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `BASE64("base64")` - - `String encryptedContent` +### Beta Local Environment - Opaque encrypted content. +- `class BetaLocalEnvironment:` - - `JsonValue; type "encrypted_content"constant` + - `JsonValue; type "local"constant` - The type of the input item. Always `encrypted_content`. + Use a local computer environment. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `LOCAL("local")` - - `String recipient` + - `Optional> skills` - The destination agent identity. + An optional list of skills. - - `JsonValue; type "agent_message"constant` + - `String description` - The item type. Always `agent_message`. + The description of the skill. - - `AGENT_MESSAGE("agent_message")` + - `String name` - - `Optional id` + The name of the skill. - The unique ID of this agent message item. + - `String path` - - `Optional agent` + The path to the directory containing the skill. - The agent that produced this item. +### Beta Local Skill - - `String agentName` +- `class BetaLocalSkill:` - The canonical name of the agent that produced this item. + - `String description` - - `MultiAgentCall` + The description of the skill. - - `Action action` + - `String name` - The multi-agent action that was executed. + The name of the skill. - - `SPAWN_AGENT("spawn_agent")` + - `String path` - - `INTERRUPT_AGENT("interrupt_agent")` + The path to the directory containing the skill. - - `LIST_AGENTS("list_agents")` +### Beta Namespace Tool - - `SEND_MESSAGE("send_message")` +- `class BetaNamespaceTool:` - - `FOLLOWUP_TASK("followup_task")` + Groups function/custom tools under a shared namespace. - - `WAIT_AGENT("wait_agent")` + - `String description` - - `String arguments` + A description of the namespace shown to the model. - The action arguments as a JSON string. + - `String name` - - `String callId` + The namespace name used in tool calls (for example, `crm`). - The unique ID linking this call to its output. + - `List tools` - - `JsonValue; type "multi_agent_call"constant` + The function/custom tools available inside this namespace. - The item type. Always `multi_agent_call`. + - `class Function:` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `String name` - - `Optional id` + - `JsonValue; type "function"constant` - The unique ID of this multi-agent call. + - `FUNCTION("function")` - - `Optional agent` + - `Optional> allowedCallers` - The agent that produced this item. + The tool invocation context(s). - - `String agentName` + - `DIRECT("direct")` - The canonical name of the agent that produced this item. + - `PROGRAMMATIC("programmatic")` - - `MultiAgentCallOutput` + - `Optional deferLoading` - - `Action action` + Whether this function should be deferred and discovered via tool search. - The multi-agent action that produced this result. + - `Optional description` - - `SPAWN_AGENT("spawn_agent")` + - `Optional outputSchema` - - `INTERRUPT_AGENT("interrupt_agent")` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `LIST_AGENTS("list_agents")` + - `Optional parameters` - - `SEND_MESSAGE("send_message")` + - `Optional strict` - - `FOLLOWUP_TASK("followup_task")` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `WAIT_AGENT("wait_agent")` + - `class BetaCustomTool:` - - `String callId` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The unique ID of the multi-agent call. + - `String name` - - `List output` + The name of the custom tool, used to identify it in tool calls. - Text output returned by the multi-agent action. + - `JsonValue; type "custom"constant` - - `String text` + The type of the custom tool. Always `custom`. - The text content. + - `CUSTOM("custom")` - - `JsonValue; type "output_text"constant` + - `Optional> allowedCallers` - The content type. Always `output_text`. + The tool invocation context(s). - - `OUTPUT_TEXT("output_text")` + - `DIRECT("direct")` - - `Optional annotations` + - `PROGRAMMATIC("programmatic")` - Citations associated with the text content. + - `Optional deferLoading` - - `List` + Whether this tool should be deferred and discovered via tool search. - - `String fileId` + - `Optional description` - The ID of the file. + Optional description of the custom tool, used to provide more context. - - `String filename` + - `Optional format` - The filename of the file cited. + The input format for the custom tool. Default is unconstrained text. - - `long index` + - `JsonValue;` - The index of the file in the list of files. + - `JsonValue; type "text"constant` - - `JsonValue; type "file_citation"constant` + Unconstrained text format. Always `text`. - The citation type. Always `file_citation`. + - `TEXT("text")` - - `FILE_CITATION("file_citation")` + - `class Grammar:` - - `List` + A grammar defined by the user. - - `long endIndex` + - `String definition` - The index of the last character of the citation in the message. + The grammar definition. - - `long startIndex` + - `Syntax syntax` - The index of the first character of the citation in the message. + The syntax of the grammar definition. One of `lark` or `regex`. - - `String title` + - `LARK("lark")` - The title of the cited resource. + - `REGEX("regex")` - - `JsonValue; type "url_citation"constant` + - `JsonValue; type "grammar"constant` - The citation type. Always `url_citation`. + Grammar format. Always `grammar`. - - `URL_CITATION("url_citation")` + - `GRAMMAR("grammar")` - - `String url` + - `JsonValue; type "namespace"constant` - The URL of the cited resource. + The type of the tool. Always `namespace`. - - `List` + - `NAMESPACE("namespace")` - - `String containerId` +### Beta Response - The ID of the container. +- `class BetaResponse:` - - `long endIndex` + - `String id` - The index of the last character of the citation in the message. + Unique identifier for this Response. - - `String fileId` + - `double createdAt` - The ID of the container file. + Unix timestamp (in seconds) of when this Response was created. - - `String filename` + - `Optional error` - The filename of the container file cited. + An error object returned when the model fails to generate a Response. - - `long startIndex` + - `Code code` - The index of the first character of the citation in the message. + The error code for the response. - - `JsonValue; type "container_file_citation"constant` + - `SERVER_ERROR("server_error")` - The citation type. Always `container_file_citation`. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `INVALID_PROMPT("invalid_prompt")` - - `JsonValue; type "multi_agent_call_output"constant` + - `BIO_POLICY("bio_policy")` - The item type. Always `multi_agent_call_output`. + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `INVALID_IMAGE("invalid_image")` - - `Optional id` + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - The unique ID of this multi-agent call output. + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - - `Optional agent` + - `INVALID_IMAGE_URL("invalid_image_url")` - The agent that produced this item. + - `IMAGE_TOO_LARGE("image_too_large")` - - `String agentName` + - `IMAGE_TOO_SMALL("image_too_small")` - The canonical name of the agent that produced this item. + - `IMAGE_PARSE_ERROR("image_parse_error")` - - `ToolSearchCall` + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - - `JsonValue arguments` + - `INVALID_IMAGE_MODE("invalid_image_mode")` - The arguments supplied to the tool search call. + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `JsonValue; type "tool_search_call"constant` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - The item type. Always `tool_search_call`. + - `EMPTY_IMAGE_FILE("empty_image_file")` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - - `Optional id` + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - The unique ID of this tool search call. + - `String message` - - `Optional agent` + A human-readable description of the error. - The agent that produced this item. + - `Optional incompleteDetails` - - `String agentName` + Details about why the response is incomplete. - The canonical name of the agent that produced this item. + - `Optional reason` - - `Optional callId` + The reason why the response is incomplete. - The unique ID of the tool search call generated by the model. + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - - `Optional execution` + - `CONTENT_FILTER("content_filter")` - Whether tool search was executed by the server or by the client. + - `Optional instructions` - - `SERVER("server")` + A system (or developer) message inserted into the model's context. - - `CLIENT("client")` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `Optional status` + - `String` - The status of the tool search call. + - `List` - - `IN_PROGRESS("in_progress")` + - `class BetaEasyInputMessage:` - - `COMPLETED("completed")` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `INCOMPLETE("incomplete")` + - `Content content` - - `class BetaResponseToolSearchOutputItemParam:` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `List tools` + - `String` - The loaded tool definitions returned by the tool search output. + - `List` - - `class BetaFunctionTool:` + - `class BetaResponseInputText:` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + A text input to the model. - - `String name` + - `String text` - The name of the function to call. + The text input to the model. - - `Optional parameters` + - `JsonValue; type "input_text"constant` - A JSON schema object describing the parameters of the function. + The type of the input item. Always `input_text`. - - `Optional strict` + - `INPUT_TEXT("input_text")` - Whether strict parameter validation is enforced for this function tool. + - `Optional promptCacheBreakpoint` - - `JsonValue; type "function"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of the function tool. Always `function`. + - `JsonValue; mode "explicit"constant` - - `FUNCTION("function")` + The breakpoint mode. Always `explicit`. - - `Optional> allowedCallers` + - `EXPLICIT("explicit")` - The tool invocation context(s). + - `class BetaResponseInputImage:` - - `DIRECT("direct")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `PROGRAMMATIC("programmatic")` + - `Detail detail` - - `Optional deferLoading` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Whether this function is deferred and loaded via tool search. + - `LOW("low")` - - `Optional description` + - `HIGH("high")` - A description of the function. Used by the model to determine whether or not to call the function. + - `AUTO("auto")` - - `Optional outputSchema` + - `ORIGINAL("original")` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `JsonValue; type "input_image"constant` - - `class BetaFileSearchTool:` + The type of the input item. Always `input_image`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `INPUT_IMAGE("input_image")` - - `JsonValue; type "file_search"constant` + - `Optional fileId` - The type of the file search tool. Always `file_search`. + The ID of the file to be sent to the model. - - `FILE_SEARCH("file_search")` + - `Optional imageUrl` - - `List vectorStoreIds` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The IDs of the vector stores to search. + - `Optional promptCacheBreakpoint` - - `Optional filters` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A filter to apply. + - `JsonValue; mode "explicit"constant` - - `class ComparisonFilter:` + The breakpoint mode. Always `explicit`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `EXPLICIT("explicit")` - - `String key` + - `class BetaResponseInputFile:` - The key to compare against the value. + A file input to the model. - - `Type type` + - `JsonValue; type "input_file"constant` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the input item. Always `input_file`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `INPUT_FILE("input_file")` - - `EQ("eq")` + - `Optional detail` - - `NE("ne")` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `GT("gt")` + - `AUTO("auto")` - - `GTE("gte")` + - `LOW("low")` - - `LT("lt")` + - `HIGH("high")` - - `LTE("lte")` + - `Optional fileData` - - `IN("in")` + The content of the file to be sent to the model. - - `NIN("nin")` + - `Optional fileId` - - `Value value` + The ID of the file to be sent to the model. - The value to compare against the attribute key; supports string, number, or boolean types. + - `Optional fileUrl` - - `String` + The URL of the file to be sent to the model. - - `double` + - `Optional filename` - - `boolean` + The name of the file to be sent to the model. - - `List` + - `Optional promptCacheBreakpoint` - - `class CompoundFilter:` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Combine multiple filters using `and` or `or`. + - `JsonValue; mode "explicit"constant` - - `List filters` + The breakpoint mode. Always `explicit`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `EXPLICIT("explicit")` - - `class ComparisonFilter:` + - `Role role` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `String key` + - `USER("user")` - The key to compare against the value. + - `ASSISTANT("assistant")` - - `Type type` + - `SYSTEM("system")` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `DEVELOPER("developer")` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `Optional phase` - - `EQ("eq")` + 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. - - `NE("ne")` + - `COMMENTARY("commentary")` - - `GT("gt")` + - `FINAL_ANSWER("final_answer")` - - `GTE("gte")` + - `Optional type` - - `LT("lt")` + The type of the message input. Always `message`. - - `LTE("lte")` + - `MESSAGE("message")` - - `IN("in")` + - `Message` - - `NIN("nin")` + - `List content` - - `Value value` + A list of one or many input items to the model, containing different content + types. - The value to compare against the attribute key; supports string, number, or boolean types. + - `class BetaResponseInputText:` - - `String` + A text input to the model. - - `double` + - `class BetaResponseInputImage:` - - `boolean` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `List` + - `class BetaResponseInputFile:` - - `JsonValue` + A file input to the model. - - `Type type` + - `Role role` - Type of operation: `and` or `or`. + The role of the message input. One of `user`, `system`, or `developer`. - - `AND("and")` + - `USER("user")` - - `OR("or")` + - `SYSTEM("system")` - - `Optional maxNumResults` + - `DEVELOPER("developer")` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `Optional agent` - - `Optional rankingOptions` + The agent that produced this item. - Ranking options for search. + - `String agentName` - - `Optional hybridSearch` + The canonical name of the agent that produced this item. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `Optional status` - - `double embeddingWeight` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The weight of the embedding in the reciprocal ranking fusion. + - `IN_PROGRESS("in_progress")` - - `double textWeight` + - `COMPLETED("completed")` - The weight of the text in the reciprocal ranking fusion. + - `INCOMPLETE("incomplete")` - - `Optional ranker` + - `Optional type` - The ranker to use for the file search. + The type of the message input. Always set to `message`. - - `AUTO("auto")` + - `MESSAGE("message")` - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `class BetaResponseOutputMessage:` - - `Optional scoreThreshold` + An output message from the model. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `String id` - - `class BetaComputerTool:` + The unique ID of the output message. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `List content` - - `JsonValue; type "computer"constant` + The content of the output message. - The type of the computer tool. Always `computer`. + - `class BetaResponseOutputText:` - - `COMPUTER("computer")` + A text output from the model. - - `class BetaComputerUsePreviewTool:` + - `List annotations` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The annotations of the text output. - - `long displayHeight` + - `class FileCitation:` - The height of the computer display. + A citation to a file. - - `long displayWidth` + - `String fileId` - The width of the computer display. + The ID of the file. - - `Environment environment` + - `String filename` - The type of computer environment to control. + The filename of the file cited. - - `WINDOWS("windows")` + - `long index` - - `MAC("mac")` + The index of the file in the list of files. - - `LINUX("linux")` + - `JsonValue; type "file_citation"constant` - - `UBUNTU("ubuntu")` + The type of the file citation. Always `file_citation`. - - `BROWSER("browser")` + - `FILE_CITATION("file_citation")` - - `JsonValue; type "computer_use_preview"constant` + - `class UrlCitation:` - The type of the computer use tool. Always `computer_use_preview`. + A citation for a web resource used to generate a model response. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `long endIndex` - - `class BetaWebSearchTool:` + The index of the last character of the URL citation in the message. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `long startIndex` - - `Type type` + The index of the first character of the URL citation in the message. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `String title` - - `WEB_SEARCH("web_search")` + The title of the web resource. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `JsonValue; type "url_citation"constant` - - `Optional filters` + The type of the URL citation. Always `url_citation`. - Filters for the search. + - `URL_CITATION("url_citation")` - - `Optional> allowedDomains` + - `String url` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The URL of the web resource. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `class ContainerFileCitation:` - - `Optional searchContextSize` + A citation for a container file used to generate a model response. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `String containerId` - - `LOW("low")` + The ID of the container file. - - `MEDIUM("medium")` + - `long endIndex` - - `HIGH("high")` + The index of the last character of the container file citation in the message. - - `Optional userLocation` + - `String fileId` - The approximate location of the user. + The ID of the file. - - `Optional city` + - `String filename` - Free text input for the city of the user, e.g. `San Francisco`. + The filename of the container file cited. - - `Optional country` + - `long startIndex` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The index of the first character of the container file citation in the message. - - `Optional region` + - `JsonValue; type "container_file_citation"constant` - Free text input for the region of the user, e.g. `California`. + The type of the container file citation. Always `container_file_citation`. - - `Optional timezone` + - `CONTAINER_FILE_CITATION("container_file_citation")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `class FilePath:` - - `Optional type` + A path to a file. - The type of location approximation. Always `approximate`. + - `String fileId` - - `APPROXIMATE("approximate")` + The ID of the file. - - `Mcp` + - `long index` - - `String serverLabel` + The index of the file in the list of files. - A label for this MCP server, used to identify it in tool calls. + - `JsonValue; type "file_path"constant` - - `JsonValue; type "mcp"constant` + The type of the file path. Always `file_path`. - The type of the MCP tool. Always `mcp`. + - `FILE_PATH("file_path")` - - `MCP("mcp")` + - `String text` - - `Optional> allowedCallers` + The text output from the model. - The tool invocation context(s). + - `JsonValue; type "output_text"constant` - - `DIRECT("direct")` + The type of the output text. Always `output_text`. - - `PROGRAMMATIC("programmatic")` + - `OUTPUT_TEXT("output_text")` - - `Optional allowedTools` + - `Optional> logprobs` - List of allowed tool names or a filter object. + - `String token` - - `List` + - `List bytes` - - `class McpToolFilter:` + - `double logprob` - A filter object to specify which tools are allowed. + - `List topLogprobs` - - `Optional readOnly` + - `String token` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `List bytes` - - `Optional> toolNames` + - `double logprob` - List of allowed tool names. + - `class BetaResponseOutputRefusal:` - - `Optional authorization` + A refusal from the model. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `String refusal` - - `Optional connectorId` + The refusal explanation from the model. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `JsonValue; type "refusal"constant` - Currently supported `connector_id` values are: + The type of the refusal. Always `refusal`. - - 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` + - `REFUSAL("refusal")` - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `JsonValue; role "assistant"constant` - - `CONNECTOR_GMAIL("connector_gmail")` + The role of the output message. Always `assistant`. - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `ASSISTANT("assistant")` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `Status status` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `IN_PROGRESS("in_progress")` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `COMPLETED("completed")` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `INCOMPLETE("incomplete")` - - `Optional deferLoading` + - `JsonValue; type "message"constant` - Whether this MCP tool is deferred and discovered via tool search. + The type of the output message. Always `message`. - - `Optional headers` + - `MESSAGE("message")` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `Optional agent` - - `Optional requireApproval` + The agent that produced this item. - Specify which of the MCP server's tools require approval. + - `String agentName` - - `class McpToolApprovalFilter:` + The canonical name of the agent that produced this item. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `Optional phase` - - `Optional always` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - A filter object to specify which tools are allowed. + - `COMMENTARY("commentary")` - - `Optional readOnly` + - `FINAL_ANSWER("final_answer")` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class BetaResponseFileSearchToolCall:` - - `Optional> toolNames` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - List of allowed tool names. + - `String id` - - `Optional never` + The unique ID of the file search tool call. - A filter object to specify which tools are allowed. + - `List queries` - - `Optional readOnly` + The queries used to search for files. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Status status` - - `Optional> toolNames` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - List of allowed tool names. + - `IN_PROGRESS("in_progress")` - - `enum McpToolApprovalSetting:` + - `SEARCHING("searching")` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `COMPLETED("completed")` - - `ALWAYS("always")` + - `INCOMPLETE("incomplete")` - - `NEVER("never")` + - `FAILED("failed")` - - `Optional serverDescription` + - `JsonValue; type "file_search_call"constant` - Optional description of the MCP server, used to provide more context. + The type of the file search tool call. Always `file_search_call`. - - `Optional serverUrl` + - `FILE_SEARCH_CALL("file_search_call")` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `Optional agent` - - `Optional tunnelId` + The agent that produced this item. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `String agentName` - - `CodeInterpreter` + The canonical name of the agent that produced this item. - - `Container container` + - `Optional> results` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The results of the file search tool call. - - `String` + - `Optional attributes` - - `class CodeInterpreterToolAuto:` + Set of 16 key-value pairs that can be attached to an object. 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. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `String` - - `JsonValue; type "auto"constant` + - `double` - Always `auto`. + - `boolean` - - `AUTO("auto")` + - `Optional fileId` - - `Optional> fileIds` + The unique ID of the file. - An optional list of uploaded files to make available to your code. + - `Optional filename` - - `Optional memoryLimit` + The name of the file. - The memory limit for the code interpreter container. + - `Optional score` - - `_1G("1g")` + The relevance score of the file - a value between 0 and 1. - - `_4G("4g")` + - `Optional text` - - `_16G("16g")` + The text that was retrieved from the file. - - `_64G("64g")` + - `class BetaResponseComputerToolCall:` - - `Optional networkPolicy` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - Network access policy for the container. + - `String id` - - `class BetaContainerNetworkPolicyDisabled:` + The unique ID of the computer call. - - `JsonValue; type "disabled"constant` + - `String callId` - Disable outbound network access. Always `disabled`. + An identifier used when responding to the tool call with output. - - `DISABLED("disabled")` + - `List pendingSafetyChecks` - - `class BetaContainerNetworkPolicyAllowlist:` + The pending safety checks for the computer call. - - `List allowedDomains` + - `String id` - A list of allowed domains when type is `allowlist`. + The ID of the pending safety check. - - `JsonValue; type "allowlist"constant` + - `Optional code` - Allow outbound network access only to specified domains. Always `allowlist`. + The type of the pending safety check. - - `ALLOWLIST("allowlist")` + - `Optional message` - - `Optional> domainSecrets` + Details about the pending safety check. - Optional domain-scoped secrets for allowlisted domains. + - `Status status` - - `String domain` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The domain associated with the secret. + - `IN_PROGRESS("in_progress")` - - `String name` + - `COMPLETED("completed")` - The name of the secret to inject for the domain. + - `INCOMPLETE("incomplete")` - - `String value` + - `Type type` - The secret value to inject for the domain. + The type of the computer call. Always `computer_call`. - - `JsonValue; type "code_interpreter"constant` + - `COMPUTER_CALL("computer_call")` - The type of the code interpreter tool. Always `code_interpreter`. + - `Optional action` - - `CODE_INTERPRETER("code_interpreter")` + A click action. - - `Optional> allowedCallers` + - `Click` - The tool invocation context(s). + - `Button button` - - `DIRECT("direct")` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `PROGRAMMATIC("programmatic")` + - `LEFT("left")` - - `JsonValue;` + - `RIGHT("right")` - - `JsonValue; type "programmatic_tool_calling"constant` + - `WHEEL("wheel")` - The type of the tool. Always `programmatic_tool_calling`. + - `BACK("back")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `FORWARD("forward")` - - `ImageGeneration` + - `JsonValue; type "click"constant` - - `JsonValue; type "image_generation"constant` + Specifies the event type. For a click action, this property is always `click`. - The type of the image generation tool. Always `image_generation`. + - `CLICK("click")` - - `IMAGE_GENERATION("image_generation")` + - `long x` - - `Optional action` + The x-coordinate where the click occurred. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `long y` - - `GENERATE("generate")` + The y-coordinate where the click occurred. - - `EDIT("edit")` + - `Optional> keys` - - `AUTO("auto")` + The keys being held while clicking. - - `Optional background` + - `DoubleClick` - 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. + - `Optional> keys` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The keys being held while double-clicking. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `JsonValue; type "double_click"constant` - - `TRANSPARENT("transparent")` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `OPAQUE("opaque")` + - `DOUBLE_CLICK("double_click")` - - `AUTO("auto")` + - `long x` - - `Optional inputFidelity` + The x-coordinate where the double click occurred. - 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`. + - `long y` - - `HIGH("high")` + The y-coordinate where the double click occurred. - - `LOW("low")` + - `Drag` - - `Optional inputImageMask` + - `List path` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `Optional fileId` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - File ID for the mask image. + - `long x` - - `Optional imageUrl` + The x-coordinate. - Base64-encoded mask image. + - `long y` - - `Optional model` + The y-coordinate. - The image generation model to use. Default: `gpt-image-1`. + - `JsonValue; type "drag"constant` - - `GPT_IMAGE_1("gpt-image-1")` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `DRAG("drag")` - - `GPT_IMAGE_2("gpt-image-2")` + - `Optional> keys` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The keys being held while dragging the mouse. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `Keypress` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `List keys` - - `Optional moderation` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Moderation level for the generated image. Default: `auto`. + - `JsonValue; type "keypress"constant` - - `AUTO("auto")` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `LOW("low")` + - `KEYPRESS("keypress")` - - `Optional outputCompression` + - `Move` - Compression level for the output image. Default: 100. + - `JsonValue; type "move"constant` - - `Optional outputFormat` + Specifies the event type. For a move action, this property is always set to `move`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `MOVE("move")` - - `PNG("png")` + - `long x` - - `WEBP("webp")` + The x-coordinate to move to. - - `JPEG("jpeg")` + - `long y` - - `Optional partialImages` + The y-coordinate to move to. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `Optional> keys` - - `Optional quality` + The keys being held while moving the mouse. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `JsonValue;` - - `LOW("low")` + - `JsonValue; type "screenshot"constant` - - `MEDIUM("medium")` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `HIGH("high")` + - `SCREENSHOT("screenshot")` - - `AUTO("auto")` + - `Scroll` - - `Optional size` + - `long scrollX` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The horizontal scroll distance. - - `_1024X1024("1024x1024")` + - `long scrollY` - - `_1024X1536("1024x1536")` + The vertical scroll distance. - - `_1536X1024("1536x1024")` + - `JsonValue; type "scroll"constant` - - `AUTO("auto")` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `JsonValue;` + - `SCROLL("scroll")` - - `JsonValue; type "local_shell"constant` + - `long x` - The type of the local shell tool. Always `local_shell`. + The x-coordinate where the scroll occurred. - - `LOCAL_SHELL("local_shell")` + - `long y` - - `class BetaFunctionShellTool:` + The y-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands. + - `Optional> keys` - - `JsonValue; type "shell"constant` + The keys being held while scrolling. - The type of the shell tool. Always `shell`. + - `Type` - - `SHELL("shell")` + - `String text` - - `Optional> allowedCallers` + The text to type. - The tool invocation context(s). + - `JsonValue; type "type"constant` - - `DIRECT("direct")` + Specifies the event type. For a type action, this property is always set to `type`. - - `PROGRAMMATIC("programmatic")` + - `TYPE("type")` - - `Optional environment` + - `JsonValue;` - - `class BetaContainerAuto:` + - `JsonValue; type "wait"constant` - - `JsonValue; type "container_auto"constant` + Specifies the event type. For a wait action, this property is always set to `wait`. - Automatically creates a container for this request + - `WAIT("wait")` - - `CONTAINER_AUTO("container_auto")` + - `Optional> actions` - - `Optional> fileIds` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - An optional list of uploaded files to make available to your code. + - `Click` - - `Optional memoryLimit` + - `DoubleClick` - The memory limit for the container. + - `Drag` - - `_1G("1g")` + - `Keypress` - - `_4G("4g")` + - `Move` - - `_16G("16g")` + - `JsonValue;` - - `_64G("64g")` + - `Scroll` - - `Optional networkPolicy` + - `Type` - Network access policy for the container. + - `JsonValue;` - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional agent` - - `class BetaContainerNetworkPolicyAllowlist:` + The agent that produced this item. - - `Optional> skills` + - `String agentName` - An optional list of skills referenced by id or inline data. + The canonical name of the agent that produced this item. - - `class BetaSkillReference:` + - `ComputerCallOutput` - - `String skillId` + - `String callId` - The ID of the referenced skill. + The ID of the computer tool call that produced the output. - - `JsonValue; type "skill_reference"constant` + - `BetaResponseComputerToolCallOutputScreenshot output` - References a skill created with the /v1/skills endpoint. + A computer screenshot image used with the computer use tool. - - `SKILL_REFERENCE("skill_reference")` + - `JsonValue; type "computer_screenshot"constant` - - `Optional version` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `class BetaInlineSkill:` + - `Optional fileId` - - `String description` + The identifier of an uploaded file that contains the screenshot. - The description of the skill. + - `Optional imageUrl` - - `String name` + The URL of the screenshot image. - The name of the skill. + - `JsonValue; type "computer_call_output"constant` - - `BetaInlineSkillSource source` + The type of the computer tool call output. Always `computer_call_output`. - Inline skill payload + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `String data` + - `Optional id` - Base64-encoded skill zip bundle. + The ID of the computer tool call output. - - `JsonValue; mediaType "application/zip"constant` + - `Optional> acknowledgedSafetyChecks` - The media type of the inline skill payload. Must be `application/zip`. + The safety checks reported by the API that have been acknowledged by the developer. - - `APPLICATION_ZIP("application/zip")` + - `String id` - - `JsonValue; type "base64"constant` + The ID of the pending safety check. - The type of the inline skill source. Must be `base64`. + - `Optional code` - - `BASE64("base64")` + The type of the pending safety check. - - `JsonValue; type "inline"constant` + - `Optional message` - Defines an inline skill for this request. + Details about the pending safety check. - - `INLINE("inline")` + - `Optional agent` - - `class BetaLocalEnvironment:` + The agent that produced this item. - - `JsonValue; type "local"constant` + - `String agentName` - Use a local computer environment. + The canonical name of the agent that produced this item. - - `LOCAL("local")` + - `Optional status` - - `Optional> skills` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - An optional list of skills. + - `IN_PROGRESS("in_progress")` - - `String description` + - `COMPLETED("completed")` - The description of the skill. + - `INCOMPLETE("incomplete")` - - `String name` + - `class BetaResponseFunctionWebSearch:` - The name of the skill. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `String path` + - `String id` - The path to the directory containing the skill. + The unique ID of the web search tool call. - - `class BetaContainerReference:` + - `Action action` - - `String containerId` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - The ID of the referenced container. + - `class Search:` - - `JsonValue; type "container_reference"constant` + Action type "search" - Performs a web search query. - References a container created with the /v1/containers endpoint + - `JsonValue; type "search"constant` - - `CONTAINER_REFERENCE("container_reference")` + The action type. - - `class BetaCustomTool:` + - `SEARCH("search")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Optional> queries` - - `String name` + The search queries. - The name of the custom tool, used to identify it in tool calls. + - `Optional query` - - `JsonValue; type "custom"constant` + The search query. - The type of the custom tool. Always `custom`. + - `Optional> sources` - - `CUSTOM("custom")` + The sources used in the search. - - `Optional> allowedCallers` + - `JsonValue; type "url"constant` - The tool invocation context(s). + The type of source. Always `url`. - - `DIRECT("direct")` + - `URL("url")` - - `PROGRAMMATIC("programmatic")` + - `String url` - - `Optional deferLoading` + The URL of the source. - Whether this tool should be deferred and discovered via tool search. + - `class OpenPage:` - - `Optional description` + Action type "open_page" - Opens a specific URL from search results. - Optional description of the custom tool, used to provide more context. + - `JsonValue; type "open_page"constant` - - `Optional format` + The action type. - The input format for the custom tool. Default is unconstrained text. + - `OPEN_PAGE("open_page")` - - `JsonValue;` + - `Optional url` - - `JsonValue; type "text"constant` + The URL opened by the model. - Unconstrained text format. Always `text`. + - `class FindInPage:` - - `TEXT("text")` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `class Grammar:` + - `String pattern` - A grammar defined by the user. + The pattern or text to search for within the page. - - `String definition` + - `JsonValue; type "find_in_page"constant` - The grammar definition. + The action type. - - `Syntax syntax` + - `FIND_IN_PAGE("find_in_page")` - The syntax of the grammar definition. One of `lark` or `regex`. + - `String url` - - `LARK("lark")` + The URL of the page searched for the pattern. - - `REGEX("regex")` + - `Status status` - - `JsonValue; type "grammar"constant` + The status of the web search tool call. - Grammar format. Always `grammar`. + - `IN_PROGRESS("in_progress")` - - `GRAMMAR("grammar")` + - `SEARCHING("searching")` - - `class BetaNamespaceTool:` + - `COMPLETED("completed")` - Groups function/custom tools under a shared namespace. + - `FAILED("failed")` - - `String description` + - `JsonValue; type "web_search_call"constant` - A description of the namespace shown to the model. + The type of the web search tool call. Always `web_search_call`. - - `String name` + - `WEB_SEARCH_CALL("web_search_call")` - The namespace name used in tool calls (for example, `crm`). + - `Optional agent` - - `List tools` + The agent that produced this item. - The function/custom tools available inside this namespace. + - `String agentName` - - `class Function:` + The canonical name of the agent that produced this item. - - `String name` + - `class BetaResponseFunctionToolCall:` - - `JsonValue; type "function"constant` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `FUNCTION("function")` + - `String arguments` - - `Optional> allowedCallers` + A JSON string of the arguments to pass to the function. - The tool invocation context(s). + - `String callId` - - `DIRECT("direct")` + The unique ID of the function tool call generated by the model. - - `PROGRAMMATIC("programmatic")` + - `String name` - - `Optional deferLoading` + The name of the function to run. - Whether this function should be deferred and discovered via tool search. + - `JsonValue; type "function_call"constant` - - `Optional description` + The type of the function tool call. Always `function_call`. - - `Optional outputSchema` + - `FUNCTION_CALL("function_call")` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `Optional id` - - `Optional parameters` + The unique ID of the function tool call. - - `Optional strict` + - `Optional agent` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The agent that produced this item. - - `class BetaCustomTool:` + - `String agentName` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The canonical name of the agent that produced this item. - - `JsonValue; type "namespace"constant` + - `Optional caller` - The type of the tool. Always `namespace`. + The execution context that produced this tool call. - - `NAMESPACE("namespace")` + - `JsonValue;` - - `class BetaToolSearchTool:` + - `JsonValue; type "direct"constant` - Hosted or BYOT tool search configuration for deferred tools. + - `DIRECT("direct")` - - `JsonValue; type "tool_search"constant` + - `class Program:` - The type of the tool. Always `tool_search`. + - `String callerId` - - `TOOL_SEARCH("tool_search")` + The call ID of the program item that produced this tool call. - - `Optional description` + - `JsonValue; type "program"constant` - Description shown to the model for a client-executed tool search tool. + - `PROGRAM("program")` - - `Optional execution` + - `Optional namespace` - Whether tool search is executed by the server or by the client. + The namespace of the function to run. - - `SERVER("server")` + - `Optional status` - - `CLIENT("client")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional parameters` + - `IN_PROGRESS("in_progress")` - Parameter schema for a client-executed tool search tool. + - `COMPLETED("completed")` - - `class BetaWebSearchPreviewTool:` + - `INCOMPLETE("incomplete")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `FunctionCallOutput` - - `Type type` + - `String callId` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The unique ID of the function tool call generated by the model. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `Output output` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + Text, image, or file output of the function tool call. - - `Optional> searchContentTypes` + - `String` - - `TEXT("text")` + - `List` - - `IMAGE("image")` + - `class BetaResponseInputTextContent:` - - `Optional searchContextSize` + A text input to the model. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `String text` - - `LOW("low")` + The text input to the model. - - `MEDIUM("medium")` + - `JsonValue; type "input_text"constant` - - `HIGH("high")` + The type of the input item. Always `input_text`. - - `Optional userLocation` + - `INPUT_TEXT("input_text")` - The user's location. + - `Optional promptCacheBreakpoint` - - `JsonValue; type "approximate"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The type of location approximation. Always `approximate`. + - `JsonValue; mode "explicit"constant` - - `APPROXIMATE("approximate")` + The breakpoint mode. Always `explicit`. - - `Optional city` + - `EXPLICIT("explicit")` - Free text input for the city of the user, e.g. `San Francisco`. + - `class BetaResponseInputImageContent:` - - `Optional country` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `JsonValue; type "input_image"constant` - - `Optional region` + The type of the input item. Always `input_image`. - Free text input for the region of the user, e.g. `California`. + - `INPUT_IMAGE("input_image")` - - `Optional timezone` + - `Optional detail` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class BetaApplyPatchTool:` + - `LOW("low")` - Allows the assistant to create, delete, or update files using unified diffs. + - `HIGH("high")` - - `JsonValue; type "apply_patch"constant` + - `AUTO("auto")` - The type of the tool. Always `apply_patch`. + - `ORIGINAL("original")` - - `APPLY_PATCH("apply_patch")` + - `Optional fileId` - - `Optional> allowedCallers` + The ID of the file to be sent to the model. - The tool invocation context(s). + - `Optional imageUrl` - - `DIRECT("direct")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `PROGRAMMATIC("programmatic")` + - `Optional promptCacheBreakpoint` - - `JsonValue; type "tool_search_output"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The item type. Always `tool_search_output`. + - `JsonValue; mode "explicit"constant` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + The breakpoint mode. Always `explicit`. - - `Optional id` + - `EXPLICIT("explicit")` - The unique ID of this tool search output. + - `class BetaResponseInputFileContent:` - - `Optional agent` + A file input to the model. - The agent that produced this item. + - `JsonValue; type "input_file"constant` - - `String agentName` + The type of the input item. Always `input_file`. - The canonical name of the agent that produced this item. + - `INPUT_FILE("input_file")` - - `Optional callId` + - `Optional detail` - The unique ID of the tool search call generated by the model. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `Optional execution` + - `AUTO("auto")` - Whether tool search was executed by the server or by the client. + - `LOW("low")` - - `SERVER("server")` + - `HIGH("high")` - - `CLIENT("client")` + - `Optional fileData` - - `Optional status` + The base64-encoded data of the file to be sent to the model. - The status of the tool search output. + - `Optional fileId` - - `IN_PROGRESS("in_progress")` + The ID of the file to be sent to the model. - - `COMPLETED("completed")` + - `Optional fileUrl` - - `INCOMPLETE("incomplete")` + The URL of the file to be sent to the model. - - `AdditionalTools` + - `Optional filename` - - `JsonValue; role "developer"constant` + The name of the file to be sent to the model. - The role that provided the additional tools. Only `developer` is supported. + - `Optional promptCacheBreakpoint` - - `DEVELOPER("developer")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `List tools` + - `JsonValue; mode "explicit"constant` - A list of additional tools made available at this item. + The breakpoint mode. Always `explicit`. - - `class BetaFunctionTool:` + - `EXPLICIT("explicit")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `JsonValue; type "function_call_output"constant` - - `class BetaFileSearchTool:` + The type of the function tool call output. Always `function_call_output`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `class BetaComputerTool:` + - `Optional id` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The unique ID of the function tool call output. Populated when this item is returned via API. - - `class BetaComputerUsePreviewTool:` + - `Optional agent` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `class BetaWebSearchTool:` + - `String agentName` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `Mcp` + - `Optional caller` - - `CodeInterpreter` + The execution context that produced this tool call. - `JsonValue;` - - `ImageGeneration` + - `JsonValue; type "direct"constant` - - `JsonValue;` + The caller type. Always `direct`. - - `class BetaFunctionShellTool:` + - `DIRECT("direct")` - A tool that allows the model to execute shell commands. + - `class Program:` - - `class BetaCustomTool:` + - `String callerId` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The call ID of the program item that produced this tool call. - - `class BetaNamespaceTool:` + - `JsonValue; type "program"constant` - Groups function/custom tools under a shared namespace. + The caller type. Always `program`. - - `class BetaToolSearchTool:` + - `PROGRAM("program")` - Hosted or BYOT tool search configuration for deferred tools. + - `Optional status` - - `class BetaWebSearchPreviewTool:` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `IN_PROGRESS("in_progress")` - - `class BetaApplyPatchTool:` + - `COMPLETED("completed")` - Allows the assistant to create, delete, or update files using unified diffs. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "additional_tools"constant` + - `AgentMessage` - The item type. Always `additional_tools`. + - `String author` - - `ADDITIONAL_TOOLS("additional_tools")` + The sending agent identity. - - `Optional id` + - `List content` - The unique ID of this additional tools item. + Plaintext, image, or encrypted content sent between agents. - - `Optional agent` + - `class BetaResponseInputTextContent:` - The agent that produced this item. + A text input to the model. - - `String agentName` + - `class BetaResponseInputImageContent:` - The canonical name of the agent that produced this item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class BetaResponseReasoningItem:` + - `class EncryptedContent:` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `String id` + - `String encryptedContent` - The unique identifier of the reasoning content. + Opaque encrypted content. - - `List summary` + - `JsonValue; type "encrypted_content"constant` - Reasoning summary content. + The type of the input item. Always `encrypted_content`. - - `String text` + - `ENCRYPTED_CONTENT("encrypted_content")` - A summary of the reasoning output from the model so far. + - `String recipient` - - `JsonValue; type "summary_text"constant` + The destination agent identity. - The type of the object. Always `summary_text`. + - `JsonValue; type "agent_message"constant` - - `SUMMARY_TEXT("summary_text")` + The item type. Always `agent_message`. - - `JsonValue; type "reasoning"constant` + - `AGENT_MESSAGE("agent_message")` - The type of the object. Always `reasoning`. + - `Optional id` - - `REASONING("reasoning")` + The unique ID of this agent message item. - `Optional agent` @@ -20504,53 +37694,41 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional> 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`. + - `MultiAgentCall` - - `REASONING_TEXT("reasoning_text")` + - `Action action` - - `Optional encryptedContent` + The multi-agent action that was executed. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `SPAWN_AGENT("spawn_agent")` - - `Optional status` + - `INTERRUPT_AGENT("interrupt_agent")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `LIST_AGENTS("list_agents")` - - `IN_PROGRESS("in_progress")` + - `SEND_MESSAGE("send_message")` - - `COMPLETED("completed")` + - `FOLLOWUP_TASK("followup_task")` - - `INCOMPLETE("incomplete")` + - `WAIT_AGENT("wait_agent")` - - `class BetaResponseCompactionItemParam:` + - `String arguments` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The action arguments as a JSON string. - - `String encryptedContent` + - `String callId` - The encrypted content of the compaction summary. + The unique ID linking this call to its output. - - `JsonValue; type "compaction"constant` + - `JsonValue; type "multi_agent_call"constant` - The type of the item. Always `compaction`. + The item type. Always `multi_agent_call`. - - `COMPACTION("compaction")` + - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional id` - The ID of the compaction item. + The unique ID of this multi-agent call. - `Optional agent` @@ -20560,110 +37738,127 @@ Create a model response The canonical name of the agent that produced this item. - - `ImageGenerationCall` + - `MultiAgentCallOutput` - - `String id` + - `Action action` - The unique ID of the image generation call. + The multi-agent action that produced this result. - - `Optional result` + - `SPAWN_AGENT("spawn_agent")` - The generated image encoded in base64. + - `INTERRUPT_AGENT("interrupt_agent")` - - `Status status` + - `LIST_AGENTS("list_agents")` - The status of the image generation call. + - `SEND_MESSAGE("send_message")` - - `IN_PROGRESS("in_progress")` + - `FOLLOWUP_TASK("followup_task")` - - `COMPLETED("completed")` + - `WAIT_AGENT("wait_agent")` - - `GENERATING("generating")` + - `String callId` - - `FAILED("failed")` + The unique ID of the multi-agent call. - - `JsonValue; type "image_generation_call"constant` + - `List output` - The type of the image generation call. Always `image_generation_call`. + Text output returned by the multi-agent action. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `String text` - - `Optional agent` + The text content. - The agent that produced this item. + - `JsonValue; type "output_text"constant` - - `String agentName` + The content type. Always `output_text`. - The canonical name of the agent that produced this item. + - `OUTPUT_TEXT("output_text")` - - `class BetaResponseCodeInterpreterToolCall:` + - `Optional annotations` - A tool call to run code. + Citations associated with the text content. - - `String id` + - `List` - The unique ID of the code interpreter tool call. + - `String fileId` - - `Optional code` + The ID of the file. - The code to run, or null if not available. + - `String filename` - - `String containerId` + The filename of the file cited. - The ID of the container used to run the code. + - `long index` - - `Optional> outputs` + The index of the file in the list of files. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `JsonValue; type "file_citation"constant` - - `class Logs:` + The citation type. Always `file_citation`. - The logs output from the code interpreter. + - `FILE_CITATION("file_citation")` - - `String logs` + - `List` - The logs output from the code interpreter. + - `long endIndex` - - `JsonValue; type "logs"constant` + The index of the last character of the citation in the message. - The type of the output. Always `logs`. + - `long startIndex` - - `LOGS("logs")` + The index of the first character of the citation in the message. - - `class Image:` + - `String title` - The image output from the code interpreter. + The title of the cited resource. - - `JsonValue; type "image"constant` + - `JsonValue; type "url_citation"constant` - The type of the output. Always `image`. + The citation type. Always `url_citation`. - - `IMAGE("image")` + - `URL_CITATION("url_citation")` - `String url` - The URL of the image output from the code interpreter. + The URL of the cited resource. - - `Status status` + - `List` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `String containerId` - - `IN_PROGRESS("in_progress")` + The ID of the container. - - `COMPLETED("completed")` + - `long endIndex` - - `INCOMPLETE("incomplete")` + The index of the last character of the citation in the message. - - `INTERPRETING("interpreting")` + - `String fileId` - - `FAILED("failed")` + The ID of the container file. - - `JsonValue; type "code_interpreter_call"constant` + - `String filename` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The filename of the container file cited. - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `long startIndex` + + The index of the first character of the citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The citation type. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. - `Optional agent` @@ -20673,49 +37868,45 @@ Create a model response The canonical name of the agent that produced this item. - - `LocalShellCall` - - - `String id` - - The unique ID of the local shell call. + - `ToolSearchCall` - - `Action action` + - `JsonValue arguments` - Execute a shell command on the server. + The arguments supplied to the tool search call. - - `List command` + - `JsonValue; type "tool_search_call"constant` - The command to run. + The item type. Always `tool_search_call`. - - `Env env` + - `TOOL_SEARCH_CALL("tool_search_call")` - Environment variables to set for the command. + - `Optional id` - - `JsonValue; type "exec"constant` + The unique ID of this tool search call. - The type of the local shell action. Always `exec`. + - `Optional agent` - - `EXEC("exec")` + The agent that produced this item. - - `Optional timeoutMs` + - `String agentName` - Optional timeout in milliseconds for the command. + The canonical name of the agent that produced this item. - - `Optional user` + - `Optional callId` - Optional user to run the command as. + The unique ID of the tool search call generated by the model. - - `Optional workingDirectory` + - `Optional execution` - Optional working directory to run the command in. + Whether tool search was executed by the server or by the client. - - `String callId` + - `SERVER("server")` - The unique ID of the local shell tool call generated by the model. + - `CLIENT("client")` - - `Status status` + - `Optional status` - The status of the local shell call. + The status of the tool search call. - `IN_PROGRESS("in_progress")` @@ -20723,1166 +37914,1218 @@ Create a model response - `INCOMPLETE("incomplete")` - - `JsonValue; type "local_shell_call"constant` - - The type of the local shell call. Always `local_shell_call`. + - `class BetaResponseToolSearchOutputItemParam:` - - `LOCAL_SHELL_CALL("local_shell_call")` + - `List tools` - - `Optional agent` + The loaded tool definitions returned by the tool search output. - The agent that produced this item. + - `class BetaFunctionTool:` - - `String agentName` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The canonical name of the agent that produced this item. + - `String name` - - `LocalShellCallOutput` + The name of the function to call. - - `String id` + - `Optional parameters` - The unique ID of the local shell tool call generated by the model. + A JSON schema object describing the parameters of the function. - - `String output` + - `Optional strict` - A JSON string of the output of the local shell tool call. + Whether strict parameter validation is enforced for this function tool. - - `JsonValue; type "local_shell_call_output"constant` + - `JsonValue; type "function"constant` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the function tool. Always `function`. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `FUNCTION("function")` - - `Optional agent` + - `Optional> allowedCallers` - The agent that produced this item. + The tool invocation context(s). - - `String agentName` + - `DIRECT("direct")` - The canonical name of the agent that produced this item. + - `PROGRAMMATIC("programmatic")` - - `Optional status` + - `Optional deferLoading` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Whether this function is deferred and loaded via tool search. - - `IN_PROGRESS("in_progress")` + - `Optional description` - - `COMPLETED("completed")` + A description of the function. Used by the model to determine whether or not to call the function. - - `INCOMPLETE("incomplete")` + - `Optional outputSchema` - - `ShellCall` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `Action action` + - `class BetaFileSearchTool:` - The shell commands and limits that describe how to run the tool call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `List commands` + - `JsonValue; type "file_search"constant` - Ordered shell commands for the execution environment to run. + The type of the file search tool. Always `file_search`. - - `Optional maxOutputLength` + - `FILE_SEARCH("file_search")` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `List vectorStoreIds` - - `Optional timeoutMs` + The IDs of the vector stores to search. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `Optional filters` - - `String callId` + A filter to apply. - The unique ID of the shell tool call generated by the model. + - `class ComparisonFilter:` - - `JsonValue; type "shell_call"constant` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the item. Always `shell_call`. + - `String key` - - `SHELL_CALL("shell_call")` + The key to compare against the value. - - `Optional id` + - `Type type` - The unique ID of the shell tool call. Populated when this item is returned via API. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `Optional agent` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The agent that produced this item. + - `EQ("eq")` - - `String agentName` + - `NE("ne")` - The canonical name of the agent that produced this item. + - `GT("gt")` - - `Optional caller` + - `GTE("gte")` - The execution context that produced this tool call. + - `LT("lt")` - - `JsonValue;` + - `LTE("lte")` - - `JsonValue; type "direct"constant` + - `IN("in")` - The caller type. Always `direct`. + - `NIN("nin")` - - `DIRECT("direct")` + - `Value value` - - `class Program:` + The value to compare against the attribute key; supports string, number, or boolean types. - - `String callerId` + - `String` - The call ID of the program item that produced this tool call. + - `double` - - `JsonValue; type "program"constant` + - `boolean` - The caller type. Always `program`. + - `List` - - `PROGRAM("program")` + - `String` - - `Optional environment` + - `double` - The environment to execute the shell commands in. + - `class CompoundFilter:` - - `class BetaLocalEnvironment:` + Combine multiple filters using `and` or `or`. - - `class BetaContainerReference:` + - `List filters` - - `Optional status` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `class ComparisonFilter:` - - `IN_PROGRESS("in_progress")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `COMPLETED("completed")` + - `String key` - - `INCOMPLETE("incomplete")` + The key to compare against the value. - - `ShellCallOutput` + - `Type type` - - `String callId` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The unique ID of the shell tool call generated by the model. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `List output` + - `EQ("eq")` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `NE("ne")` - - `Outcome outcome` + - `GT("gt")` - The exit or timeout outcome associated with this shell call. + - `GTE("gte")` - - `JsonValue;` + - `LT("lt")` - - `JsonValue; type "timeout"constant` + - `LTE("lte")` - The outcome type. Always `timeout`. + - `IN("in")` - - `TIMEOUT("timeout")` + - `NIN("nin")` - - `class Exit:` + - `Value value` - Indicates that the shell commands finished and returned an exit code. + The value to compare against the attribute key; supports string, number, or boolean types. - - `long exitCode` + - `String` - The exit code returned by the shell process. + - `double` - - `JsonValue; type "exit"constant` + - `boolean` - The outcome type. Always `exit`. + - `List` - - `EXIT("exit")` + - `String` - - `String stderr` + - `double` - Captured stderr output for the shell call. + - `JsonValue` - - `String stdout` + - `Type type` - Captured stdout output for the shell call. + Type of operation: `and` or `or`. - - `JsonValue; type "shell_call_output"constant` + - `AND("and")` - The type of the item. Always `shell_call_output`. + - `OR("or")` - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional maxNumResults` - - `Optional id` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `Optional rankingOptions` - - `Optional agent` + Ranking options for search. - The agent that produced this item. + - `Optional hybridSearch` - - `String agentName` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The canonical name of the agent that produced this item. + - `double embeddingWeight` - - `Optional caller` + The weight of the embedding in the reciprocal ranking fusion. - The execution context that produced this tool call. + - `double textWeight` - - `JsonValue;` + The weight of the text in the reciprocal ranking fusion. - - `JsonValue; type "direct"constant` + - `Optional ranker` - The caller type. Always `direct`. + The ranker to use for the file search. - - `DIRECT("direct")` + - `AUTO("auto")` - - `class Program:` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `String callerId` + - `Optional scoreThreshold` - The call ID of the program item that produced this tool call. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `JsonValue; type "program"constant` + - `class BetaComputerTool:` - The caller type. Always `program`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `PROGRAM("program")` + - `JsonValue; type "computer"constant` - - `Optional maxOutputLength` + The type of the computer tool. Always `computer`. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `COMPUTER("computer")` - - `Optional status` + - `class BetaComputerUsePreviewTool:` - The status of the shell call output. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `IN_PROGRESS("in_progress")` + - `long displayHeight` - - `COMPLETED("completed")` + The height of the computer display. - - `INCOMPLETE("incomplete")` + - `long displayWidth` - - `ApplyPatchCall` + The width of the computer display. - - `String callId` + - `Environment environment` - The unique ID of the apply patch tool call generated by the model. + The type of computer environment to control. - - `Operation operation` + - `WINDOWS("windows")` - The specific create, delete, or update instruction for the apply_patch tool call. + - `MAC("mac")` - - `class CreateFile:` + - `LINUX("linux")` - Instruction for creating a new file via the apply_patch tool. + - `UBUNTU("ubuntu")` - - `String diff` + - `BROWSER("browser")` - Unified diff content to apply when creating the file. + - `JsonValue; type "computer_use_preview"constant` - - `String path` + The type of the computer use tool. Always `computer_use_preview`. - Path of the file to create relative to the workspace root. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `JsonValue; type "create_file"constant` + - `class BetaWebSearchTool:` - The operation type. Always `create_file`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `CREATE_FILE("create_file")` + - `Type type` - - `class DeleteFile:` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Instruction for deleting an existing file via the apply_patch tool. + - `WEB_SEARCH("web_search")` - - `String path` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - Path of the file to delete relative to the workspace root. + - `Optional filters` - - `JsonValue; type "delete_file"constant` + Filters for the search. - The operation type. Always `delete_file`. + - `Optional> allowedDomains` - - `DELETE_FILE("delete_file")` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `class UpdateFile:` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Instruction for updating an existing file via the apply_patch tool. + - `Optional searchContextSize` - - `String diff` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Unified diff content to apply to the existing file. + - `LOW("low")` - - `String path` + - `MEDIUM("medium")` - Path of the file to update relative to the workspace root. + - `HIGH("high")` - - `JsonValue; type "update_file"constant` + - `Optional userLocation` - The operation type. Always `update_file`. + The approximate location of the user. - - `UPDATE_FILE("update_file")` + - `Optional city` - - `Status status` + Free text input for the city of the user, e.g. `San Francisco`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `Optional country` - - `IN_PROGRESS("in_progress")` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `COMPLETED("completed")` + - `Optional region` - - `JsonValue; type "apply_patch_call"constant` + Free text input for the region of the user, e.g. `California`. - The type of the item. Always `apply_patch_call`. + - `Optional timezone` - - `APPLY_PATCH_CALL("apply_patch_call")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Optional id` + - `Optional type` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of location approximation. Always `approximate`. - - `Optional agent` + - `APPROXIMATE("approximate")` - The agent that produced this item. + - `Mcp` - - `String agentName` + - `String serverLabel` - The canonical name of the agent that produced this item. + A label for this MCP server, used to identify it in tool calls. - - `Optional caller` + - `JsonValue; type "mcp"constant` - The execution context that produced this tool call. + The type of the MCP tool. Always `mcp`. - - `JsonValue;` + - `MCP("mcp")` - - `JsonValue; type "direct"constant` + - `Optional> allowedCallers` - The caller type. Always `direct`. + The tool invocation context(s). - `DIRECT("direct")` - - `class Program:` + - `PROGRAMMATIC("programmatic")` - - `String callerId` + - `Optional allowedTools` - The call ID of the program item that produced this tool call. + List of allowed tool names or a filter object. - - `JsonValue; type "program"constant` + - `List` - The caller type. Always `program`. + - `class McpToolFilter:` - - `PROGRAM("program")` + A filter object to specify which tools are allowed. - - `ApplyPatchCallOutput` + - `Optional readOnly` - - `String callId` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The unique ID of the apply patch tool call generated by the model. + - `Optional> toolNames` - - `Status status` + List of allowed tool names. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `Optional authorization` - - `COMPLETED("completed")` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `FAILED("failed")` + - `Optional connectorId` - - `JsonValue; type "apply_patch_call_output"constant` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The type of the item. Always `apply_patch_call_output`. + Currently supported `connector_id` values are: - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `Optional id` + - `CONNECTOR_DROPBOX("connector_dropbox")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `CONNECTOR_GMAIL("connector_gmail")` - - `Optional agent` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - The agent that produced this item. + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `String agentName` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - The canonical name of the agent that produced this item. + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `Optional caller` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - The execution context that produced this tool call. + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `JsonValue;` + - `Optional deferLoading` - - `JsonValue; type "direct"constant` + Whether this MCP tool is deferred and discovered via tool search. - The caller type. Always `direct`. + - `Optional headers` - - `DIRECT("direct")` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `class Program:` + - `Optional requireApproval` - - `String callerId` + Specify which of the MCP server's tools require approval. - The call ID of the program item that produced this tool call. + - `class McpToolApprovalFilter:` - - `JsonValue; type "program"constant` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The caller type. Always `program`. + - `Optional always` - - `PROGRAM("program")` + A filter object to specify which tools are allowed. - - `Optional output` + - `Optional readOnly` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `McpListTools` + - `Optional> toolNames` - - `String id` + List of allowed tool names. - The unique ID of the list. + - `Optional never` - - `String serverLabel` + A filter object to specify which tools are allowed. - The label of the MCP server. + - `Optional readOnly` - - `List tools` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The tools available on the server. + - `Optional> toolNames` - - `JsonValue inputSchema` + List of allowed tool names. - The JSON schema describing the tool's input. + - `enum McpToolApprovalSetting:` - - `String name` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The name of the tool. + - `ALWAYS("always")` - - `Optional annotations` + - `NEVER("never")` - Additional annotations about the tool. + - `Optional serverDescription` - - `Optional description` + Optional description of the MCP server, used to provide more context. - The description of the tool. + - `Optional serverUrl` - - `JsonValue; type "mcp_list_tools"constant` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The type of the item. Always `mcp_list_tools`. + - `Optional tunnelId` - - `MCP_LIST_TOOLS("mcp_list_tools")` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `Optional agent` + - `CodeInterpreter` - The agent that produced this item. + - `Container container` - - `String agentName` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The canonical name of the agent that produced this item. + - `String` - - `Optional error` + - `class CodeInterpreterToolAuto:` - Error message if the server could not list tools. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `McpApprovalRequest` + - `JsonValue; type "auto"constant` - - `String id` + Always `auto`. - The unique ID of the approval request. + - `AUTO("auto")` - - `String arguments` + - `Optional> fileIds` - A JSON string of arguments for the tool. + An optional list of uploaded files to make available to your code. - - `String name` + - `Optional memoryLimit` - The name of the tool to run. + The memory limit for the code interpreter container. - - `String serverLabel` + - `_1G("1g")` - The label of the MCP server making the request. + - `_4G("4g")` - - `JsonValue; type "mcp_approval_request"constant` + - `_16G("16g")` - The type of the item. Always `mcp_approval_request`. + - `_64G("64g")` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `Optional networkPolicy` - - `Optional agent` + Network access policy for the container. - The agent that produced this item. + - `class BetaContainerNetworkPolicyDisabled:` - - `String agentName` + - `JsonValue; type "disabled"constant` - The canonical name of the agent that produced this item. + Disable outbound network access. Always `disabled`. - - `McpApprovalResponse` + - `DISABLED("disabled")` - - `String approvalRequestId` + - `class BetaContainerNetworkPolicyAllowlist:` - The ID of the approval request being answered. + - `List allowedDomains` - - `boolean approve` + A list of allowed domains when type is `allowlist`. - Whether the request was approved. + - `JsonValue; type "allowlist"constant` - - `JsonValue; type "mcp_approval_response"constant` + Allow outbound network access only to specified domains. Always `allowlist`. - The type of the item. Always `mcp_approval_response`. + - `ALLOWLIST("allowlist")` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `Optional> domainSecrets` - - `Optional id` + Optional domain-scoped secrets for allowlisted domains. - The unique ID of the approval response + - `String domain` - - `Optional agent` + The domain associated with the secret. - The agent that produced this item. + - `String name` - - `String agentName` + The name of the secret to inject for the domain. - The canonical name of the agent that produced this item. + - `String value` - - `Optional reason` + The secret value to inject for the domain. - Optional reason for the decision. + - `JsonValue; type "code_interpreter"constant` - - `McpCall` + The type of the code interpreter tool. Always `code_interpreter`. - - `String id` + - `CODE_INTERPRETER("code_interpreter")` - The unique ID of the tool call. + - `Optional> allowedCallers` - - `String arguments` + The tool invocation context(s). - A JSON string of the arguments passed to the tool. + - `DIRECT("direct")` - - `String name` + - `PROGRAMMATIC("programmatic")` - The name of the tool that was run. + - `JsonValue;` - - `String serverLabel` + - `JsonValue; type "programmatic_tool_calling"constant` - The label of the MCP server running the tool. + The type of the tool. Always `programmatic_tool_calling`. - - `JsonValue; type "mcp_call"constant` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - The type of the item. Always `mcp_call`. + - `ImageGeneration` - - `MCP_CALL("mcp_call")` + - `JsonValue; type "image_generation"constant` - - `Optional agent` + The type of the image generation tool. Always `image_generation`. - The agent that produced this item. + - `IMAGE_GENERATION("image_generation")` - - `String agentName` + - `Optional action` - The canonical name of the agent that produced this item. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `Optional approvalRequestId` + - `GENERATE("generate")` - 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. + - `EDIT("edit")` - - `Optional error` + - `AUTO("auto")` - The error from the tool call, if any. + - `Optional background` - - `Optional output` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - The output from the tool call. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `Optional status` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `TRANSPARENT("transparent")` - - `IN_PROGRESS("in_progress")` + - `OPAQUE("opaque")` - - `COMPLETED("completed")` + - `AUTO("auto")` - - `INCOMPLETE("incomplete")` + - `Optional inputFidelity` - - `CALLING("calling")` + 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`. - - `FAILED("failed")` + - `HIGH("high")` - - `class BetaResponseCustomToolCallOutput:` + - `LOW("low")` - The output of a custom tool call from your code, being sent back to the model. + - `Optional inputImageMask` - - `String callId` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The call ID, used to map this custom tool call output to a custom tool call. + - `Optional fileId` - - `Output output` + File ID for the mask image. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `Optional imageUrl` - - `String` + Base64-encoded mask image. - - `List` + - `Optional model` - - `class BetaResponseInputText:` + The image generation model to use. Default: `gpt-image-1`. - A text input to the model. + - `GPT_IMAGE_1("gpt-image-1")` - - `class BetaResponseInputImage:` + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `GPT_IMAGE_2("gpt-image-2")` - - `class BetaResponseInputFile:` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - A file input to the model. + - `GPT_IMAGE_1_5("gpt-image-1.5")` - - `JsonValue; type "custom_tool_call_output"constant` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `Optional moderation` - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + Moderation level for the generated image. Default: `auto`. - - `Optional id` + - `AUTO("auto")` - The unique ID of the custom tool call output in the OpenAI platform. + - `LOW("low")` - - `Optional agent` + - `Optional outputCompression` - The agent that produced this item. + Compression level for the output image. Default: 100. - - `String agentName` + - `Optional outputFormat` - The canonical name of the agent that produced this item. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `Optional caller` + - `PNG("png")` - The execution context that produced this tool call. + - `WEBP("webp")` - - `JsonValue;` + - `JPEG("jpeg")` - - `JsonValue; type "direct"constant` + - `Optional partialImages` - The caller type. Always `direct`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `DIRECT("direct")` + - `Optional quality` - - `class Program:` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `String callerId` + - `LOW("low")` - The call ID of the program item that produced this tool call. + - `MEDIUM("medium")` - - `JsonValue; type "program"constant` + - `HIGH("high")` - The caller type. Always `program`. + - `AUTO("auto")` - - `PROGRAM("program")` + - `Optional size` - - `class BetaResponseCustomToolCall:` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - A call to a custom tool created by the model. + - `_1024X1024("1024x1024")` - - `String callId` + - `_1024X1536("1024x1536")` - An identifier used to map this custom tool call to a tool call output. + - `_1536X1024("1536x1024")` - - `String input` + - `AUTO("auto")` - The input for the custom tool call generated by the model. + - `JsonValue;` - - `String name` + - `JsonValue; type "local_shell"constant` - The name of the custom tool being called. + The type of the local shell tool. Always `local_shell`. - - `JsonValue; type "custom_tool_call"constant` + - `LOCAL_SHELL("local_shell")` - The type of the custom tool call. Always `custom_tool_call`. + - `class BetaFunctionShellTool:` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + A tool that allows the model to execute shell commands. - - `Optional id` + - `JsonValue; type "shell"constant` - The unique ID of the custom tool call in the OpenAI platform. + The type of the shell tool. Always `shell`. - - `Optional agent` + - `SHELL("shell")` - The agent that produced this item. + - `Optional> allowedCallers` - - `String agentName` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `DIRECT("direct")` - - `Optional caller` + - `PROGRAMMATIC("programmatic")` - The execution context that produced this tool call. + - `Optional environment` - - `JsonValue;` + - `class BetaContainerAuto:` - - `JsonValue; type "direct"constant` + - `JsonValue; type "container_auto"constant` - - `DIRECT("direct")` + Automatically creates a container for this request - - `class Program:` + - `CONTAINER_AUTO("container_auto")` - - `String callerId` + - `Optional> fileIds` - The call ID of the program item that produced this tool call. + An optional list of uploaded files to make available to your code. - - `JsonValue; type "program"constant` + - `Optional memoryLimit` - - `PROGRAM("program")` + The memory limit for the container. - - `Optional namespace` + - `_1G("1g")` - The namespace of the custom tool being called. + - `_4G("4g")` - - `CompactionTrigger` + - `_16G("16g")` - - `JsonValue; type "compaction_trigger"constant` + - `_64G("64g")` - The type of the item. Always `compaction_trigger`. + - `Optional networkPolicy` - - `COMPACTION_TRIGGER("compaction_trigger")` + Network access policy for the container. - - `Optional agent` + - `class BetaContainerNetworkPolicyDisabled:` - The agent that produced this item. + - `class BetaContainerNetworkPolicyAllowlist:` - - `String agentName` + - `Optional> skills` - The canonical name of the agent that produced this item. + An optional list of skills referenced by id or inline data. - - `ItemReference` + - `class BetaSkillReference:` - - `String id` + - `String skillId` - The ID of the item to reference. + The ID of the referenced skill. - - `Optional agent` + - `JsonValue; type "skill_reference"constant` - The agent that produced this item. + References a skill created with the /v1/skills endpoint. - - `String agentName` + - `SKILL_REFERENCE("skill_reference")` - The canonical name of the agent that produced this item. + - `Optional version` - - `Optional type` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The type of item to reference. Always `item_reference`. + - `class BetaInlineSkill:` + + - `String description` + + The description of the skill. + + - `String name` + + The name of the skill. + + - `BetaInlineSkillSource source` + + Inline skill payload + + - `String data` - - `ITEM_REFERENCE("item_reference")` + Base64-encoded skill zip bundle. - - `Program` + - `JsonValue; mediaType "application/zip"constant` - - `String id` + The media type of the inline skill payload. Must be `application/zip`. - The unique ID of this program item. + - `APPLICATION_ZIP("application/zip")` - - `String callId` + - `JsonValue; type "base64"constant` - The stable call ID of the program item. + The type of the inline skill source. Must be `base64`. - - `String code` + - `BASE64("base64")` - The JavaScript source executed by programmatic tool calling. + - `JsonValue; type "inline"constant` - - `String fingerprint` + Defines an inline skill for this request. - Opaque program replay fingerprint that must be round-tripped. + - `INLINE("inline")` - - `JsonValue; type "program"constant` + - `class BetaLocalEnvironment:` - The item type. Always `program`. + - `JsonValue; type "local"constant` - - `PROGRAM("program")` + Use a local computer environment. - - `Optional agent` + - `LOCAL("local")` - The agent that produced this item. + - `Optional> skills` - - `String agentName` + An optional list of skills. - The canonical name of the agent that produced this item. + - `String description` - - `ProgramOutput` + The description of the skill. - - `String id` + - `String name` - The unique ID of this program output item. + The name of the skill. - - `String callId` + - `String path` - The call ID of the program item. + The path to the directory containing the skill. - - `String result` + - `class BetaContainerReference:` - The result produced by the program item. + - `String containerId` - - `Status status` + The ID of the referenced container. - The terminal status of the program output. + - `JsonValue; type "container_reference"constant` - - `COMPLETED("completed")` + References a container created with the /v1/containers endpoint - - `INCOMPLETE("incomplete")` + - `CONTAINER_REFERENCE("container_reference")` - - `JsonValue; type "program_output"constant` + - `class BetaCustomTool:` - The item type. Always `program_output`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `PROGRAM_OUTPUT("program_output")` + - `String name` - - `Optional agent` + The name of the custom tool, used to identify it in tool calls. - The agent that produced this item. + - `JsonValue; type "custom"constant` - - `String agentName` + The type of the custom tool. Always `custom`. - The canonical name of the agent that produced this item. + - `CUSTOM("custom")` - - `Optional metadata` + - `Optional> allowedCallers` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The tool invocation context(s). - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `DIRECT("direct")` - - `Model model` + - `PROGRAMMATIC("programmatic")` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `Optional deferLoading` - - `GPT_5_6_SOL("gpt-5.6-sol")` + Whether this tool should be deferred and discovered via tool search. - - `GPT_5_6_TERRA("gpt-5.6-terra")` + - `Optional description` - - `GPT_5_6_LUNA("gpt-5.6-luna")` + Optional description of the custom tool, used to provide more context. - - `GPT_5_4("gpt-5.4")` + - `Optional format` - - `GPT_5_4_MINI("gpt-5.4-mini")` + The input format for the custom tool. Default is unconstrained text. - - `GPT_5_4_NANO("gpt-5.4-nano")` + - `JsonValue;` - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `JsonValue; type "text"constant` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + Unconstrained text format. Always `text`. - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `TEXT("text")` - - `GPT_5_2("gpt-5.2")` + - `class Grammar:` - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + A grammar defined by the user. - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + - `String definition` - - `GPT_5_2_PRO("gpt-5.2-pro")` + The grammar definition. - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + - `Syntax syntax` - - `GPT_5_1("gpt-5.1")` + The syntax of the grammar definition. One of `lark` or `regex`. - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `LARK("lark")` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + - `REGEX("regex")` - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `JsonValue; type "grammar"constant` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + Grammar format. Always `grammar`. - - `GPT_5("gpt-5")` + - `GRAMMAR("grammar")` - - `GPT_5_MINI("gpt-5-mini")` + - `class BetaNamespaceTool:` - - `GPT_5_NANO("gpt-5-nano")` + Groups function/custom tools under a shared namespace. - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + - `String description` - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + A description of the namespace shown to the model. - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `String name` - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + The namespace name used in tool calls (for example, `crm`). - - `GPT_4_1("gpt-4.1")` + - `List tools` - - `GPT_4_1_MINI("gpt-4.1-mini")` + The function/custom tools available inside this namespace. - - `GPT_4_1_NANO("gpt-4.1-nano")` + - `class Function:` - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `String name` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + - `JsonValue; type "function"constant` - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + - `FUNCTION("function")` - - `O4_MINI("o4-mini")` + - `Optional> allowedCallers` - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + The tool invocation context(s). - - `O3("o3")` + - `DIRECT("direct")` - - `O3_2025_04_16("o3-2025-04-16")` + - `PROGRAMMATIC("programmatic")` - - `O3_MINI("o3-mini")` + - `Optional deferLoading` - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + Whether this function should be deferred and discovered via tool search. - - `O1("o1")` + - `Optional description` - - `O1_2024_12_17("o1-2024-12-17")` + - `Optional outputSchema` - - `O1_PREVIEW("o1-preview")` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + - `Optional parameters` - - `O1_MINI("o1-mini")` + - `Optional strict` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `GPT_4O("gpt-4o")` + - `class BetaCustomTool:` - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + - `JsonValue; type "namespace"constant` - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + The type of the tool. Always `namespace`. - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + - `NAMESPACE("namespace")` - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + - `class BetaToolSearchTool:` - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + Hosted or BYOT tool search configuration for deferred tools. - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + - `JsonValue; type "tool_search"constant` - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + The type of the tool. Always `tool_search`. - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + - `TOOL_SEARCH("tool_search")` - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + - `Optional description` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + Description shown to the model for a client-executed tool search tool. - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `Optional execution` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + Whether tool search is executed by the server or by the client. - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `SERVER("server")` - - `CODEX_MINI_LATEST("codex-mini-latest")` + - `CLIENT("client")` - - `GPT_4O_MINI("gpt-4o-mini")` + - `Optional parameters` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + Parameter schema for a client-executed tool search tool. - - `GPT_4_TURBO("gpt-4-turbo")` + - `class BetaWebSearchPreviewTool:` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + - `Type type` - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `GPT_4("gpt-4")` + - `Optional> searchContentTypes` - - `GPT_4_0314("gpt-4-0314")` + - `TEXT("text")` - - `GPT_4_0613("gpt-4-0613")` + - `IMAGE("image")` - - `GPT_4_32K("gpt-4-32k")` + - `Optional searchContextSize` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `LOW("low")` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `MEDIUM("medium")` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `HIGH("high")` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `Optional userLocation` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + The user's location. - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `JsonValue; type "approximate"constant` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + The type of location approximation. Always `approximate`. - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + - `APPROXIMATE("approximate")` - - `O1_PRO("o1-pro")` + - `Optional city` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + Free text input for the city of the user, e.g. `San Francisco`. - - `O3_PRO("o3-pro")` + - `Optional country` - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `Optional region` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + Free text input for the region of the user, e.g. `California`. - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + - `Optional timezone` - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `class BetaApplyPatchTool:` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + Allows the assistant to create, delete, or update files using unified diffs. - - `GPT_5_CODEX("gpt-5-codex")` + - `JsonValue; type "apply_patch"constant` - - `GPT_5_PRO("gpt-5-pro")` + The type of the tool. Always `apply_patch`. - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `APPLY_PATCH("apply_patch")` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + - `Optional> allowedCallers` - - `JsonValue; object_ "response"constant` + The tool invocation context(s). - The object type of this resource - always set to `response`. + - `DIRECT("direct")` - - `RESPONSE("response")` + - `PROGRAMMATIC("programmatic")` - - `List output` + - `JsonValue; type "tool_search_output"constant` - An array of content items generated by the model. + The item type. Always `tool_search_output`. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `class BetaResponseOutputMessage:` + - `Optional id` - An output message from the model. + The unique ID of this tool search output. - - `class BetaResponseFileSearchToolCall:` + - `Optional agent` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The agent that produced this item. - - `class BetaResponseFunctionToolCall:` + - `String agentName` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCallOutputItem:` + - `Optional callId` - - `String id` + The unique ID of the tool search call generated by the model. - The unique ID of the function call tool output. + - `Optional execution` - - `String callId` + Whether tool search was executed by the server or by the client. - The unique ID of the function tool call generated by the model. + - `SERVER("server")` - - `Output output` + - `CLIENT("client")` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `Optional status` - - `String` + The status of the tool search output. - - `List` + - `IN_PROGRESS("in_progress")` - - `class BetaResponseInputText:` + - `COMPLETED("completed")` - A text input to the model. + - `INCOMPLETE("incomplete")` - - `class BetaResponseInputImage:` + - `AdditionalTools` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `JsonValue; role "developer"constant` - - `class BetaResponseInputFile:` + The role that provided the additional tools. Only `developer` is supported. - A file input to the model. + - `DEVELOPER("developer")` - - `Status status` + - `List tools` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A list of additional tools made available at this item. - - `IN_PROGRESS("in_progress")` + - `class BetaFunctionTool:` - - `COMPLETED("completed")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `INCOMPLETE("incomplete")` + - `class BetaFileSearchTool:` - - `JsonValue; type "function_call_output"constant` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The type of the function tool call output. Always `function_call_output`. + - `class BetaComputerTool:` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional agent` + - `class BetaComputerUsePreviewTool:` - The agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String agentName` + - `class BetaWebSearchTool:` - The canonical name of the agent that produced this item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional caller` + - `Mcp` - The execution context that produced this tool call. + - `CodeInterpreter` - `JsonValue;` - - `JsonValue; type "direct"constant` + - `ImageGeneration` - The caller type. Always `direct`. + - `JsonValue;` - - `DIRECT("direct")` + - `class BetaFunctionShellTool:` - - `class Program:` + A tool that allows the model to execute shell commands. - - `String callerId` + - `class BetaCustomTool:` - The call ID of the program item that produced this tool call. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `JsonValue; type "program"constant` + - `class BetaNamespaceTool:` - The caller type. Always `program`. + Groups function/custom tools under a shared namespace. - - `PROGRAM("program")` + - `class BetaToolSearchTool:` - - `Optional createdBy` + Hosted or BYOT tool search configuration for deferred tools. - The identifier of the actor that created the item. + - `class BetaWebSearchPreviewTool:` - - `AgentMessage` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String id` + - `class BetaApplyPatchTool:` - The unique ID of the agent message. + Allows the assistant to create, delete, or update files using unified diffs. - - `String author` + - `JsonValue; type "additional_tools"constant` - The sending agent identity. + The item type. Always `additional_tools`. - - `List content` + - `ADDITIONAL_TOOLS("additional_tools")` - Encrypted content sent between agents. + - `Optional id` - - `class BetaResponseInputText:` + The unique ID of this additional tools item. - A text input to the model. + - `Optional agent` - - `class BetaResponseOutputText:` + The agent that produced this item. - A text output from the model. + - `String agentName` - - `class Text:` + The canonical name of the agent that produced this item. - A text content. + - `class BetaResponseReasoningItem:` - - `String text` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `JsonValue; type "text"constant` + - `String id` - - `TEXT("text")` + The unique identifier of the reasoning content. - - `class SummaryText:` + - `List summary` - A summary text from the model. + Reasoning summary content. - `String text` @@ -21894,9 +39137,23 @@ Create a model response - `SUMMARY_TEXT("summary_text")` - - `class ReasoningText:` + - `JsonValue; type "reasoning"constant` - Reasoning text from the model. + The type of the object. Always `reasoning`. + + - `REASONING("reasoning")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> content` + + Reasoning text content. - `String text` @@ -21908,81 +39165,75 @@ Create a model response - `REASONING_TEXT("reasoning_text")` - - `class BetaResponseOutputRefusal:` - - A refusal from the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ComputerScreenshot:` + - `Optional encryptedContent` - A screenshot of a computer. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `Detail detail` + - `Optional status` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `LOW("low")` + - `IN_PROGRESS("in_progress")` - - `HIGH("high")` + - `COMPLETED("completed")` - - `AUTO("auto")` + - `INCOMPLETE("incomplete")` - - `ORIGINAL("original")` + - `class BetaResponseCompactionItemParam:` - - `Optional fileId` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The identifier of an uploaded file that contains the screenshot. + - `String encryptedContent` - - `Optional imageUrl` + The encrypted content of the compaction summary. - The URL of the screenshot image. + - `JsonValue; type "compaction"constant` - - `JsonValue; type "computer_screenshot"constant` + The type of the item. Always `compaction`. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `COMPACTION("compaction")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `Optional id` - - `Optional promptCacheBreakpoint` + The ID of the compaction item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional agent` - - `JsonValue; mode "explicit"constant` + The agent that produced this item. - The breakpoint mode. Always `explicit`. + - `String agentName` - - `EXPLICIT("explicit")` + The canonical name of the agent that produced this item. - - `class BetaResponseInputFile:` + - `ImageGenerationCall` - A file input to the model. + - `String id` - - `class EncryptedContent:` + The unique ID of the image generation call. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `Optional result` - - `String encryptedContent` + The generated image encoded in base64. - Opaque encrypted content. + - `Status status` - - `JsonValue; type "encrypted_content"constant` + The status of the image generation call. - The type of the input item. Always `encrypted_content`. + - `IN_PROGRESS("in_progress")` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `COMPLETED("completed")` - - `String recipient` + - `GENERATING("generating")` - The destination agent identity. + - `FAILED("failed")` - - `JsonValue; type "agent_message"constant` + - `JsonValue; type "image_generation_call"constant` - The type of the item. Always `agent_message`. + The type of the image generation call. Always `image_generation_call`. - - `AGENT_MESSAGE("agent_message")` + - `IMAGE_GENERATION_CALL("image_generation_call")` - `Optional agent` @@ -21992,167 +39243,162 @@ Create a model response The canonical name of the agent that produced this item. - - `MultiAgentCall` - - - `String id` - - The unique ID of the multi-agent call item. + - `class BetaResponseCodeInterpreterToolCall:` - - `Action action` + A tool call to run code. - The multi-agent action to execute. + - `String id` - - `SPAWN_AGENT("spawn_agent")` + The unique ID of the code interpreter tool call. - - `INTERRUPT_AGENT("interrupt_agent")` + - `Optional code` - - `LIST_AGENTS("list_agents")` + The code to run, or null if not available. - - `SEND_MESSAGE("send_message")` + - `String containerId` - - `FOLLOWUP_TASK("followup_task")` + The ID of the container used to run the code. - - `WAIT_AGENT("wait_agent")` + - `Optional> outputs` - - `String arguments` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The JSON string of arguments generated for the action. + - `class Logs:` - - `String callId` + The logs output from the code interpreter. - The unique ID linking this call to its output. + - `String logs` - - `JsonValue; type "multi_agent_call"constant` + The logs output from the code interpreter. - The type of the multi-agent call. Always `multi_agent_call`. + - `JsonValue; type "logs"constant` - - `MULTI_AGENT_CALL("multi_agent_call")` + The type of the output. Always `logs`. - - `Optional agent` + - `LOGS("logs")` - The agent that produced this item. + - `class Image:` - - `String agentName` + The image output from the code interpreter. - The canonical name of the agent that produced this item. + - `JsonValue; type "image"constant` - - `MultiAgentCallOutput` + The type of the output. Always `image`. - - `String id` + - `IMAGE("image")` - The unique ID of the multi-agent call output item. + - `String url` - - `Action action` + The URL of the image output from the code interpreter. - The multi-agent action that produced this result. + - `Status status` - - `SPAWN_AGENT("spawn_agent")` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `INTERRUPT_AGENT("interrupt_agent")` + - `IN_PROGRESS("in_progress")` - - `LIST_AGENTS("list_agents")` + - `COMPLETED("completed")` - - `SEND_MESSAGE("send_message")` + - `INCOMPLETE("incomplete")` - - `FOLLOWUP_TASK("followup_task")` + - `INTERPRETING("interpreting")` - - `WAIT_AGENT("wait_agent")` + - `FAILED("failed")` - - `String callId` + - `JsonValue; type "code_interpreter_call"constant` - The unique ID of the multi-agent call. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `List output` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - Text output returned by the multi-agent action. + - `Optional agent` - - `List annotations` + The agent that produced this item. - The annotations of the text output. + - `String agentName` - - `String text` + The canonical name of the agent that produced this item. - The text output from the model. + - `LocalShellCall` - - `JsonValue; type "output_text"constant` + - `String id` - The type of the output text. Always `output_text`. + The unique ID of the local shell call. - - `Optional> logprobs` + - `Action action` - - `JsonValue; type "multi_agent_call_output"constant` + Execute a shell command on the server. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `List command` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + The command to run. - - `Optional agent` + - `Env env` - The agent that produced this item. + Environment variables to set for the command. - - `String agentName` + - `JsonValue; type "exec"constant` - The canonical name of the agent that produced this item. + The type of the local shell action. Always `exec`. - - `class BetaResponseFunctionWebSearch:` + - `EXEC("exec")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Optional timeoutMs` - - `class BetaResponseComputerToolCall:` + Optional timeout in milliseconds for the command. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `Optional user` - - `class BetaResponseComputerToolCallOutputItem:` + Optional user to run the command as. - - `String id` + - `Optional workingDirectory` - The unique ID of the computer call tool output. + Optional working directory to run the command in. - `String callId` - The ID of the computer tool call that produced the output. - - - `BetaResponseComputerToolCallOutputScreenshot output` - - A computer screenshot image used with the computer use tool. + The unique ID of the local shell tool call generated by the model. - `Status status` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The status of the local shell call. + + - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `FAILED("failed")` + - `JsonValue; type "local_shell_call"constant` - - `IN_PROGRESS("in_progress")` + The type of the local shell call. Always `local_shell_call`. - - `JsonValue; type "computer_call_output"constant` + - `LOCAL_SHELL_CALL("local_shell_call")` - The type of the computer tool call output. Always `computer_call_output`. + - `Optional agent` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The agent that produced this item. - - `Optional> acknowledgedSafetyChecks` + - `String agentName` - The safety checks reported by the API that have been acknowledged by the - developer. + The canonical name of the agent that produced this item. + + - `LocalShellCallOutput` - `String id` - The ID of the pending safety check. + The unique ID of the local shell tool call generated by the model. - - `Optional code` + - `String output` - The type of the pending safety check. + A JSON string of the output of the local shell tool call. - - `Optional message` + - `JsonValue; type "local_shell_call_output"constant` - Details about the pending safety check. + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - `Optional agent` @@ -22162,40 +39408,47 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional status` - The identifier of the actor that created the item. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `class BetaResponseReasoningItem:` + - `IN_PROGRESS("in_progress")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `COMPLETED("completed")` - - `Program` + - `INCOMPLETE("incomplete")` - - `String id` + - `ShellCall` - The unique ID of the program item. + - `Action action` - - `String callId` + The shell commands and limits that describe how to run the tool call. - The stable call ID of the program item. + - `List commands` - - `String code` + Ordered shell commands for the execution environment to run. - The JavaScript source executed by programmatic tool calling. + - `Optional maxOutputLength` - - `String fingerprint` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Opaque program replay fingerprint that must be round-tripped. + - `Optional timeoutMs` - - `JsonValue; type "program"constant` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The type of the item. Always `program`. + - `String callId` - - `PROGRAM("program")` + 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 id` + + The unique ID of the shell tool call. Populated when this item is returned via API. - `Optional agent` @@ -22205,79 +39458,101 @@ Create a model response The canonical name of the agent that produced this item. - - `ProgramOutput` + - `Optional caller` - - `String id` + The execution context that produced this tool call. - The unique ID of the program output item. + - `JsonValue;` - - `String callId` + - `JsonValue; type "direct"constant` - The call ID of the program item. + The caller type. Always `direct`. - - `String result` + - `DIRECT("direct")` - The result produced by the program item. + - `class Program:` - - `Status status` + - `String callerId` - The terminal status of the program output item. + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional environment` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment:` + + - `class BetaContainerReference:` + + - `Optional status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `JsonValue; type "program_output"constant` + - `ShellCallOutput` - The type of the item. Always `program_output`. + - `String callId` - - `PROGRAM_OUTPUT("program_output")` + The unique ID of the shell tool call generated by the model. - - `Optional agent` + - `List output` - The agent that produced this item. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `String agentName` + - `Outcome outcome` - The canonical name of the agent that produced this item. + The exit or timeout outcome associated with this shell call. - - `class BetaResponseToolSearchCall:` + - `JsonValue;` - - `String id` + - `JsonValue; type "timeout"constant` - The unique ID of the tool search call item. + The outcome type. Always `timeout`. - - `JsonValue arguments` + - `TIMEOUT("timeout")` - Arguments used for the tool search call. + - `class Exit:` - - `Optional callId` + Indicates that the shell commands finished and returned an exit code. - The unique ID of the tool search call generated by the model. + - `long exitCode` - - `Execution execution` + The exit code returned by the shell process. - Whether tool search was executed by the server or by the client. + - `JsonValue; type "exit"constant` - - `SERVER("server")` + The outcome type. Always `exit`. - - `CLIENT("client")` + - `EXIT("exit")` - - `Status status` + - `String stderr` - The status of the tool search call item that was recorded. + Captured stderr output for the shell call. - - `IN_PROGRESS("in_progress")` + - `String stdout` - - `COMPLETED("completed")` + Captured stdout output for the shell call. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "shell_call_output"constant` - - `JsonValue; type "tool_search_call"constant` + The type of the item. Always `shell_call_output`. - The type of the item. Always `tool_search_call`. + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `Optional id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. - `Optional agent` @@ -22287,31 +39562,37 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional caller` - The identifier of the actor that created the item. + The execution context that produced this tool call. - - `class BetaResponseToolSearchOutputItem:` + - `JsonValue;` - - `String id` + - `JsonValue; type "direct"constant` - The unique ID of the tool search output item. + The caller type. Always `direct`. - - `Optional callId` + - `DIRECT("direct")` - The unique ID of the tool search call generated by the model. + - `class Program:` - - `Execution execution` + - `String callerId` - Whether tool search was executed by the server or by the client. + The call ID of the program item that produced this tool call. - - `SERVER("server")` + - `JsonValue; type "program"constant` - - `CLIENT("client")` + The caller type. Always `program`. - - `Status status` + - `PROGRAM("program")` - The status of the tool search output item that was recorded. + - `Optional maxOutputLength` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `Optional status` + + The status of the shell call output. - `IN_PROGRESS("in_progress")` @@ -22319,70 +39600,83 @@ Create a model response - `INCOMPLETE("incomplete")` - - `List tools` + - `ApplyPatchCall` - The loaded tool definitions returned by tool search. + - `String callId` - - `class BetaFunctionTool:` + The unique ID of the apply patch tool call generated by the model. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Operation operation` - - `class BetaFileSearchTool:` + The specific create, delete, or update instruction for the apply_patch tool call. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class CreateFile:` - - `class BetaComputerTool:` + Instruction for creating a new file via the apply_patch tool. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String diff` - - `class BetaComputerUsePreviewTool:` + Unified diff content to apply when creating the file. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String path` - - `class BetaWebSearchTool:` + Path of the file to create relative to the workspace root. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "create_file"constant` - - `Mcp` + The operation type. Always `create_file`. - - `CodeInterpreter` + - `CREATE_FILE("create_file")` - - `JsonValue;` + - `class DeleteFile:` - - `ImageGeneration` + Instruction for deleting an existing file via the apply_patch tool. - - `JsonValue;` + - `String path` - - `class BetaFunctionShellTool:` + Path of the file to delete relative to the workspace root. - A tool that allows the model to execute shell commands. + - `JsonValue; type "delete_file"constant` - - `class BetaCustomTool:` + The operation type. Always `delete_file`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `DELETE_FILE("delete_file")` - - `class BetaNamespaceTool:` + - `class UpdateFile:` - Groups function/custom tools under a shared namespace. + Instruction for updating an existing file via the apply_patch tool. - - `class BetaToolSearchTool:` + - `String diff` - Hosted or BYOT tool search configuration for deferred tools. + Unified diff content to apply to the existing file. - - `class BetaWebSearchPreviewTool:` + - `String path` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Path of the file to update relative to the workspace root. - - `class BetaApplyPatchTool:` + - `JsonValue; type "update_file"constant` - Allows the assistant to create, delete, or update files using unified diffs. + The operation type. Always `update_file`. - - `JsonValue; type "tool_search_output"constant` + - `UPDATE_FILE("update_file")` - The type of the item. Always `tool_search_output`. + - `Status status` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + 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 id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `Optional agent` @@ -22392,100 +39686,125 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional caller` - The identifier of the actor that created the item. + The execution context that produced this tool call. - - `AdditionalTools` + - `JsonValue;` - - `String id` + - `JsonValue; type "direct"constant` - The unique ID of the additional tools item. + The caller type. Always `direct`. - - `Role role` + - `DIRECT("direct")` - The role that provided the additional tools. + - `class Program:` - - `UNKNOWN("unknown")` + - `String callerId` - - `USER("user")` + The call ID of the program item that produced this tool call. - - `ASSISTANT("assistant")` + - `JsonValue; type "program"constant` - - `SYSTEM("system")` + The caller type. Always `program`. - - `CRITIC("critic")` + - `PROGRAM("program")` - - `DISCRIMINATOR("discriminator")` + - `ApplyPatchCallOutput` - - `DEVELOPER("developer")` + - `String callId` - - `TOOL("tool")` + The unique ID of the apply patch tool call generated by the model. - - `List tools` + - `Status status` - The additional tool definitions made available at this item. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `class BetaFunctionTool:` + - `COMPLETED("completed")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `FAILED("failed")` - - `class BetaFileSearchTool:` + - `JsonValue; type "apply_patch_call_output"constant` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The type of the item. Always `apply_patch_call_output`. - - `class BetaComputerTool:` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional id` - - `class BetaComputerUsePreviewTool:` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional agent` - - `class BetaWebSearchTool:` + The agent that produced this item. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String agentName` - - `Mcp` + The canonical name of the agent that produced this item. - - `CodeInterpreter` + - `Optional caller` + + The execution context that produced this tool call. - `JsonValue;` - - `ImageGeneration` + - `JsonValue; type "direct"constant` - - `JsonValue;` + The caller type. Always `direct`. - - `class BetaFunctionShellTool:` + - `DIRECT("direct")` - A tool that allows the model to execute shell commands. + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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. - - `class BetaCustomTool:` + - `List tools` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The tools available on the server. - - `class BetaNamespaceTool:` + - `JsonValue inputSchema` - Groups function/custom tools under a shared namespace. + The JSON schema describing the tool's input. - - `class BetaToolSearchTool:` + - `String name` - Hosted or BYOT tool search configuration for deferred tools. + The name of the tool. - - `class BetaWebSearchPreviewTool:` + - `Optional annotations` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Additional annotations about the tool. - - `class BetaApplyPatchTool:` + - `Optional description` - Allows the assistant to create, delete, or update files using unified diffs. + The description of the tool. - - `JsonValue; type "additional_tools"constant` + - `JsonValue; type "mcp_list_tools"constant` - The type of the item. Always `additional_tools`. + The type of the item. Always `mcp_list_tools`. - - `ADDITIONAL_TOOLS("additional_tools")` + - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` @@ -22495,63 +39814,61 @@ Create a model response The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `Optional error` - - `String id` + Error message if the server could not list tools. - The unique ID of the compaction item. + - `McpApprovalRequest` - - `String encryptedContent` + - `String id` - The encrypted content that was produced by compaction. + The unique ID of the approval request. - - `JsonValue; type "compaction"constant` + - `String arguments` - The type of the item. Always `compaction`. + A JSON string of arguments for the tool. - - `COMPACTION("compaction")` + - `String name` - - `Optional agent` + The name of the tool to run. - The agent that produced this item. + - `String serverLabel` - - `String agentName` + The label of the MCP server making the request. - The canonical name of the agent that produced this item. + - `JsonValue; type "mcp_approval_request"constant` - - `Optional createdBy` + The type of the item. Always `mcp_approval_request`. - The identifier of the actor that created the item. + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `ImageGenerationCall` + - `Optional agent` - - `String id` + The agent that produced this item. - The unique ID of the image generation call. + - `String agentName` - - `Optional result` + The canonical name of the agent that produced this item. - The generated image encoded in base64. + - `McpApprovalResponse` - - `Status status` + - `String approvalRequestId` - The status of the image generation call. + The ID of the approval request being answered. - - `IN_PROGRESS("in_progress")` + - `boolean approve` - - `COMPLETED("completed")` + Whether the request was approved. - - `GENERATING("generating")` + - `JsonValue; type "mcp_approval_response"constant` - - `FAILED("failed")` + The type of the item. Always `mcp_approval_response`. - - `JsonValue; type "image_generation_call"constant` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - The type of the image generation call. Always `image_generation_call`. + - `Optional id` - - `IMAGE_GENERATION_CALL("image_generation_call")` + The unique ID of the approval response - `Optional agent` @@ -22561,53 +39878,58 @@ Create a model response The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` + - `Optional reason` - A tool call to run code. + Optional reason for the decision. - - `LocalShellCall` + - `McpCall` - `String id` - The unique ID of the local shell call. + The unique ID of the tool call. - - `Action action` + - `String arguments` - Execute a shell command on the server. + A JSON string of the arguments passed to the tool. - - `List command` + - `String name` - The command to run. + The name of the tool that was run. - - `Env env` + - `String serverLabel` - Environment variables to set for the command. + The label of the MCP server running the tool. - - `JsonValue; type "exec"constant` + - `JsonValue; type "mcp_call"constant` - The type of the local shell action. Always `exec`. + The type of the item. Always `mcp_call`. - - `EXEC("exec")` + - `MCP_CALL("mcp_call")` - - `Optional timeoutMs` + - `Optional agent` - Optional timeout in milliseconds for the command. + The agent that produced this item. - - `Optional user` + - `String agentName` - Optional user to run the command as. + The canonical name of the agent that produced this item. - - `Optional workingDirectory` + - `Optional approvalRequestId` - Optional working directory to run the command in. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `String callId` + - `Optional error` - The unique ID of the local shell tool call generated by the model. + The error from the tool call, if any. - - `Status status` + - `Optional output` - The status of the local shell call. + The output from the tool call. + + - `Optional status` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `IN_PROGRESS("in_progress")` @@ -22615,121 +39937,106 @@ Create a model response - `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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `LocalShellCallOutput` - - - `String id` + - `CALLING("calling")` - The unique ID of the local shell tool call generated by the model. + - `FAILED("failed")` - - `String output` + - `class BetaResponseCustomToolCallOutput:` - A JSON string of the output of the local shell tool call. + The output of a custom tool call from your code, being sent back to the model. - - `JsonValue; type "local_shell_call_output"constant` + - `String callId` - The type of the local shell tool call output. Always `local_shell_call_output`. + The call ID, used to map this custom tool call output to a custom tool call. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `Output output` - - `Optional agent` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The agent that produced this item. + - `String` - - `String agentName` + - `List` - The canonical name of the agent that produced this item. + - `class BetaResponseInputText:` - - `Optional status` + A text input to the model. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `class BetaResponseInputImage:` - - `IN_PROGRESS("in_progress")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `COMPLETED("completed")` + - `class BetaResponseInputFile:` - - `INCOMPLETE("incomplete")` + A file input to the model. - - `class BetaResponseFunctionShellToolCall:` + - `JsonValue; type "custom_tool_call_output"constant` - A tool call that executes one or more shell commands in a managed environment. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `String id` + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `Optional id` - - `Action action` + The unique ID of the custom tool call output in the OpenAI platform. - The shell commands and limits that describe how to run the tool call. + - `Optional agent` - - `List commands` + The agent that produced this item. - - `Optional maxOutputLength` + - `String agentName` - Optional maximum number of characters to return from each command. + The canonical name of the agent that produced this item. - - `Optional timeoutMs` + - `Optional caller` - Optional timeout in milliseconds for the commands. + The execution context that produced this tool call. - - `String callId` + - `JsonValue;` - The unique ID of the shell tool call generated by the model. + - `JsonValue; type "direct"constant` - - `Optional environment` + The caller type. Always `direct`. - Represents the use of a local environment to perform shell actions. + - `DIRECT("direct")` - - `class BetaResponseLocalEnvironment:` + - `class Program:` - Represents the use of a local environment to perform shell actions. + - `String callerId` - - `JsonValue; type "local"constant` + The call ID of the program item that produced this tool call. - The environment type. Always `local`. + - `JsonValue; type "program"constant` - - `LOCAL("local")` + The caller type. Always `program`. - - `class BetaResponseContainerReference:` + - `PROGRAM("program")` - Represents a container created with /v1/containers. + - `class BetaResponseCustomToolCall:` - - `String containerId` + A call to a custom tool created by the model. - - `JsonValue; type "container_reference"constant` + - `String callId` - The environment type. Always `container_reference`. + An identifier used to map this custom tool call to a tool call output. - - `CONTAINER_REFERENCE("container_reference")` + - `String input` - - `Status status` + The input for the custom tool call generated by the model. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `String name` - - `IN_PROGRESS("in_progress")` + The name of the custom tool being called. - - `COMPLETED("completed")` + - `JsonValue; type "custom_tool_call"constant` - - `INCOMPLETE("incomplete")` + The type of the custom tool call. Always `custom_tool_call`. - - `JsonValue; type "shell_call"constant` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - The type of the item. Always `shell_call`. + - `Optional id` - - `SHELL_CALL("shell_call")` + The unique ID of the custom tool call in the OpenAI platform. - `Optional agent` @@ -22759,83 +40066,105 @@ Create a model response - `PROGRAM("program")` - - `Optional createdBy` + - `Optional namespace` - The ID of the entity that created this tool call. + The namespace of the custom tool being called. - - `class BetaResponseFunctionShellToolCallOutput:` + - `CompactionTrigger` - The output of a shell tool call that was emitted. + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` - `String id` - The unique ID of the shell call output. Populated when this item is returned via API. + The ID of the item to reference. - - `String callId` + - `Optional agent` - The unique ID of the shell tool call generated by the model. + The agent that produced this item. - - `Optional maxOutputLength` + - `String agentName` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The canonical name of the agent that produced this item. - - `List output` + - `Optional type` - An array of shell call output contents + The type of item to reference. Always `item_reference`. - - `Outcome outcome` + - `ITEM_REFERENCE("item_reference")` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `Program` - - `JsonValue;` + - `String id` - - `JsonValue; type "timeout"constant` + The unique ID of this program item. - The outcome type. Always `timeout`. + - `String callId` - - `TIMEOUT("timeout")` + The stable call ID of the program item. - - `class Exit:` + - `String code` - Indicates that the shell commands finished and returned an exit code. + The JavaScript source executed by programmatic tool calling. - - `long exitCode` + - `String fingerprint` - Exit code from the shell process. + Opaque program replay fingerprint that must be round-tripped. - - `JsonValue; type "exit"constant` + - `JsonValue; type "program"constant` - The outcome type. Always `exit`. + The item type. Always `program`. - - `EXIT("exit")` + - `PROGRAM("program")` - - `String stderr` + - `Optional agent` - The standard error output that was captured. + The agent that produced this item. - - `String stdout` + - `String agentName` - The standard output that was captured. + The canonical name of the agent that produced this item. - - `Optional createdBy` + - `ProgramOutput` - The identifier of the actor that created the item. + - `String id` - - `Status status` + The unique ID of this program output item. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `String callId` - - `IN_PROGRESS("in_progress")` + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `JsonValue; type "shell_call_output"constant` + - `JsonValue; type "program_output"constant` - The type of the shell call output. Always `shell_call_output`. + The item type. Always `program_output`. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -22845,252 +40174,278 @@ Create a model response The canonical name of the agent that produced this item. - - `Optional caller` + - `Optional metadata` - The execution context that produced this tool call. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `JsonValue;` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `JsonValue; type "direct"constant` + - `Model model` - - `DIRECT("direct")` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `class Program:` + - `GPT_5_6_SOL("gpt-5.6-sol")` - - `String callerId` + - `GPT_5_6_TERRA("gpt-5.6-terra")` - The call ID of the program item that produced this tool call. + - `GPT_5_6_LUNA("gpt-5.6-luna")` - - `JsonValue; type "program"constant` + - `GPT_5_4("gpt-5.4")` - - `PROGRAM("program")` + - `GPT_5_4_MINI("gpt-5.4-mini")` - - `Optional createdBy` + - `GPT_5_4_NANO("gpt-5.4-nano")` - The identifier of the actor that created the item. + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - - `class BetaResponseApplyPatchToolCall:` + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - A tool call that applies file diffs by creating, deleting, or updating files. + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - `String id` + - `GPT_5_2("gpt-5.2")` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - - `String callId` + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - The unique ID of the apply patch tool call generated by the model. + - `GPT_5_2_PRO("gpt-5.2-pro")` - - `Operation operation` + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `GPT_5_1("gpt-5.1")` - - `class CreateFile:` + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - Instruction describing how to create a file via the apply_patch tool. + - `GPT_5_1_CODEX("gpt-5.1-codex")` - - `String diff` + - `GPT_5_1_MINI("gpt-5.1-mini")` - Diff to apply. + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - `String path` + - `GPT_5("gpt-5")` - Path of the file to create. + - `GPT_5_MINI("gpt-5-mini")` - - `JsonValue; type "create_file"constant` + - `GPT_5_NANO("gpt-5-nano")` - Create a new file with the provided diff. + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - `CREATE_FILE("create_file")` + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `class DeleteFile:` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - Instruction describing how to delete a file via the apply_patch tool. + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `String path` + - `GPT_4_1("gpt-4.1")` - Path of the file to delete. + - `GPT_4_1_MINI("gpt-4.1-mini")` - - `JsonValue; type "delete_file"constant` + - `GPT_4_1_NANO("gpt-4.1-nano")` - Delete the specified file. + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - `DELETE_FILE("delete_file")` + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `class UpdateFile:` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - Instruction describing how to update a file via the apply_patch tool. + - `O4_MINI("o4-mini")` - - `String diff` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - Diff to apply. + - `O3("o3")` - - `String path` + - `O3_2025_04_16("o3-2025-04-16")` - Path of the file to update. + - `O3_MINI("o3-mini")` - - `JsonValue; type "update_file"constant` + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - Update an existing file with the provided diff. + - `O1("o1")` - - `UPDATE_FILE("update_file")` + - `O1_2024_12_17("o1-2024-12-17")` - - `Status status` + - `O1_PREVIEW("o1-preview")` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - - `IN_PROGRESS("in_progress")` + - `O1_MINI("o1-mini")` - - `COMPLETED("completed")` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - - `JsonValue; type "apply_patch_call"constant` + - `GPT_4O("gpt-4o")` - The type of the item. Always `apply_patch_call`. + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - - `APPLY_PATCH_CALL("apply_patch_call")` + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - `Optional agent` + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - The agent that produced this item. + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - `String agentName` + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - The canonical name of the agent that produced this item. + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - - `Optional caller` + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - The execution context that produced this tool call. + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - - `JsonValue;` + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - `JsonValue; type "direct"constant` + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `DIRECT("direct")` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `class Program:` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - - `String callerId` + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - The call ID of the program item that produced this tool call. + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - `JsonValue; type "program"constant` + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `PROGRAM("program")` + - `GPT_4O_MINI("gpt-4o-mini")` - - `Optional createdBy` + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - The ID of the entity that created this tool call. + - `GPT_4_TURBO("gpt-4-turbo")` - - `class BetaResponseApplyPatchToolCallOutput:` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - The output emitted by an apply patch tool call. + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `String id` + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - - `String callId` + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - The unique ID of the apply patch tool call generated by the model. + - `GPT_4("gpt-4")` - - `Status status` + - `GPT_4_0314("gpt-4-0314")` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `GPT_4_0613("gpt-4-0613")` - - `COMPLETED("completed")` + - `GPT_4_32K("gpt-4-32k")` - - `FAILED("failed")` + - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `JsonValue; type "apply_patch_call_output"constant` + - `GPT_4_32K_0613("gpt-4-32k-0613")` - The type of the item. Always `apply_patch_call_output`. + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `Optional agent` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - The agent that produced this item. + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `String agentName` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - The canonical name of the agent that produced this item. + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - `Optional caller` + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - The execution context that produced this tool call. + - `O1_PRO("o1-pro")` - - `JsonValue;` + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - - `JsonValue; type "direct"constant` + - `O3_PRO("o3-pro")` - - `DIRECT("direct")` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - - `class Program:` + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `String callerId` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - The call ID of the program item that produced this tool call. + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - - `JsonValue; type "program"constant` + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - - `PROGRAM("program")` + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - `Optional createdBy` + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - The ID of the entity that created this tool call output. + - `GPT_5_CODEX("gpt-5-codex")` - - `Optional output` + - `GPT_5_PRO("gpt-5-pro")` - Optional textual output returned by the apply patch tool. + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - - `McpCall` + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - - `String id` + - `JsonValue; object_ "response"constant` - The unique ID of the tool call. + The object type of this resource - always set to `response`. - - `String arguments` + - `RESPONSE("response")` - A JSON string of the arguments passed to the tool. + - `List output` - - `String name` + An array of content items generated by the model. - The name of the tool that was run. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `String serverLabel` + - `class BetaResponseOutputMessage:` - The label of the MCP server running the tool. + An output message from the model. - - `JsonValue; type "mcp_call"constant` + - `class BetaResponseFileSearchToolCall:` - The type of the item. Always `mcp_call`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `MCP_CALL("mcp_call")` + - `class BetaResponseFunctionToolCall:` - - `Optional agent` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The agent that produced this item. + - `class BetaResponseFunctionToolCallOutputItem:` - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The unique ID of the function call tool output. - - `Optional approvalRequestId` + - `String callId` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The unique ID of the function tool call generated by the model. - - `Optional error` + - `Output output` - The error from the tool call, if any. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `Optional output` + - `String` - The output from the tool call. + - `List` - - `Optional status` + - `class BetaResponseInputText:` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Status status` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -23098,1426 +40453,1148 @@ Create a model response - `INCOMPLETE("incomplete")` - - `CALLING("calling")` + - `JsonValue; type "function_call_output"constant` - - `FAILED("failed")` + The type of the function tool call output. Always `function_call_output`. - - `McpListTools` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `String id` + - `Optional agent` - The unique ID of the list. + The agent that produced this item. - - `String serverLabel` + - `String agentName` - The label of the MCP server. + The canonical name of the agent that produced this item. - - `List tools` + - `Optional caller` - The tools available on the server. + The execution context that produced this tool call. - - `JsonValue inputSchema` + - `JsonValue;` - The JSON schema describing the tool's input. + - `JsonValue; type "direct"constant` - - `String name` + The caller type. Always `direct`. - The name of the tool. + - `DIRECT("direct")` - - `Optional annotations` + - `class Program:` - Additional annotations about the tool. + - `String callerId` - - `Optional description` + The call ID of the program item that produced this tool call. - The description of the tool. + - `JsonValue; type "program"constant` - - `JsonValue; type "mcp_list_tools"constant` + The caller type. Always `program`. - The type of the item. Always `mcp_list_tools`. + - `PROGRAM("program")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `Optional createdBy` - - `Optional agent` + The identifier of the actor that created the item. - The agent that produced this item. + - `AgentMessage` - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The unique ID of the agent message. - - `Optional error` + - `String author` - Error message if the server could not list tools. + The sending agent identity. - - `McpApprovalRequest` + - `List content` - - `String id` + Encrypted content sent between agents. - The unique ID of the approval request. + - `class BetaResponseInputText:` - - `String arguments` + A text input to the model. - A JSON string of arguments for the tool. + - `class BetaResponseOutputText:` - - `String name` + A text output from the model. - The name of the tool to run. + - `class Text:` - - `String serverLabel` + A text content. - The label of the MCP server making the request. + - `String text` - - `JsonValue; type "mcp_approval_request"constant` + - `JsonValue; type "text"constant` - The type of the item. Always `mcp_approval_request`. + - `TEXT("text")` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `class SummaryText:` - - `Optional agent` + A summary text from the model. - The agent that produced this item. + - `String text` - - `String agentName` + A summary of the reasoning output from the model so far. - The canonical name of the agent that produced this item. + - `JsonValue; type "summary_text"constant` - - `McpApprovalResponse` + The type of the object. Always `summary_text`. - - `String id` + - `SUMMARY_TEXT("summary_text")` - The unique ID of the approval response + - `class ReasoningText:` - - `String approvalRequestId` + Reasoning text from the model. - The ID of the approval request being answered. + - `String text` - - `boolean approve` + The reasoning text from the model. - Whether the request was approved. + - `JsonValue; type "reasoning_text"constant` - - `JsonValue; type "mcp_approval_response"constant` + The type of the reasoning text. Always `reasoning_text`. - The type of the item. Always `mcp_approval_response`. + - `REASONING_TEXT("reasoning_text")` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `class BetaResponseOutputRefusal:` - - `Optional agent` + A refusal from the model. - The agent that produced this item. + - `class BetaResponseInputImage:` - - `String agentName` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The canonical name of the agent that produced this item. + - `class ComputerScreenshot:` - - `Optional reason` + A screenshot of a computer. - Optional reason for the decision. + - `Detail detail` - - `class BetaResponseCustomToolCall:` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A call to a custom tool created by the model. + - `LOW("low")` - - `class BetaResponseCustomToolCallOutputItem:` + - `HIGH("high")` - The output of a custom tool call from your code, being sent back to the model. + - `AUTO("auto")` - - `String id` + - `ORIGINAL("original")` - The unique ID of the custom tool call output item. + - `Optional fileId` - - `Status status` + The identifier of an uploaded file that contains the screenshot. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional imageUrl` - - `IN_PROGRESS("in_progress")` + The URL of the screenshot image. - - `COMPLETED("completed")` + - `JsonValue; type "computer_screenshot"constant` - - `INCOMPLETE("incomplete")` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `Optional createdBy` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The identifier of the actor that created the item. + - `Optional promptCacheBreakpoint` - - `boolean parallelToolCalls` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Whether to allow the model to run tool calls in parallel. + - `JsonValue; mode "explicit"constant` - - `Optional temperature` + The breakpoint mode. Always `explicit`. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `EXPLICIT("explicit")` - - `ToolChoice toolChoice` + - `class BetaResponseInputFile:` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + A file input to the model. - - `enum BetaToolChoiceOptions:` + - `class EncryptedContent:` - Controls which (if any) tool is called by the model. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - `none` means the model will not call any tool and instead generates a message. + - `String encryptedContent` - `auto` means the model can pick between generating a message or calling one or - more tools. + Opaque encrypted content. - `required` means the model must call one or more tools. + - `JsonValue; type "encrypted_content"constant` - - `NONE("none")` + The type of the input item. Always `encrypted_content`. - - `AUTO("auto")` + - `ENCRYPTED_CONTENT("encrypted_content")` - - `REQUIRED("required")` + - `String recipient` - - `class BetaToolChoiceAllowed:` + The destination agent identity. - Constrains the tools available to the model to a pre-defined set. + - `JsonValue; type "agent_message"constant` - - `Mode mode` + The type of the item. Always `agent_message`. - Constrains the tools available to the model to a pre-defined set. + - `AGENT_MESSAGE("agent_message")` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `Optional agent` - `required` requires the model to call one or more of the allowed tools. + The agent that produced this item. - - `AUTO("auto")` + - `String agentName` - - `REQUIRED("required")` + The canonical name of the agent that produced this item. - - `List tools` + - `MultiAgentCall` - A list of tool definitions that the model should be allowed to call. + - `String id` - For the Responses API, the list of tool definitions might look like: + The unique ID of the multi-agent call item. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `Action action` - - `JsonValue; type "allowed_tools"constant` + The multi-agent action to execute. - Allowed tool configuration type. Always `allowed_tools`. + - `SPAWN_AGENT("spawn_agent")` - - `ALLOWED_TOOLS("allowed_tools")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `class BetaToolChoiceTypes:` + - `LIST_AGENTS("list_agents")` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `SEND_MESSAGE("send_message")` - - `Type type` + - `FOLLOWUP_TASK("followup_task")` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `WAIT_AGENT("wait_agent")` - Allowed values are: + - `String arguments` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The JSON string of arguments generated for the action. - - `FILE_SEARCH("file_search")` + - `String callId` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + The unique ID linking this call to its output. - - `COMPUTER("computer")` + - `JsonValue; type "multi_agent_call"constant` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The type of the multi-agent call. Always `multi_agent_call`. - - `COMPUTER_USE("computer_use")` + - `MULTI_AGENT_CALL("multi_agent_call")` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `Optional agent` - - `IMAGE_GENERATION("image_generation")` + The agent that produced this item. - - `CODE_INTERPRETER("code_interpreter")` + - `String agentName` - - `class BetaToolChoiceFunction:` + The canonical name of the agent that produced this item. - Use this option to force the model to call a specific function. + - `MultiAgentCallOutput` - - `String name` + - `String id` - The name of the function to call. + The unique ID of the multi-agent call output item. - - `JsonValue; type "function"constant` + - `Action action` - For function calling, the type is always `function`. + The multi-agent action that produced this result. - - `FUNCTION("function")` + - `SPAWN_AGENT("spawn_agent")` - - `class BetaToolChoiceMcp:` + - `INTERRUPT_AGENT("interrupt_agent")` - Use this option to force the model to call a specific tool on a remote MCP server. + - `LIST_AGENTS("list_agents")` - - `String serverLabel` + - `SEND_MESSAGE("send_message")` - The label of the MCP server to use. + - `FOLLOWUP_TASK("followup_task")` - - `JsonValue; type "mcp"constant` + - `WAIT_AGENT("wait_agent")` - For MCP tools, the type is always `mcp`. + - `String callId` - - `MCP("mcp")` + The unique ID of the multi-agent call. - - `Optional name` + - `List output` - The name of the tool to call on the server. + Text output returned by the multi-agent action. - - `class BetaToolChoiceCustom:` + - `List annotations` - Use this option to force the model to call a specific custom tool. + The annotations of the text output. - - `String name` + - `String text` - The name of the custom tool to call. + The text output from the model. - - `JsonValue; type "custom"constant` + - `JsonValue; type "output_text"constant` - For custom tool calling, the type is always `custom`. + The type of the output text. Always `output_text`. - - `CUSTOM("custom")` + - `Optional> logprobs` - - `JsonValue;` + - `JsonValue; type "multi_agent_call_output"constant` - - `JsonValue; type "programmatic_tool_calling"constant` + The type of the multi-agent result. Always `multi_agent_call_output`. - The tool to call. Always `programmatic_tool_calling`. + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional agent` - - `class BetaToolChoiceApplyPatch:` + The agent that produced this item. - Forces the model to call the apply_patch tool when executing a tool call. + - `String agentName` - - `JsonValue; type "apply_patch"constant` + The canonical name of the agent that produced this item. - The tool to call. Always `apply_patch`. + - `class BetaResponseFunctionWebSearch:` - - `APPLY_PATCH("apply_patch")` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `class BetaToolChoiceShell:` + - `class BetaResponseComputerToolCall:` - Forces the model to call the shell tool when a tool call is required. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `JsonValue; type "shell"constant` + - `class BetaResponseComputerToolCallOutputItem:` - The tool to call. Always `shell`. + - `String id` - - `SHELL("shell")` + The unique ID of the computer call tool output. - - `List tools` + - `String callId` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The ID of the computer tool call that produced the output. - We support the following categories of tools: + - `BetaResponseComputerToolCallOutputScreenshot output` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + A computer screenshot image used with the computer use tool. - - `class BetaFunctionTool:` + - `Status status` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class BetaFileSearchTool:` + - `COMPLETED("completed")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `INCOMPLETE("incomplete")` - - `class BetaComputerTool:` + - `FAILED("failed")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `IN_PROGRESS("in_progress")` - - `class BetaComputerUsePreviewTool:` + - `JsonValue; type "computer_call_output"constant` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the computer tool call output. Always `computer_call_output`. - - `class BetaWebSearchTool:` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional> acknowledgedSafetyChecks` - - `Mcp` + The safety checks reported by the API that have been acknowledged by the + developer. - - `CodeInterpreter` + - `String id` - - `JsonValue;` + The ID of the pending safety check. - - `ImageGeneration` + - `Optional code` - - `JsonValue;` + The type of the pending safety check. - - `class BetaFunctionShellTool:` + - `Optional message` - A tool that allows the model to execute shell commands. + Details about the pending safety check. - - `class BetaCustomTool:` + - `Optional agent` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The agent that produced this item. - - `class BetaNamespaceTool:` + - `String agentName` - Groups function/custom tools under a shared namespace. + The canonical name of the agent that produced this item. - - `class BetaToolSearchTool:` + - `Optional createdBy` - Hosted or BYOT tool search configuration for deferred tools. + The identifier of the actor that created the item. - - `class BetaWebSearchPreviewTool:` + - `class BetaResponseReasoningItem:` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `Program` + + - `String id` - - `class BetaApplyPatchTool:` + The unique ID of the program item. - Allows the assistant to create, delete, or update files using unified diffs. + - `String callId` - - `Optional topP` + The stable call ID of the program item. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `String code` - We generally recommend altering this or `temperature` but not both. + The JavaScript source executed by programmatic tool calling. - - `Optional background` + - `String fingerprint` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + Opaque program replay fingerprint that must be round-tripped. - - `Optional completedAt` + - `JsonValue; type "program"constant` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The type of the item. Always `program`. - - `Optional conversation` + - `PROGRAM("program")` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `Optional agent` - - `String id` + The agent that produced this item. - The unique ID of the conversation that this response was associated with. + - `String agentName` - - `Optional maxOutputTokens` + The canonical name of the agent that produced this item. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `ProgramOutput` - - `Optional maxToolCalls` + - `String id` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The unique ID of the program output item. - - `Optional moderation` + - `String callId` - Moderation results for the response input and output, if moderated completions were requested. + The call ID of the program item. - - `Input input` + - `String result` - Moderation for the response input. + The result produced by the program item. - - `class ModerationResult:` + - `Status status` - A moderation result produced for the response input or output. + The terminal status of the program output item. - - `Categories categories` + - `COMPLETED("completed")` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `INCOMPLETE("incomplete")` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `JsonValue; type "program_output"constant` - Which modalities of input are reflected by the score for each category. + The type of the item. Always `program_output`. - - `TEXT("text")` + - `PROGRAM_OUTPUT("program_output")` - - `IMAGE("image")` + - `Optional agent` - - `CategoryScores categoryScores` + The agent that produced this item. - A dictionary of moderation categories to scores. + - `String agentName` - - `boolean flagged` + The canonical name of the agent that produced this item. - A boolean indicating whether the content was flagged by any category. + - `class BetaResponseToolSearchCall:` - - `String model` + - `String id` - The moderation model that produced this result. + The unique ID of the tool search call item. - - `JsonValue; type "moderation_result"constant` + - `JsonValue arguments` - The object type, which was always `moderation_result` for successful moderation results. + Arguments used for the tool search call. - - `MODERATION_RESULT("moderation_result")` + - `Optional callId` - - `class Error:` + The unique ID of the tool search call generated by the model. - An error produced while attempting moderation for the response input or output. + - `Execution execution` - - `String code` + Whether tool search was executed by the server or by the client. - The error code. + - `SERVER("server")` - - `String message` + - `CLIENT("client")` - The error message. + - `Status status` - - `JsonValue; type "error"constant` + The status of the tool search call item that was recorded. - The object type, which was always `error` for moderation failures. + - `IN_PROGRESS("in_progress")` - - `ERROR("error")` + - `COMPLETED("completed")` - - `Output output` + - `INCOMPLETE("incomplete")` - Moderation for the response output. + - `JsonValue; type "tool_search_call"constant` - - `class ModerationResult:` + The type of the item. Always `tool_search_call`. - A moderation result produced for the response input or output. + - `TOOL_SEARCH_CALL("tool_search_call")` - - `Categories categories` + - `Optional agent` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The agent that produced this item. - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `String agentName` - Which modalities of input are reflected by the score for each category. + The canonical name of the agent that produced this item. - - `TEXT("text")` + - `Optional createdBy` - - `IMAGE("image")` + The identifier of the actor that created the item. - - `CategoryScores categoryScores` + - `class BetaResponseToolSearchOutputItem:` - A dictionary of moderation categories to scores. + - `String id` - - `boolean flagged` + The unique ID of the tool search output item. - A boolean indicating whether the content was flagged by any category. + - `Optional callId` - - `String model` + The unique ID of the tool search call generated by the model. - The moderation model that produced this result. + - `Execution execution` - - `JsonValue; type "moderation_result"constant` + Whether tool search was executed by the server or by the client. - The object type, which was always `moderation_result` for successful moderation results. + - `SERVER("server")` - - `MODERATION_RESULT("moderation_result")` + - `CLIENT("client")` - - `class Error:` + - `Status status` - An error produced while attempting moderation for the response input or output. + The status of the tool search output item that was recorded. - - `String code` + - `IN_PROGRESS("in_progress")` - The error code. + - `COMPLETED("completed")` - - `String message` + - `INCOMPLETE("incomplete")` - The error message. + - `List tools` - - `JsonValue; type "error"constant` + The loaded tool definitions returned by tool search. - The object type, which was always `error` for moderation failures. + - `class BetaFunctionTool:` - - `ERROR("error")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `Optional previousResponseId` + - `class BetaFileSearchTool:` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional prompt` + - `class BetaComputerTool:` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String id` + - `class BetaComputerUsePreviewTool:` - The unique identifier of the prompt template to use. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional variables` + - `class BetaWebSearchTool:` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String` + - `Mcp` - - `class BetaResponseInputText:` + - `CodeInterpreter` - A text input to the model. + - `JsonValue;` - - `class BetaResponseInputImage:` + - `ImageGeneration` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `JsonValue;` - - `class BetaResponseInputFile:` + - `class BetaFunctionShellTool:` - A file input to the model. + A tool that allows the model to execute shell commands. - - `Optional version` + - `class BetaCustomTool:` - Optional version of the prompt template. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional promptCacheKey` + - `class BetaNamespaceTool:` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Groups function/custom tools under a shared namespace. - - `Optional promptCacheOptions` + - `class BetaToolSearchTool:` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + Hosted or BYOT tool search configuration for deferred tools. - - `Mode mode` + - `class BetaWebSearchPreviewTool:` - Whether implicit prompt-cache breakpoints were enabled. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `IMPLICIT("implicit")` + - `class BetaApplyPatchTool:` - - `EXPLICIT("explicit")` + Allows the assistant to create, delete, or update files using unified diffs. - - `Ttl ttl` + - `JsonValue; type "tool_search_output"constant` - The minimum lifetime applied to each cache breakpoint. + The type of the item. Always `tool_search_output`. - - `_30M("30m")` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `Optional promptCacheRetention` + - `Optional agent` - Deprecated. Use `prompt_cache_options.ttl` instead. + The agent that produced this item. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `String agentName` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The canonical name of the agent that produced this item. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `Optional createdBy` - - `IN_MEMORY("in_memory")` + The identifier of the actor that created the item. - - `_24H("24h")` + - `AdditionalTools` - - `Optional reasoning` + - `String id` - **gpt-5 and o-series models only** + The unique ID of the additional tools item. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `Role role` - - `Optional context` + The role that provided the additional tools. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `UNKNOWN("unknown")` - - `AUTO("auto")` + - `USER("user")` - - `CURRENT_TURN("current_turn")` + - `ASSISTANT("assistant")` - - `ALL_TURNS("all_turns")` + - `SYSTEM("system")` - - `Optional effort` + - `CRITIC("critic")` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `DISCRIMINATOR("discriminator")` - - `NONE("none")` + - `DEVELOPER("developer")` - - `MINIMAL("minimal")` + - `TOOL("tool")` - - `LOW("low")` + - `List tools` - - `MEDIUM("medium")` + The additional tool definitions made available at this item. - - `HIGH("high")` + - `class BetaFunctionTool:` - - `XHIGH("xhigh")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `MAX("max")` + - `class BetaFileSearchTool:` - - `Optional generateSummary` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - **Deprecated:** use `summary` instead. + - `class BetaComputerTool:` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `AUTO("auto")` + - `class BetaComputerUsePreviewTool:` - - `CONCISE("concise")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `DETAILED("detailed")` + - `class BetaWebSearchTool:` - - `Optional mode` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Controls the reasoning execution mode for the request. + - `Mcp` - When returned on a response, this is the effective execution mode. + - `CodeInterpreter` - - `STANDARD("standard")` + - `JsonValue;` - - `PRO("pro")` + - `ImageGeneration` - - `Optional summary` + - `JsonValue;` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `class BetaFunctionShellTool:` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + A tool that allows the model to execute shell commands. - - `AUTO("auto")` + - `class BetaCustomTool:` - - `CONCISE("concise")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `DETAILED("detailed")` + - `class BetaNamespaceTool:` - - `Optional safetyIdentifier` + Groups function/custom tools under a shared namespace. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `class BetaToolSearchTool:` - - `Optional serviceTier` + Hosted or BYOT tool search configuration for deferred tools. - Specifies the processing type used for serving the request. + - `class BetaWebSearchPreviewTool:` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `class BetaApplyPatchTool:` - - `AUTO("auto")` + Allows the assistant to create, delete, or update files using unified diffs. - - `DEFAULT("default")` + - `JsonValue; type "additional_tools"constant` - - `FLEX("flex")` + The type of the item. Always `additional_tools`. - - `SCALE("scale")` + - `ADDITIONAL_TOOLS("additional_tools")` - - `PRIORITY("priority")` + - `Optional agent` - - `Optional status` + The agent that produced this item. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `String agentName` - - `COMPLETED("completed")` + The canonical name of the agent that produced this item. - - `FAILED("failed")` + - `class BetaResponseCompactionItem:` - - `IN_PROGRESS("in_progress")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `CANCELLED("cancelled")` + - `String id` - - `QUEUED("queued")` + The unique ID of the compaction item. - - `INCOMPLETE("incomplete")` + - `String encryptedContent` - - `Optional text` + The encrypted content that was produced by compaction. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `JsonValue; type "compaction"constant` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The type of the item. Always `compaction`. - - `Optional format` + - `COMPACTION("compaction")` - An object specifying the format that the model must output. + - `Optional agent` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The agent that produced this item. - The default format is `{ "type": "text" }` with no additional options. + - `String agentName` - **Not recommended for gpt-4o and newer models:** + The canonical name of the agent that produced this item. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `Optional createdBy` - - `JsonValue;` + The identifier of the actor that created the item. - - `JsonValue; type "text"constant` + - `ImageGenerationCall` - The type of response format being defined. Always `text`. + - `String id` - - `TEXT("text")` + The unique ID of the image generation call. - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `Optional result` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The generated image encoded in base64. - - `String name` + - `Status status` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The status of the image generation call. - - `Schema schema` + - `IN_PROGRESS("in_progress")` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `COMPLETED("completed")` - - `JsonValue; type "json_schema"constant` + - `GENERATING("generating")` - The type of response format being defined. Always `json_schema`. + - `FAILED("failed")` - - `JSON_SCHEMA("json_schema")` + - `JsonValue; type "image_generation_call"constant` - - `Optional description` + The type of the image generation call. Always `image_generation_call`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `Optional strict` + - `Optional agent` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The agent that produced this item. - - `JsonValue;` + - `String agentName` - - `JsonValue; type "json_object"constant` + The canonical name of the agent that produced this item. - The type of response format being defined. Always `json_object`. + - `class BetaResponseCodeInterpreterToolCall:` - - `JSON_OBJECT("json_object")` + A tool call to run code. - - `Optional verbosity` + - `LocalShellCall` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `String id` - - `LOW("low")` + The unique ID of the local shell call. - - `MEDIUM("medium")` + - `Action action` - - `HIGH("high")` + Execute a shell command on the server. - - `Optional topLogprobs` + - `List command` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The command to run. - - `Optional truncation` + - `Env env` - The truncation strategy to use for the model response. + Environment variables to set for the command. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `JsonValue; type "exec"constant` - - `AUTO("auto")` + The type of the local shell action. Always `exec`. - - `DISABLED("disabled")` + - `EXEC("exec")` - - `Optional usage` + - `Optional timeoutMs` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + Optional timeout in milliseconds for the command. - - `long inputTokens` + - `Optional user` - The number of input tokens. + Optional user to run the command as. - - `InputTokensDetails inputTokensDetails` + - `Optional workingDirectory` - A detailed breakdown of the input tokens. + Optional working directory to run the command in. - - `long cacheWriteTokens` + - `String callId` - The number of input tokens that were written to the cache. + The unique ID of the local shell tool call generated by the model. - - `long cachedTokens` + - `Status status` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The status of the local shell call. - - `long outputTokens` + - `IN_PROGRESS("in_progress")` - The number of output tokens. + - `COMPLETED("completed")` - - `OutputTokensDetails outputTokensDetails` + - `INCOMPLETE("incomplete")` - A detailed breakdown of the output tokens. + - `JsonValue; type "local_shell_call"constant` - - `long reasoningTokens` + The type of the local shell call. Always `local_shell_call`. - The number of reasoning tokens. + - `LOCAL_SHELL_CALL("local_shell_call")` - - `long totalTokens` + - `Optional agent` - The total number of tokens used. + The agent that produced this item. - - `Optional user` + - `String agentName` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The canonical name of the agent that produced this item. -### Example + - `LocalShellCallOutput` -```java -package com.openai.example; + - `String id` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.responses.BetaResponse; -import com.openai.models.beta.responses.ResponseCreateParams; + The unique ID of the local shell tool call generated by the model. -public final class Main { - private Main() {} + - `String output` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + A JSON string of the output of the local shell tool call. - BetaResponse betaResponse = client.beta().responses().create(); - } -} -``` + - `JsonValue; type "local_shell_call_output"constant` -#### Response + The type of the local shell tool call output. Always `local_shell_call_output`. -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` -## Get a model response + - `Optional agent` -`BetaResponse beta().responses().retrieve(ResponseRetrieveParamsparams = ResponseRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The agent that produced this item. -**get** `/responses/{response_id}?beta=true` + - `String agentName` -Get a model response + The canonical name of the agent that produced this item. -### Parameters + - `Optional status` -- `ResponseRetrieveParams params` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `Optional responseId` + - `IN_PROGRESS("in_progress")` - - `Optional> include` + - `COMPLETED("completed")` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `INCOMPLETE("incomplete")` - - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` + - `class BetaResponseFunctionShellToolCall:` - - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` + A tool call that executes one or more shell commands in a managed environment. - - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` + - `String id` - - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` + - `Action action` - - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` + The shell commands and limits that describe how to run the tool call. - - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` + - `List commands` - - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` + - `Optional maxOutputLength` - - `Optional includeObfuscation` + Optional maximum number of characters to return from each command. - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events - to normalize payload sizes as a mitigation to certain side-channel - attacks. These obfuscation fields are included by default, but add a - small amount of overhead to the data stream. You can set - `include_obfuscation` to false to optimize for bandwidth if you trust - the network links between your application and the OpenAI API. + - `Optional timeoutMs` - - `Optional startingAfter` + Optional timeout in milliseconds for the commands. - The sequence number of the event after which to start streaming. + - `String callId` - - `Optional> betas` + The unique ID of the shell tool call generated by the model. - - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + - `Optional environment` -### Returns + Represents the use of a local environment to perform shell actions. -- `class BetaResponse:` + - `class BetaResponseLocalEnvironment:` - - `String id` + Represents the use of a local environment to perform shell actions. - Unique identifier for this Response. + - `JsonValue; type "local"constant` - - `double createdAt` + The environment type. Always `local`. - Unix timestamp (in seconds) of when this Response was created. + - `LOCAL("local")` - - `Optional error` + - `class BetaResponseContainerReference:` - An error object returned when the model fails to generate a Response. + Represents a container created with /v1/containers. - - `Code code` + - `String containerId` - The error code for the response. + - `JsonValue; type "container_reference"constant` - - `SERVER_ERROR("server_error")` + The environment type. Always `container_reference`. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `CONTAINER_REFERENCE("container_reference")` - - `INVALID_PROMPT("invalid_prompt")` + - `Status status` - - `BIO_POLICY("bio_policy")` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + - `IN_PROGRESS("in_progress")` - - `INVALID_IMAGE("invalid_image")` + - `COMPLETED("completed")` - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + - `INCOMPLETE("incomplete")` - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `JsonValue; type "shell_call"constant` - - `INVALID_IMAGE_URL("invalid_image_url")` + The type of the item. Always `shell_call`. - - `IMAGE_TOO_LARGE("image_too_large")` + - `SHELL_CALL("shell_call")` - - `IMAGE_TOO_SMALL("image_too_small")` + - `Optional agent` - - `IMAGE_PARSE_ERROR("image_parse_error")` + The agent that produced this item. - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + - `String agentName` - - `INVALID_IMAGE_MODE("invalid_image_mode")` + The canonical name of the agent that produced this item. - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + - `Optional caller` - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + The execution context that produced this tool call. - - `EMPTY_IMAGE_FILE("empty_image_file")` + - `JsonValue;` - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + - `JsonValue; type "direct"constant` - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + - `DIRECT("direct")` - - `String message` + - `class Program:` - A human-readable description of the error. + - `String callerId` - - `Optional incompleteDetails` + The call ID of the program item that produced this tool call. - Details about why the response is incomplete. + - `JsonValue; type "program"constant` - - `Optional reason` + - `PROGRAM("program")` - The reason why the response is incomplete. + - `Optional createdBy` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + The ID of the entity that created this tool call. - - `CONTENT_FILTER("content_filter")` + - `class BetaResponseFunctionShellToolCallOutput:` - - `Optional instructions` + The output of a shell tool call that was emitted. - A system (or developer) message inserted into the model's context. + - `String id` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + The unique ID of the shell call output. Populated when this item is returned via API. - - `String` + - `String callId` - - `List` + The unique ID of the shell tool call generated by the model. - - `class BetaEasyInputMessage:` + - `Optional maxOutputLength` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `Content content` + - `List output` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + An array of shell call output contents - - `String` + - `Outcome outcome` - - `List` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `class BetaResponseInputText:` + - `JsonValue;` - A text input to the model. + - `JsonValue; type "timeout"constant` - - `String text` + The outcome type. Always `timeout`. - The text input to the model. + - `TIMEOUT("timeout")` - - `JsonValue; type "input_text"constant` + - `class Exit:` - The type of the input item. Always `input_text`. + Indicates that the shell commands finished and returned an exit code. - - `INPUT_TEXT("input_text")` + - `long exitCode` - - `Optional promptCacheBreakpoint` + Exit code from the shell process. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; type "exit"constant` - - `JsonValue; mode "explicit"constant` + The outcome type. Always `exit`. - The breakpoint mode. Always `explicit`. + - `EXIT("exit")` - - `EXPLICIT("explicit")` + - `String stderr` - - `class BetaResponseInputImage:` + The standard error output that was captured. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `String stdout` - - `Detail detail` + The standard output that was captured. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Optional createdBy` - - `LOW("low")` + The identifier of the actor that created the item. - - `HIGH("high")` + - `Status status` - - `AUTO("auto")` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `ORIGINAL("original")` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "input_image"constant` + - `COMPLETED("completed")` - The type of the input item. Always `input_image`. + - `INCOMPLETE("incomplete")` - - `INPUT_IMAGE("input_image")` + - `JsonValue; type "shell_call_output"constant` - - `Optional fileId` + The type of the shell call output. Always `shell_call_output`. - The ID of the file to be sent to the model. + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `Optional imageUrl` + - `Optional agent` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The agent that produced this item. - - `Optional promptCacheBreakpoint` + - `String agentName` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The canonical name of the agent that produced this item. - - `JsonValue; mode "explicit"constant` + - `Optional caller` - The breakpoint mode. Always `explicit`. + The execution context that produced this tool call. - - `EXPLICIT("explicit")` + - `JsonValue;` - - `class BetaResponseInputFile:` + - `JsonValue; type "direct"constant` - A file input to the model. + - `DIRECT("direct")` - - `JsonValue; type "input_file"constant` + - `class Program:` - The type of the input item. Always `input_file`. + - `String callerId` - - `INPUT_FILE("input_file")` + The call ID of the program item that produced this tool call. - - `Optional detail` + - `JsonValue; type "program"constant` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `PROGRAM("program")` - - `AUTO("auto")` + - `Optional createdBy` - - `LOW("low")` + The identifier of the actor that created the item. - - `HIGH("high")` + - `class BetaResponseApplyPatchToolCall:` - - `Optional fileData` + A tool call that applies file diffs by creating, deleting, or updating files. - The content of the file to be sent to the model. + - `String id` - - `Optional fileId` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The ID of the file to be sent to the model. + - `String callId` - - `Optional fileUrl` + The unique ID of the apply patch tool call generated by the model. - The URL of the file to be sent to the model. + - `Operation operation` - - `Optional filename` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The name of the file to be sent to the model. + - `class CreateFile:` - - `Optional promptCacheBreakpoint` + Instruction describing how to create a file via the apply_patch tool. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String diff` - - `JsonValue; mode "explicit"constant` + Diff to apply. - The breakpoint mode. Always `explicit`. + - `String path` - - `EXPLICIT("explicit")` + Path of the file to create. - - `Role role` + - `JsonValue; type "create_file"constant` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Create a new file with the provided diff. - - `USER("user")` + - `CREATE_FILE("create_file")` - - `ASSISTANT("assistant")` + - `class DeleteFile:` - - `SYSTEM("system")` + Instruction describing how to delete a file via the apply_patch tool. - - `DEVELOPER("developer")` + - `String path` - - `Optional phase` + Path of the file to delete. - 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. + - `JsonValue; type "delete_file"constant` - - `COMMENTARY("commentary")` + Delete the specified file. - - `Optional type` + - `DELETE_FILE("delete_file")` - The type of the message input. Always `message`. + - `class UpdateFile:` - - `MESSAGE("message")` + Instruction describing how to update a file via the apply_patch tool. - - `Message` + - `String diff` - - `List content` + Diff to apply. - A list of one or many input items to the model, containing different content - types. + - `String path` - - `class BetaResponseInputText:` + Path of the file to update. - A text input to the model. + - `JsonValue; type "update_file"constant` - - `class BetaResponseInputImage:` + Update an existing file with the provided diff. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `UPDATE_FILE("update_file")` - - `class BetaResponseInputFile:` + - `Status status` - A file input to the model. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `Role role` + - `IN_PROGRESS("in_progress")` - The role of the message input. One of `user`, `system`, or `developer`. + - `COMPLETED("completed")` - - `USER("user")` + - `JsonValue; type "apply_patch_call"constant` - - `SYSTEM("system")` + The type of the item. Always `apply_patch_call`. - - `DEVELOPER("developer")` + - `APPLY_PATCH_CALL("apply_patch_call")` - `Optional agent` @@ -24527,201 +41604,186 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional 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` - - The type of the message input. Always set to `message`. - - - `MESSAGE("message")` + - `Optional caller` - - `class BetaResponseOutputMessage:` + The execution context that produced this tool call. - An output message from the model. + - `JsonValue;` - - `String id` + - `JsonValue; type "direct"constant` - The unique ID of the output message. + - `DIRECT("direct")` - - `List content` + - `class Program:` - The content of the output message. + - `String callerId` - - `class BetaResponseOutputText:` + The call ID of the program item that produced this tool call. - A text output from the model. + - `JsonValue; type "program"constant` - - `List annotations` + - `PROGRAM("program")` - The annotations of the text output. + - `Optional createdBy` - - `class FileCitation:` + The ID of the entity that created this tool call. - A citation to a file. + - `class BetaResponseApplyPatchToolCallOutput:` - - `String fileId` + The output emitted by an apply patch tool call. - The ID of the file. + - `String id` - - `String filename` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The filename of the file cited. + - `String callId` - - `long index` + The unique ID of the apply patch tool call generated by the model. - The index of the file in the list of files. + - `Status status` - - `JsonValue; type "file_citation"constant` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the file citation. Always `file_citation`. + - `COMPLETED("completed")` - - `FILE_CITATION("file_citation")` + - `FAILED("failed")` - - `class UrlCitation:` + - `JsonValue; type "apply_patch_call_output"constant` - A citation for a web resource used to generate a model response. + The type of the item. Always `apply_patch_call_output`. - - `long endIndex` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - The index of the last character of the URL citation in the message. + - `Optional agent` - - `long startIndex` + The agent that produced this item. - The index of the first character of the URL citation in the message. + - `String agentName` - - `String title` + The canonical name of the agent that produced this item. - The title of the web resource. + - `Optional caller` - - `JsonValue; type "url_citation"constant` + The execution context that produced this tool call. - The type of the URL citation. Always `url_citation`. + - `JsonValue;` - - `URL_CITATION("url_citation")` + - `JsonValue; type "direct"constant` - - `String url` + - `DIRECT("direct")` - The URL of the web resource. + - `class Program:` - - `class ContainerFileCitation:` + - `String callerId` - A citation for a container file used to generate a model response. + The call ID of the program item that produced this tool call. - - `String containerId` + - `JsonValue; type "program"constant` - The ID of the container file. + - `PROGRAM("program")` - - `long endIndex` + - `Optional createdBy` - The index of the last character of the container file citation in the message. + The ID of the entity that created this tool call output. - - `String fileId` + - `Optional output` - The ID of the file. + Optional textual output returned by the apply patch tool. - - `String filename` + - `McpCall` - The filename of the container file cited. + - `String id` - - `long startIndex` + The unique ID of the tool call. - The index of the first character of the container file citation in the message. + - `String arguments` - - `JsonValue; type "container_file_citation"constant` + A JSON string of the arguments passed to the tool. - The type of the container file citation. Always `container_file_citation`. + - `String name` - - `CONTAINER_FILE_CITATION("container_file_citation")` + The name of the tool that was run. - - `class FilePath:` + - `String serverLabel` - A path to a file. + The label of the MCP server running the tool. - - `String fileId` + - `JsonValue; type "mcp_call"constant` - The ID of the file. + The type of the item. Always `mcp_call`. - - `long index` + - `MCP_CALL("mcp_call")` - The index of the file in the list of files. + - `Optional agent` - - `JsonValue; type "file_path"constant` + The agent that produced this item. - The type of the file path. Always `file_path`. + - `String agentName` - - `FILE_PATH("file_path")` + The canonical name of the agent that produced this item. - - `String text` + - `Optional approvalRequestId` - The text output from the model. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `JsonValue; type "output_text"constant` + - `Optional error` - The type of the output text. Always `output_text`. + The error from the tool call, if any. - - `OUTPUT_TEXT("output_text")` + - `Optional output` - - `Optional> logprobs` + The output from the tool call. - - `String token` + - `Optional status` - - `List bytes` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `double logprob` + - `IN_PROGRESS("in_progress")` - - `List topLogprobs` + - `COMPLETED("completed")` - - `String token` + - `INCOMPLETE("incomplete")` - - `List bytes` + - `CALLING("calling")` - - `double logprob` + - `FAILED("failed")` - - `class BetaResponseOutputRefusal:` + - `McpListTools` - A refusal from the model. + - `String id` - - `String refusal` + The unique ID of the list. - The refusal explanation from the model. + - `String serverLabel` - - `JsonValue; type "refusal"constant` + The label of the MCP server. - The type of the refusal. Always `refusal`. + - `List tools` - - `REFUSAL("refusal")` + The tools available on the server. - - `JsonValue; role "assistant"constant` + - `JsonValue inputSchema` - The role of the output message. Always `assistant`. + The JSON schema describing the tool's input. - - `ASSISTANT("assistant")` + - `String name` - - `Status status` + The name of the tool. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `Optional annotations` - - `IN_PROGRESS("in_progress")` + Additional annotations about the tool. - - `COMPLETED("completed")` + - `Optional description` - - `INCOMPLETE("incomplete")` + The description of the tool. - - `JsonValue; type "message"constant` + - `JsonValue; type "mcp_list_tools"constant` - The type of the output message. Always `message`. + The type of the item. Always `mcp_list_tools`. - - `MESSAGE("message")` + - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` @@ -24731,47 +41793,33 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional 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")` + - `Optional error` - - `class BetaResponseFileSearchToolCall:` + Error message if the server could not list tools. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `McpApprovalRequest` - `String id` - The unique ID of the file search tool call. - - - `List queries` - - The queries used to search for files. - - - `Status status` + The unique ID of the approval request. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `String arguments` - - `IN_PROGRESS("in_progress")` + A JSON string of arguments for the tool. - - `SEARCHING("searching")` + - `String name` - - `COMPLETED("completed")` + The name of the tool to run. - - `INCOMPLETE("incomplete")` + - `String serverLabel` - - `FAILED("failed")` + The label of the MCP server making the request. - - `JsonValue; type "file_search_call"constant` + - `JsonValue; type "mcp_approval_request"constant` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `mcp_approval_request`. - - `FILE_SEARCH_CALL("file_search_call")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - `Optional agent` @@ -24781,68 +41829,49 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional> results` - - The results of the file search tool call. - - - `Optional 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. + - `McpApprovalResponse` - - `String` + - `String id` - - `double` + The unique ID of the approval response - - `boolean` + - `String approvalRequestId` - - `Optional fileId` + The ID of the approval request being answered. - The unique ID of the file. + - `boolean approve` - - `Optional filename` + Whether the request was approved. - The name of the file. + - `JsonValue; type "mcp_approval_response"constant` - - `Optional score` + The type of the item. Always `mcp_approval_response`. - The relevance score of the file - a value between 0 and 1. + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `Optional text` + - `Optional agent` - The text that was retrieved from the file. + The agent that produced this item. - - `class BetaResponseComputerToolCall:` + - `String agentName` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The canonical name of the agent that produced this item. - - `String id` + - `Optional reason` - The unique ID of the computer call. + Optional reason for the decision. - - `String callId` + - `class BetaResponseCustomToolCall:` - An identifier used when responding to the tool call with output. + A call to a custom tool created by the model. - - `List pendingSafetyChecks` + - `class BetaResponseCustomToolCallOutputItem:` - The pending safety checks for the computer call. + The output of a custom tool call from your code, being sent back to the model. - `String id` - The ID of the pending safety check. - - - `Optional code` - - The type of the pending safety check. - - - `Optional message` - - Details about the pending safety check. + The unique ID of the custom tool call output item. - `Status status` @@ -24855,2133 +41884,2179 @@ Get a model response - `INCOMPLETE("incomplete")` - - `Type type` - - The type of the computer call. Always `computer_call`. + - `Optional createdBy` - - `COMPUTER_CALL("computer_call")` + The identifier of the actor that created the item. - - `Optional action` + - `boolean parallelToolCalls` - A click action. + Whether to allow the model to run tool calls in parallel. - - `Click` + - `Optional temperature` - - `Button button` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `ToolChoice toolChoice` - - `LEFT("left")` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `RIGHT("right")` + - `enum BetaToolChoiceOptions:` - - `WHEEL("wheel")` + Controls which (if any) tool is called by the model. - - `BACK("back")` + `none` means the model will not call any tool and instead generates a message. - - `FORWARD("forward")` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `JsonValue; type "click"constant` + `required` means the model must call one or more tools. - Specifies the event type. For a click action, this property is always `click`. + - `NONE("none")` - - `CLICK("click")` + - `AUTO("auto")` - - `long x` + - `REQUIRED("required")` - The x-coordinate where the click occurred. + - `class BetaToolChoiceAllowed:` - - `long y` + Constrains the tools available to the model to a pre-defined set. - The y-coordinate where the click occurred. + - `Mode mode` - - `Optional> keys` + Constrains the tools available to the model to a pre-defined set. - The keys being held while clicking. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `DoubleClick` + `required` requires the model to call one or more of the allowed tools. - - `Optional> keys` + - `AUTO("auto")` - The keys being held while double-clicking. + - `REQUIRED("required")` - - `JsonValue; type "double_click"constant` + - `List tools` - Specifies the event type. For a double click action, this property is always set to `double_click`. + A list of tool definitions that the model should be allowed to call. - - `DOUBLE_CLICK("double_click")` + For the Responses API, the list of tool definitions might look like: - - `long x` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The x-coordinate where the double click occurred. + - `JsonValue; type "allowed_tools"constant` - - `long y` + Allowed tool configuration type. Always `allowed_tools`. - The y-coordinate where the double click occurred. + - `ALLOWED_TOOLS("allowed_tools")` - - `Drag` + - `class BetaToolChoiceTypes:` - - `List path` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `Type type` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `long x` + Allowed values are: - The x-coordinate. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `long y` + - `FILE_SEARCH("file_search")` - The y-coordinate. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `JsonValue; type "drag"constant` + - `COMPUTER("computer")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `DRAG("drag")` + - `COMPUTER_USE("computer_use")` - - `Optional> keys` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - The keys being held while dragging the mouse. + - `IMAGE_GENERATION("image_generation")` - - `Keypress` + - `CODE_INTERPRETER("code_interpreter")` - - `List keys` + - `class BetaToolChoiceFunction:` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Use this option to force the model to call a specific function. - - `JsonValue; type "keypress"constant` + - `String name` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The name of the function to call. - - `KEYPRESS("keypress")` + - `JsonValue; type "function"constant` - - `Move` + For function calling, the type is always `function`. - - `JsonValue; type "move"constant` + - `FUNCTION("function")` - Specifies the event type. For a move action, this property is always set to `move`. + - `class BetaToolChoiceMcp:` - - `MOVE("move")` + Use this option to force the model to call a specific tool on a remote MCP server. - - `long x` + - `String serverLabel` - The x-coordinate to move to. + The label of the MCP server to use. - - `long y` + - `JsonValue; type "mcp"constant` - The y-coordinate to move to. + For MCP tools, the type is always `mcp`. - - `Optional> keys` + - `MCP("mcp")` - The keys being held while moving the mouse. + - `Optional name` - - `JsonValue;` + The name of the tool to call on the server. - - `JsonValue; type "screenshot"constant` + - `class BetaToolChoiceCustom:` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Use this option to force the model to call a specific custom tool. - - `SCREENSHOT("screenshot")` + - `String name` - - `Scroll` + The name of the custom tool to call. - - `long scrollX` + - `JsonValue; type "custom"constant` - The horizontal scroll distance. + For custom tool calling, the type is always `custom`. - - `long scrollY` + - `CUSTOM("custom")` - The vertical scroll distance. + - `JsonValue;` - - `JsonValue; type "scroll"constant` + - `JsonValue; type "programmatic_tool_calling"constant` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The tool to call. Always `programmatic_tool_calling`. - - `SCROLL("scroll")` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `long x` + - `class BetaToolChoiceApplyPatch:` - The x-coordinate where the scroll occurred. + Forces the model to call the apply_patch tool when executing a tool call. - - `long y` + - `JsonValue; type "apply_patch"constant` - The y-coordinate where the scroll occurred. + The tool to call. Always `apply_patch`. - - `Optional> keys` + - `APPLY_PATCH("apply_patch")` - The keys being held while scrolling. + - `class BetaToolChoiceShell:` - - `Type` + Forces the model to call the shell tool when a tool call is required. - - `String text` + - `JsonValue; type "shell"constant` - The text to type. + The tool to call. Always `shell`. - - `JsonValue; type "type"constant` + - `SHELL("shell")` - Specifies the event type. For a type action, this property is always set to `type`. + - `List tools` - - `TYPE("type")` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `JsonValue;` + We support the following categories of tools: - - `JsonValue; type "wait"constant` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `class BetaFunctionTool:` - - `WAIT("wait")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `Optional> actions` + - `class BetaFileSearchTool:` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Click` + - `class BetaComputerTool:` - - `DoubleClick` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Drag` + - `class BetaComputerUsePreviewTool:` - - `Keypress` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Move` + - `class BetaWebSearchTool:` - - `JsonValue;` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Scroll` + - `Mcp` - - `Type` + - `CodeInterpreter` - `JsonValue;` - - `Optional agent` + - `ImageGeneration` - The agent that produced this item. + - `JsonValue;` - - `String agentName` + - `class BetaFunctionShellTool:` - The canonical name of the agent that produced this item. + A tool that allows the model to execute shell commands. - - `ComputerCallOutput` + - `class BetaCustomTool:` - - `String callId` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The ID of the computer tool call that produced the output. + - `class BetaNamespaceTool:` - - `BetaResponseComputerToolCallOutputScreenshot output` + Groups function/custom tools under a shared namespace. - A computer screenshot image used with the computer use tool. + - `class BetaToolSearchTool:` - - `JsonValue; type "computer_screenshot"constant` + Hosted or BYOT tool search configuration for deferred tools. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `class BetaWebSearchPreviewTool:` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional fileId` + - `class BetaApplyPatchTool:` - The identifier of an uploaded file that contains the screenshot. + Allows the assistant to create, delete, or update files using unified diffs. - - `Optional imageUrl` + - `Optional topP` - The URL of the screenshot image. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `JsonValue; type "computer_call_output"constant` + We generally recommend altering this or `temperature` but not both. - The type of the computer tool call output. Always `computer_call_output`. + - `Optional background` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `Optional id` + - `Optional completedAt` - The ID of the computer tool call output. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Optional> acknowledgedSafetyChecks` + - `Optional conversation` - The safety checks reported by the API that have been acknowledged by the developer. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - `String id` - The ID of the pending safety check. - - - `Optional code` - - The type of the pending safety check. - - - `Optional message` + The unique ID of the conversation that this response was associated with. - Details about the pending safety check. + - `Optional maxOutputTokens` - - `Optional agent` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The agent that produced this item. + - `Optional maxToolCalls` - - `String agentName` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The canonical name of the agent that produced this item. + - `Optional moderation` - - `Optional status` + Moderation results for the response input and output, if moderated completions were requested. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `Input input` - - `IN_PROGRESS("in_progress")` + Moderation for the response input. - - `COMPLETED("completed")` + - `class ModerationResult:` - - `INCOMPLETE("incomplete")` + A moderation result produced for the response input or output. - - `class BetaResponseFunctionWebSearch:` + - `Categories categories` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `String id` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - The unique ID of the web search tool call. + Which modalities of input are reflected by the score for each category. - - `Action action` + - `TEXT("text")` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `IMAGE("image")` - - `class Search:` + - `CategoryScores categoryScores` - Action type "search" - Performs a web search query. + A dictionary of moderation categories to scores. - - `JsonValue; type "search"constant` + - `boolean flagged` - The action type. + A boolean indicating whether the content was flagged by any category. - - `SEARCH("search")` + - `String model` - - `Optional> queries` + The moderation model that produced this result. - The search queries. + - `JsonValue; type "moderation_result"constant` - - `Optional query` + The object type, which was always `moderation_result` for successful moderation results. - The search query. + - `MODERATION_RESULT("moderation_result")` - - `Optional> sources` + - `class Error:` - The sources used in the search. + An error produced while attempting moderation for the response input or output. - - `JsonValue; type "url"constant` + - `String code` - The type of source. Always `url`. + The error code. - - `URL("url")` + - `String message` - - `String url` + The error message. - The URL of the source. + - `JsonValue; type "error"constant` - - `class OpenPage:` + The object type, which was always `error` for moderation failures. - Action type "open_page" - Opens a specific URL from search results. + - `ERROR("error")` - - `JsonValue; type "open_page"constant` + - `Output output` - The action type. + Moderation for the response output. - - `OPEN_PAGE("open_page")` + - `class ModerationResult:` - - `Optional url` + A moderation result produced for the response input or output. - The URL opened by the model. + - `Categories categories` - - `class FindInPage:` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `String pattern` + Which modalities of input are reflected by the score for each category. - The pattern or text to search for within the page. + - `TEXT("text")` - - `JsonValue; type "find_in_page"constant` + - `IMAGE("image")` - The action type. + - `CategoryScores categoryScores` - - `FIND_IN_PAGE("find_in_page")` + A dictionary of moderation categories to scores. - - `String url` + - `boolean flagged` - The URL of the page searched for the pattern. + A boolean indicating whether the content was flagged by any category. - - `Status status` + - `String model` - The status of the web search tool call. + The moderation model that produced this result. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "moderation_result"constant` - - `SEARCHING("searching")` + The object type, which was always `moderation_result` for successful moderation results. - - `COMPLETED("completed")` + - `MODERATION_RESULT("moderation_result")` - - `FAILED("failed")` + - `class Error:` - - `JsonValue; type "web_search_call"constant` + An error produced while attempting moderation for the response input or output. - The type of the web search tool call. Always `web_search_call`. + - `String code` - - `WEB_SEARCH_CALL("web_search_call")` + The error code. - - `Optional agent` + - `String message` - The agent that produced this item. + The error message. - - `String agentName` + - `JsonValue; type "error"constant` - The canonical name of the agent that produced this item. + The object type, which was always `error` for moderation failures. - - `class BetaResponseFunctionToolCall:` + - `ERROR("error")` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `Optional previousResponseId` - - `String arguments` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - A JSON string of the arguments to pass to the function. + - `Optional prompt` - - `String callId` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The unique ID of the function tool call generated by the model. + - `String id` - - `String name` + The unique identifier of the prompt template to use. - The name of the function to run. + - `Optional variables` - - `JsonValue; type "function_call"constant` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The type of the function tool call. Always `function_call`. + - `String` - - `FUNCTION_CALL("function_call")` + - `class BetaResponseInputText:` - - `Optional id` + A text input to the model. - The unique ID of the function tool call. + - `class BetaResponseInputImage:` - - `Optional agent` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The agent that produced this item. + - `class BetaResponseInputFile:` - - `String agentName` + A file input to the model. - The canonical name of the agent that produced this item. + - `Optional version` - - `Optional caller` + Optional version of the prompt template. - The execution context that produced this tool call. + - `Optional promptCacheKey` - - `JsonValue;` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `JsonValue; type "direct"constant` + - `Optional promptCacheOptions` - - `DIRECT("direct")` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `class Program:` + - `Mode mode` - - `String callerId` + Whether implicit prompt-cache breakpoints were enabled. - The call ID of the program item that produced this tool call. + - `IMPLICIT("implicit")` - - `JsonValue; type "program"constant` + - `EXPLICIT("explicit")` - - `PROGRAM("program")` + - `Ttl ttl` - - `Optional namespace` + The minimum lifetime applied to each cache breakpoint. - The namespace of the function to run. + - `_30M("30m")` - - `Optional status` + - `Optional promptCacheRetention` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `IN_PROGRESS("in_progress")` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `COMPLETED("completed")` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `INCOMPLETE("incomplete")` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `FunctionCallOutput` + - `IN_MEMORY("in_memory")` - - `String callId` + - `_24H("24h")` - The unique ID of the function tool call generated by the model. + - `Optional reasoning` - - `Output output` + **gpt-5 and o-series models only** - Text, image, or file output of the function tool call. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `String` + - `Optional context` - - `List` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `class BetaResponseInputTextContent:` + - `AUTO("auto")` - A text input to the model. + - `CURRENT_TURN("current_turn")` - - `String text` + - `ALL_TURNS("all_turns")` - The text input to the model. + - `Optional effort` - - `JsonValue; type "input_text"constant` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The type of the input item. Always `input_text`. + - `NONE("none")` - - `INPUT_TEXT("input_text")` + - `MINIMAL("minimal")` - - `Optional promptCacheBreakpoint` + - `LOW("low")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `MEDIUM("medium")` - - `JsonValue; mode "explicit"constant` + - `HIGH("high")` - The breakpoint mode. Always `explicit`. + - `XHIGH("xhigh")` - - `EXPLICIT("explicit")` + - `MAX("max")` - - `class BetaResponseInputImageContent:` + - `Optional generateSummary` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + **Deprecated:** use `summary` instead. - - `JsonValue; type "input_image"constant` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The type of the input item. Always `input_image`. + - `AUTO("auto")` - - `INPUT_IMAGE("input_image")` + - `CONCISE("concise")` - - `Optional detail` + - `DETAILED("detailed")` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Optional mode` - - `LOW("low")` + Controls the reasoning execution mode for the request. - - `HIGH("high")` + When returned on a response, this is the effective execution mode. - - `AUTO("auto")` + - `STANDARD("standard")` - - `ORIGINAL("original")` + - `PRO("pro")` - - `Optional fileId` + - `Optional summary` - The ID of the file to be sent to the model. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `Optional imageUrl` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `AUTO("auto")` - - `Optional promptCacheBreakpoint` + - `CONCISE("concise")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `DETAILED("detailed")` - - `JsonValue; mode "explicit"constant` + - `Optional safetyIdentifier` - The breakpoint mode. Always `explicit`. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `EXPLICIT("explicit")` + - `Optional serviceTier` - - `class BetaResponseInputFileContent:` + Specifies the processing type used for serving the request. - A file input to the model. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `JsonValue; type "input_file"constant` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The type of the input item. Always `input_file`. + - `AUTO("auto")` - - `INPUT_FILE("input_file")` + - `DEFAULT("default")` - - `Optional detail` + - `FLEX("flex")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `SCALE("scale")` - - `AUTO("auto")` + - `PRIORITY("priority")` - - `LOW("low")` + - `Optional status` - - `HIGH("high")` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `Optional fileData` + - `COMPLETED("completed")` - The base64-encoded data of the file to be sent to the model. + - `FAILED("failed")` - - `Optional fileId` + - `IN_PROGRESS("in_progress")` - The ID of the file to be sent to the model. + - `CANCELLED("cancelled")` - - `Optional fileUrl` + - `QUEUED("queued")` - The URL of the file to be sent to the model. + - `INCOMPLETE("incomplete")` - - `Optional filename` + - `Optional text` - The name of the file to be sent to the model. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `Optional promptCacheBreakpoint` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional format` - - `JsonValue; mode "explicit"constant` + An object specifying the format that the model must output. - The breakpoint mode. Always `explicit`. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `EXPLICIT("explicit")` + The default format is `{ "type": "text" }` with no additional options. - - `JsonValue; type "function_call_output"constant` + **Not recommended for gpt-4o and newer models:** - The type of the function tool call output. Always `function_call_output`. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `JsonValue;` - - `Optional id` + - `JsonValue; type "text"constant` - The unique ID of the function tool call output. Populated when this item is returned via API. + The type of response format being defined. Always `text`. - - `Optional agent` + - `TEXT("text")` - The agent that produced this item. + - `class BetaResponseFormatTextJsonSchemaConfig:` - - `String agentName` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The canonical name of the agent that produced this item. + - `String name` - - `Optional caller` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The execution context that produced this tool call. + - `Schema schema` - - `JsonValue;` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `JsonValue; type "direct"constant` + - `JsonValue; type "json_schema"constant` - The caller type. Always `direct`. + The type of response format being defined. Always `json_schema`. - - `DIRECT("direct")` + - `JSON_SCHEMA("json_schema")` - - `class Program:` + - `Optional description` - - `String callerId` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The call ID of the program item that produced this tool call. + - `Optional strict` - - `JsonValue; type "program"constant` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The caller type. Always `program`. + - `JsonValue;` - - `PROGRAM("program")` + - `JsonValue; type "json_object"constant` - - `Optional status` + The type of response format being defined. Always `json_object`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `JSON_OBJECT("json_object")` - - `IN_PROGRESS("in_progress")` + - `Optional verbosity` - - `COMPLETED("completed")` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `INCOMPLETE("incomplete")` + - `LOW("low")` - - `AgentMessage` + - `MEDIUM("medium")` - - `String author` + - `HIGH("high")` - The sending agent identity. + - `Optional topLogprobs` - - `List content` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - Plaintext, image, or encrypted content sent between agents. + - `Optional truncation` - - `class BetaResponseInputTextContent:` + The truncation strategy to use for the model response. - A text input to the model. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `class BetaResponseInputImageContent:` + - `AUTO("auto")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `DISABLED("disabled")` - - `class EncryptedContent:` + - `Optional usage` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `String encryptedContent` + - `long inputTokens` - Opaque encrypted content. + The number of input tokens. - - `JsonValue; type "encrypted_content"constant` + - `InputTokensDetails inputTokensDetails` - The type of the input item. Always `encrypted_content`. + A detailed breakdown of the input tokens. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `long cacheWriteTokens` - - `String recipient` + The number of input tokens that were written to the cache. - The destination agent identity. + - `long cachedTokens` - - `JsonValue; type "agent_message"constant` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The item type. Always `agent_message`. + - `long outputTokens` - - `AGENT_MESSAGE("agent_message")` + The number of output tokens. - - `Optional id` + - `OutputTokensDetails outputTokensDetails` - The unique ID of this agent message item. + A detailed breakdown of the output tokens. - - `Optional agent` + - `long reasoningTokens` - The agent that produced this item. + The number of reasoning tokens. - - `String agentName` + - `long totalTokens` - The canonical name of the agent that produced this item. + The total number of tokens used. - - `MultiAgentCall` + - `Optional user` - - `Action action` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The multi-agent action that was executed. +### Beta Response Apply Patch Tool Call - - `SPAWN_AGENT("spawn_agent")` +- `class BetaResponseApplyPatchToolCall:` - - `INTERRUPT_AGENT("interrupt_agent")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `LIST_AGENTS("list_agents")` + - `String id` - - `SEND_MESSAGE("send_message")` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `FOLLOWUP_TASK("followup_task")` + - `String callId` - - `WAIT_AGENT("wait_agent")` + The unique ID of the apply patch tool call generated by the model. - - `String arguments` + - `Operation operation` - The action arguments as a JSON string. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `String callId` + - `class CreateFile:` - The unique ID linking this call to its output. + Instruction describing how to create a file via the apply_patch tool. - - `JsonValue; type "multi_agent_call"constant` + - `String diff` - The item type. Always `multi_agent_call`. + Diff to apply. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `String path` - - `Optional id` + Path of the file to create. - The unique ID of this multi-agent call. + - `JsonValue; type "create_file"constant` - - `Optional agent` + Create a new file with the provided diff. - The agent that produced this item. + - `CREATE_FILE("create_file")` - - `String agentName` + - `class DeleteFile:` - The canonical name of the agent that produced this item. + Instruction describing how to delete a file via the apply_patch tool. - - `MultiAgentCallOutput` + - `String path` - - `Action action` + Path of the file to delete. - The multi-agent action that produced this result. + - `JsonValue; type "delete_file"constant` - - `SPAWN_AGENT("spawn_agent")` + Delete the specified file. - - `INTERRUPT_AGENT("interrupt_agent")` + - `DELETE_FILE("delete_file")` - - `LIST_AGENTS("list_agents")` + - `class UpdateFile:` - - `SEND_MESSAGE("send_message")` + Instruction describing how to update a file via the apply_patch tool. - - `FOLLOWUP_TASK("followup_task")` + - `String diff` - - `WAIT_AGENT("wait_agent")` + Diff to apply. - - `String callId` + - `String path` - The unique ID of the multi-agent call. + Path of the file to update. - - `List output` + - `JsonValue; type "update_file"constant` - Text output returned by the multi-agent action. + Update an existing file with the provided diff. - - `String text` + - `UPDATE_FILE("update_file")` - The text content. + - `Status status` - - `JsonValue; type "output_text"constant` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The content type. Always `output_text`. + - `IN_PROGRESS("in_progress")` - - `OUTPUT_TEXT("output_text")` + - `COMPLETED("completed")` - - `Optional annotations` + - `JsonValue; type "apply_patch_call"constant` - Citations associated with the text content. + The type of the item. Always `apply_patch_call`. - - `List` + - `APPLY_PATCH_CALL("apply_patch_call")` - - `String fileId` + - `Optional agent` - The ID of the file. + The agent that produced this item. - - `String filename` + - `String agentName` - The filename of the file cited. + The canonical name of the agent that produced this item. - - `long index` + - `Optional caller` - The index of the file in the list of files. + The execution context that produced this tool call. - - `JsonValue; type "file_citation"constant` + - `JsonValue;` - The citation type. Always `file_citation`. + - `JsonValue; type "direct"constant` - - `FILE_CITATION("file_citation")` + - `DIRECT("direct")` - - `List` + - `class Program:` - - `long endIndex` + - `String callerId` - The index of the last character of the citation in the message. + The call ID of the program item that produced this tool call. - - `long startIndex` + - `JsonValue; type "program"constant` - The index of the first character of the citation in the message. + - `PROGRAM("program")` - - `String title` + - `Optional createdBy` - The title of the cited resource. + The ID of the entity that created this tool call. - - `JsonValue; type "url_citation"constant` +### Beta Response Apply Patch Tool Call Output - The citation type. Always `url_citation`. +- `class BetaResponseApplyPatchToolCallOutput:` - - `URL_CITATION("url_citation")` + The output emitted by an apply patch tool call. - - `String url` + - `String id` - The URL of the cited resource. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `List` + - `String callId` - - `String containerId` + The unique ID of the apply patch tool call generated by the model. - The ID of the container. + - `Status status` - - `long endIndex` + The status of the apply patch tool call output. One of `completed` or `failed`. - The index of the last character of the citation in the message. + - `COMPLETED("completed")` - - `String fileId` + - `FAILED("failed")` - The ID of the container file. + - `JsonValue; type "apply_patch_call_output"constant` - - `String filename` + The type of the item. Always `apply_patch_call_output`. - The filename of the container file cited. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `long startIndex` + - `Optional agent` - The index of the first character of the citation in the message. + The agent that produced this item. - - `JsonValue; type "container_file_citation"constant` + - `String agentName` - The citation type. Always `container_file_citation`. + The canonical name of the agent that produced this item. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `Optional caller` - - `JsonValue; type "multi_agent_call_output"constant` + The execution context that produced this tool call. - The item type. Always `multi_agent_call_output`. + - `JsonValue;` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `JsonValue; type "direct"constant` - - `Optional id` + - `DIRECT("direct")` - The unique ID of this multi-agent call output. + - `class Program:` - - `Optional agent` + - `String callerId` - The agent that produced this item. + The call ID of the program item that produced this tool call. - - `String agentName` + - `JsonValue; type "program"constant` - The canonical name of the agent that produced this item. + - `PROGRAM("program")` - - `ToolSearchCall` + - `Optional createdBy` - - `JsonValue arguments` + The ID of the entity that created this tool call output. - The arguments supplied to the tool search call. + - `Optional output` - - `JsonValue; type "tool_search_call"constant` + Optional textual output returned by the apply patch tool. - The item type. Always `tool_search_call`. +### Beta Response Audio Delta Event - - `TOOL_SEARCH_CALL("tool_search_call")` +- `class BetaResponseAudioDeltaEvent:` - - `Optional id` + Emitted when there is a partial audio response. - The unique ID of this tool search call. + - `String delta` - - `Optional agent` + A chunk of Base64 encoded response audio bytes. - The agent that produced this item. + - `long sequenceNumber` - - `String agentName` + A sequence number for this chunk of the stream response. - The canonical name of the agent that produced this item. + - `JsonValue; type "response.audio.delta"constant` - - `Optional callId` + The type of the event. Always `response.audio.delta`. - The unique ID of the tool search call generated by the model. + - `RESPONSE_AUDIO_DELTA("response.audio.delta")` - - `Optional execution` + - `Optional agent` - Whether tool search was executed by the server or by the client. + The agent that owns this multi-agent streaming event. - - `SERVER("server")` + - `String agentName` - - `CLIENT("client")` + The canonical name of the agent that produced this item. - - `Optional status` +### Beta Response Audio Done Event - The status of the tool search call. +- `class BetaResponseAudioDoneEvent:` - - `IN_PROGRESS("in_progress")` + Emitted when the audio response is complete. - - `COMPLETED("completed")` + - `long sequenceNumber` - - `INCOMPLETE("incomplete")` + The sequence number of the delta. - - `class BetaResponseToolSearchOutputItemParam:` + - `JsonValue; type "response.audio.done"constant` - - `List tools` + The type of the event. Always `response.audio.done`. - The loaded tool definitions returned by the tool search output. + - `RESPONSE_AUDIO_DONE("response.audio.done")` - - `class BetaFunctionTool:` + - `Optional agent` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The agent that owns this multi-agent streaming event. - - `String name` + - `String agentName` - The name of the function to call. + The canonical name of the agent that produced this item. - - `Optional parameters` +### Beta Response Audio Transcript Delta Event - A JSON schema object describing the parameters of the function. +- `class BetaResponseAudioTranscriptDeltaEvent:` - - `Optional strict` + Emitted when there is a partial transcript of audio. - Whether strict parameter validation is enforced for this function tool. + - `String delta` - - `JsonValue; type "function"constant` + The partial transcript of the audio response. - The type of the function tool. Always `function`. + - `long sequenceNumber` - - `FUNCTION("function")` + The sequence number of this event. - - `Optional> allowedCallers` + - `JsonValue; type "response.audio.transcript.delta"constant` - The tool invocation context(s). + The type of the event. Always `response.audio.transcript.delta`. - - `DIRECT("direct")` + - `RESPONSE_AUDIO_TRANSCRIPT_DELTA("response.audio.transcript.delta")` - - `PROGRAMMATIC("programmatic")` + - `Optional agent` - - `Optional deferLoading` + The agent that owns this multi-agent streaming event. - Whether this function is deferred and loaded via tool search. + - `String agentName` - - `Optional description` + The canonical name of the agent that produced this item. - A description of the function. Used by the model to determine whether or not to call the function. +### Beta Response Audio Transcript Done Event - - `Optional outputSchema` +- `class BetaResponseAudioTranscriptDoneEvent:` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Emitted when the full audio transcript is completed. - - `class BetaFileSearchTool:` + - `long sequenceNumber` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The sequence number of this event. - - `JsonValue; type "file_search"constant` + - `JsonValue; type "response.audio.transcript.done"constant` - The type of the file search tool. Always `file_search`. + The type of the event. Always `response.audio.transcript.done`. - - `FILE_SEARCH("file_search")` + - `RESPONSE_AUDIO_TRANSCRIPT_DONE("response.audio.transcript.done")` - - `List vectorStoreIds` + - `Optional agent` - The IDs of the vector stores to search. + The agent that owns this multi-agent streaming event. - - `Optional filters` + - `String agentName` - A filter to apply. + The canonical name of the agent that produced this item. - - `class ComparisonFilter:` +### Beta Response Code Interpreter Call Code Delta Event - A filter used to compare a specified attribute key to a given value using a defined comparison operation. +- `class BetaResponseCodeInterpreterCallCodeDeltaEvent:` - - `String key` + Emitted when a partial code snippet is streamed by the code interpreter. - The key to compare against the value. + - `String delta` - - `Type type` + The partial code snippet being streamed by the code interpreter. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `String itemId` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The unique identifier of the code interpreter tool call item. - - `EQ("eq")` + - `long outputIndex` - - `NE("ne")` + The index of the output item in the response for which the code is being streamed. - - `GT("gt")` + - `long sequenceNumber` - - `GTE("gte")` + The sequence number of this event, used to order streaming events. - - `LT("lt")` + - `JsonValue; type "response.code_interpreter_call_code.delta"constant` - - `LTE("lte")` + The type of the event. Always `response.code_interpreter_call_code.delta`. - - `IN("in")` + - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DELTA("response.code_interpreter_call_code.delta")` - - `NIN("nin")` + - `Optional agent` - - `Value value` + The agent that owns this multi-agent streaming event. - The value to compare against the attribute key; supports string, number, or boolean types. + - `String agentName` - - `String` + The canonical name of the agent that produced this item. - - `double` +### Beta Response Code Interpreter Call Code Done Event - - `boolean` +- `class BetaResponseCodeInterpreterCallCodeDoneEvent:` - - `List` + Emitted when the code snippet is finalized by the code interpreter. - - `class CompoundFilter:` + - `String code` - Combine multiple filters using `and` or `or`. + The final code snippet output by the code interpreter. - - `List filters` + - `String itemId` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The unique identifier of the code interpreter tool call item. - - `class ComparisonFilter:` + - `long outputIndex` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The index of the output item in the response for which the code is finalized. - - `String key` + - `long sequenceNumber` - The key to compare against the value. + The sequence number of this event, used to order streaming events. - - `Type type` + - `JsonValue; type "response.code_interpreter_call_code.done"constant` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the event. Always `response.code_interpreter_call_code.done`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DONE("response.code_interpreter_call_code.done")` - - `EQ("eq")` + - `Optional agent` - - `NE("ne")` + The agent that owns this multi-agent streaming event. - - `GT("gt")` + - `String agentName` - - `GTE("gte")` + The canonical name of the agent that produced this item. - - `LT("lt")` +### Beta Response Code Interpreter Call Completed Event - - `LTE("lte")` +- `class BetaResponseCodeInterpreterCallCompletedEvent:` - - `IN("in")` + Emitted when the code interpreter call is completed. - - `NIN("nin")` + - `String itemId` - - `Value value` + The unique identifier of the code interpreter tool call item. - The value to compare against the attribute key; supports string, number, or boolean types. + - `long outputIndex` - - `String` + The index of the output item in the response for which the code interpreter call is completed. - - `double` + - `long sequenceNumber` - - `boolean` + The sequence number of this event, used to order streaming events. - - `List` + - `JsonValue; type "response.code_interpreter_call.completed"constant` - - `JsonValue` + The type of the event. Always `response.code_interpreter_call.completed`. - - `Type type` + - `RESPONSE_CODE_INTERPRETER_CALL_COMPLETED("response.code_interpreter_call.completed")` - Type of operation: `and` or `or`. + - `Optional agent` - - `AND("and")` + The agent that owns this multi-agent streaming event. - - `OR("or")` + - `String agentName` - - `Optional maxNumResults` + The canonical name of the agent that produced this item. - The maximum number of results to return. This number should be between 1 and 50 inclusive. +### Beta Response Code Interpreter Call In Progress Event - - `Optional rankingOptions` +- `class BetaResponseCodeInterpreterCallInProgressEvent:` - Ranking options for search. + Emitted when a code interpreter call is in progress. - - `Optional hybridSearch` + - `String itemId` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The unique identifier of the code interpreter tool call item. - - `double embeddingWeight` + - `long outputIndex` - The weight of the embedding in the reciprocal ranking fusion. + The index of the output item in the response for which the code interpreter call is in progress. - - `double textWeight` + - `long sequenceNumber` - The weight of the text in the reciprocal ranking fusion. + The sequence number of this event, used to order streaming events. - - `Optional ranker` + - `JsonValue; type "response.code_interpreter_call.in_progress"constant` - The ranker to use for the file search. + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `AUTO("auto")` + - `RESPONSE_CODE_INTERPRETER_CALL_IN_PROGRESS("response.code_interpreter_call.in_progress")` - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `Optional agent` - - `Optional scoreThreshold` + The agent that owns this multi-agent streaming event. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `String agentName` - - `class BetaComputerTool:` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +### Beta Response Code Interpreter Call Interpreting Event - - `JsonValue; type "computer"constant` +- `class BetaResponseCodeInterpreterCallInterpretingEvent:` - The type of the computer tool. Always `computer`. + Emitted when the code interpreter is actively interpreting the code snippet. - - `COMPUTER("computer")` + - `String itemId` - - `class BetaComputerUsePreviewTool:` + The unique identifier of the code interpreter tool call item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `long outputIndex` - - `long displayHeight` + The index of the output item in the response for which the code interpreter is interpreting code. - The height of the computer display. + - `long sequenceNumber` - - `long displayWidth` + The sequence number of this event, used to order streaming events. - The width of the computer display. + - `JsonValue; type "response.code_interpreter_call.interpreting"constant` - - `Environment environment` + The type of the event. Always `response.code_interpreter_call.interpreting`. - The type of computer environment to control. + - `RESPONSE_CODE_INTERPRETER_CALL_INTERPRETING("response.code_interpreter_call.interpreting")` - - `WINDOWS("windows")` + - `Optional agent` - - `MAC("mac")` + The agent that owns this multi-agent streaming event. - - `LINUX("linux")` + - `String agentName` - - `UBUNTU("ubuntu")` + The canonical name of the agent that produced this item. - - `BROWSER("browser")` +### Beta Response Code Interpreter Tool Call - - `JsonValue; type "computer_use_preview"constant` +- `class BetaResponseCodeInterpreterToolCall:` - The type of the computer use tool. Always `computer_use_preview`. + A tool call to run code. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `String id` - - `class BetaWebSearchTool:` + The unique ID of the code interpreter tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional code` - - `Type type` + The code to run, or null if not available. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `String containerId` - - `WEB_SEARCH("web_search")` + The ID of the container used to run the code. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `Optional> outputs` - - `Optional filters` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - Filters for the search. + - `class Logs:` - - `Optional> allowedDomains` + The logs output from the code interpreter. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `String logs` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The logs output from the code interpreter. - - `Optional searchContextSize` + - `JsonValue; type "logs"constant` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the output. Always `logs`. - - `LOW("low")` + - `LOGS("logs")` - - `MEDIUM("medium")` + - `class Image:` - - `HIGH("high")` + The image output from the code interpreter. - - `Optional userLocation` + - `JsonValue; type "image"constant` - The approximate location of the user. + The type of the output. Always `image`. - - `Optional city` + - `IMAGE("image")` - Free text input for the city of the user, e.g. `San Francisco`. + - `String url` - - `Optional country` + The URL of the image output from the code interpreter. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Status status` - - `Optional region` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Free text input for the region of the user, e.g. `California`. + - `IN_PROGRESS("in_progress")` - - `Optional timezone` + - `COMPLETED("completed")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `INCOMPLETE("incomplete")` - - `Optional type` + - `INTERPRETING("interpreting")` - The type of location approximation. Always `approximate`. + - `FAILED("failed")` - - `APPROXIMATE("approximate")` + - `JsonValue; type "code_interpreter_call"constant` - - `Mcp` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `String serverLabel` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - A label for this MCP server, used to identify it in tool calls. + - `Optional agent` - - `JsonValue; type "mcp"constant` + The agent that produced this item. - The type of the MCP tool. Always `mcp`. + - `String agentName` - - `MCP("mcp")` + The canonical name of the agent that produced this item. - - `Optional> allowedCallers` +### Beta Response Compaction Item - The tool invocation context(s). +- `class BetaResponseCompactionItem:` - - `DIRECT("direct")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `PROGRAMMATIC("programmatic")` + - `String id` - - `Optional allowedTools` + The unique ID of the compaction item. - List of allowed tool names or a filter object. + - `String encryptedContent` - - `List` + The encrypted content that was produced by compaction. - - `class McpToolFilter:` + - `JsonValue; type "compaction"constant` - A filter object to specify which tools are allowed. + The type of the item. Always `compaction`. - - `Optional readOnly` + - `COMPACTION("compaction")` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Optional agent` - - `Optional> toolNames` + The agent that produced this item. - List of allowed tool names. + - `String agentName` - - `Optional authorization` + The canonical name of the agent that produced this item. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `Optional createdBy` - - `Optional connectorId` + The identifier of the actor that created the item. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). +### Beta Response Compaction Item Param - Currently supported `connector_id` values are: +- `class BetaResponseCompactionItemParam:` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `String encryptedContent` - - `CONNECTOR_GMAIL("connector_gmail")` + The encrypted content of the compaction summary. - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `JsonValue; type "compaction"constant` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + The type of the item. Always `compaction`. - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `COMPACTION("compaction")` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `Optional id` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + The ID of the compaction item. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `Optional agent` - - `Optional deferLoading` + The agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `String agentName` - - `Optional headers` + The canonical name of the agent that produced this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. +### Beta Response Completed Event - - `Optional requireApproval` +- `class BetaResponseCompletedEvent:` - Specify which of the MCP server's tools require approval. + Emitted when the model response is complete. - - `class McpToolApprovalFilter:` + - `BetaResponse response` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Properties of the completed response. - - `Optional always` + - `String id` - A filter object to specify which tools are allowed. + Unique identifier for this Response. - - `Optional readOnly` + - `double createdAt` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Unix timestamp (in seconds) of when this Response was created. - - `Optional> toolNames` + - `Optional error` - List of allowed tool names. + An error object returned when the model fails to generate a Response. - - `Optional never` + - `Code code` - A filter object to specify which tools are allowed. + The error code for the response. - - `Optional readOnly` + - `SERVER_ERROR("server_error")` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `Optional> toolNames` + - `INVALID_PROMPT("invalid_prompt")` - List of allowed tool names. + - `BIO_POLICY("bio_policy")` - - `enum McpToolApprovalSetting:` + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `INVALID_IMAGE("invalid_image")` - - `ALWAYS("always")` + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - - `NEVER("never")` + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - - `Optional serverDescription` + - `INVALID_IMAGE_URL("invalid_image_url")` - Optional description of the MCP server, used to provide more context. + - `IMAGE_TOO_LARGE("image_too_large")` - - `Optional serverUrl` + - `IMAGE_TOO_SMALL("image_too_small")` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `IMAGE_PARSE_ERROR("image_parse_error")` - - `Optional tunnelId` + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `INVALID_IMAGE_MODE("invalid_image_mode")` - - `CodeInterpreter` + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `Container container` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `EMPTY_IMAGE_FILE("empty_image_file")` - - `String` + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - - `class CodeInterpreterToolAuto:` + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `String message` - - `JsonValue; type "auto"constant` + A human-readable description of the error. - Always `auto`. + - `Optional incompleteDetails` - - `AUTO("auto")` + Details about why the response is incomplete. - - `Optional> fileIds` + - `Optional reason` - An optional list of uploaded files to make available to your code. + The reason why the response is incomplete. - - `Optional memoryLimit` + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - The memory limit for the code interpreter container. + - `CONTENT_FILTER("content_filter")` - - `_1G("1g")` + - `Optional instructions` - - `_4G("4g")` + A system (or developer) message inserted into the model's context. - - `_16G("16g")` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `_64G("64g")` + - `String` - - `Optional networkPolicy` + - `List` - Network access policy for the container. + - `class BetaEasyInputMessage:` - - `class BetaContainerNetworkPolicyDisabled:` + 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. - - `JsonValue; type "disabled"constant` + - `Content content` - Disable outbound network access. Always `disabled`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `DISABLED("disabled")` + - `String` - - `class BetaContainerNetworkPolicyAllowlist:` + - `List` - - `List allowedDomains` + - `class BetaResponseInputText:` - A list of allowed domains when type is `allowlist`. + A text input to the model. - - `JsonValue; type "allowlist"constant` + - `String text` - Allow outbound network access only to specified domains. Always `allowlist`. + The text input to the model. - - `ALLOWLIST("allowlist")` + - `JsonValue; type "input_text"constant` - - `Optional> domainSecrets` + The type of the input item. Always `input_text`. - Optional domain-scoped secrets for allowlisted domains. + - `INPUT_TEXT("input_text")` - - `String domain` + - `Optional promptCacheBreakpoint` - The domain associated with the secret. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String name` + - `JsonValue; mode "explicit"constant` - The name of the secret to inject for the domain. + The breakpoint mode. Always `explicit`. - - `String value` + - `EXPLICIT("explicit")` - The secret value to inject for the domain. + - `class BetaResponseInputImage:` - - `JsonValue; type "code_interpreter"constant` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The type of the code interpreter tool. Always `code_interpreter`. + - `Detail detail` - - `CODE_INTERPRETER("code_interpreter")` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Optional> allowedCallers` + - `LOW("low")` - The tool invocation context(s). + - `HIGH("high")` - - `DIRECT("direct")` + - `AUTO("auto")` - - `PROGRAMMATIC("programmatic")` + - `ORIGINAL("original")` - - `JsonValue;` + - `JsonValue; type "input_image"constant` - - `JsonValue; type "programmatic_tool_calling"constant` + The type of the input item. Always `input_image`. - The type of the tool. Always `programmatic_tool_calling`. + - `INPUT_IMAGE("input_image")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional fileId` - - `ImageGeneration` + The ID of the file to be sent to the model. - - `JsonValue; type "image_generation"constant` + - `Optional imageUrl` - The type of the image generation tool. Always `image_generation`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `IMAGE_GENERATION("image_generation")` + - `Optional promptCacheBreakpoint` - - `Optional action` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `JsonValue; mode "explicit"constant` - - `GENERATE("generate")` + The breakpoint mode. Always `explicit`. - - `EDIT("edit")` + - `EXPLICIT("explicit")` - - `AUTO("auto")` + - `class BetaResponseInputFile:` - - `Optional background` + A file input to the model. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `JsonValue; type "input_file"constant` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The type of the input item. Always `input_file`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `INPUT_FILE("input_file")` - - `TRANSPARENT("transparent")` + - `Optional detail` - - `OPAQUE("opaque")` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `AUTO("auto")` - - `Optional 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`. + - `LOW("low")` - `HIGH("high")` - - `LOW("low")` - - - `Optional inputImageMask` + - `Optional fileData` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The content of the file to be sent to the model. - `Optional fileId` - File ID for the mask image. + The ID of the file to be sent to the model. - - `Optional imageUrl` + - `Optional fileUrl` - Base64-encoded mask image. + The URL of the file to be sent to the model. - - `Optional model` + - `Optional filename` - The image generation model to use. Default: `gpt-image-1`. + The name of the file to be sent to the model. - - `GPT_IMAGE_1("gpt-image-1")` + - `Optional promptCacheBreakpoint` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `GPT_IMAGE_2("gpt-image-2")` + - `JsonValue; mode "explicit"constant` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The breakpoint mode. Always `explicit`. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `EXPLICIT("explicit")` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `Role role` - - `Optional moderation` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Moderation level for the generated image. Default: `auto`. + - `USER("user")` - - `AUTO("auto")` + - `ASSISTANT("assistant")` - - `LOW("low")` + - `SYSTEM("system")` - - `Optional outputCompression` + - `DEVELOPER("developer")` - Compression level for the output image. Default: 100. + - `Optional phase` - - `Optional outputFormat` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `COMMENTARY("commentary")` - - `PNG("png")` + - `FINAL_ANSWER("final_answer")` - - `WEBP("webp")` + - `Optional type` - - `JPEG("jpeg")` + The type of the message input. Always `message`. - - `Optional partialImages` + - `MESSAGE("message")` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `Message` - - `Optional quality` + - `List content` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A list of one or many input items to the model, containing different content + types. - - `LOW("low")` + - `class BetaResponseInputText:` - - `MEDIUM("medium")` + A text input to the model. - - `HIGH("high")` + - `class BetaResponseInputImage:` - - `AUTO("auto")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional size` + - `class BetaResponseInputFile:` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + A file input to the model. - - `_1024X1024("1024x1024")` + - `Role role` - - `_1024X1536("1024x1536")` + The role of the message input. One of `user`, `system`, or `developer`. - - `_1536X1024("1536x1024")` + - `USER("user")` - - `AUTO("auto")` + - `SYSTEM("system")` - - `JsonValue;` + - `DEVELOPER("developer")` - - `JsonValue; type "local_shell"constant` + - `Optional agent` - The type of the local shell tool. Always `local_shell`. + The agent that produced this item. - - `LOCAL_SHELL("local_shell")` + - `String agentName` - - `class BetaFunctionShellTool:` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands. + - `Optional status` - - `JsonValue; type "shell"constant` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the shell tool. Always `shell`. + - `IN_PROGRESS("in_progress")` - - `SHELL("shell")` + - `COMPLETED("completed")` - - `Optional> allowedCallers` + - `INCOMPLETE("incomplete")` - The tool invocation context(s). + - `Optional type` - - `DIRECT("direct")` + The type of the message input. Always set to `message`. - - `PROGRAMMATIC("programmatic")` + - `MESSAGE("message")` - - `Optional environment` + - `class BetaResponseOutputMessage:` - - `class BetaContainerAuto:` + An output message from the model. - - `JsonValue; type "container_auto"constant` + - `String id` - Automatically creates a container for this request + The unique ID of the output message. - - `CONTAINER_AUTO("container_auto")` + - `List content` - - `Optional> fileIds` + The content of the output message. - An optional list of uploaded files to make available to your code. + - `class BetaResponseOutputText:` - - `Optional memoryLimit` + A text output from the model. - The memory limit for the container. + - `List annotations` - - `_1G("1g")` + The annotations of the text output. - - `_4G("4g")` + - `class FileCitation:` - - `_16G("16g")` + A citation to a file. + + - `String fileId` - - `_64G("64g")` + The ID of the file. - - `Optional networkPolicy` + - `String filename` - Network access policy for the container. + The filename of the file cited. - - `class BetaContainerNetworkPolicyDisabled:` + - `long index` - - `class BetaContainerNetworkPolicyAllowlist:` + The index of the file in the list of files. - - `Optional> skills` + - `JsonValue; type "file_citation"constant` - An optional list of skills referenced by id or inline data. + The type of the file citation. Always `file_citation`. - - `class BetaSkillReference:` + - `FILE_CITATION("file_citation")` - - `String skillId` + - `class UrlCitation:` - The ID of the referenced skill. + A citation for a web resource used to generate a model response. - - `JsonValue; type "skill_reference"constant` + - `long endIndex` - References a skill created with the /v1/skills endpoint. + The index of the last character of the URL citation in the message. - - `SKILL_REFERENCE("skill_reference")` + - `long startIndex` - - `Optional version` + The index of the first character of the URL citation in the message. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `String title` - - `class BetaInlineSkill:` + The title of the web resource. - - `String description` + - `JsonValue; type "url_citation"constant` - The description of the skill. + The type of the URL citation. Always `url_citation`. - - `String name` + - `URL_CITATION("url_citation")` - The name of the skill. + - `String url` - - `BetaInlineSkillSource source` + The URL of the web resource. - Inline skill payload + - `class ContainerFileCitation:` - - `String data` + A citation for a container file used to generate a model response. - Base64-encoded skill zip bundle. + - `String containerId` - - `JsonValue; mediaType "application/zip"constant` + The ID of the container file. - The media type of the inline skill payload. Must be `application/zip`. + - `long endIndex` - - `APPLICATION_ZIP("application/zip")` + The index of the last character of the container file citation in the message. - - `JsonValue; type "base64"constant` + - `String fileId` - The type of the inline skill source. Must be `base64`. + The ID of the file. - - `BASE64("base64")` + - `String filename` - - `JsonValue; type "inline"constant` + The filename of the container file cited. - Defines an inline skill for this request. + - `long startIndex` - - `INLINE("inline")` + The index of the first character of the container file citation in the message. - - `class BetaLocalEnvironment:` + - `JsonValue; type "container_file_citation"constant` - - `JsonValue; type "local"constant` + The type of the container file citation. Always `container_file_citation`. - Use a local computer environment. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `LOCAL("local")` + - `class FilePath:` - - `Optional> skills` + A path to a file. - An optional list of skills. + - `String fileId` - - `String description` + The ID of the file. - The description of the skill. + - `long index` - - `String name` + The index of the file in the list of files. - The name of the skill. + - `JsonValue; type "file_path"constant` - - `String path` + The type of the file path. Always `file_path`. - The path to the directory containing the skill. + - `FILE_PATH("file_path")` - - `class BetaContainerReference:` + - `String text` - - `String containerId` + The text output from the model. - The ID of the referenced container. + - `JsonValue; type "output_text"constant` - - `JsonValue; type "container_reference"constant` + The type of the output text. Always `output_text`. - References a container created with the /v1/containers endpoint + - `OUTPUT_TEXT("output_text")` - - `CONTAINER_REFERENCE("container_reference")` + - `Optional> logprobs` - - `class BetaCustomTool:` + - `String token` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `List bytes` - - `String name` + - `double logprob` - The name of the custom tool, used to identify it in tool calls. + - `List topLogprobs` - - `JsonValue; type "custom"constant` + - `String token` - The type of the custom tool. Always `custom`. + - `List bytes` - - `CUSTOM("custom")` + - `double logprob` - - `Optional> allowedCallers` + - `class BetaResponseOutputRefusal:` - The tool invocation context(s). + A refusal from the model. - - `DIRECT("direct")` + - `String refusal` - - `PROGRAMMATIC("programmatic")` + The refusal explanation from the model. - - `Optional deferLoading` + - `JsonValue; type "refusal"constant` - Whether this tool should be deferred and discovered via tool search. + The type of the refusal. Always `refusal`. - - `Optional description` + - `REFUSAL("refusal")` - Optional description of the custom tool, used to provide more context. + - `JsonValue; role "assistant"constant` - - `Optional format` + The role of the output message. Always `assistant`. - The input format for the custom tool. Default is unconstrained text. + - `ASSISTANT("assistant")` - - `JsonValue;` + - `Status status` - - `JsonValue; type "text"constant` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Unconstrained text format. Always `text`. + - `IN_PROGRESS("in_progress")` - - `TEXT("text")` + - `COMPLETED("completed")` - - `class Grammar:` + - `INCOMPLETE("incomplete")` - A grammar defined by the user. + - `JsonValue; type "message"constant` - - `String definition` + The type of the output message. Always `message`. - The grammar definition. + - `MESSAGE("message")` - - `Syntax syntax` + - `Optional agent` - The syntax of the grammar definition. One of `lark` or `regex`. + The agent that produced this item. - - `LARK("lark")` + - `String agentName` - - `REGEX("regex")` + The canonical name of the agent that produced this item. - - `JsonValue; type "grammar"constant` + - `Optional phase` - Grammar format. Always `grammar`. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `GRAMMAR("grammar")` + - `COMMENTARY("commentary")` - - `class BetaNamespaceTool:` + - `FINAL_ANSWER("final_answer")` - Groups function/custom tools under a shared namespace. + - `class BetaResponseFileSearchToolCall:` - - `String description` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - A description of the namespace shown to the model. + - `String id` - - `String name` + The unique ID of the file search tool call. - The namespace name used in tool calls (for example, `crm`). + - `List queries` - - `List tools` + The queries used to search for files. - The function/custom tools available inside this namespace. + - `Status status` - - `class Function:` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `String name` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "function"constant` + - `SEARCHING("searching")` - - `FUNCTION("function")` + - `COMPLETED("completed")` - - `Optional> allowedCallers` + - `INCOMPLETE("incomplete")` - The tool invocation context(s). + - `FAILED("failed")` - - `DIRECT("direct")` + - `JsonValue; type "file_search_call"constant` - - `PROGRAMMATIC("programmatic")` + The type of the file search tool call. Always `file_search_call`. - - `Optional deferLoading` + - `FILE_SEARCH_CALL("file_search_call")` - Whether this function should be deferred and discovered via tool search. + - `Optional agent` - - `Optional description` + The agent that produced this item. - - `Optional outputSchema` + - `String agentName` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The canonical name of the agent that produced this item. - - `Optional parameters` + - `Optional> results` - - `Optional strict` + The results of the file search tool call. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `Optional attributes` - - `class BetaCustomTool:` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `String` - - `JsonValue; type "namespace"constant` + - `double` - The type of the tool. Always `namespace`. + - `boolean` - - `NAMESPACE("namespace")` + - `Optional fileId` - - `class BetaToolSearchTool:` + The unique ID of the file. - Hosted or BYOT tool search configuration for deferred tools. + - `Optional filename` - - `JsonValue; type "tool_search"constant` + The name of the file. - The type of the tool. Always `tool_search`. + - `Optional score` - - `TOOL_SEARCH("tool_search")` + The relevance score of the file - a value between 0 and 1. - - `Optional description` + - `Optional text` - Description shown to the model for a client-executed tool search tool. + The text that was retrieved from the file. - - `Optional execution` + - `class BetaResponseComputerToolCall:` - Whether tool search is executed by the server or by the client. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `SERVER("server")` + - `String id` - - `CLIENT("client")` + The unique ID of the computer call. - - `Optional parameters` + - `String callId` - Parameter schema for a client-executed tool search tool. + An identifier used when responding to the tool call with output. - - `class BetaWebSearchPreviewTool:` + - `List pendingSafetyChecks` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The pending safety checks for the computer call. - - `Type type` + - `String id` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The ID of the pending safety check. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `Optional code` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The type of the pending safety check. - - `Optional> searchContentTypes` + - `Optional message` - - `TEXT("text")` + Details about the pending safety check. - - `IMAGE("image")` + - `Status status` - - `Optional searchContextSize` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `IN_PROGRESS("in_progress")` - - `LOW("low")` + - `COMPLETED("completed")` - - `MEDIUM("medium")` + - `INCOMPLETE("incomplete")` - - `HIGH("high")` + - `Type type` - - `Optional userLocation` + The type of the computer call. Always `computer_call`. - The user's location. + - `COMPUTER_CALL("computer_call")` - - `JsonValue; type "approximate"constant` + - `Optional action` - The type of location approximation. Always `approximate`. + A click action. - - `APPROXIMATE("approximate")` + - `Click` - - `Optional city` + - `Button button` - Free text input for the city of the user, e.g. `San Francisco`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Optional country` + - `LEFT("left")` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `RIGHT("right")` - - `Optional region` + - `WHEEL("wheel")` - Free text input for the region of the user, e.g. `California`. + - `BACK("back")` - - `Optional timezone` + - `FORWARD("forward")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `JsonValue; type "click"constant` - - `class BetaApplyPatchTool:` + Specifies the event type. For a click action, this property is always `click`. - Allows the assistant to create, delete, or update files using unified diffs. + - `CLICK("click")` - - `JsonValue; type "apply_patch"constant` + - `long x` - The type of the tool. Always `apply_patch`. + The x-coordinate where the click occurred. - - `APPLY_PATCH("apply_patch")` + - `long y` - - `Optional> allowedCallers` + The y-coordinate where the click occurred. - The tool invocation context(s). + - `Optional> keys` - - `DIRECT("direct")` + The keys being held while clicking. - - `PROGRAMMATIC("programmatic")` + - `DoubleClick` - - `JsonValue; type "tool_search_output"constant` + - `Optional> keys` - The item type. Always `tool_search_output`. + The keys being held while double-clicking. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `JsonValue; type "double_click"constant` - - `Optional id` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The unique ID of this tool search output. + - `DOUBLE_CLICK("double_click")` - - `Optional agent` + - `long x` - The agent that produced this item. + The x-coordinate where the double click occurred. - - `String agentName` + - `long y` - The canonical name of the agent that produced this item. + The y-coordinate where the double click occurred. - - `Optional callId` + - `Drag` - The unique ID of the tool search call generated by the model. + - `List path` - - `Optional execution` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Whether tool search was executed by the server or by the client. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `SERVER("server")` + - `long x` - - `CLIENT("client")` + The x-coordinate. - - `Optional status` + - `long y` - The status of the tool search output. + The y-coordinate. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "drag"constant` - - `COMPLETED("completed")` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `INCOMPLETE("incomplete")` + - `DRAG("drag")` - - `AdditionalTools` + - `Optional> keys` - - `JsonValue; role "developer"constant` + The keys being held while dragging the mouse. - The role that provided the additional tools. Only `developer` is supported. + - `Keypress` - - `DEVELOPER("developer")` + - `List keys` - - `List tools` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A list of additional tools made available at this item. + - `JsonValue; type "keypress"constant` - - `class BetaFunctionTool:` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `KEYPRESS("keypress")` - - `class BetaFileSearchTool:` + - `Move` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `JsonValue; type "move"constant` - - `class BetaComputerTool:` + Specifies the event type. For a move action, this property is always set to `move`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `MOVE("move")` - - `class BetaComputerUsePreviewTool:` + - `long x` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The x-coordinate to move to. - - `class BetaWebSearchTool:` + - `long y` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The y-coordinate to move to. - - `Mcp` + - `Optional> keys` - - `CodeInterpreter` + The keys being held while moving the mouse. - `JsonValue;` - - `ImageGeneration` + - `JsonValue; type "screenshot"constant` - - `JsonValue;` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `class BetaFunctionShellTool:` + - `SCREENSHOT("screenshot")` - A tool that allows the model to execute shell commands. + - `Scroll` - - `class BetaCustomTool:` + - `long scrollX` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The horizontal scroll distance. - - `class BetaNamespaceTool:` + - `long scrollY` - Groups function/custom tools under a shared namespace. + The vertical scroll distance. - - `class BetaToolSearchTool:` + - `JsonValue; type "scroll"constant` - Hosted or BYOT tool search configuration for deferred tools. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class BetaWebSearchPreviewTool:` + - `SCROLL("scroll")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `long x` - - `class BetaApplyPatchTool:` + The x-coordinate where the scroll occurred. - Allows the assistant to create, delete, or update files using unified diffs. + - `long y` - - `JsonValue; type "additional_tools"constant` + The y-coordinate where the scroll occurred. - The item type. Always `additional_tools`. + - `Optional> keys` - - `ADDITIONAL_TOOLS("additional_tools")` + The keys being held while scrolling. - - `Optional id` + - `Type` - The unique ID of this additional tools item. + - `String text` - - `Optional agent` + The text to type. - The agent that produced this item. + - `JsonValue; type "type"constant` - - `String agentName` + Specifies the event type. For a type action, this property is always set to `type`. - The canonical name of the agent that produced this item. + - `TYPE("type")` - - `class BetaResponseReasoningItem:` + - `JsonValue;` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `JsonValue; type "wait"constant` - - `String id` + Specifies the event type. For a wait action, this property is always set to `wait`. - The unique identifier of the reasoning content. + - `WAIT("wait")` - - `List summary` + - `Optional> actions` - Reasoning summary content. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `String text` + - `Click` - A summary of the reasoning output from the model so far. + - `DoubleClick` - - `JsonValue; type "summary_text"constant` + - `Drag` - The type of the object. Always `summary_text`. + - `Keypress` - - `SUMMARY_TEXT("summary_text")` + - `Move` - - `JsonValue; type "reasoning"constant` + - `JsonValue;` - The type of the object. Always `reasoning`. + - `Scroll` - - `REASONING("reasoning")` + - `Type` + + - `JsonValue;` - `Optional agent` @@ -26991,53 +44066,56 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional> content` + - `ComputerCallOutput` - Reasoning text content. + - `String callId` - - `String text` + The ID of the computer tool call that produced the output. - The reasoning text from the model. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `JsonValue; type "reasoning_text"constant` + A computer screenshot image used with the computer use tool. - The type of the reasoning text. Always `reasoning_text`. + - `JsonValue; type "computer_screenshot"constant` - - `REASONING_TEXT("reasoning_text")` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `Optional encryptedContent` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `Optional fileId` - - `Optional status` + The identifier of an uploaded file that contains the screenshot. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional imageUrl` - - `IN_PROGRESS("in_progress")` + The URL of the screenshot image. - - `COMPLETED("completed")` + - `JsonValue; type "computer_call_output"constant` - - `INCOMPLETE("incomplete")` + The type of the computer tool call output. Always `computer_call_output`. - - `class BetaResponseCompactionItemParam:` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `Optional id` - - `String encryptedContent` + The ID of the computer tool call output. - The encrypted content of the compaction summary. + - `Optional> acknowledgedSafetyChecks` - - `JsonValue; type "compaction"constant` + The safety checks reported by the API that have been acknowledged by the developer. - The type of the item. Always `compaction`. + - `String id` - - `COMPACTION("compaction")` + The ID of the pending safety check. - - `Optional id` + - `Optional code` - The ID of the compaction item. + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. - `Optional agent` @@ -27047,110 +44125,111 @@ Get a model response The canonical name of the agent that produced this item. - - `ImageGenerationCall` + - `Optional status` - - `String id` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The unique ID of the image generation call. + - `IN_PROGRESS("in_progress")` - - `Optional result` + - `COMPLETED("completed")` - The generated image encoded in base64. + - `INCOMPLETE("incomplete")` - - `Status status` + - `class BetaResponseFunctionWebSearch:` - The status of the image generation call. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The unique ID of the web search tool call. - - `GENERATING("generating")` + - `Action action` - - `FAILED("failed")` + 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). - - `JsonValue; type "image_generation_call"constant` + - `class Search:` - The type of the image generation call. Always `image_generation_call`. + Action type "search" - Performs a web search query. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `JsonValue; type "search"constant` - - `Optional agent` + The action type. - The agent that produced this item. + - `SEARCH("search")` - - `String agentName` + - `Optional> queries` - The canonical name of the agent that produced this item. + The search queries. - - `class BetaResponseCodeInterpreterToolCall:` + - `Optional query` - A tool call to run code. + The search query. - - `String id` + - `Optional> sources` - The unique ID of the code interpreter tool call. + The sources used in the search. - - `Optional code` + - `JsonValue; type "url"constant` - The code to run, or null if not available. + The type of source. Always `url`. - - `String containerId` + - `URL("url")` - The ID of the container used to run the code. + - `String url` - - `Optional> outputs` + The URL of the source. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `class OpenPage:` - - `class Logs:` + Action type "open_page" - Opens a specific URL from search results. - The logs output from the code interpreter. + - `JsonValue; type "open_page"constant` - - `String logs` + The action type. - The logs output from the code interpreter. + - `OPEN_PAGE("open_page")` - - `JsonValue; type "logs"constant` + - `Optional url` - The type of the output. Always `logs`. + The URL opened by the model. - - `LOGS("logs")` + - `class FindInPage:` - - `class Image:` + Action type "find_in_page": Searches for a pattern within a loaded page. - The image output from the code interpreter. + - `String pattern` - - `JsonValue; type "image"constant` + The pattern or text to search for within the page. - The type of the output. Always `image`. + - `JsonValue; type "find_in_page"constant` - - `IMAGE("image")` + The action type. + + - `FIND_IN_PAGE("find_in_page")` - `String url` - The URL of the image output from the code interpreter. + The URL of the page searched for the pattern. - `Status status` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the web search tool call. - `IN_PROGRESS("in_progress")` - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` + - `SEARCHING("searching")` - - `INTERPRETING("interpreting")` + - `COMPLETED("completed")` - `FAILED("failed")` - - `JsonValue; type "code_interpreter_call"constant` + - `JsonValue; type "web_search_call"constant` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the web search tool call. Always `web_search_call`. - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `WEB_SEARCH_CALL("web_search_call")` - `Optional agent` @@ -27160,61 +44239,32 @@ Get a model response The canonical name of the agent that produced this item. - - `LocalShellCall` - - - `String id` - - The unique ID of the local shell call. - - - `Action action` - - Execute a shell command on the server. - - - `List 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 timeoutMs` - - Optional timeout in milliseconds for the command. - - - `Optional user` + - `class BetaResponseFunctionToolCall:` - Optional user to run the command as. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `Optional workingDirectory` + - `String arguments` - Optional working directory to run the command in. + A JSON string of the arguments to pass to the function. - `String callId` - The unique ID of the local shell tool call generated by the model. - - - `Status status` + The unique ID of the function tool call generated by the model. - The status of the local shell call. + - `String name` - - `IN_PROGRESS("in_progress")` + The name of the function to run. - - `COMPLETED("completed")` + - `JsonValue; type "function_call"constant` - - `INCOMPLETE("incomplete")` + The type of the function tool call. Always `function_call`. - - `JsonValue; type "local_shell_call"constant` + - `FUNCTION_CALL("function_call")` - The type of the local shell call. Always `local_shell_call`. + - `Optional id` - - `LOCAL_SHELL_CALL("local_shell_call")` + The unique ID of the function tool call. - `Optional agent` @@ -27224,33 +44274,34 @@ Get a model response The canonical name of the agent that produced this item. - - `LocalShellCallOutput` + - `Optional caller` - - `String id` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `JsonValue;` - - `String output` + - `JsonValue; type "direct"constant` - A JSON string of the output of the local shell tool call. + - `DIRECT("direct")` - - `JsonValue; type "local_shell_call_output"constant` + - `class Program:` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `String callerId` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The call ID of the program item that produced this tool call. - - `Optional agent` + - `JsonValue; type "program"constant` - The agent that produced this item. + - `PROGRAM("program")` - - `String agentName` + - `Optional namespace` - The canonical name of the agent that produced this item. + The namespace of the function to run. - `Optional status` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -27258,141 +44309,139 @@ Get a model response - `INCOMPLETE("incomplete")` - - `ShellCall` - - - `Action action` + - `FunctionCallOutput` - The shell commands and limits that describe how to run the tool call. + - `String callId` - - `List commands` + The unique ID of the function tool call generated by the model. - Ordered shell commands for the execution environment to run. + - `Output output` - - `Optional maxOutputLength` + Text, image, or file output of the function tool call. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `String` - - `Optional timeoutMs` + - `List` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `class BetaResponseInputTextContent:` - - `String callId` + A text input to the model. - The unique ID of the shell tool call generated by the model. + - `String text` - - `JsonValue; type "shell_call"constant` + The text input to the model. - The type of the item. Always `shell_call`. + - `JsonValue; type "input_text"constant` - - `SHELL_CALL("shell_call")` + The type of the input item. Always `input_text`. - - `Optional id` + - `INPUT_TEXT("input_text")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `Optional promptCacheBreakpoint` - - `Optional agent` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The agent that produced this item. + - `JsonValue; mode "explicit"constant` - - `String agentName` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `EXPLICIT("explicit")` - - `Optional caller` + - `class BetaResponseInputImageContent:` - The execution context that produced this tool call. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `JsonValue;` + - `JsonValue; type "input_image"constant` - - `JsonValue; type "direct"constant` + The type of the input item. Always `input_image`. - The caller type. Always `direct`. + - `INPUT_IMAGE("input_image")` - - `DIRECT("direct")` + - `Optional detail` - - `class Program:` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String callerId` + - `LOW("low")` - The call ID of the program item that produced this tool call. + - `HIGH("high")` - - `JsonValue; type "program"constant` + - `AUTO("auto")` - The caller type. Always `program`. + - `ORIGINAL("original")` - - `PROGRAM("program")` + - `Optional fileId` - - `Optional environment` + The ID of the file to be sent to the model. - The environment to execute the shell commands in. + - `Optional imageUrl` - - `class BetaLocalEnvironment:` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class BetaContainerReference:` + - `Optional promptCacheBreakpoint` - - `Optional status` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `JsonValue; mode "explicit"constant` - - `IN_PROGRESS("in_progress")` + The breakpoint mode. Always `explicit`. - - `COMPLETED("completed")` + - `EXPLICIT("explicit")` - - `INCOMPLETE("incomplete")` + - `class BetaResponseInputFileContent:` - - `ShellCallOutput` + A file input to the model. - - `String callId` + - `JsonValue; type "input_file"constant` - The unique ID of the shell tool call generated by the model. + The type of the input item. Always `input_file`. - - `List output` + - `INPUT_FILE("input_file")` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `Optional detail` - - `Outcome outcome` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The exit or timeout outcome associated with this shell call. + - `AUTO("auto")` - - `JsonValue;` + - `LOW("low")` - - `JsonValue; type "timeout"constant` + - `HIGH("high")` - The outcome type. Always `timeout`. + - `Optional fileData` - - `TIMEOUT("timeout")` + The base64-encoded data of the file to be sent to the model. - - `class Exit:` + - `Optional fileId` - Indicates that the shell commands finished and returned an exit code. + The ID of the file to be sent to the model. - - `long exitCode` + - `Optional fileUrl` - The exit code returned by the shell process. + The URL of the file to be sent to the model. - - `JsonValue; type "exit"constant` + - `Optional filename` - The outcome type. Always `exit`. + The name of the file to be sent to the model. - - `EXIT("exit")` + - `Optional promptCacheBreakpoint` - - `String stderr` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Captured stderr output for the shell call. + - `JsonValue; mode "explicit"constant` - - `String stdout` + The breakpoint mode. Always `explicit`. - Captured stdout output for the shell call. + - `EXPLICIT("explicit")` - - `JsonValue; type "shell_call_output"constant` + - `JsonValue; type "function_call_output"constant` - The type of the item. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional id` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - `Optional agent` @@ -27426,13 +44475,9 @@ Get a model response - `PROGRAM("program")` - - `Optional maxOutputLength` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - `Optional status` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -27440,83 +44485,95 @@ Get a model response - `INCOMPLETE("incomplete")` - - `ApplyPatchCall` + - `AgentMessage` - - `String callId` + - `String author` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `Operation operation` + - `List content` - The specific create, delete, or update instruction for the apply_patch tool call. + Plaintext, image, or encrypted content sent between agents. - - `class CreateFile:` + - `class BetaResponseInputTextContent:` - Instruction for creating a new file via the apply_patch tool. + A text input to the model. - - `String diff` + - `class BetaResponseInputImageContent:` - Unified diff content to apply when creating the file. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `String path` + - `class EncryptedContent:` - Path of the file to create relative to the workspace root. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `JsonValue; type "create_file"constant` + - `String encryptedContent` - The operation type. Always `create_file`. + Opaque encrypted content. - - `CREATE_FILE("create_file")` + - `JsonValue; type "encrypted_content"constant` - - `class DeleteFile:` + The type of the input item. Always `encrypted_content`. - Instruction for deleting an existing file via the apply_patch tool. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `String path` + - `String recipient` - Path of the file to delete relative to the workspace root. + The destination agent identity. - - `JsonValue; type "delete_file"constant` + - `JsonValue; type "agent_message"constant` - The operation type. Always `delete_file`. + The item type. Always `agent_message`. - - `DELETE_FILE("delete_file")` + - `AGENT_MESSAGE("agent_message")` - - `class UpdateFile:` + - `Optional id` - Instruction for updating an existing file via the apply_patch tool. + The unique ID of this agent message item. - - `String diff` + - `Optional agent` - Unified diff content to apply to the existing file. + The agent that produced this item. - - `String path` + - `String agentName` - Path of the file to update relative to the workspace root. + The canonical name of the agent that produced this item. - - `JsonValue; type "update_file"constant` + - `MultiAgentCall` - The operation type. Always `update_file`. + - `Action action` - - `UPDATE_FILE("update_file")` + The multi-agent action that was executed. - - `Status status` + - `SPAWN_AGENT("spawn_agent")` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `INTERRUPT_AGENT("interrupt_agent")` - - `IN_PROGRESS("in_progress")` + - `LIST_AGENTS("list_agents")` - - `COMPLETED("completed")` + - `SEND_MESSAGE("send_message")` - - `JsonValue; type "apply_patch_call"constant` + - `FOLLOWUP_TASK("followup_task")` - The type of the item. Always `apply_patch_call`. + - `WAIT_AGENT("wait_agent")` - - `APPLY_PATCH_CALL("apply_patch_call")` + - `String arguments` + + The action arguments as a JSON string. + + - `String callId` + + The unique ID linking this call to its output. + + - `JsonValue; type "multi_agent_call"constant` + + The item type. Always `multi_agent_call`. + + - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional id` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of this multi-agent call. - `Optional agent` @@ -27526,125 +44583,127 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional caller` + - `MultiAgentCallOutput` - The execution context that produced this tool call. + - `Action action` - - `JsonValue;` + The multi-agent action that produced this result. - - `JsonValue; type "direct"constant` + - `SPAWN_AGENT("spawn_agent")` - The caller type. Always `direct`. + - `INTERRUPT_AGENT("interrupt_agent")` - - `DIRECT("direct")` + - `LIST_AGENTS("list_agents")` - - `class Program:` + - `SEND_MESSAGE("send_message")` - - `String callerId` + - `FOLLOWUP_TASK("followup_task")` - The call ID of the program item that produced this tool call. + - `WAIT_AGENT("wait_agent")` - - `JsonValue; type "program"constant` + - `String callId` - The caller type. Always `program`. + The unique ID of the multi-agent call. - - `PROGRAM("program")` + - `List output` - - `ApplyPatchCallOutput` + Text output returned by the multi-agent action. - - `String callId` + - `String text` - The unique ID of the apply patch tool call generated by the model. + The text content. - - `Status status` + - `JsonValue; type "output_text"constant` - The status of the apply patch tool call output. One of `completed` or `failed`. + The content type. Always `output_text`. - - `COMPLETED("completed")` + - `OUTPUT_TEXT("output_text")` - - `FAILED("failed")` + - `Optional annotations` - - `JsonValue; type "apply_patch_call_output"constant` + Citations associated with the text content. - The type of the item. Always `apply_patch_call_output`. + - `List` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `String fileId` - - `Optional id` + The ID of the file. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `String filename` - - `Optional agent` + The filename of the file cited. - The agent that produced this item. + - `long index` - - `String agentName` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `JsonValue; type "file_citation"constant` - - `Optional caller` + The citation type. Always `file_citation`. - The execution context that produced this tool call. + - `FILE_CITATION("file_citation")` - - `JsonValue;` + - `List` - - `JsonValue; type "direct"constant` + - `long endIndex` + + The index of the last character of the citation in the message. - The caller type. Always `direct`. + - `long startIndex` - - `DIRECT("direct")` + The index of the first character of the citation in the message. - - `class Program:` + - `String title` - - `String callerId` + The title of the cited resource. - The call ID of the program item that produced this tool call. + - `JsonValue; type "url_citation"constant` - - `JsonValue; type "program"constant` + The citation type. Always `url_citation`. - The caller type. Always `program`. + - `URL_CITATION("url_citation")` - - `PROGRAM("program")` + - `String url` - - `Optional output` + The URL of the cited resource. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `List` - - `McpListTools` + - `String containerId` - - `String id` + The ID of the container. - The unique ID of the list. + - `long endIndex` - - `String serverLabel` + The index of the last character of the citation in the message. - The label of the MCP server. + - `String fileId` - - `List tools` + The ID of the container file. - The tools available on the server. + - `String filename` - - `JsonValue inputSchema` + The filename of the container file cited. - The JSON schema describing the tool's input. + - `long startIndex` - - `String name` + The index of the first character of the citation in the message. - The name of the tool. + - `JsonValue; type "container_file_citation"constant` - - `Optional annotations` + The citation type. Always `container_file_citation`. - Additional annotations about the tool. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `Optional description` + - `JsonValue; type "multi_agent_call_output"constant` - The description of the tool. + The item type. Always `multi_agent_call_output`. - - `JsonValue; type "mcp_list_tools"constant` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - The type of the item. Always `mcp_list_tools`. + - `Optional id` - - `MCP_LIST_TOOLS("mcp_list_tools")` + The unique ID of this multi-agent call output. - `Optional agent` @@ -27654,33 +44713,21 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional 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. + - `ToolSearchCall` - - `String name` + - `JsonValue arguments` - The name of the tool to run. + The arguments supplied to the tool search call. - - `String serverLabel` + - `JsonValue; type "tool_search_call"constant` - The label of the MCP server making the request. + The item type. Always `tool_search_call`. - - `JsonValue; type "mcp_approval_request"constant` + - `TOOL_SEARCH_CALL("tool_search_call")` - The type of the item. Always `mcp_approval_request`. + - `Optional id` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + The unique ID of this tool search call. - `Optional agent` @@ -27690,1081 +44737,1110 @@ Get a model response The canonical name of the agent that produced this item. - - `McpApprovalResponse` + - `Optional callId` - - `String approvalRequestId` + The unique ID of the tool search call generated by the model. - The ID of the approval request being answered. + - `Optional execution` - - `boolean approve` + Whether tool search was executed by the server or by the client. - Whether the request was approved. + - `SERVER("server")` - - `JsonValue; type "mcp_approval_response"constant` + - `CLIENT("client")` - The type of the item. Always `mcp_approval_response`. + - `Optional status` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + The status of the tool search call. - - `Optional id` + - `IN_PROGRESS("in_progress")` - The unique ID of the approval response + - `COMPLETED("completed")` - - `Optional agent` + - `INCOMPLETE("incomplete")` - The agent that produced this item. + - `class BetaResponseToolSearchOutputItemParam:` - - `String agentName` + - `List tools` - The canonical name of the agent that produced this item. + The loaded tool definitions returned by the tool search output. - - `Optional reason` + - `class BetaFunctionTool:` - Optional reason for the decision. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `McpCall` + - `String name` - - `String id` + The name of the function to call. - The unique ID of the tool call. + - `Optional parameters` - - `String arguments` + A JSON schema object describing the parameters of the function. - A JSON string of the arguments passed to the tool. + - `Optional strict` - - `String name` + Whether strict parameter validation is enforced for this function tool. - The name of the tool that was run. + - `JsonValue; type "function"constant` - - `String serverLabel` + The type of the function tool. Always `function`. - The label of the MCP server running the tool. + - `FUNCTION("function")` - - `JsonValue; type "mcp_call"constant` + - `Optional> allowedCallers` - The type of the item. Always `mcp_call`. + The tool invocation context(s). - - `MCP_CALL("mcp_call")` + - `DIRECT("direct")` - - `Optional agent` + - `PROGRAMMATIC("programmatic")` - The agent that produced this item. + - `Optional deferLoading` - - `String agentName` + Whether this function is deferred and loaded via tool search. - The canonical name of the agent that produced this item. + - `Optional description` - - `Optional approvalRequestId` + A description of the function. Used by the model to determine whether or not to call the function. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `Optional outputSchema` - - `Optional error` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The error from the tool call, if any. + - `class BetaFileSearchTool:` - - `Optional output` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The output from the tool call. + - `JsonValue; type "file_search"constant` - - `Optional status` + The type of the file search tool. Always `file_search`. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `FILE_SEARCH("file_search")` - - `IN_PROGRESS("in_progress")` + - `List vectorStoreIds` - - `COMPLETED("completed")` + The IDs of the vector stores to search. - - `INCOMPLETE("incomplete")` + - `Optional filters` - - `CALLING("calling")` + A filter to apply. - - `FAILED("failed")` + - `class ComparisonFilter:` - - `class BetaResponseCustomToolCallOutput:` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The output of a custom tool call from your code, being sent back to the model. + - `String key` - - `String callId` + The key to compare against the value. - The call ID, used to map this custom tool call output to a custom tool call. + - `Type type` - - `Output output` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `String` + - `EQ("eq")` - - `List` + - `NE("ne")` - - `class BetaResponseInputText:` + - `GT("gt")` - A text input to the model. + - `GTE("gte")` - - `class BetaResponseInputImage:` + - `LT("lt")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `LTE("lte")` - - `class BetaResponseInputFile:` + - `IN("in")` - A file input to the model. + - `NIN("nin")` - - `JsonValue; type "custom_tool_call_output"constant` + - `Value value` - The type of the custom tool call output. Always `custom_tool_call_output`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `String` - - `Optional id` + - `double` - The unique ID of the custom tool call output in the OpenAI platform. + - `boolean` - - `Optional agent` + - `List` - The agent that produced this item. + - `String` - - `String agentName` + - `double` - The canonical name of the agent that produced this item. + - `class CompoundFilter:` - - `Optional caller` + Combine multiple filters using `and` or `or`. - The execution context that produced this tool call. + - `List filters` - - `JsonValue;` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `JsonValue; type "direct"constant` + - `class ComparisonFilter:` - The caller type. Always `direct`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `DIRECT("direct")` + - `String key` - - `class Program:` + The key to compare against the value. - - `String callerId` + - `Type type` - The call ID of the program item that produced this tool call. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `JsonValue; type "program"constant` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The caller type. Always `program`. + - `EQ("eq")` - - `PROGRAM("program")` + - `NE("ne")` - - `class BetaResponseCustomToolCall:` + - `GT("gt")` - A call to a custom tool created by the model. + - `GTE("gte")` - - `String callId` + - `LT("lt")` - An identifier used to map this custom tool call to a tool call output. + - `LTE("lte")` - - `String input` + - `IN("in")` - The input for the custom tool call generated by the model. + - `NIN("nin")` - - `String name` + - `Value value` - The name of the custom tool being called. + The value to compare against the attribute key; supports string, number, or boolean types. - - `JsonValue; type "custom_tool_call"constant` + - `String` - The type of the custom tool call. Always `custom_tool_call`. + - `double` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `boolean` - - `Optional id` + - `List` - The unique ID of the custom tool call in the OpenAI platform. + - `String` - - `Optional agent` + - `double` - The agent that produced this item. + - `JsonValue` - - `String agentName` + - `Type type` - The canonical name of the agent that produced this item. + Type of operation: `and` or `or`. - - `Optional caller` + - `AND("and")` - The execution context that produced this tool call. + - `OR("or")` - - `JsonValue;` + - `Optional maxNumResults` - - `JsonValue; type "direct"constant` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `DIRECT("direct")` + - `Optional rankingOptions` - - `class Program:` + Ranking options for search. - - `String callerId` + - `Optional hybridSearch` - The call ID of the program item that produced this tool call. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `JsonValue; type "program"constant` + - `double embeddingWeight` - - `PROGRAM("program")` + The weight of the embedding in the reciprocal ranking fusion. - - `Optional namespace` + - `double textWeight` - The namespace of the custom tool being called. + The weight of the text in the reciprocal ranking fusion. - - `CompactionTrigger` + - `Optional ranker` - - `JsonValue; type "compaction_trigger"constant` + The ranker to use for the file search. - The type of the item. Always `compaction_trigger`. + - `AUTO("auto")` - - `COMPACTION_TRIGGER("compaction_trigger")` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `Optional agent` + - `Optional scoreThreshold` - The agent that produced this item. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `String agentName` + - `class BetaComputerTool:` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `ItemReference` + - `JsonValue; type "computer"constant` - - `String id` + The type of the computer tool. Always `computer`. - The ID of the item to reference. + - `COMPUTER("computer")` - - `Optional agent` + - `class BetaComputerUsePreviewTool:` - The agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String agentName` + - `long displayHeight` - The canonical name of the agent that produced this item. + The height of the computer display. - - `Optional type` + - `long displayWidth` - The type of item to reference. Always `item_reference`. + The width of the computer display. - - `ITEM_REFERENCE("item_reference")` + - `Environment environment` - - `Program` + The type of computer environment to control. - - `String id` + - `WINDOWS("windows")` - The unique ID of this program item. + - `MAC("mac")` - - `String callId` + - `LINUX("linux")` - The stable call ID of the program item. + - `UBUNTU("ubuntu")` - - `String code` + - `BROWSER("browser")` - The JavaScript source executed by programmatic tool calling. + - `JsonValue; type "computer_use_preview"constant` - - `String fingerprint` + The type of the computer use tool. Always `computer_use_preview`. - Opaque program replay fingerprint that must be round-tripped. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `JsonValue; type "program"constant` + - `class BetaWebSearchTool:` - The item type. Always `program`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `PROGRAM("program")` + - `Type type` - - `Optional agent` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The agent that produced this item. + - `WEB_SEARCH("web_search")` - - `String agentName` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - The canonical name of the agent that produced this item. + - `Optional filters` - - `ProgramOutput` + Filters for the search. - - `String id` + - `Optional> allowedDomains` - The unique ID of this program output item. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `String callId` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The call ID of the program item. + - `Optional searchContextSize` - - `String result` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The result produced by the program item. + - `LOW("low")` - - `Status status` + - `MEDIUM("medium")` - The terminal status of the program output. + - `HIGH("high")` - - `COMPLETED("completed")` + - `Optional userLocation` - - `INCOMPLETE("incomplete")` + The approximate location of the user. - - `JsonValue; type "program_output"constant` + - `Optional city` - The item type. Always `program_output`. + Free text input for the city of the user, e.g. `San Francisco`. - - `PROGRAM_OUTPUT("program_output")` + - `Optional country` - - `Optional agent` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The agent that produced this item. + - `Optional region` - - `String agentName` + Free text input for the region of the user, e.g. `California`. - The canonical name of the agent that produced this item. + - `Optional timezone` - - `Optional metadata` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional type` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of location approximation. Always `approximate`. - - `Model model` + - `APPROXIMATE("approximate")` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `Mcp` - - `GPT_5_6_SOL("gpt-5.6-sol")` + - `String serverLabel` - - `GPT_5_6_TERRA("gpt-5.6-terra")` + A label for this MCP server, used to identify it in tool calls. - - `GPT_5_6_LUNA("gpt-5.6-luna")` + - `JsonValue; type "mcp"constant` - - `GPT_5_4("gpt-5.4")` + The type of the MCP tool. Always `mcp`. - - `GPT_5_4_MINI("gpt-5.4-mini")` + - `MCP("mcp")` - - `GPT_5_4_NANO("gpt-5.4-nano")` + - `Optional> allowedCallers` - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + The tool invocation context(s). - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + - `DIRECT("direct")` - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `PROGRAMMATIC("programmatic")` - - `GPT_5_2("gpt-5.2")` + - `Optional allowedTools` - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + List of allowed tool names or a filter object. - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + - `List` - - `GPT_5_2_PRO("gpt-5.2-pro")` + - `class McpToolFilter:` - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + A filter object to specify which tools are allowed. - - `GPT_5_1("gpt-5.1")` + - `Optional readOnly` - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `GPT_5_1_CODEX("gpt-5.1-codex")` + - `Optional> toolNames` - - `GPT_5_1_MINI("gpt-5.1-mini")` + List of allowed tool names. - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + - `Optional authorization` - - `GPT_5("gpt-5")` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `GPT_5_MINI("gpt-5-mini")` + - `Optional connectorId` - - `GPT_5_NANO("gpt-5-nano")` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + Currently supported `connector_id` values are: - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `CONNECTOR_GMAIL("connector_gmail")` - - `GPT_4_1("gpt-4.1")` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `GPT_4_1_MINI("gpt-4.1-mini")` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `GPT_4_1_NANO("gpt-4.1-nano")` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `O4_MINI("o4-mini")` + - `Optional deferLoading` - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + Whether this MCP tool is deferred and discovered via tool search. - - `O3("o3")` + - `Optional headers` - - `O3_2025_04_16("o3-2025-04-16")` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `O3_MINI("o3-mini")` + - `Optional requireApproval` - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + Specify which of the MCP server's tools require approval. - - `O1("o1")` + - `class McpToolApprovalFilter:` - - `O1_2024_12_17("o1-2024-12-17")` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `O1_PREVIEW("o1-preview")` + - `Optional always` - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + A filter object to specify which tools are allowed. - - `O1_MINI("o1-mini")` + - `Optional readOnly` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `GPT_4O("gpt-4o")` + - `Optional> toolNames` - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + List of allowed tool names. - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + - `Optional never` - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + A filter object to specify which tools are allowed. - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + - `Optional readOnly` - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + - `Optional> toolNames` - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + List of allowed tool names. - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + - `enum McpToolApprovalSetting:` - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + - `ALWAYS("always")` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + - `NEVER("never")` - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `Optional serverDescription` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + Optional description of the MCP server, used to provide more context. - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `Optional serverUrl` - - `CODEX_MINI_LATEST("codex-mini-latest")` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `GPT_4O_MINI("gpt-4o-mini")` + - `Optional tunnelId` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `GPT_4_TURBO("gpt-4-turbo")` + - `CodeInterpreter` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `Container container` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + - `String` - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `class CodeInterpreterToolAuto:` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `GPT_4("gpt-4")` + - `JsonValue; type "auto"constant` - - `GPT_4_0314("gpt-4-0314")` + Always `auto`. - - `GPT_4_0613("gpt-4-0613")` + - `AUTO("auto")` - - `GPT_4_32K("gpt-4-32k")` + - `Optional> fileIds` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + An optional list of uploaded files to make available to your code. - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `Optional memoryLimit` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + The memory limit for the code interpreter container. - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `_1G("1g")` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `_4G("4g")` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `_16G("16g")` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `_64G("64g")` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `Optional networkPolicy` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + Network access policy for the container. - - `O1_PRO("o1-pro")` + - `class BetaContainerNetworkPolicyDisabled:` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - `JsonValue; type "disabled"constant` - - `O3_PRO("o3-pro")` + Disable outbound network access. Always `disabled`. - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `DISABLED("disabled")` - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `class BetaContainerNetworkPolicyAllowlist:` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + - `List allowedDomains` - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + A list of allowed domains when type is `allowlist`. - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `JsonValue; type "allowlist"constant` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + Allow outbound network access only to specified domains. Always `allowlist`. - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `ALLOWLIST("allowlist")` - - `GPT_5_CODEX("gpt-5-codex")` + - `Optional> domainSecrets` - - `GPT_5_PRO("gpt-5-pro")` + Optional domain-scoped secrets for allowlisted domains. - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `String domain` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + The domain associated with the secret. - - `JsonValue; object_ "response"constant` + - `String name` - The object type of this resource - always set to `response`. + The name of the secret to inject for the domain. - - `RESPONSE("response")` + - `String value` - - `List output` + The secret value to inject for the domain. - An array of content items generated by the model. + - `JsonValue; type "code_interpreter"constant` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The type of the code interpreter tool. Always `code_interpreter`. - - `class BetaResponseOutputMessage:` + - `CODE_INTERPRETER("code_interpreter")` - An output message from the model. + - `Optional> allowedCallers` - - `class BetaResponseFileSearchToolCall:` + The tool invocation context(s). - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `DIRECT("direct")` - - `class BetaResponseFunctionToolCall:` + - `PROGRAMMATIC("programmatic")` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `JsonValue;` - - `class BetaResponseFunctionToolCallOutputItem:` + - `JsonValue; type "programmatic_tool_calling"constant` - - `String id` + The type of the tool. Always `programmatic_tool_calling`. - The unique ID of the function call tool output. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `String callId` + - `ImageGeneration` - The unique ID of the function tool call generated by the model. + - `JsonValue; type "image_generation"constant` - - `Output output` + The type of the image generation tool. Always `image_generation`. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `IMAGE_GENERATION("image_generation")` - - `String` + - `Optional action` - - `List` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `class BetaResponseInputText:` + - `GENERATE("generate")` - A text input to the model. + - `EDIT("edit")` - - `class BetaResponseInputImage:` + - `AUTO("auto")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Optional background` - - `class BetaResponseInputFile:` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - A file input to the model. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `Status status` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `TRANSPARENT("transparent")` - - `IN_PROGRESS("in_progress")` + - `OPAQUE("opaque")` - - `COMPLETED("completed")` + - `AUTO("auto")` - - `INCOMPLETE("incomplete")` + - `Optional inputFidelity` - - `JsonValue; type "function_call_output"constant` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The type of the function tool call output. Always `function_call_output`. + - `HIGH("high")` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `LOW("low")` - - `Optional agent` + - `Optional inputImageMask` - The agent that produced this item. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `String agentName` + - `Optional fileId` - The canonical name of the agent that produced this item. + File ID for the mask image. - - `Optional caller` + - `Optional imageUrl` - The execution context that produced this tool call. + Base64-encoded mask image. - - `JsonValue;` + - `Optional model` - - `JsonValue; type "direct"constant` + The image generation model to use. Default: `gpt-image-1`. - The caller type. Always `direct`. + - `GPT_IMAGE_1("gpt-image-1")` - - `DIRECT("direct")` + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `class Program:` + - `GPT_IMAGE_2("gpt-image-2")` - - `String callerId` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - The call ID of the program item that produced this tool call. + - `GPT_IMAGE_1_5("gpt-image-1.5")` - - `JsonValue; type "program"constant` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - The caller type. Always `program`. + - `Optional moderation` - - `PROGRAM("program")` + Moderation level for the generated image. Default: `auto`. - - `Optional createdBy` + - `AUTO("auto")` - The identifier of the actor that created the item. + - `LOW("low")` - - `AgentMessage` + - `Optional outputCompression` - - `String id` + Compression level for the output image. Default: 100. - The unique ID of the agent message. + - `Optional outputFormat` - - `String author` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The sending agent identity. + - `PNG("png")` - - `List content` + - `WEBP("webp")` - Encrypted content sent between agents. + - `JPEG("jpeg")` - - `class BetaResponseInputText:` + - `Optional partialImages` - A text input to the model. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `class BetaResponseOutputText:` + - `Optional quality` - A text output from the model. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `class Text:` + - `LOW("low")` - A text content. + - `MEDIUM("medium")` - - `String text` + - `HIGH("high")` - - `JsonValue; type "text"constant` + - `AUTO("auto")` - - `TEXT("text")` + - `Optional size` - - `class SummaryText:` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - A summary text from the model. + - `_1024X1024("1024x1024")` - - `String text` + - `_1024X1536("1024x1536")` - A summary of the reasoning output from the model so far. + - `_1536X1024("1536x1024")` - - `JsonValue; type "summary_text"constant` + - `AUTO("auto")` - The type of the object. Always `summary_text`. + - `JsonValue;` - - `SUMMARY_TEXT("summary_text")` + - `JsonValue; type "local_shell"constant` - - `class ReasoningText:` + The type of the local shell tool. Always `local_shell`. - Reasoning text from the model. + - `LOCAL_SHELL("local_shell")` - - `String text` + - `class BetaFunctionShellTool:` - The reasoning text from the model. + A tool that allows the model to execute shell commands. - - `JsonValue; type "reasoning_text"constant` + - `JsonValue; type "shell"constant` - The type of the reasoning text. Always `reasoning_text`. + The type of the shell tool. Always `shell`. - - `REASONING_TEXT("reasoning_text")` + - `SHELL("shell")` - - `class BetaResponseOutputRefusal:` + - `Optional> allowedCallers` - A refusal from the model. + The tool invocation context(s). - - `class BetaResponseInputImage:` + - `DIRECT("direct")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `PROGRAMMATIC("programmatic")` - - `class ComputerScreenshot:` + - `Optional environment` - A screenshot of a computer. + - `class BetaContainerAuto:` - - `Detail detail` + - `JsonValue; type "container_auto"constant` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Automatically creates a container for this request - - `LOW("low")` + - `CONTAINER_AUTO("container_auto")` - - `HIGH("high")` + - `Optional> fileIds` - - `AUTO("auto")` + An optional list of uploaded files to make available to your code. - - `ORIGINAL("original")` + - `Optional memoryLimit` - - `Optional fileId` + The memory limit for the container. - The identifier of an uploaded file that contains the screenshot. + - `_1G("1g")` - - `Optional imageUrl` + - `_4G("4g")` - The URL of the screenshot image. + - `_16G("16g")` - - `JsonValue; type "computer_screenshot"constant` + - `_64G("64g")` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `Optional networkPolicy` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + Network access policy for the container. - - `Optional promptCacheBreakpoint` + - `class BetaContainerNetworkPolicyDisabled:` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaContainerNetworkPolicyAllowlist:` - - `JsonValue; mode "explicit"constant` + - `Optional> skills` - The breakpoint mode. Always `explicit`. + An optional list of skills referenced by id or inline data. - - `EXPLICIT("explicit")` + - `class BetaSkillReference:` - - `class BetaResponseInputFile:` + - `String skillId` - A file input to the model. + The ID of the referenced skill. - - `class EncryptedContent:` + - `JsonValue; type "skill_reference"constant` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + References a skill created with the /v1/skills endpoint. - - `String encryptedContent` + - `SKILL_REFERENCE("skill_reference")` - Opaque encrypted content. + - `Optional version` - - `JsonValue; type "encrypted_content"constant` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The type of the input item. Always `encrypted_content`. + - `class BetaInlineSkill:` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `String description` - - `String recipient` + The description of the skill. - The destination agent identity. + - `String name` - - `JsonValue; type "agent_message"constant` + The name of the skill. - The type of the item. Always `agent_message`. + - `BetaInlineSkillSource source` - - `AGENT_MESSAGE("agent_message")` + Inline skill payload - - `Optional agent` + - `String data` - The agent that produced this item. + Base64-encoded skill zip bundle. - - `String agentName` + - `JsonValue; mediaType "application/zip"constant` - The canonical name of the agent that produced this item. + The media type of the inline skill payload. Must be `application/zip`. - - `MultiAgentCall` + - `APPLICATION_ZIP("application/zip")` - - `String id` + - `JsonValue; type "base64"constant` - The unique ID of the multi-agent call item. + The type of the inline skill source. Must be `base64`. - - `Action action` + - `BASE64("base64")` - The multi-agent action to execute. + - `JsonValue; type "inline"constant` - - `SPAWN_AGENT("spawn_agent")` + Defines an inline skill for this request. - - `INTERRUPT_AGENT("interrupt_agent")` + - `INLINE("inline")` - - `LIST_AGENTS("list_agents")` + - `class BetaLocalEnvironment:` - - `SEND_MESSAGE("send_message")` + - `JsonValue; type "local"constant` - - `FOLLOWUP_TASK("followup_task")` + Use a local computer environment. - - `WAIT_AGENT("wait_agent")` + - `LOCAL("local")` - - `String arguments` + - `Optional> skills` - The JSON string of arguments generated for the action. + An optional list of skills. - - `String callId` + - `String description` - The unique ID linking this call to its output. + The description of the skill. - - `JsonValue; type "multi_agent_call"constant` + - `String name` - The type of the multi-agent call. Always `multi_agent_call`. + The name of the skill. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `String path` - - `Optional agent` + The path to the directory containing the skill. - The agent that produced this item. + - `class BetaContainerReference:` - - `String agentName` + - `String containerId` - The canonical name of the agent that produced this item. + The ID of the referenced container. - - `MultiAgentCallOutput` + - `JsonValue; type "container_reference"constant` - - `String id` + References a container created with the /v1/containers endpoint - The unique ID of the multi-agent call output item. + - `CONTAINER_REFERENCE("container_reference")` - - `Action action` + - `class BetaCustomTool:` - The multi-agent action that produced this result. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `SPAWN_AGENT("spawn_agent")` + - `String name` - - `INTERRUPT_AGENT("interrupt_agent")` + The name of the custom tool, used to identify it in tool calls. - - `LIST_AGENTS("list_agents")` + - `JsonValue; type "custom"constant` - - `SEND_MESSAGE("send_message")` + The type of the custom tool. Always `custom`. - - `FOLLOWUP_TASK("followup_task")` + - `CUSTOM("custom")` - - `WAIT_AGENT("wait_agent")` + - `Optional> allowedCallers` - - `String callId` + The tool invocation context(s). - The unique ID of the multi-agent call. + - `DIRECT("direct")` - - `List output` + - `PROGRAMMATIC("programmatic")` - Text output returned by the multi-agent action. + - `Optional deferLoading` - - `List annotations` + Whether this tool should be deferred and discovered via tool search. - The annotations of the text output. + - `Optional description` - - `String text` + Optional description of the custom tool, used to provide more context. - The text output from the model. + - `Optional format` - - `JsonValue; type "output_text"constant` + The input format for the custom tool. Default is unconstrained text. - The type of the output text. Always `output_text`. + - `JsonValue;` - - `Optional> logprobs` + - `JsonValue; type "text"constant` - - `JsonValue; type "multi_agent_call_output"constant` + Unconstrained text format. Always `text`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `TEXT("text")` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `class Grammar:` - - `Optional agent` + A grammar defined by the user. - The agent that produced this item. + - `String definition` - - `String agentName` + The grammar definition. - The canonical name of the agent that produced this item. + - `Syntax syntax` - - `class BetaResponseFunctionWebSearch:` + The syntax of the grammar definition. One of `lark` or `regex`. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `LARK("lark")` - - `class BetaResponseComputerToolCall:` + - `REGEX("regex")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `JsonValue; type "grammar"constant` - - `class BetaResponseComputerToolCallOutputItem:` + Grammar format. Always `grammar`. - - `String id` + - `GRAMMAR("grammar")` - The unique ID of the computer call tool output. + - `class BetaNamespaceTool:` - - `String callId` + Groups function/custom tools under a shared namespace. - The ID of the computer tool call that produced the output. + - `String description` - - `BetaResponseComputerToolCallOutputScreenshot output` + A description of the namespace shown to the model. - A computer screenshot image used with the computer use tool. + - `String name` - - `Status status` + The namespace name used in tool calls (for example, `crm`). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `List tools` - - `COMPLETED("completed")` + The function/custom tools available inside this namespace. - - `INCOMPLETE("incomplete")` + - `class Function:` - - `FAILED("failed")` + - `String name` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "function"constant` - - `JsonValue; type "computer_call_output"constant` + - `FUNCTION("function")` - The type of the computer tool call output. Always `computer_call_output`. + - `Optional> allowedCallers` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The tool invocation context(s). - - `Optional> acknowledgedSafetyChecks` + - `DIRECT("direct")` - The safety checks reported by the API that have been acknowledged by the - developer. + - `PROGRAMMATIC("programmatic")` - - `String id` + - `Optional deferLoading` - The ID of the pending safety check. + Whether this function should be deferred and discovered via tool search. - - `Optional code` + - `Optional description` - The type of the pending safety check. + - `Optional outputSchema` - - `Optional message` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Details about the pending safety check. + - `Optional parameters` - - `Optional agent` + - `Optional strict` - The agent that produced this item. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `String agentName` + - `class BetaCustomTool:` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional createdBy` + - `JsonValue; type "namespace"constant` - The identifier of the actor that created the item. + The type of the tool. Always `namespace`. - - `class BetaResponseReasoningItem:` + - `NAMESPACE("namespace")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class BetaToolSearchTool:` - - `Program` + Hosted or BYOT tool search configuration for deferred tools. - - `String id` + - `JsonValue; type "tool_search"constant` - The unique ID of the program item. + The type of the tool. Always `tool_search`. - - `String callId` + - `TOOL_SEARCH("tool_search")` - The stable call ID of the program item. + - `Optional description` - - `String code` + Description shown to the model for a client-executed tool search tool. - The JavaScript source executed by programmatic tool calling. + - `Optional execution` - - `String fingerprint` + Whether tool search is executed by the server or by the client. - Opaque program replay fingerprint that must be round-tripped. + - `SERVER("server")` - - `JsonValue; type "program"constant` + - `CLIENT("client")` - The type of the item. Always `program`. + - `Optional parameters` - - `PROGRAM("program")` + Parameter schema for a client-executed tool search tool. - - `Optional agent` + - `class BetaWebSearchPreviewTool:` - The agent that produced this item. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String agentName` + - `Type type` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `ProgramOutput` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `String id` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - The unique ID of the program output item. + - `Optional> searchContentTypes` - - `String callId` + - `TEXT("text")` - The call ID of the program item. + - `IMAGE("image")` - - `String result` + - `Optional searchContextSize` - The result produced by the program item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Status status` + - `LOW("low")` - The terminal status of the program output item. + - `MEDIUM("medium")` - - `COMPLETED("completed")` + - `HIGH("high")` - - `INCOMPLETE("incomplete")` + - `Optional userLocation` - - `JsonValue; type "program_output"constant` + The user's location. - The type of the item. Always `program_output`. + - `JsonValue; type "approximate"constant` - - `PROGRAM_OUTPUT("program_output")` + The type of location approximation. Always `approximate`. - - `Optional agent` + - `APPROXIMATE("approximate")` - The agent that produced this item. + - `Optional city` - - `String agentName` + Free text input for the city of the user, e.g. `San Francisco`. - The canonical name of the agent that produced this item. + - `Optional country` - - `class BetaResponseToolSearchCall:` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `String id` + - `Optional region` - The unique ID of the tool search call item. + Free text input for the region of the user, e.g. `California`. - - `JsonValue arguments` + - `Optional timezone` - Arguments used for the tool search call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Optional callId` + - `class BetaApplyPatchTool:` - The unique ID of the tool search call generated by the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `Execution execution` + - `JsonValue; type "apply_patch"constant` - Whether tool search was executed by the server or by the client. + The type of the tool. Always `apply_patch`. - - `SERVER("server")` + - `APPLY_PATCH("apply_patch")` - - `CLIENT("client")` + - `Optional> allowedCallers` - - `Status status` + The tool invocation context(s). - The status of the tool search call item that was recorded. + - `DIRECT("direct")` - - `IN_PROGRESS("in_progress")` + - `PROGRAMMATIC("programmatic")` - - `COMPLETED("completed")` + - `JsonValue; type "tool_search_output"constant` - - `INCOMPLETE("incomplete")` + The item type. Always `tool_search_output`. - - `JsonValue; type "tool_search_call"constant` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - The type of the item. Always `tool_search_call`. + - `Optional id` - - `TOOL_SEARCH_CALL("tool_search_call")` + The unique ID of this tool search output. - `Optional agent` @@ -28774,21 +45850,11 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem:` - - - `String id` - - The unique ID of the tool search output item. - - `Optional callId` The unique ID of the tool search call generated by the model. - - `Execution execution` + - `Optional execution` Whether tool search was executed by the server or by the client. @@ -28796,9 +45862,9 @@ Get a model response - `CLIENT("client")` - - `Status status` + - `Optional status` - The status of the tool search output item that was recorded. + The status of the tool search output. - `IN_PROGRESS("in_progress")` @@ -28806,9 +45872,17 @@ Get a model response - `INCOMPLETE("incomplete")` + - `AdditionalTools` + + - `JsonValue; role "developer"constant` + + The role that provided the additional tools. Only `developer` is supported. + + - `DEVELOPER("developer")` + - `List tools` - The loaded tool definitions returned by tool search. + A list of additional tools made available at this item. - `class BetaFunctionTool:` @@ -28865,11 +45939,15 @@ Get a model response Allows the assistant to create, delete, or update files using unified diffs. - - `JsonValue; type "tool_search_output"constant` + - `JsonValue; type "additional_tools"constant` - The type of the item. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `ADDITIONAL_TOOLS("additional_tools")` + + - `Optional id` + + The unique ID of this additional tools item. - `Optional agent` @@ -28879,100 +45957,128 @@ Get a model response The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningItem:` - - `AdditionalTools` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `String id` - The unique ID of the additional tools item. + The unique identifier of the reasoning content. - - `Role role` + - `List summary` - The role that provided the additional tools. + Reasoning summary content. - - `UNKNOWN("unknown")` + - `String text` - - `USER("user")` + A summary of the reasoning output from the model so far. - - `ASSISTANT("assistant")` + - `JsonValue; type "summary_text"constant` - - `SYSTEM("system")` + The type of the object. Always `summary_text`. - - `CRITIC("critic")` + - `SUMMARY_TEXT("summary_text")` - - `DISCRIMINATOR("discriminator")` + - `JsonValue; type "reasoning"constant` - - `DEVELOPER("developer")` + The type of the object. Always `reasoning`. - - `TOOL("tool")` + - `REASONING("reasoning")` - - `List tools` + - `Optional agent` - The additional tool definitions made available at this item. + The agent that produced this item. - - `class BetaFunctionTool:` + - `String agentName` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool:` + - `Optional> content` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Reasoning text content. - - `class BetaComputerTool:` + - `String text` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The reasoning text from the model. - - `class BetaComputerUsePreviewTool:` + - `JsonValue; type "reasoning_text"constant` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the reasoning text. Always `reasoning_text`. - - `class BetaWebSearchTool:` + - `REASONING_TEXT("reasoning_text")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional encryptedContent` - - `Mcp` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `CodeInterpreter` + - `Optional status` - - `JsonValue;` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `ImageGeneration` + - `IN_PROGRESS("in_progress")` - - `JsonValue;` + - `COMPLETED("completed")` - - `class BetaFunctionShellTool:` + - `INCOMPLETE("incomplete")` - A tool that allows the model to execute shell commands. + - `class BetaResponseCompactionItemParam:` - - `class BetaCustomTool:` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `String encryptedContent` - - `class BetaNamespaceTool:` + The encrypted content of the compaction summary. - Groups function/custom tools under a shared namespace. + - `JsonValue; type "compaction"constant` - - `class BetaToolSearchTool:` + The type of the item. Always `compaction`. - Hosted or BYOT tool search configuration for deferred tools. + - `COMPACTION("compaction")` - - `class BetaWebSearchPreviewTool:` + - `Optional id` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The ID of the compaction item. - - `class BetaApplyPatchTool:` + - `Optional agent` - Allows the assistant to create, delete, or update files using unified diffs. + The agent that produced this item. - - `JsonValue; type "additional_tools"constant` + - `String agentName` - The type of the item. Always `additional_tools`. + The canonical name of the agent that produced this item. - - `ADDITIONAL_TOOLS("additional_tools")` + - `ImageGenerationCall` + + - `String id` + + The unique ID of the image generation call. + + - `Optional 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")` - `Optional agent` @@ -28982,63 +46088,74 @@ Get a model response The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` + - `class BetaResponseCodeInterpreterToolCall:` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A tool call to run code. - `String id` - The unique ID of the compaction item. + The unique ID of the code interpreter tool call. - - `String encryptedContent` + - `Optional code` - The encrypted content that was produced by compaction. + The code to run, or null if not available. - - `JsonValue; type "compaction"constant` + - `String containerId` - The type of the item. Always `compaction`. + The ID of the container used to run the code. - - `COMPACTION("compaction")` + - `Optional> outputs` - - `Optional agent` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The agent that produced this item. + - `class Logs:` - - `String agentName` + The logs output from the code interpreter. - The canonical name of the agent that produced this item. + - `String logs` - - `Optional createdBy` + The logs output from the code interpreter. - The identifier of the actor that created the item. + - `JsonValue; type "logs"constant` - - `ImageGenerationCall` + The type of the output. Always `logs`. - - `String id` + - `LOGS("logs")` - The unique ID of the image generation call. + - `class Image:` - - `Optional result` + The image output from the code interpreter. - The generated image encoded in base64. + - `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 image generation call. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - - `GENERATING("generating")` + - `INCOMPLETE("incomplete")` + + - `INTERPRETING("interpreting")` - `FAILED("failed")` - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "code_interpreter_call"constant` - The type of the image generation call. Always `image_generation_call`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - `Optional agent` @@ -29048,10 +46165,6 @@ Get a model response The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. - - `LocalShellCall` - `String id` @@ -29150,13 +46263,7 @@ Get a model response - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionShellToolCall:` - - A tool call that executes one or more shell commands in a managed environment. - - - `String id` - - The unique ID of the shell tool call. Populated when this item is returned via API. + - `ShellCall` - `Action action` @@ -29164,60 +46271,30 @@ Get a model response - `List commands` + Ordered shell commands for the execution environment to run. + - `Optional maxOutputLength` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `Optional timeoutMs` - Optional timeout in milliseconds for the commands. + 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. - - `Optional environment` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment:` - - Represents the use of a local environment to perform shell actions. - - - `JsonValue; type "local"constant` - - The environment type. Always `local`. - - - `LOCAL("local")` - - - `class BetaResponseContainerReference:` - - Represents a container created with /v1/containers. - - - `String containerId` - - - `JsonValue; type "container_reference"constant` - - The environment type. Always `container_reference`. - - - `CONTAINER_REFERENCE("container_reference")` - - - `Status status` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - `JsonValue; type "shell_call"constant` The type of the item. Always `shell_call`. - `SHELL_CALL("shell_call")` + - `Optional id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -29234,6 +46311,8 @@ Get a model response - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -29244,35 +46323,41 @@ Get a model response - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - - `Optional createdBy` + - `Optional environment` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput:` + - `class BetaLocalEnvironment:` - The output of a shell tool call that was emitted. + - `class BetaContainerReference:` - - `String id` + - `Optional status` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String callId` + - `IN_PROGRESS("in_progress")` - The unique ID of the shell tool call generated by the model. + - `COMPLETED("completed")` - - `Optional maxOutputLength` + - `INCOMPLETE("incomplete")` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `ShellCallOutput` - - `List output` + - `String callId` - An array of shell call output contents + The unique ID of the shell tool call generated by the model. + + - `List output` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `Outcome outcome` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `JsonValue;` @@ -29288,7 +46373,7 @@ Get a model response - `long exitCode` - Exit code from the shell process. + The exit code returned by the shell process. - `JsonValue; type "exit"constant` @@ -29298,32 +46383,22 @@ Get a model response - `String stderr` - The standard error output that was captured. + Captured stderr output for the shell call. - `String stdout` - The standard output that was captured. - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `Status status` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` + Captured stdout output for the shell call. - `JsonValue; type "shell_call_output"constant` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -29340,6 +46415,8 @@ Get a model response - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -29350,19 +46427,25 @@ Get a model response - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - - `Optional createdBy` + - `Optional maxOutputLength` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall:` + - `Optional status` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `String id` + - `IN_PROGRESS("in_progress")` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `ApplyPatchCall` - `String callId` @@ -29370,55 +46453,55 @@ Get a model response - `Operation operation` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `class CreateFile:` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `String diff` - Diff to apply. + Unified diff content to apply when creating the file. - `String path` - Path of the file to create. + Path of the file to create relative to the workspace root. - `JsonValue; type "create_file"constant` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `CREATE_FILE("create_file")` - `class DeleteFile:` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `String path` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `JsonValue; type "delete_file"constant` - Delete the specified file. + The operation type. Always `delete_file`. - `DELETE_FILE("delete_file")` - `class UpdateFile:` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `String diff` - Diff to apply. + Unified diff content to apply to the existing file. - `String path` - Path of the file to update. + Path of the file to update relative to the workspace root. - `JsonValue; type "update_file"constant` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `UPDATE_FILE("update_file")` @@ -29436,6 +46519,10 @@ Get a model response - `APPLY_PATCH_CALL("apply_patch_call")` + - `Optional id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -29452,6 +46539,8 @@ Get a model response - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -29462,19 +46551,11 @@ Get a model response - `JsonValue; type "program"constant` - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput:` - - The output emitted by an apply patch tool call. + The caller type. Always `program`. - - `String id` + - `PROGRAM("program")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `ApplyPatchCallOutput` - `String callId` @@ -29494,6 +46575,10 @@ Get a model response - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `Optional id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -29510,6 +46595,8 @@ Get a model response - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -29520,74 +46607,13 @@ Get a model response - `JsonValue; type "program"constant` - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call output. - - - `Optional output` - - Optional textual output returned by the apply patch tool. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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 error` + The caller type. Always `program`. - The error from the tool call, if any. + - `PROGRAM("program")` - `Optional output` - The output from the tool call. - - - `Optional 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")` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `McpListTools` @@ -29671,10 +46697,6 @@ Get a model response - `McpApprovalResponse` - - `String id` - - The unique ID of the approval response - - `String approvalRequestId` The ID of the approval request being answered. @@ -29689,6 +46711,10 @@ Get a model response - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `Optional id` + + The unique ID of the approval response + - `Optional agent` The agent that produced this item. @@ -29701,1179 +46727,694 @@ Get a model response Optional reason for the decision. - - `class BetaResponseCustomToolCall:` - - A call to a custom tool created by the model. - - - `class BetaResponseCustomToolCallOutputItem:` - - The output of a custom tool call from your code, being sent back to the model. + - `McpCall` - `String id` - The unique ID of the custom tool call output item. - - - `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")` - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `boolean parallelToolCalls` - - Whether to allow the model to run tool calls in parallel. - - - `Optional temperature` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. - - - `ToolChoice toolChoice` - - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. - - - `enum BetaToolChoiceOptions:` - - Controls which (if any) tool is called by the model. - - `none` means the model will not call any tool and instead generates a message. - - `auto` means the model can pick between generating a message or calling one or - more tools. - - `required` means the model must call one or more tools. - - - `NONE("none")` - - - `AUTO("auto")` - - - `REQUIRED("required")` - - - `class BetaToolChoiceAllowed:` - - Constrains the tools available to the model to a pre-defined set. - - - `Mode mode` - - Constrains the tools available to the model to a pre-defined set. - - `auto` allows the model to pick from among the allowed tools and generate a - message. - - `required` requires the model to call one or more of the allowed tools. - - - `AUTO("auto")` - - - `REQUIRED("required")` - - - `List tools` - - A list of tool definitions that the model should be allowed to call. - - For the Responses API, the list of tool definitions might look like: - - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` - - - `JsonValue; type "allowed_tools"constant` - - Allowed tool configuration type. Always `allowed_tools`. - - - `ALLOWED_TOOLS("allowed_tools")` - - - `class BetaToolChoiceTypes:` - - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - - `Type type` - - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - Allowed values are: - - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` - - - `FILE_SEARCH("file_search")` - - - `WEB_SEARCH_PREVIEW("web_search_preview")` - - - `COMPUTER("computer")` - - - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - - `COMPUTER_USE("computer_use")` - - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - - `IMAGE_GENERATION("image_generation")` - - - `CODE_INTERPRETER("code_interpreter")` + The unique ID of the tool call. - - `class BetaToolChoiceFunction:` + - `String arguments` - Use this option to force the model to call a specific function. + A JSON string of the arguments passed to the tool. - `String name` - The name of the function to call. - - - `JsonValue; type "function"constant` - - For function calling, the type is always `function`. - - - `FUNCTION("function")` - - - `class BetaToolChoiceMcp:` - - Use this option to force the model to call a specific tool on a remote MCP server. + The name of the tool that was run. - `String serverLabel` - The label of the MCP server to use. - - - `JsonValue; type "mcp"constant` - - For MCP tools, the type is always `mcp`. - - - `MCP("mcp")` - - - `Optional name` - - The name of the tool to call on the server. - - - `class BetaToolChoiceCustom:` - - Use this option to force the model to call a specific custom tool. - - - `String name` - - The name of the custom tool to call. - - - `JsonValue; type "custom"constant` - - For custom tool calling, the type is always `custom`. - - - `CUSTOM("custom")` - - - `JsonValue;` - - - `JsonValue; type "programmatic_tool_calling"constant` - - The tool to call. Always `programmatic_tool_calling`. - - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - - `class BetaToolChoiceApplyPatch:` - - Forces the model to call the apply_patch tool when executing a tool call. - - - `JsonValue; type "apply_patch"constant` - - The tool to call. Always `apply_patch`. - - - `APPLY_PATCH("apply_patch")` - - - `class BetaToolChoiceShell:` - - Forces the model to call the shell tool when a tool call is required. - - - `JsonValue; type "shell"constant` - - The tool to call. Always `shell`. - - - `SHELL("shell")` - - - `List tools` - - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. - - We support the following categories of tools: - - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. - - - `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `class BetaFileSearchTool:` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class BetaComputerTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool:` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `Mcp` - - - `CodeInterpreter` - - - `JsonValue;` - - - `ImageGeneration` - - - `JsonValue;` - - - `class BetaFunctionShellTool:` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool:` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class BetaNamespaceTool:` - - Groups function/custom tools under a shared namespace. + The label of the MCP server running the tool. - - `class BetaToolSearchTool:` + - `JsonValue; type "mcp_call"constant` - Hosted or BYOT tool search configuration for deferred tools. + The type of the item. Always `mcp_call`. - - `class BetaWebSearchPreviewTool:` + - `MCP_CALL("mcp_call")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional agent` - - `class BetaApplyPatchTool:` + The agent that produced this item. - Allows the assistant to create, delete, or update files using unified diffs. + - `String agentName` - - `Optional topP` + The canonical name of the agent that produced this item. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `Optional approvalRequestId` - We generally recommend altering this or `temperature` but not both. + 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 background` + - `Optional error` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The error from the tool call, if any. - - `Optional completedAt` + - `Optional output` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The output from the tool call. - - `Optional conversation` + - `Optional status` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `String id` + - `IN_PROGRESS("in_progress")` - The unique ID of the conversation that this response was associated with. + - `COMPLETED("completed")` - - `Optional maxOutputTokens` + - `INCOMPLETE("incomplete")` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `CALLING("calling")` - - `Optional maxToolCalls` + - `FAILED("failed")` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `class BetaResponseCustomToolCallOutput:` - - `Optional moderation` + The output of a custom tool call from your code, being sent back to the model. - Moderation results for the response input and output, if moderated completions were requested. + - `String callId` - - `Input input` + The call ID, used to map this custom tool call output to a custom tool call. - Moderation for the response input. + - `Output output` - - `class ModerationResult:` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - A moderation result produced for the response input or output. + - `String` - - `Categories categories` + - `List` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `class BetaResponseInputText:` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + A text input to the model. - Which modalities of input are reflected by the score for each category. + - `class BetaResponseInputImage:` - - `TEXT("text")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `IMAGE("image")` + - `class BetaResponseInputFile:` - - `CategoryScores categoryScores` + A file input to the model. - A dictionary of moderation categories to scores. + - `JsonValue; type "custom_tool_call_output"constant` - - `boolean flagged` + The type of the custom tool call output. Always `custom_tool_call_output`. - A boolean indicating whether the content was flagged by any category. + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - - `String model` + - `Optional id` - The moderation model that produced this result. + The unique ID of the custom tool call output in the OpenAI platform. - - `JsonValue; type "moderation_result"constant` + - `Optional agent` - The object type, which was always `moderation_result` for successful moderation results. + The agent that produced this item. - - `MODERATION_RESULT("moderation_result")` + - `String agentName` - - `class Error:` + The canonical name of the agent that produced this item. - An error produced while attempting moderation for the response input or output. + - `Optional caller` - - `String code` + The execution context that produced this tool call. - The error code. + - `JsonValue;` - - `String message` + - `JsonValue; type "direct"constant` - The error message. + The caller type. Always `direct`. - - `JsonValue; type "error"constant` + - `DIRECT("direct")` - The object type, which was always `error` for moderation failures. + - `class Program:` - - `ERROR("error")` + - `String callerId` - - `Output output` + The call ID of the program item that produced this tool call. - Moderation for the response output. + - `JsonValue; type "program"constant` - - `class ModerationResult:` + The caller type. Always `program`. - A moderation result produced for the response input or output. + - `PROGRAM("program")` - - `Categories categories` + - `class BetaResponseCustomToolCall:` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + A call to a custom tool created by the model. - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `String callId` - Which modalities of input are reflected by the score for each category. + An identifier used to map this custom tool call to a tool call output. - - `TEXT("text")` + - `String input` - - `IMAGE("image")` + The input for the custom tool call generated by the model. - - `CategoryScores categoryScores` + - `String name` - A dictionary of moderation categories to scores. + The name of the custom tool being called. - - `boolean flagged` + - `JsonValue; type "custom_tool_call"constant` - A boolean indicating whether the content was flagged by any category. + The type of the custom tool call. Always `custom_tool_call`. - - `String model` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - The moderation model that produced this result. + - `Optional id` - - `JsonValue; type "moderation_result"constant` + The unique ID of the custom tool call in the OpenAI platform. - The object type, which was always `moderation_result` for successful moderation results. + - `Optional agent` - - `MODERATION_RESULT("moderation_result")` + The agent that produced this item. - - `class Error:` + - `String agentName` - An error produced while attempting moderation for the response input or output. + The canonical name of the agent that produced this item. - - `String code` + - `Optional caller` - The error code. + The execution context that produced this tool call. - - `String message` + - `JsonValue;` - The error message. + - `JsonValue; type "direct"constant` - - `JsonValue; type "error"constant` + - `DIRECT("direct")` - The object type, which was always `error` for moderation failures. + - `class Program:` - - `ERROR("error")` + - `String callerId` - - `Optional previousResponseId` + The call ID of the program item that produced this tool call. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `JsonValue; type "program"constant` - - `Optional prompt` + - `PROGRAM("program")` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `Optional namespace` - - `String id` + The namespace of the custom tool being called. - The unique identifier of the prompt template to use. + - `CompactionTrigger` - - `Optional variables` + - `JsonValue; type "compaction_trigger"constant` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The type of the item. Always `compaction_trigger`. - - `String` + - `COMPACTION_TRIGGER("compaction_trigger")` - - `class BetaResponseInputText:` + - `Optional agent` - A text input to the model. + The agent that produced this item. - - `class BetaResponseInputImage:` + - `String agentName` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `class BetaResponseInputFile:` + - `ItemReference` - A file input to the model. + - `String id` - - `Optional version` + The ID of the item to reference. - Optional version of the prompt template. + - `Optional agent` - - `Optional promptCacheKey` + The agent that produced this item. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `String agentName` - - `Optional promptCacheOptions` + The canonical name of the agent that produced this item. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `Optional type` - - `Mode mode` + The type of item to reference. Always `item_reference`. - Whether implicit prompt-cache breakpoints were enabled. + - `ITEM_REFERENCE("item_reference")` - - `IMPLICIT("implicit")` + - `Program` - - `EXPLICIT("explicit")` + - `String id` - - `Ttl ttl` + The unique ID of this program item. - The minimum lifetime applied to each cache breakpoint. + - `String callId` - - `_30M("30m")` + The stable call ID of the program item. - - `Optional promptCacheRetention` + - `String code` - Deprecated. Use `prompt_cache_options.ttl` instead. + The JavaScript source executed by programmatic tool calling. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `String fingerprint` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Opaque program replay fingerprint that must be round-tripped. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `JsonValue; type "program"constant` - - `IN_MEMORY("in_memory")` + The item type. Always `program`. - - `_24H("24h")` + - `PROGRAM("program")` - - `Optional reasoning` + - `Optional agent` - **gpt-5 and o-series models only** + The agent that produced this item. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `String agentName` - - `Optional context` + The canonical name of the agent that produced this item. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `ProgramOutput` - - `AUTO("auto")` + - `String id` - - `CURRENT_TURN("current_turn")` + The unique ID of this program output item. - - `ALL_TURNS("all_turns")` + - `String callId` - - `Optional effort` + The call ID of the program item. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `String result` - - `NONE("none")` + The result produced by the program item. - - `MINIMAL("minimal")` + - `Status status` - - `LOW("low")` + The terminal status of the program output. - - `MEDIUM("medium")` + - `COMPLETED("completed")` - - `HIGH("high")` + - `INCOMPLETE("incomplete")` - - `XHIGH("xhigh")` + - `JsonValue; type "program_output"constant` - - `MAX("max")` + The item type. Always `program_output`. - - `Optional generateSummary` + - `PROGRAM_OUTPUT("program_output")` - **Deprecated:** use `summary` instead. + - `Optional agent` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The agent that produced this item. - - `AUTO("auto")` + - `String agentName` - - `CONCISE("concise")` + The canonical name of the agent that produced this item. - - `DETAILED("detailed")` + - `Optional metadata` - - `Optional mode` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Controls the reasoning execution mode for the request. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - When returned on a response, this is the effective execution mode. + - `Model model` - - `STANDARD("standard")` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `PRO("pro")` + - `GPT_5_6_SOL("gpt-5.6-sol")` - - `Optional summary` + - `GPT_5_6_TERRA("gpt-5.6-terra")` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `GPT_5_6_LUNA("gpt-5.6-luna")` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `GPT_5_4("gpt-5.4")` - - `AUTO("auto")` + - `GPT_5_4_MINI("gpt-5.4-mini")` - - `CONCISE("concise")` + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `DETAILED("detailed")` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - - `Optional safetyIdentifier` + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - `Optional serviceTier` + - `GPT_5_2("gpt-5.2")` - Specifies the processing type used for serving the request. + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `GPT_5_2_PRO("gpt-5.2-pro")` - - `AUTO("auto")` + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `DEFAULT("default")` + - `GPT_5_1("gpt-5.1")` - - `FLEX("flex")` + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - `SCALE("scale")` + - `GPT_5_1_CODEX("gpt-5.1-codex")` - - `PRIORITY("priority")` + - `GPT_5_1_MINI("gpt-5.1-mini")` - - `Optional status` + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `GPT_5("gpt-5")` - - `COMPLETED("completed")` + - `GPT_5_MINI("gpt-5-mini")` - - `FAILED("failed")` + - `GPT_5_NANO("gpt-5-nano")` - - `IN_PROGRESS("in_progress")` + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - `CANCELLED("cancelled")` + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `QUEUED("queued")` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - `INCOMPLETE("incomplete")` + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `Optional text` + - `GPT_4_1("gpt-4.1")` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `GPT_4_1_MINI("gpt-4.1-mini")` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `Optional format` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - An object specifying the format that the model must output. + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - The default format is `{ "type": "text" }` with no additional options. + - `O4_MINI("o4-mini")` - **Not recommended for gpt-4o and newer models:** + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `O3("o3")` - - `JsonValue;` + - `O3_2025_04_16("o3-2025-04-16")` - - `JsonValue; type "text"constant` + - `O3_MINI("o3-mini")` - The type of response format being defined. Always `text`. + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - `TEXT("text")` + - `O1("o1")` - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `O1_2024_12_17("o1-2024-12-17")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `O1_PREVIEW("o1-preview")` - - `String name` + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `O1_MINI("o1-mini")` - - `Schema schema` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `GPT_4O("gpt-4o")` - - `JsonValue; type "json_schema"constant` + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - The type of response format being defined. Always `json_schema`. + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - `JSON_SCHEMA("json_schema")` + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - - `Optional description` + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - `Optional strict` + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - - `JsonValue;` + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - - `JsonValue; type "json_object"constant` + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - The type of response format being defined. Always `json_object`. + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `JSON_OBJECT("json_object")` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `Optional verbosity` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - `LOW("low")` + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - `MEDIUM("medium")` + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `HIGH("high")` + - `GPT_4O_MINI("gpt-4o-mini")` - - `Optional topLogprobs` + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `GPT_4_TURBO("gpt-4-turbo")` - - `Optional truncation` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - The truncation strategy to use for the model response. + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `AUTO("auto")` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - - `DISABLED("disabled")` + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - - `Optional usage` + - `GPT_4("gpt-4")` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `GPT_4_0314("gpt-4-0314")` - - `long inputTokens` + - `GPT_4_0613("gpt-4-0613")` - The number of input tokens. + - `GPT_4_32K("gpt-4-32k")` - - `InputTokensDetails inputTokensDetails` + - `GPT_4_32K_0314("gpt-4-32k-0314")` - A detailed breakdown of the input tokens. + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `long cacheWriteTokens` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - The number of input tokens that were written to the cache. + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `long cachedTokens` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `long outputTokens` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - The number of output tokens. + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - `OutputTokensDetails outputTokensDetails` + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - A detailed breakdown of the output tokens. + - `O1_PRO("o1-pro")` - - `long reasoningTokens` + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - The number of reasoning tokens. + - `O3_PRO("o3-pro")` - - `long totalTokens` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - The total number of tokens used. + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `Optional user` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` -### Example + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` -```java -package com.openai.example; + - `COMPUTER_USE_PREVIEW("computer-use-preview")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.responses.BetaResponse; -import com.openai.models.beta.responses.ResponseRetrieveParams; + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` -public final class Main { - private Main() {} + - `GPT_5_CODEX("gpt-5-codex")` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `GPT_5_PRO("gpt-5-pro")` - BetaResponse betaResponse = client.beta().responses().retrieve("resp_677efb5139a88190b512bc3fef8e535d"); - } -} -``` + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` -#### Response + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + - `JsonValue; object_ "response"constant` -## Delete a model response + The object type of this resource - always set to `response`. -`beta().responses().delete(ResponseDeleteParamsparams = ResponseDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `RESPONSE("response")` -**delete** `/responses/{response_id}?beta=true` + - `List output` -Delete a model response + An array of content items generated by the model. -### Parameters + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. -- `ResponseDeleteParams params` + - `class BetaResponseOutputMessage:` - - `Optional responseId` + An output message from the model. - - `Optional> betas` + - `class BetaResponseFileSearchToolCall:` - - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. -### Example + - `class BetaResponseFunctionToolCall:` -```java -package com.openai.example; + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.responses.ResponseDeleteParams; + - `class BetaResponseFunctionToolCallOutputItem:` -public final class Main { - private Main() {} + - `String id` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The unique ID of the function call tool output. - client.beta().responses().delete("resp_677efb5139a88190b512bc3fef8e535d"); - } -} -``` + - `String callId` -## Cancel a response + The unique ID of the function tool call generated by the model. -`BetaResponse beta().responses().cancel(ResponseCancelParamsparams = ResponseCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `Output output` -**post** `/responses/{response_id}/cancel?beta=true` + The output from the function call generated by your code. + Can be a string or an list of output content. -Cancel a response + - `String` -### Parameters + - `List` -- `ResponseCancelParams params` + - `class BetaResponseInputText:` - - `Optional responseId` + A text input to the model. - - `Optional> betas` + - `class BetaResponseInputImage:` - - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -### Returns + - `class BetaResponseInputFile:` -- `class BetaResponse:` + A file input to the model. - - `String id` + - `Status status` - Unique identifier for this Response. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `double createdAt` + - `IN_PROGRESS("in_progress")` - Unix timestamp (in seconds) of when this Response was created. + - `COMPLETED("completed")` - - `Optional error` + - `INCOMPLETE("incomplete")` - An error object returned when the model fails to generate a Response. + - `JsonValue; type "function_call_output"constant` - - `Code code` + The type of the function tool call output. Always `function_call_output`. - The error code for the response. + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `SERVER_ERROR("server_error")` + - `Optional agent` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The agent that produced this item. - - `INVALID_PROMPT("invalid_prompt")` + - `String agentName` - - `BIO_POLICY("bio_policy")` + The canonical name of the agent that produced this item. - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + - `Optional caller` - - `INVALID_IMAGE("invalid_image")` + The execution context that produced this tool call. - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + - `JsonValue;` - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `JsonValue; type "direct"constant` - - `INVALID_IMAGE_URL("invalid_image_url")` + The caller type. Always `direct`. - - `IMAGE_TOO_LARGE("image_too_large")` + - `DIRECT("direct")` - - `IMAGE_TOO_SMALL("image_too_small")` + - `class Program:` - - `IMAGE_PARSE_ERROR("image_parse_error")` + - `String callerId` - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + The call ID of the program item that produced this tool call. - - `INVALID_IMAGE_MODE("invalid_image_mode")` + - `JsonValue; type "program"constant` - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + The caller type. Always `program`. - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + - `PROGRAM("program")` - - `EMPTY_IMAGE_FILE("empty_image_file")` + - `Optional createdBy` - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + The identifier of the actor that created the item. - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + - `AgentMessage` - - `String message` + - `String id` - A human-readable description of the error. + The unique ID of the agent message. - - `Optional incompleteDetails` + - `String author` - Details about why the response is incomplete. + The sending agent identity. - - `Optional reason` + - `List content` - The reason why the response is incomplete. + Encrypted content sent between agents. - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + - `class BetaResponseInputText:` - - `CONTENT_FILTER("content_filter")` + A text input to the model. - - `Optional instructions` + - `class BetaResponseOutputText:` - A system (or developer) message inserted into the model's context. + A text output from the model. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `class Text:` - - `String` + A text content. - - `List` + - `String text` - - `class BetaEasyInputMessage:` + - `JsonValue; type "text"constant` - 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. + - `TEXT("text")` - - `Content content` + - `class SummaryText:` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + A summary text from the model. - - `String` + - `String text` - - `List` + A summary of the reasoning output from the model so far. - - `class BetaResponseInputText:` + - `JsonValue; type "summary_text"constant` - A text input to the model. + The type of the object. Always `summary_text`. - - `String text` + - `SUMMARY_TEXT("summary_text")` - The text input to the model. + - `class ReasoningText:` - - `JsonValue; type "input_text"constant` + Reasoning text from the model. - The type of the input item. Always `input_text`. + - `String text` - - `INPUT_TEXT("input_text")` + The reasoning text from the model. - - `Optional promptCacheBreakpoint` + - `JsonValue; type "reasoning_text"constant` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the reasoning text. Always `reasoning_text`. - - `JsonValue; mode "explicit"constant` + - `REASONING_TEXT("reasoning_text")` - The breakpoint mode. Always `explicit`. + - `class BetaResponseOutputRefusal:` - - `EXPLICIT("explicit")` + A refusal from the model. - `class BetaResponseInputImage:` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class ComputerScreenshot:` + + A screenshot of a computer. + - `Detail detail` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `LOW("low")` @@ -30883,19 +47424,19 @@ Cancel a response - `ORIGINAL("original")` - - `JsonValue; type "input_image"constant` + - `Optional fileId` - The type of the input item. Always `input_image`. + The identifier of an uploaded file that contains the screenshot. - - `INPUT_IMAGE("input_image")` + - `Optional imageUrl` - - `Optional fileId` + The URL of the screenshot image. - The ID of the file to be sent to the model. + - `JsonValue; type "computer_screenshot"constant` - - `Optional imageUrl` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - `Optional promptCacheBreakpoint` @@ -30911,103 +47452,73 @@ Cancel a response 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` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. + - `class EncryptedContent:` - - `Optional filename` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The name of the file to be sent to the model. + - `String encryptedContent` - - `Optional promptCacheBreakpoint` + Opaque encrypted content. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; type "encrypted_content"constant` - - `JsonValue; mode "explicit"constant` + The type of the input item. Always `encrypted_content`. - The breakpoint mode. Always `explicit`. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `EXPLICIT("explicit")` + - `String recipient` - - `Role role` + The destination agent identity. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `JsonValue; type "agent_message"constant` - - `USER("user")` + The type of the item. Always `agent_message`. - - `ASSISTANT("assistant")` + - `AGENT_MESSAGE("agent_message")` - - `SYSTEM("system")` + - `Optional agent` - - `DEVELOPER("developer")` + The agent that produced this item. - - `Optional phase` + - `String agentName` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The canonical name of the agent that produced this item. - - `COMMENTARY("commentary")` + - `MultiAgentCall` - - `Optional type` + - `String id` - The type of the message input. Always `message`. + The unique ID of the multi-agent call item. - - `MESSAGE("message")` + - `Action action` - - `Message` + The multi-agent action to execute. - - `List content` + - `SPAWN_AGENT("spawn_agent")` - A list of one or many input items to the model, containing different content - types. + - `INTERRUPT_AGENT("interrupt_agent")` - - `class BetaResponseInputText:` + - `LIST_AGENTS("list_agents")` - A text input to the model. + - `SEND_MESSAGE("send_message")` - - `class BetaResponseInputImage:` + - `FOLLOWUP_TASK("followup_task")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `WAIT_AGENT("wait_agent")` - - `class BetaResponseInputFile:` + - `String arguments` - A file input to the model. + The JSON string of arguments generated for the action. - - `Role role` + - `String callId` - The role of the message input. One of `user`, `system`, or `developer`. + The unique ID linking this call to its output. - - `USER("user")` + - `JsonValue; type "multi_agent_call"constant` - - `SYSTEM("system")` + The type of the multi-agent call. Always `multi_agent_call`. - - `DEVELOPER("developer")` + - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional agent` @@ -31017,201 +47528,202 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional status` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `MultiAgentCallOutput` - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The unique ID of the multi-agent call output item. - - `INCOMPLETE("incomplete")` + - `Action action` - - `Optional type` + The multi-agent action that produced this result. - The type of the message input. Always set to `message`. + - `SPAWN_AGENT("spawn_agent")` - - `MESSAGE("message")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `class BetaResponseOutputMessage:` + - `LIST_AGENTS("list_agents")` - An output message from the model. + - `SEND_MESSAGE("send_message")` - - `String id` + - `FOLLOWUP_TASK("followup_task")` - The unique ID of the output message. + - `WAIT_AGENT("wait_agent")` - - `List content` + - `String callId` - The content of the output message. + The unique ID of the multi-agent call. - - `class BetaResponseOutputText:` + - `List output` - A text output from the model. + Text output returned by the multi-agent action. - `List annotations` The annotations of the text output. - - `class FileCitation:` + - `String text` - A citation to a file. + The text output from the model. - - `String fileId` + - `JsonValue; type "output_text"constant` - The ID of the file. + The type of the output text. Always `output_text`. - - `String filename` + - `Optional> logprobs` - The filename of the file cited. + - `JsonValue; type "multi_agent_call_output"constant` - - `long index` + The type of the multi-agent result. Always `multi_agent_call_output`. - The index of the file in the list of files. + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `JsonValue; type "file_citation"constant` + - `Optional agent` - The type of the file citation. Always `file_citation`. + The agent that produced this item. - - `FILE_CITATION("file_citation")` + - `String agentName` - - `class UrlCitation:` + The canonical name of the agent that produced this item. - A citation for a web resource used to generate a model response. + - `class BetaResponseFunctionWebSearch:` - - `long endIndex` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The index of the last character of the URL citation in the message. + - `class BetaResponseComputerToolCall:` - - `long startIndex` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The index of the first character of the URL citation in the message. + - `class BetaResponseComputerToolCallOutputItem:` - - `String title` + - `String id` - The title of the web resource. + The unique ID of the computer call tool output. - - `JsonValue; type "url_citation"constant` + - `String callId` - The type of the URL citation. Always `url_citation`. + The ID of the computer tool call that produced the output. - - `URL_CITATION("url_citation")` + - `BetaResponseComputerToolCallOutputScreenshot output` - - `String url` + A computer screenshot image used with the computer use tool. - The URL of the web resource. + - `Status status` - - `class ContainerFileCitation:` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - A citation for a container file used to generate a model response. + - `COMPLETED("completed")` - - `String containerId` + - `INCOMPLETE("incomplete")` - The ID of the container file. + - `FAILED("failed")` - - `long endIndex` + - `IN_PROGRESS("in_progress")` - The index of the last character of the container file citation in the message. + - `JsonValue; type "computer_call_output"constant` - - `String fileId` + The type of the computer tool call output. Always `computer_call_output`. - The ID of the file. + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `String filename` + - `Optional> acknowledgedSafetyChecks` - The filename of the container file cited. + The safety checks reported by the API that have been acknowledged by the + developer. - - `long startIndex` + - `String id` - The index of the first character of the container file citation in the message. + The ID of the pending safety check. - - `JsonValue; type "container_file_citation"constant` + - `Optional code` - The type of the container file citation. Always `container_file_citation`. + The type of the pending safety check. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `Optional message` - - `class FilePath:` + Details about the pending safety check. - A path to a file. + - `Optional agent` - - `String fileId` + The agent that produced this item. - The ID of the file. + - `String agentName` - - `long index` + The canonical name of the agent that produced this item. - The index of the file in the list of files. + - `Optional createdBy` - - `JsonValue; type "file_path"constant` + The identifier of the actor that created the item. - The type of the file path. Always `file_path`. + - `class BetaResponseReasoningItem:` - - `FILE_PATH("file_path")` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `String text` + - `Program` - The text output from the model. + - `String id` - - `JsonValue; type "output_text"constant` + The unique ID of the program item. - The type of the output text. Always `output_text`. + - `String callId` - - `OUTPUT_TEXT("output_text")` + The stable call ID of the program item. - - `Optional> logprobs` + - `String code` - - `String token` + The JavaScript source executed by programmatic tool calling. - - `List bytes` + - `String fingerprint` - - `double logprob` + Opaque program replay fingerprint that must be round-tripped. - - `List topLogprobs` + - `JsonValue; type "program"constant` - - `String token` + The type of the item. Always `program`. - - `List bytes` + - `PROGRAM("program")` - - `double logprob` + - `Optional agent` - - `class BetaResponseOutputRefusal:` + The agent that produced this item. - A refusal from the model. + - `String agentName` - - `String refusal` + The canonical name of the agent that produced this item. - The refusal explanation from the model. + - `ProgramOutput` - - `JsonValue; type "refusal"constant` + - `String id` - The type of the refusal. Always `refusal`. + The unique ID of the program output item. - - `REFUSAL("refusal")` + - `String callId` - - `JsonValue; role "assistant"constant` + The call ID of the program item. - The role of the output message. Always `assistant`. + - `String result` - - `ASSISTANT("assistant")` + The result produced by the program item. - `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")` + The terminal status of the program output item. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `JsonValue; type "message"constant` + - `JsonValue; type "program_output"constant` - The type of the output message. Always `message`. + The type of the item. Always `program_output`. - - `MESSAGE("message")` + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -31221,47 +47733,43 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional phase` + - `class BetaResponseToolSearchCall:` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `String id` - - `COMMENTARY("commentary")` + The unique ID of the tool search call item. - - `class BetaResponseFileSearchToolCall:` + - `JsonValue arguments` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Arguments used for the tool search call. - - `String id` + - `Optional callId` - The unique ID of the file search tool call. + The unique ID of the tool search call generated by the model. - - `List queries` + - `Execution execution` - The queries used to search for files. + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` - `Status status` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The status of the tool search call item that was recorded. - `IN_PROGRESS("in_progress")` - - `SEARCHING("searching")` - - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `FAILED("failed")` - - - `JsonValue; type "file_search_call"constant` + - `JsonValue; type "tool_search_call"constant` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `tool_search_call`. - - `FILE_SEARCH_CALL("file_search_call")` + - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional agent` @@ -31271,285 +47779,271 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional> results` - - The results of the file search tool call. - - - `Optional attributes` + - `Optional createdBy` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The identifier of the actor that created the item. - - `String` + - `class BetaResponseToolSearchOutputItem:` - - `double` + - `String id` - - `boolean` + The unique ID of the tool search output item. - - `Optional fileId` + - `Optional callId` - The unique ID of the file. + The unique ID of the tool search call generated by the model. - - `Optional filename` + - `Execution execution` - The name of the file. + Whether tool search was executed by the server or by the client. - - `Optional score` + - `SERVER("server")` - The relevance score of the file - a value between 0 and 1. + - `CLIENT("client")` - - `Optional text` + - `Status status` - The text that was retrieved from the file. + The status of the tool search output item that was recorded. - - `class BetaResponseComputerToolCall:` + - `IN_PROGRESS("in_progress")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `COMPLETED("completed")` - - `String id` + - `INCOMPLETE("incomplete")` - The unique ID of the computer call. + - `List tools` - - `String callId` + The loaded tool definitions returned by tool search. - An identifier used when responding to the tool call with output. + - `class BetaFunctionTool:` - - `List pendingSafetyChecks` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The pending safety checks for the computer call. + - `class BetaFileSearchTool:` - - `String id` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The ID of the pending safety check. + - `class BetaComputerTool:` - - `Optional code` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the pending safety check. + - `class BetaComputerUsePreviewTool:` - - `Optional message` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Details about the pending safety check. + - `class BetaWebSearchTool:` - - `Status status` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Mcp` - - `IN_PROGRESS("in_progress")` + - `CodeInterpreter` - - `COMPLETED("completed")` + - `JsonValue;` - - `INCOMPLETE("incomplete")` + - `ImageGeneration` - - `Type type` + - `JsonValue;` - The type of the computer call. Always `computer_call`. + - `class BetaFunctionShellTool:` - - `COMPUTER_CALL("computer_call")` + A tool that allows the model to execute shell commands. - - `Optional action` + - `class BetaCustomTool:` - A click action. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Click` + - `class BetaNamespaceTool:` - - `Button button` + Groups function/custom tools under a shared namespace. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class BetaToolSearchTool:` - - `LEFT("left")` + Hosted or BYOT tool search configuration for deferred tools. - - `RIGHT("right")` + - `class BetaWebSearchPreviewTool:` - - `WHEEL("wheel")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `BACK("back")` + - `class BetaApplyPatchTool:` - - `FORWARD("forward")` + Allows the assistant to create, delete, or update files using unified diffs. - - `JsonValue; type "click"constant` + - `JsonValue; type "tool_search_output"constant` - Specifies the event type. For a click action, this property is always `click`. + The type of the item. Always `tool_search_output`. - - `CLICK("click")` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `long x` + - `Optional agent` - The x-coordinate where the click occurred. + The agent that produced this item. - - `long y` + - `String agentName` - The y-coordinate where the click occurred. + The canonical name of the agent that produced this item. - - `Optional> keys` + - `Optional createdBy` - The keys being held while clicking. + The identifier of the actor that created the item. - - `DoubleClick` + - `AdditionalTools` - - `Optional> keys` + - `String id` - The keys being held while double-clicking. + The unique ID of the additional tools item. - - `JsonValue; type "double_click"constant` + - `Role role` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The role that provided the additional tools. - - `DOUBLE_CLICK("double_click")` + - `UNKNOWN("unknown")` - - `long x` + - `USER("user")` - The x-coordinate where the double click occurred. + - `ASSISTANT("assistant")` - - `long y` + - `SYSTEM("system")` - The y-coordinate where the double click occurred. + - `CRITIC("critic")` - - `Drag` + - `DISCRIMINATOR("discriminator")` - - `List path` + - `DEVELOPER("developer")` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `TOOL("tool")` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `List tools` - - `long x` + The additional tool definitions made available at this item. - The x-coordinate. + - `class BetaFunctionTool:` - - `long y` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The y-coordinate. + - `class BetaFileSearchTool:` - - `JsonValue; type "drag"constant` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Specifies the event type. For a drag action, this property is always set to `drag`. + - `class BetaComputerTool:` - - `DRAG("drag")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional> keys` + - `class BetaComputerUsePreviewTool:` - The keys being held while dragging the mouse. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Keypress` + - `class BetaWebSearchTool:` - - `List keys` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `Mcp` - - `JsonValue; type "keypress"constant` + - `CodeInterpreter` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `JsonValue;` - - `KEYPRESS("keypress")` + - `ImageGeneration` - - `Move` + - `JsonValue;` - - `JsonValue; type "move"constant` + - `class BetaFunctionShellTool:` - Specifies the event type. For a move action, this property is always set to `move`. + A tool that allows the model to execute shell commands. - - `MOVE("move")` + - `class BetaCustomTool:` - - `long x` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The x-coordinate to move to. + - `class BetaNamespaceTool:` - - `long y` + Groups function/custom tools under a shared namespace. - The y-coordinate to move to. + - `class BetaToolSearchTool:` - - `Optional> keys` + Hosted or BYOT tool search configuration for deferred tools. - The keys being held while moving the mouse. + - `class BetaWebSearchPreviewTool:` - - `JsonValue;` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue; type "screenshot"constant` + - `class BetaApplyPatchTool:` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Allows the assistant to create, delete, or update files using unified diffs. - - `SCREENSHOT("screenshot")` + - `JsonValue; type "additional_tools"constant` - - `Scroll` + The type of the item. Always `additional_tools`. - - `long scrollX` + - `ADDITIONAL_TOOLS("additional_tools")` - The horizontal scroll distance. + - `Optional agent` - - `long scrollY` + The agent that produced this item. - The vertical scroll distance. + - `String agentName` - - `JsonValue; type "scroll"constant` + The canonical name of the agent that produced this item. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `class BetaResponseCompactionItem:` - - `SCROLL("scroll")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `long x` + - `String id` - The x-coordinate where the scroll occurred. + The unique ID of the compaction item. - - `long y` + - `String encryptedContent` - The y-coordinate where the scroll occurred. + The encrypted content that was produced by compaction. - - `Optional> keys` + - `JsonValue; type "compaction"constant` - The keys being held while scrolling. + The type of the item. Always `compaction`. - - `Type` + - `COMPACTION("compaction")` - - `String text` + - `Optional agent` - The text to type. + The agent that produced this item. - - `JsonValue; type "type"constant` + - `String agentName` - Specifies the event type. For a type action, this property is always set to `type`. + The canonical name of the agent that produced this item. - - `TYPE("type")` + - `Optional createdBy` - - `JsonValue;` + The identifier of the actor that created the item. - - `JsonValue; type "wait"constant` + - `ImageGenerationCall` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `String id` - - `WAIT("wait")` + The unique ID of the image generation call. - - `Optional> actions` + - `Optional result` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The generated image encoded in base64. - - `Click` + - `Status status` - - `DoubleClick` + The status of the image generation call. - - `Drag` + - `IN_PROGRESS("in_progress")` - - `Keypress` + - `COMPLETED("completed")` - - `Move` + - `GENERATING("generating")` - - `JsonValue;` + - `FAILED("failed")` - - `Scroll` + - `JsonValue; type "image_generation_call"constant` - - `Type` + The type of the image generation call. Always `image_generation_call`. - - `JsonValue;` + - `IMAGE_GENERATION_CALL("image_generation_call")` - `Optional agent` @@ -31559,56 +48053,65 @@ Cancel a response The canonical name of the agent that produced this item. - - `ComputerCallOutput` + - `class BetaResponseCodeInterpreterToolCall:` - - `String callId` + A tool call to run code. - The ID of the computer tool call that produced the output. + - `LocalShellCall` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `String id` - A computer screenshot image used with the computer use tool. + The unique ID of the local shell call. - - `JsonValue; type "computer_screenshot"constant` + - `Action action` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Execute a shell command on the server. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `List command` - - `Optional fileId` + The command to run. - The identifier of an uploaded file that contains the screenshot. + - `Env env` - - `Optional imageUrl` + Environment variables to set for the command. - The URL of the screenshot image. + - `JsonValue; type "exec"constant` - - `JsonValue; type "computer_call_output"constant` + The type of the local shell action. Always `exec`. - The type of the computer tool call output. Always `computer_call_output`. + - `EXEC("exec")` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `Optional timeoutMs` - - `Optional id` + Optional timeout in milliseconds for the command. - The ID of the computer tool call output. + - `Optional user` - - `Optional> acknowledgedSafetyChecks` + Optional user to run the command as. - The safety checks reported by the API that have been acknowledged by the developer. + - `Optional workingDirectory` - - `String id` + Optional working directory to run the command in. - The ID of the pending safety check. + - `String callId` - - `Optional code` + The unique ID of the local shell tool call generated by the model. - The type of the pending safety check. + - `Status status` - - `Optional message` + The status of the local shell call. - Details about the pending safety check. + - `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")` - `Optional agent` @@ -31618,111 +48121,107 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional status` + - `LocalShellCallOutput` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `String id` - - `IN_PROGRESS("in_progress")` + The unique ID of the local shell tool call generated by the model. - - `COMPLETED("completed")` + - `String output` - - `INCOMPLETE("incomplete")` + A JSON string of the output of the local shell tool call. - - `class BetaResponseFunctionWebSearch:` + - `JsonValue; type "local_shell_call_output"constant` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `String id` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - The unique ID of the web search tool call. + - `Optional agent` - - `Action action` + The agent that produced this item. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `String agentName` - - `class Search:` + The canonical name of the agent that produced this item. - Action type "search" - Performs a web search query. + - `Optional status` - - `JsonValue; type "search"constant` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The action type. + - `IN_PROGRESS("in_progress")` - - `SEARCH("search")` + - `COMPLETED("completed")` - - `Optional> queries` + - `INCOMPLETE("incomplete")` - The search queries. + - `class BetaResponseFunctionShellToolCall:` - - `Optional query` + A tool call that executes one or more shell commands in a managed environment. - The search query. + - `String id` - - `Optional> sources` + The unique ID of the shell tool call. Populated when this item is returned via API. - The sources used in the search. + - `Action action` - - `JsonValue; type "url"constant` + The shell commands and limits that describe how to run the tool call. - The type of source. Always `url`. + - `List commands` - - `URL("url")` + - `Optional maxOutputLength` - - `String url` + Optional maximum number of characters to return from each command. - The URL of the source. + - `Optional timeoutMs` - - `class OpenPage:` + Optional timeout in milliseconds for the commands. - Action type "open_page" - Opens a specific URL from search results. + - `String callId` - - `JsonValue; type "open_page"constant` + The unique ID of the shell tool call generated by the model. - The action type. + - `Optional environment` - - `OPEN_PAGE("open_page")` + Represents the use of a local environment to perform shell actions. - - `Optional url` + - `class BetaResponseLocalEnvironment:` - The URL opened by the model. + Represents the use of a local environment to perform shell actions. - - `class FindInPage:` + - `JsonValue; type "local"constant` - Action type "find_in_page": Searches for a pattern within a loaded page. + The environment type. Always `local`. - - `String pattern` + - `LOCAL("local")` - The pattern or text to search for within the page. + - `class BetaResponseContainerReference:` - - `JsonValue; type "find_in_page"constant` + Represents a container created with /v1/containers. - The action type. + - `String containerId` - - `FIND_IN_PAGE("find_in_page")` + - `JsonValue; type "container_reference"constant` - - `String url` + The environment type. Always `container_reference`. - The URL of the page searched for the pattern. + - `CONTAINER_REFERENCE("container_reference")` - `Status status` - The status of the web search tool call. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` - - `SEARCHING("searching")` - - `COMPLETED("completed")` - - `FAILED("failed")` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "web_search_call"constant` + - `JsonValue; type "shell_call"constant` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `shell_call`. - - `WEB_SEARCH_CALL("web_search_call")` + - `SHELL_CALL("shell_call")` - `Optional agent` @@ -31732,209 +48231,215 @@ Cancel a response The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall:` + - `Optional caller` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The execution context that produced this tool call. - - `String arguments` + - `JsonValue;` - A JSON string of the arguments to pass to the function. + - `JsonValue; type "direct"constant` - - `String callId` + - `DIRECT("direct")` - The unique ID of the function tool call generated by the model. + - `class Program:` - - `String name` + - `String callerId` - The name of the function to run. + The call ID of the program item that produced this tool call. - - `JsonValue; type "function_call"constant` + - `JsonValue; type "program"constant` - The type of the function tool call. Always `function_call`. + - `PROGRAM("program")` - - `FUNCTION_CALL("function_call")` + - `Optional createdBy` - - `Optional id` + The ID of the entity that created this tool call. - The unique ID of the function tool call. + - `class BetaResponseFunctionShellToolCallOutput:` - - `Optional agent` + The output of a shell tool call that was emitted. - The agent that produced this item. + - `String id` - - `String agentName` + The unique ID of the shell call output. Populated when this item is returned via API. - The canonical name of the agent that produced this item. + - `String callId` - - `Optional caller` + The unique ID of the shell tool call generated by the model. - The execution context that produced this tool call. + - `Optional maxOutputLength` - - `JsonValue;` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `JsonValue; type "direct"constant` + - `List output` - - `DIRECT("direct")` + An array of shell call output contents - - `class Program:` + - `Outcome outcome` - - `String callerId` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The call ID of the program item that produced this tool call. + - `JsonValue;` - - `JsonValue; type "program"constant` + - `JsonValue; type "timeout"constant` - - `PROGRAM("program")` + The outcome type. Always `timeout`. - - `Optional namespace` + - `TIMEOUT("timeout")` - The namespace of the function to run. + - `class Exit:` - - `Optional status` + Indicates that the shell commands finished and returned an exit code. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `long exitCode` - - `IN_PROGRESS("in_progress")` + Exit code from the shell process. - - `COMPLETED("completed")` + - `JsonValue; type "exit"constant` - - `INCOMPLETE("incomplete")` + The outcome type. Always `exit`. - - `FunctionCallOutput` + - `EXIT("exit")` - - `String callId` + - `String stderr` - The unique ID of the function tool call generated by the model. + The standard error output that was captured. - - `Output output` + - `String stdout` - Text, image, or file output of the function tool call. + The standard output that was captured. - - `String` + - `Optional createdBy` - - `List` + The identifier of the actor that created the item. - - `class BetaResponseInputTextContent:` + - `Status status` - A text input to the model. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `String text` + - `IN_PROGRESS("in_progress")` - The text input to the model. + - `COMPLETED("completed")` - - `JsonValue; type "input_text"constant` + - `INCOMPLETE("incomplete")` - The type of the input item. Always `input_text`. + - `JsonValue; type "shell_call_output"constant` - - `INPUT_TEXT("input_text")` + The type of the shell call output. Always `shell_call_output`. - - `Optional promptCacheBreakpoint` + - `SHELL_CALL_OUTPUT("shell_call_output")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional agent` - - `JsonValue; mode "explicit"constant` + The agent that produced this item. - The breakpoint mode. Always `explicit`. + - `String agentName` - - `EXPLICIT("explicit")` + The canonical name of the agent that produced this item. - - `class BetaResponseInputImageContent:` + - `Optional caller` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The execution context that produced this tool call. - - `JsonValue; type "input_image"constant` + - `JsonValue;` - The type of the input item. Always `input_image`. + - `JsonValue; type "direct"constant` - - `INPUT_IMAGE("input_image")` + - `DIRECT("direct")` - - `Optional detail` + - `class Program:` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `String callerId` - - `LOW("low")` + The call ID of the program item that produced this tool call. - - `HIGH("high")` + - `JsonValue; type "program"constant` - - `AUTO("auto")` + - `PROGRAM("program")` - - `ORIGINAL("original")` + - `Optional createdBy` - - `Optional fileId` + The identifier of the actor that created the item. - The ID of the file to be sent to the model. + - `class BetaResponseApplyPatchToolCall:` - - `Optional imageUrl` + A tool call that applies file diffs by creating, deleting, or updating files. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `String id` - - `Optional promptCacheBreakpoint` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String callId` - - `JsonValue; mode "explicit"constant` + The unique ID of the apply patch tool call generated by the model. - The breakpoint mode. Always `explicit`. + - `Operation operation` - - `EXPLICIT("explicit")` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `class BetaResponseInputFileContent:` + - `class CreateFile:` - A file input to the model. + Instruction describing how to create a file via the apply_patch tool. - - `JsonValue; type "input_file"constant` + - `String diff` - The type of the input item. Always `input_file`. + Diff to apply. - - `INPUT_FILE("input_file")` + - `String path` - - `Optional detail` + Path of the file to create. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `JsonValue; type "create_file"constant` - - `AUTO("auto")` + Create a new file with the provided diff. - - `LOW("low")` + - `CREATE_FILE("create_file")` - - `HIGH("high")` + - `class DeleteFile:` - - `Optional fileData` + Instruction describing how to delete a file via the apply_patch tool. - The base64-encoded data of the file to be sent to the model. + - `String path` - - `Optional fileId` + Path of the file to delete. - The ID of the file to be sent to the model. + - `JsonValue; type "delete_file"constant` - - `Optional fileUrl` + Delete the specified file. - The URL of the file to be sent to the model. + - `DELETE_FILE("delete_file")` - - `Optional filename` + - `class UpdateFile:` - The name of the file to be sent to the model. + Instruction describing how to update a file via the apply_patch tool. - - `Optional promptCacheBreakpoint` + - `String diff` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Diff to apply. - - `JsonValue; mode "explicit"constant` + - `String path` - The breakpoint mode. Always `explicit`. + Path of the file to update. - - `EXPLICIT("explicit")` + - `JsonValue; type "update_file"constant` - - `JsonValue; type "function_call_output"constant` + Update an existing file with the provided diff. - The type of the function tool call output. Always `function_call_output`. + - `UPDATE_FILE("update_file")` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `Status status` - - `Optional id` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `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 agent` @@ -31952,8 +48457,6 @@ Cancel a response - `JsonValue; type "direct"constant` - The caller type. Always `direct`. - - `DIRECT("direct")` - `class Program:` @@ -31964,109 +48467,97 @@ Cancel a response - `JsonValue; type "program"constant` - The caller type. Always `program`. - - `PROGRAM("program")` - - `Optional 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")` - - - `AgentMessage` + - `Optional createdBy` - - `String author` + The ID of the entity that created this tool call. - The sending agent identity. + - `class BetaResponseApplyPatchToolCallOutput:` - - `List content` + The output emitted by an apply patch tool call. - Plaintext, image, or encrypted content sent between agents. + - `String id` - - `class BetaResponseInputTextContent:` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A text input to the model. + - `String callId` - - `class BetaResponseInputImageContent:` + The unique ID of the apply patch tool call generated by the model. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `Status status` - - `class EncryptedContent:` + The status of the apply patch tool call output. One of `completed` or `failed`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `COMPLETED("completed")` - - `String encryptedContent` + - `FAILED("failed")` - Opaque encrypted content. + - `JsonValue; type "apply_patch_call_output"constant` - - `JsonValue; type "encrypted_content"constant` + The type of the item. Always `apply_patch_call_output`. - The type of the input item. Always `encrypted_content`. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `Optional agent` - - `String recipient` + The agent that produced this item. - The destination agent identity. + - `String agentName` - - `JsonValue; type "agent_message"constant` + The canonical name of the agent that produced this item. - The item type. Always `agent_message`. + - `Optional caller` - - `AGENT_MESSAGE("agent_message")` + The execution context that produced this tool call. - - `Optional id` + - `JsonValue;` - The unique ID of this agent message item. + - `JsonValue; type "direct"constant` - - `Optional agent` + - `DIRECT("direct")` - The agent that produced this item. + - `class Program:` - - `String agentName` + - `String callerId` - The canonical name of the agent that produced this item. + The call ID of the program item that produced this tool call. - - `MultiAgentCall` + - `JsonValue; type "program"constant` - - `Action action` + - `PROGRAM("program")` - The multi-agent action that was executed. + - `Optional createdBy` - - `SPAWN_AGENT("spawn_agent")` + The ID of the entity that created this tool call output. - - `INTERRUPT_AGENT("interrupt_agent")` + - `Optional output` - - `LIST_AGENTS("list_agents")` + Optional textual output returned by the apply patch tool. - - `SEND_MESSAGE("send_message")` + - `McpCall` - - `FOLLOWUP_TASK("followup_task")` + - `String id` - - `WAIT_AGENT("wait_agent")` + The unique ID of the tool call. - `String arguments` - The action arguments as a JSON string. + A JSON string of the arguments passed to the tool. - - `String callId` + - `String name` - The unique ID linking this call to its output. + The name of the tool that was run. - - `JsonValue; type "multi_agent_call"constant` + - `String serverLabel` - The item type. Always `multi_agent_call`. + The label of the MCP server running the tool. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `JsonValue; type "mcp_call"constant` - - `Optional id` + The type of the item. Always `mcp_call`. - The unique ID of this multi-agent call. + - `MCP_CALL("mcp_call")` - `Optional agent` @@ -32076,127 +48567,104 @@ Cancel a response The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `Action action` - - The multi-agent action that produced this result. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` - - - `SEND_MESSAGE("send_message")` - - - `FOLLOWUP_TASK("followup_task")` - - - `WAIT_AGENT("wait_agent")` - - - `String callId` - - The unique ID of the multi-agent call. - - - `List output` - - Text output returned by the multi-agent action. + - `Optional approvalRequestId` - - `String text` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The text content. + - `Optional error` - - `JsonValue; type "output_text"constant` + The error from the tool call, if any. - The content type. Always `output_text`. + - `Optional output` - - `OUTPUT_TEXT("output_text")` + The output from the tool call. - - `Optional annotations` + - `Optional status` - Citations associated with the text content. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `List` + - `IN_PROGRESS("in_progress")` - - `String fileId` + - `COMPLETED("completed")` - The ID of the file. + - `INCOMPLETE("incomplete")` - - `String filename` + - `CALLING("calling")` - The filename of the file cited. + - `FAILED("failed")` - - `long index` + - `McpListTools` - The index of the file in the list of files. + - `String id` - - `JsonValue; type "file_citation"constant` + The unique ID of the list. - The citation type. Always `file_citation`. + - `String serverLabel` - - `FILE_CITATION("file_citation")` + The label of the MCP server. - - `List` + - `List tools` - - `long endIndex` + The tools available on the server. - The index of the last character of the citation in the message. + - `JsonValue inputSchema` - - `long startIndex` + The JSON schema describing the tool's input. - The index of the first character of the citation in the message. + - `String name` - - `String title` + The name of the tool. - The title of the cited resource. + - `Optional annotations` - - `JsonValue; type "url_citation"constant` + Additional annotations about the tool. - The citation type. Always `url_citation`. + - `Optional description` - - `URL_CITATION("url_citation")` + The description of the tool. - - `String url` + - `JsonValue; type "mcp_list_tools"constant` - The URL of the cited resource. + The type of the item. Always `mcp_list_tools`. - - `List` + - `MCP_LIST_TOOLS("mcp_list_tools")` - - `String containerId` + - `Optional agent` - The ID of the container. + The agent that produced this item. - - `long endIndex` + - `String agentName` - The index of the last character of the citation in the message. + The canonical name of the agent that produced this item. - - `String fileId` + - `Optional error` - The ID of the container file. + Error message if the server could not list tools. - - `String filename` + - `McpApprovalRequest` - The filename of the container file cited. + - `String id` - - `long startIndex` + The unique ID of the approval request. - The index of the first character of the citation in the message. + - `String arguments` - - `JsonValue; type "container_file_citation"constant` + A JSON string of arguments for the tool. - The citation type. Always `container_file_citation`. + - `String name` - - `CONTAINER_FILE_CITATION("container_file_citation")` + The name of the tool to run. - - `JsonValue; type "multi_agent_call_output"constant` + - `String serverLabel` - The item type. Always `multi_agent_call_output`. + The label of the MCP server making the request. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `JsonValue; type "mcp_approval_request"constant` - - `Optional id` + The type of the item. Always `mcp_approval_request`. - The unique ID of this multi-agent call output. + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - `Optional agent` @@ -32206,21 +48674,25 @@ Cancel a response The canonical name of the agent that produced this item. - - `ToolSearchCall` + - `McpApprovalResponse` - - `JsonValue arguments` + - `String id` - The arguments supplied to the tool search call. + The unique ID of the approval response - - `JsonValue; type "tool_search_call"constant` + - `String approvalRequestId` - The item type. Always `tool_search_call`. + The ID of the approval request being answered. - - `TOOL_SEARCH_CALL("tool_search_call")` + - `boolean approve` - - `Optional id` + Whether the request was approved. - The unique ID of this tool search call. + - `JsonValue; type "mcp_approval_response"constant` + + The type of the item. Always `mcp_approval_response`. + + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - `Optional agent` @@ -32230,21 +48702,26 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional callId` + - `Optional reason` - The unique ID of the tool search call generated by the model. + Optional reason for the decision. - - `Optional execution` + - `class BetaResponseCustomToolCall:` - Whether tool search was executed by the server or by the client. + A call to a custom tool created by the model. - - `SERVER("server")` + - `class BetaResponseCustomToolCallOutputItem:` - - `CLIENT("client")` + The output of a custom tool call from your code, being sent back to the model. - - `Optional status` + - `String id` - The status of the tool search call. + The unique ID of the custom tool call output item. + + - `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")` @@ -32252,678 +48729,698 @@ Cancel a response - `INCOMPLETE("incomplete")` - - `class BetaResponseToolSearchOutputItemParam:` - - - `List tools` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Optional createdBy` - - `String name` + The identifier of the actor that created the item. - The name of the function to call. + - `boolean parallelToolCalls` - - `Optional parameters` + Whether to allow the model to run tool calls in parallel. - A JSON schema object describing the parameters of the function. + - `Optional temperature` - - `Optional strict` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - Whether strict parameter validation is enforced for this function tool. + - `ToolChoice toolChoice` - - `JsonValue; type "function"constant` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The type of the function tool. Always `function`. + - `enum BetaToolChoiceOptions:` - - `FUNCTION("function")` + Controls which (if any) tool is called by the model. - - `Optional> allowedCallers` + `none` means the model will not call any tool and instead generates a message. - The tool invocation context(s). + `auto` means the model can pick between generating a message or calling one or + more tools. - - `DIRECT("direct")` + `required` means the model must call one or more tools. - - `PROGRAMMATIC("programmatic")` + - `NONE("none")` - - `Optional deferLoading` + - `AUTO("auto")` - Whether this function is deferred and loaded via tool search. + - `REQUIRED("required")` - - `Optional description` + - `class BetaToolChoiceAllowed:` - A description of the function. Used by the model to determine whether or not to call the function. + Constrains the tools available to the model to a pre-defined set. - - `Optional outputSchema` + - `Mode mode` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Constrains the tools available to the model to a pre-defined set. - - `class BetaFileSearchTool:` + `auto` allows the model to pick from among the allowed tools and generate a + message. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + `required` requires the model to call one or more of the allowed tools. - - `JsonValue; type "file_search"constant` + - `AUTO("auto")` - The type of the file search tool. Always `file_search`. + - `REQUIRED("required")` - - `FILE_SEARCH("file_search")` + - `List tools` - - `List vectorStoreIds` + A list of tool definitions that the model should be allowed to call. - The IDs of the vector stores to search. + For the Responses API, the list of tool definitions might look like: - - `Optional filters` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - A filter to apply. + - `JsonValue; type "allowed_tools"constant` - - `class ComparisonFilter:` + Allowed tool configuration type. Always `allowed_tools`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `ALLOWED_TOOLS("allowed_tools")` - - `String key` + - `class BetaToolChoiceTypes:` - The key to compare against the value. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - `Type type` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Allowed values are: - - `EQ("eq")` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `NE("ne")` + - `FILE_SEARCH("file_search")` - - `GT("gt")` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `GTE("gte")` + - `COMPUTER("computer")` - - `LT("lt")` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `LTE("lte")` + - `COMPUTER_USE("computer_use")` - - `IN("in")` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `NIN("nin")` + - `IMAGE_GENERATION("image_generation")` - - `Value value` + - `CODE_INTERPRETER("code_interpreter")` - The value to compare against the attribute key; supports string, number, or boolean types. + - `class BetaToolChoiceFunction:` - - `String` + Use this option to force the model to call a specific function. - - `double` + - `String name` - - `boolean` + The name of the function to call. - - `List` + - `JsonValue; type "function"constant` - - `class CompoundFilter:` + For function calling, the type is always `function`. - Combine multiple filters using `and` or `or`. + - `FUNCTION("function")` - - `List filters` + - `class BetaToolChoiceMcp:` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Use this option to force the model to call a specific tool on a remote MCP server. - - `class ComparisonFilter:` + - `String serverLabel` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The label of the MCP server to use. - - `String key` + - `JsonValue; type "mcp"constant` - The key to compare against the value. + For MCP tools, the type is always `mcp`. - - `Type type` + - `MCP("mcp")` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `Optional name` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The name of the tool to call on the server. - - `EQ("eq")` + - `class BetaToolChoiceCustom:` - - `NE("ne")` + Use this option to force the model to call a specific custom tool. - - `GT("gt")` + - `String name` - - `GTE("gte")` + The name of the custom tool to call. - - `LT("lt")` + - `JsonValue; type "custom"constant` - - `LTE("lte")` + For custom tool calling, the type is always `custom`. - - `IN("in")` + - `CUSTOM("custom")` - - `NIN("nin")` + - `JsonValue;` - - `Value value` + - `JsonValue; type "programmatic_tool_calling"constant` - The value to compare against the attribute key; supports string, number, or boolean types. + The tool to call. Always `programmatic_tool_calling`. - - `String` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `double` + - `class BetaToolChoiceApplyPatch:` - - `boolean` + Forces the model to call the apply_patch tool when executing a tool call. - - `List` + - `JsonValue; type "apply_patch"constant` - - `JsonValue` + The tool to call. Always `apply_patch`. - - `Type type` + - `APPLY_PATCH("apply_patch")` - Type of operation: `and` or `or`. + - `class BetaToolChoiceShell:` - - `AND("and")` + Forces the model to call the shell tool when a tool call is required. - - `OR("or")` + - `JsonValue; type "shell"constant` - - `Optional maxNumResults` + The tool to call. Always `shell`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `SHELL("shell")` - - `Optional rankingOptions` + - `List tools` - Ranking options for search. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `Optional hybridSearch` + We support the following categories of tools: - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `double embeddingWeight` + - `class BetaFunctionTool:` - The weight of the embedding in the reciprocal ranking fusion. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `double textWeight` + - `class BetaFileSearchTool:` - The weight of the text in the reciprocal ranking fusion. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional ranker` + - `class BetaComputerTool:` - The ranker to use for the file search. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `AUTO("auto")` + - `class BetaComputerUsePreviewTool:` - - `DEFAULT_2024_11_15("default-2024-11-15")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional scoreThreshold` + - `class BetaWebSearchTool:` - 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. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class BetaComputerTool:` + - `Mcp` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `CodeInterpreter` - - `JsonValue; type "computer"constant` + - `JsonValue;` - The type of the computer tool. Always `computer`. + - `ImageGeneration` - - `COMPUTER("computer")` + - `JsonValue;` - - `class BetaComputerUsePreviewTool:` + - `class BetaFunctionShellTool:` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A tool that allows the model to execute shell commands. - - `long displayHeight` + - `class BetaCustomTool:` - The height of the computer display. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `long displayWidth` + - `class BetaNamespaceTool:` - The width of the computer display. + Groups function/custom tools under a shared namespace. - - `Environment environment` + - `class BetaToolSearchTool:` - The type of computer environment to control. + Hosted or BYOT tool search configuration for deferred tools. - - `WINDOWS("windows")` + - `class BetaWebSearchPreviewTool:` - - `MAC("mac")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `LINUX("linux")` + - `class BetaApplyPatchTool:` - - `UBUNTU("ubuntu")` + Allows the assistant to create, delete, or update files using unified diffs. - - `BROWSER("browser")` + - `Optional topP` - - `JsonValue; type "computer_use_preview"constant` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - The type of the computer use tool. Always `computer_use_preview`. + We generally recommend altering this or `temperature` but not both. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `Optional background` - - `class BetaWebSearchTool:` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional completedAt` - - `Type type` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `Optional conversation` - - `WEB_SEARCH("web_search")` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `String id` - - `Optional filters` + The unique ID of the conversation that this response was associated with. - Filters for the search. + - `Optional maxOutputTokens` - - `Optional> allowedDomains` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Optional maxToolCalls` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `Optional searchContextSize` + - `Optional moderation` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + Moderation results for the response input and output, if moderated completions were requested. - - `LOW("low")` + - `Input input` - - `MEDIUM("medium")` + Moderation for the response input. - - `HIGH("high")` + - `class ModerationResult:` - - `Optional userLocation` + A moderation result produced for the response input or output. - The approximate location of the user. + - `Categories categories` - - `Optional city` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - Free text input for the city of the user, e.g. `San Francisco`. + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `Optional country` + Which modalities of input are reflected by the score for each category. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `TEXT("text")` - - `Optional region` + - `IMAGE("image")` - Free text input for the region of the user, e.g. `California`. + - `CategoryScores categoryScores` - - `Optional timezone` + A dictionary of moderation categories to scores. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `boolean flagged` - - `Optional type` + A boolean indicating whether the content was flagged by any category. - The type of location approximation. Always `approximate`. + - `String model` - - `APPROXIMATE("approximate")` + The moderation model that produced this result. - - `Mcp` + - `JsonValue; type "moderation_result"constant` - - `String serverLabel` + The object type, which was always `moderation_result` for successful moderation results. - A label for this MCP server, used to identify it in tool calls. + - `MODERATION_RESULT("moderation_result")` - - `JsonValue; type "mcp"constant` + - `class Error:` - The type of the MCP tool. Always `mcp`. + An error produced while attempting moderation for the response input or output. - - `MCP("mcp")` + - `String code` - - `Optional> allowedCallers` + The error code. - The tool invocation context(s). + - `String message` - - `DIRECT("direct")` + The error message. - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "error"constant` - - `Optional allowedTools` + The object type, which was always `error` for moderation failures. - List of allowed tool names or a filter object. + - `ERROR("error")` - - `List` + - `Output output` - - `class McpToolFilter:` + Moderation for the response output. - A filter object to specify which tools are allowed. + - `class ModerationResult:` - - `Optional readOnly` + A moderation result produced for the response input or output. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Categories categories` - - `Optional> toolNames` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - List of allowed tool names. + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `Optional authorization` + Which modalities of input are reflected by the score for each category. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `TEXT("text")` - - `Optional connectorId` + - `IMAGE("image")` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `CategoryScores categoryScores` - Currently supported `connector_id` values are: + A dictionary of moderation categories to scores. - - 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` + - `boolean flagged` - - `CONNECTOR_DROPBOX("connector_dropbox")` + A boolean indicating whether the content was flagged by any category. - - `CONNECTOR_GMAIL("connector_gmail")` + - `String model` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + The moderation model that produced this result. - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `JsonValue; type "moderation_result"constant` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + The object type, which was always `moderation_result` for successful moderation results. - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `MODERATION_RESULT("moderation_result")` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `class Error:` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + An error produced while attempting moderation for the response input or output. - - `Optional deferLoading` + - `String code` - Whether this MCP tool is deferred and discovered via tool search. + The error code. - - `Optional headers` + - `String message` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The error message. - - `Optional requireApproval` + - `JsonValue; type "error"constant` - Specify which of the MCP server's tools require approval. + The object type, which was always `error` for moderation failures. - - `class McpToolApprovalFilter:` + - `ERROR("error")` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `Optional previousResponseId` - - `Optional always` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - A filter object to specify which tools are allowed. + - `Optional prompt` - - `Optional readOnly` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `String id` - - `Optional> toolNames` + The unique identifier of the prompt template to use. - List of allowed tool names. + - `Optional variables` - - `Optional never` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - A filter object to specify which tools are allowed. + - `String` - - `Optional readOnly` + - `class BetaResponseInputText:` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + A text input to the model. - - `Optional> toolNames` + - `class BetaResponseInputImage:` - List of allowed tool names. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `enum McpToolApprovalSetting:` + - `class BetaResponseInputFile:` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + A file input to the model. - - `ALWAYS("always")` + - `Optional version` - - `NEVER("never")` + Optional version of the prompt template. - - `Optional serverDescription` + - `Optional promptCacheKey` - Optional description of the MCP server, used to provide more context. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `Optional serverUrl` + - `Optional promptCacheOptions` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `Optional tunnelId` + - `Mode mode` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + Whether implicit prompt-cache breakpoints were enabled. - - `CodeInterpreter` + - `IMPLICIT("implicit")` - - `Container container` + - `EXPLICIT("explicit")` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `Ttl ttl` - - `String` + The minimum lifetime applied to each cache breakpoint. - - `class CodeInterpreterToolAuto:` + - `_30M("30m")` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `Optional promptCacheRetention` - - `JsonValue; type "auto"constant` + Deprecated. Use `prompt_cache_options.ttl` instead. - Always `auto`. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `AUTO("auto")` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `Optional> fileIds` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - An optional list of uploaded files to make available to your code. + - `IN_MEMORY("in_memory")` - - `Optional memoryLimit` + - `_24H("24h")` - The memory limit for the code interpreter container. + - `Optional reasoning` - - `_1G("1g")` + **gpt-5 and o-series models only** - - `_4G("4g")` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `_16G("16g")` + - `Optional context` - - `_64G("64g")` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `Optional networkPolicy` + - `AUTO("auto")` - Network access policy for the container. + - `CURRENT_TURN("current_turn")` - - `class BetaContainerNetworkPolicyDisabled:` + - `ALL_TURNS("all_turns")` - - `JsonValue; type "disabled"constant` + - `Optional effort` - Disable outbound network access. Always `disabled`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `DISABLED("disabled")` + - `NONE("none")` - - `class BetaContainerNetworkPolicyAllowlist:` + - `MINIMAL("minimal")` - - `List allowedDomains` + - `LOW("low")` - A list of allowed domains when type is `allowlist`. + - `MEDIUM("medium")` - - `JsonValue; type "allowlist"constant` + - `HIGH("high")` - Allow outbound network access only to specified domains. Always `allowlist`. + - `XHIGH("xhigh")` - - `ALLOWLIST("allowlist")` + - `MAX("max")` - - `Optional> domainSecrets` + - `Optional generateSummary` - Optional domain-scoped secrets for allowlisted domains. + **Deprecated:** use `summary` instead. - - `String domain` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The domain associated with the secret. + - `AUTO("auto")` - - `String name` + - `CONCISE("concise")` - The name of the secret to inject for the domain. + - `DETAILED("detailed")` - - `String value` + - `Optional mode` - The secret value to inject for the domain. + Controls the reasoning execution mode for the request. - - `JsonValue; type "code_interpreter"constant` + When returned on a response, this is the effective execution mode. - The type of the code interpreter tool. Always `code_interpreter`. + - `STANDARD("standard")` - - `CODE_INTERPRETER("code_interpreter")` + - `PRO("pro")` - - `Optional> allowedCallers` + - `Optional summary` - The tool invocation context(s). + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `DIRECT("direct")` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `PROGRAMMATIC("programmatic")` + - `AUTO("auto")` - - `JsonValue;` + - `CONCISE("concise")` - - `JsonValue; type "programmatic_tool_calling"constant` + - `DETAILED("detailed")` - The type of the tool. Always `programmatic_tool_calling`. + - `Optional safetyIdentifier` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `ImageGeneration` + - `Optional serviceTier` - - `JsonValue; type "image_generation"constant` + Specifies the processing type used for serving the request. - The type of the image generation tool. Always `image_generation`. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `IMAGE_GENERATION("image_generation")` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `Optional action` + - `AUTO("auto")` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `DEFAULT("default")` - - `GENERATE("generate")` + - `FLEX("flex")` - - `EDIT("edit")` + - `SCALE("scale")` - - `AUTO("auto")` + - `PRIORITY("priority")` - - `Optional background` + - `Optional status` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `COMPLETED("completed")` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `FAILED("failed")` - - `TRANSPARENT("transparent")` + - `IN_PROGRESS("in_progress")` - - `OPAQUE("opaque")` + - `CANCELLED("cancelled")` - - `AUTO("auto")` + - `QUEUED("queued")` - - `Optional inputFidelity` + - `INCOMPLETE("incomplete")` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `Optional text` - - `HIGH("high")` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `LOW("low")` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `Optional inputImageMask` + - `Optional format` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + An object specifying the format that the model must output. - - `Optional fileId` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - File ID for the mask image. + The default format is `{ "type": "text" }` with no additional options. - - `Optional imageUrl` + **Not recommended for gpt-4o and newer models:** - Base64-encoded mask image. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `Optional model` + - `JsonValue;` - The image generation model to use. Default: `gpt-image-1`. + - `JsonValue; type "text"constant` - - `GPT_IMAGE_1("gpt-image-1")` + The type of response format being defined. Always `text`. - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `TEXT("text")` - - `GPT_IMAGE_2("gpt-image-2")` + - `class BetaResponseFormatTextJsonSchemaConfig:` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `String name` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `Optional moderation` + - `Schema schema` - Moderation level for the generated image. Default: `auto`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `AUTO("auto")` + - `JsonValue; type "json_schema"constant` - - `LOW("low")` + The type of response format being defined. Always `json_schema`. - - `Optional outputCompression` + - `JSON_SCHEMA("json_schema")` - Compression level for the output image. Default: 100. + - `Optional description` - - `Optional outputFormat` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `Optional strict` - - `PNG("png")` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `WEBP("webp")` + - `JsonValue;` - - `JPEG("jpeg")` + - `JsonValue; type "json_object"constant` - - `Optional partialImages` + The type of response format being defined. Always `json_object`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `JSON_OBJECT("json_object")` - - `Optional quality` + - `Optional verbosity` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - `LOW("low")` @@ -32931,401 +49428,411 @@ Cancel a response - `HIGH("high")` - - `AUTO("auto")` - - - `Optional size` + - `Optional topLogprobs` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `_1024X1024("1024x1024")` + - `Optional truncation` - - `_1024X1536("1024x1536")` + The truncation strategy to use for the model response. - - `_1536X1024("1536x1024")` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - `AUTO("auto")` - - `JsonValue;` - - - `JsonValue; type "local_shell"constant` - - The type of the local shell tool. Always `local_shell`. - - - `LOCAL_SHELL("local_shell")` - - - `class BetaFunctionShellTool:` - - A tool that allows the model to execute shell commands. + - `DISABLED("disabled")` - - `JsonValue; type "shell"constant` + - `Optional usage` - The type of the shell tool. Always `shell`. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `SHELL("shell")` + - `long inputTokens` - - `Optional> allowedCallers` + The number of input tokens. - The tool invocation context(s). + - `InputTokensDetails inputTokensDetails` - - `DIRECT("direct")` + A detailed breakdown of the input tokens. - - `PROGRAMMATIC("programmatic")` + - `long cacheWriteTokens` - - `Optional environment` + The number of input tokens that were written to the cache. - - `class BetaContainerAuto:` + - `long cachedTokens` - - `JsonValue; type "container_auto"constant` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - Automatically creates a container for this request + - `long outputTokens` - - `CONTAINER_AUTO("container_auto")` + The number of output tokens. - - `Optional> fileIds` + - `OutputTokensDetails outputTokensDetails` - An optional list of uploaded files to make available to your code. + A detailed breakdown of the output tokens. - - `Optional memoryLimit` + - `long reasoningTokens` - The memory limit for the container. + The number of reasoning tokens. - - `_1G("1g")` + - `long totalTokens` - - `_4G("4g")` + The total number of tokens used. - - `_16G("16g")` + - `Optional user` - - `_64G("64g")` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `Optional networkPolicy` + - `long sequenceNumber` - Network access policy for the container. + The sequence number for this event. - - `class BetaContainerNetworkPolicyDisabled:` + - `JsonValue; type "response.completed"constant` - - `class BetaContainerNetworkPolicyAllowlist:` + The type of the event. Always `response.completed`. - - `Optional> skills` + - `RESPONSE_COMPLETED("response.completed")` - An optional list of skills referenced by id or inline data. + - `Optional agent` - - `class BetaSkillReference:` + The agent that owns this multi-agent streaming event. - - `String skillId` + - `String agentName` - The ID of the referenced skill. + The canonical name of the agent that produced this item. - - `JsonValue; type "skill_reference"constant` +### Beta Response Computer Tool Call - References a skill created with the /v1/skills endpoint. +- `class BetaResponseComputerToolCall:` - - `SKILL_REFERENCE("skill_reference")` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `Optional version` + - `String id` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The unique ID of the computer call. - - `class BetaInlineSkill:` + - `String callId` - - `String description` + An identifier used when responding to the tool call with output. - The description of the skill. + - `List pendingSafetyChecks` - - `String name` + The pending safety checks for the computer call. - The name of the skill. + - `String id` - - `BetaInlineSkillSource source` + The ID of the pending safety check. - Inline skill payload + - `Optional code` - - `String data` + The type of the pending safety check. - Base64-encoded skill zip bundle. + - `Optional message` - - `JsonValue; mediaType "application/zip"constant` + Details about the pending safety check. - The media type of the inline skill payload. Must be `application/zip`. + - `Status status` - - `APPLICATION_ZIP("application/zip")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue; type "base64"constant` + - `IN_PROGRESS("in_progress")` - The type of the inline skill source. Must be `base64`. + - `COMPLETED("completed")` - - `BASE64("base64")` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "inline"constant` + - `Type type` - Defines an inline skill for this request. + The type of the computer call. Always `computer_call`. - - `INLINE("inline")` + - `COMPUTER_CALL("computer_call")` - - `class BetaLocalEnvironment:` + - `Optional action` - - `JsonValue; type "local"constant` + A click action. - Use a local computer environment. + - `Click` - - `LOCAL("local")` + - `Button button` - - `Optional> skills` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - An optional list of skills. + - `LEFT("left")` - - `String description` + - `RIGHT("right")` - The description of the skill. + - `WHEEL("wheel")` - - `String name` + - `BACK("back")` - The name of the skill. + - `FORWARD("forward")` - - `String path` + - `JsonValue; type "click"constant` - The path to the directory containing the skill. + Specifies the event type. For a click action, this property is always `click`. - - `class BetaContainerReference:` + - `CLICK("click")` - - `String containerId` + - `long x` - The ID of the referenced container. + The x-coordinate where the click occurred. - - `JsonValue; type "container_reference"constant` + - `long y` - References a container created with the /v1/containers endpoint + The y-coordinate where the click occurred. - - `CONTAINER_REFERENCE("container_reference")` + - `Optional> keys` - - `class BetaCustomTool:` + The keys being held while clicking. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `DoubleClick` - - `String name` + - `Optional> keys` - The name of the custom tool, used to identify it in tool calls. + The keys being held while double-clicking. - - `JsonValue; type "custom"constant` + - `JsonValue; type "double_click"constant` - The type of the custom tool. Always `custom`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `CUSTOM("custom")` + - `DOUBLE_CLICK("double_click")` - - `Optional> allowedCallers` + - `long x` - The tool invocation context(s). + The x-coordinate where the double click occurred. - - `DIRECT("direct")` + - `long y` - - `PROGRAMMATIC("programmatic")` + The y-coordinate where the double click occurred. - - `Optional deferLoading` + - `Drag` - Whether this tool should be deferred and discovered via tool search. + - `List path` - - `Optional description` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Optional description of the custom tool, used to provide more context. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `Optional format` + - `long x` - The input format for the custom tool. Default is unconstrained text. + The x-coordinate. - - `JsonValue;` + - `long y` - - `JsonValue; type "text"constant` + The y-coordinate. - Unconstrained text format. Always `text`. + - `JsonValue; type "drag"constant` - - `TEXT("text")` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `class Grammar:` + - `DRAG("drag")` - A grammar defined by the user. + - `Optional> keys` - - `String definition` + The keys being held while dragging the mouse. - The grammar definition. + - `Keypress` - - `Syntax syntax` + - `List keys` - The syntax of the grammar definition. One of `lark` or `regex`. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `LARK("lark")` + - `JsonValue; type "keypress"constant` - - `REGEX("regex")` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `JsonValue; type "grammar"constant` + - `KEYPRESS("keypress")` - Grammar format. Always `grammar`. + - `Move` - - `GRAMMAR("grammar")` + - `JsonValue; type "move"constant` - - `class BetaNamespaceTool:` + Specifies the event type. For a move action, this property is always set to `move`. - Groups function/custom tools under a shared namespace. + - `MOVE("move")` - - `String description` + - `long x` - A description of the namespace shown to the model. + The x-coordinate to move to. - - `String name` + - `long y` - The namespace name used in tool calls (for example, `crm`). + The y-coordinate to move to. - - `List tools` + - `Optional> keys` - The function/custom tools available inside this namespace. + The keys being held while moving the mouse. - - `class Function:` + - `JsonValue;` - - `String name` + - `JsonValue; type "screenshot"constant` - - `JsonValue; type "function"constant` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `FUNCTION("function")` + - `SCREENSHOT("screenshot")` - - `Optional> allowedCallers` + - `Scroll` - The tool invocation context(s). + - `long scrollX` - - `DIRECT("direct")` + The horizontal scroll distance. - - `PROGRAMMATIC("programmatic")` + - `long scrollY` - - `Optional deferLoading` + The vertical scroll distance. - Whether this function should be deferred and discovered via tool search. + - `JsonValue; type "scroll"constant` - - `Optional description` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `Optional outputSchema` + - `SCROLL("scroll")` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `long x` - - `Optional parameters` + The x-coordinate where the scroll occurred. - - `Optional strict` + - `long y` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The y-coordinate where the scroll occurred. - - `class BetaCustomTool:` + - `Optional> keys` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The keys being held while scrolling. - - `JsonValue; type "namespace"constant` + - `Type` - The type of the tool. Always `namespace`. + - `String text` - - `NAMESPACE("namespace")` + The text to type. - - `class BetaToolSearchTool:` + - `JsonValue; type "type"constant` - Hosted or BYOT tool search configuration for deferred tools. + Specifies the event type. For a type action, this property is always set to `type`. - - `JsonValue; type "tool_search"constant` + - `TYPE("type")` - The type of the tool. Always `tool_search`. + - `JsonValue;` - - `TOOL_SEARCH("tool_search")` + - `JsonValue; type "wait"constant` - - `Optional description` + Specifies the event type. For a wait action, this property is always set to `wait`. - Description shown to the model for a client-executed tool search tool. + - `WAIT("wait")` - - `Optional execution` + - `Optional> actions` - Whether tool search is executed by the server or by the client. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `SERVER("server")` + - `Click` - - `CLIENT("client")` + - `DoubleClick` - - `Optional parameters` + - `Drag` - Parameter schema for a client-executed tool search tool. + - `Keypress` - - `class BetaWebSearchPreviewTool:` + - `Move` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue;` - - `Type type` + - `Scroll` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `Type` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `JsonValue;` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `Optional agent` - - `Optional> searchContentTypes` + The agent that produced this item. - - `TEXT("text")` + - `String agentName` - - `IMAGE("image")` + The canonical name of the agent that produced this item. - - `Optional searchContextSize` +### Beta Response Computer Tool Call Output Item - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. +- `class BetaResponseComputerToolCallOutputItem:` - - `LOW("low")` + - `String id` - - `MEDIUM("medium")` + The unique ID of the computer call tool output. - - `HIGH("high")` + - `String callId` - - `Optional userLocation` + The ID of the computer tool call that produced the output. - The user's location. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `JsonValue; type "approximate"constant` + A computer screenshot image used with the computer use tool. - The type of location approximation. Always `approximate`. + - `JsonValue; type "computer_screenshot"constant` - - `APPROXIMATE("approximate")` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `Optional city` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - Free text input for the city of the user, e.g. `San Francisco`. + - `Optional fileId` - - `Optional country` + The identifier of an uploaded file that contains the screenshot. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Optional imageUrl` - - `Optional region` + The URL of the screenshot image. - Free text input for the region of the user, e.g. `California`. + - `Status status` - - `Optional timezone` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `COMPLETED("completed")` - - `class BetaApplyPatchTool:` + - `INCOMPLETE("incomplete")` - Allows the assistant to create, delete, or update files using unified diffs. + - `FAILED("failed")` - - `JsonValue; type "apply_patch"constant` + - `IN_PROGRESS("in_progress")` - The type of the tool. Always `apply_patch`. + - `JsonValue; type "computer_call_output"constant` - - `APPLY_PATCH("apply_patch")` + The type of the computer tool call output. Always `computer_call_output`. - - `Optional> allowedCallers` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - The tool invocation context(s). + - `Optional> acknowledgedSafetyChecks` - - `DIRECT("direct")` + The safety checks reported by the API that have been acknowledged by the + developer. - - `PROGRAMMATIC("programmatic")` + - `String id` - - `JsonValue; type "tool_search_output"constant` + The ID of the pending safety check. - The item type. Always `tool_search_output`. + - `Optional code` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + The type of the pending safety check. - - `Optional id` + - `Optional message` - The unique ID of this tool search output. + Details about the pending safety check. - `Optional agent` @@ -33335,958 +49842,977 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional callId` + - `Optional createdBy` - The unique ID of the tool search call generated by the model. + The identifier of the actor that created the item. - - `Optional execution` +### Beta Response Computer Tool Call Output Screenshot - Whether tool search was executed by the server or by the client. +- `class BetaResponseComputerToolCallOutputScreenshot:` - - `SERVER("server")` + A computer screenshot image used with the computer use tool. - - `CLIENT("client")` + - `JsonValue; type "computer_screenshot"constant` - - `Optional status` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The status of the tool search output. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `IN_PROGRESS("in_progress")` + - `Optional fileId` - - `COMPLETED("completed")` + The identifier of an uploaded file that contains the screenshot. - - `INCOMPLETE("incomplete")` + - `Optional imageUrl` - - `AdditionalTools` + The URL of the screenshot image. - - `JsonValue; role "developer"constant` +### Beta Response Container Reference - The role that provided the additional tools. Only `developer` is supported. +- `class BetaResponseContainerReference:` - - `DEVELOPER("developer")` + Represents a container created with /v1/containers. - - `List tools` + - `String containerId` - A list of additional tools made available at this item. + - `JsonValue; type "container_reference"constant` - - `class BetaFunctionTool:` + The environment type. Always `container_reference`. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `CONTAINER_REFERENCE("container_reference")` - - `class BetaFileSearchTool:` +### Beta Response Content - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). +- `class BetaResponseContent: A class that can be one of several variants.union` - - `class BetaComputerTool:` + Multi-modal input and output contents. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class BetaResponseInputText:` - - `class BetaComputerUsePreviewTool:` + A text input to the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String text` - - `class BetaWebSearchTool:` + The text input to the model. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "input_text"constant` - - `Mcp` + The type of the input item. Always `input_text`. - - `CodeInterpreter` + - `INPUT_TEXT("input_text")` - - `JsonValue;` + - `Optional promptCacheBreakpoint` - - `ImageGeneration` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue;` + - `JsonValue; mode "explicit"constant` - - `class BetaFunctionShellTool:` + The breakpoint mode. Always `explicit`. - A tool that allows the model to execute shell commands. + - `EXPLICIT("explicit")` - - `class BetaCustomTool:` + - `class BetaResponseInputImage:` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class BetaNamespaceTool:` + - `Detail detail` - Groups function/custom tools under a shared namespace. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class BetaToolSearchTool:` + - `LOW("low")` - Hosted or BYOT tool search configuration for deferred tools. + - `HIGH("high")` - - `class BetaWebSearchPreviewTool:` + - `AUTO("auto")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `ORIGINAL("original")` - - `class BetaApplyPatchTool:` + - `JsonValue; type "input_image"constant` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the input item. Always `input_image`. - - `JsonValue; type "additional_tools"constant` + - `INPUT_IMAGE("input_image")` - The item type. Always `additional_tools`. + - `Optional fileId` - - `ADDITIONAL_TOOLS("additional_tools")` + The ID of the file to be sent to the model. - - `Optional id` + - `Optional imageUrl` - The unique ID of this additional tools item. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `Optional agent` + - `Optional promptCacheBreakpoint` - The agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String agentName` + - `JsonValue; mode "explicit"constant` - The canonical name of the agent that produced this item. + The breakpoint mode. Always `explicit`. - - `class BetaResponseReasoningItem:` + - `EXPLICIT("explicit")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class BetaResponseInputFile:` - - `String id` + A file input to the model. - The unique identifier of the reasoning content. + - `JsonValue; type "input_file"constant` - - `List summary` + The type of the input item. Always `input_file`. - Reasoning summary content. + - `INPUT_FILE("input_file")` - - `String text` + - `Optional detail` - A summary of the reasoning output from the model so far. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `JsonValue; type "summary_text"constant` + - `AUTO("auto")` - The type of the object. Always `summary_text`. + - `LOW("low")` - - `SUMMARY_TEXT("summary_text")` + - `HIGH("high")` - - `JsonValue; type "reasoning"constant` + - `Optional fileData` - The type of the object. Always `reasoning`. + The content of the file to be sent to the model. - - `REASONING("reasoning")` + - `Optional fileId` - - `Optional agent` + The ID of the file to be sent to the model. - The agent that produced this item. + - `Optional fileUrl` - - `String agentName` + The URL of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `Optional filename` - - `Optional> content` + The name of the file to be sent to the model. - Reasoning text content. + - `Optional promptCacheBreakpoint` - - `String text` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The reasoning text from the model. + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "reasoning_text"constant` + The breakpoint mode. Always `explicit`. - The type of the reasoning text. Always `reasoning_text`. + - `EXPLICIT("explicit")` - - `REASONING_TEXT("reasoning_text")` + - `class BetaResponseOutputText:` - - `Optional encryptedContent` + A text output from the model. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `List annotations` - - `Optional status` + The annotations of the text output. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class FileCitation:` - - `IN_PROGRESS("in_progress")` + A citation to a file. - - `COMPLETED("completed")` + - `String fileId` - - `INCOMPLETE("incomplete")` + The ID of the file. - - `class BetaResponseCompactionItemParam:` + - `String filename` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The filename of the file cited. - - `String encryptedContent` + - `long index` - The encrypted content of the compaction summary. + The index of the file in the list of files. - - `JsonValue; type "compaction"constant` + - `JsonValue; type "file_citation"constant` - The type of the item. Always `compaction`. + The type of the file citation. Always `file_citation`. - - `COMPACTION("compaction")` + - `FILE_CITATION("file_citation")` - - `Optional id` + - `class UrlCitation:` - The ID of the compaction item. + A citation for a web resource used to generate a model response. - - `Optional agent` + - `long endIndex` - The agent that produced this item. + The index of the last character of the URL citation in the message. - - `String agentName` + - `long startIndex` - The canonical name of the agent that produced this item. + The index of the first character of the URL citation in the message. - - `ImageGenerationCall` + - `String title` - - `String id` + The title of the web resource. - The unique ID of the image generation call. + - `JsonValue; type "url_citation"constant` - - `Optional result` + The type of the URL citation. Always `url_citation`. - The generated image encoded in base64. + - `URL_CITATION("url_citation")` - - `Status status` + - `String url` - The status of the image generation call. + The URL of the web resource. - - `IN_PROGRESS("in_progress")` + - `class ContainerFileCitation:` - - `COMPLETED("completed")` + A citation for a container file used to generate a model response. - - `GENERATING("generating")` + - `String containerId` - - `FAILED("failed")` + The ID of the container file. - - `JsonValue; type "image_generation_call"constant` + - `long endIndex` - The type of the image generation call. Always `image_generation_call`. + The index of the last character of the container file citation in the message. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `String fileId` - - `Optional agent` + The ID of the file. - The agent that produced this item. + - `String filename` - - `String agentName` + The filename of the container file cited. - The canonical name of the agent that produced this item. + - `long startIndex` - - `class BetaResponseCodeInterpreterToolCall:` + The index of the first character of the container file citation in the message. - A tool call to run code. + - `JsonValue; type "container_file_citation"constant` - - `String id` + The type of the container file citation. Always `container_file_citation`. - The unique ID of the code interpreter tool call. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `Optional code` + - `class FilePath:` - The code to run, or null if not available. + A path to a file. - - `String containerId` + - `String fileId` - The ID of the container used to run the code. + The ID of the file. - - `Optional> outputs` + - `long index` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The index of the file in the list of files. - - `class Logs:` + - `JsonValue; type "file_path"constant` - The logs output from the code interpreter. + The type of the file path. Always `file_path`. - - `String logs` + - `FILE_PATH("file_path")` - The logs output from the code interpreter. + - `String text` - - `JsonValue; type "logs"constant` + The text output from the model. - The type of the output. Always `logs`. + - `JsonValue; type "output_text"constant` - - `LOGS("logs")` + The type of the output text. Always `output_text`. - - `class Image:` + - `OUTPUT_TEXT("output_text")` - The image output from the code interpreter. + - `Optional> logprobs` - - `JsonValue; type "image"constant` + - `String token` - The type of the output. Always `image`. + - `List bytes` - - `IMAGE("image")` + - `double logprob` - - `String url` + - `List topLogprobs` - The URL of the image output from the code interpreter. + - `String token` - - `Status status` + - `List bytes` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `double logprob` - - `IN_PROGRESS("in_progress")` + - `class BetaResponseOutputRefusal:` - - `COMPLETED("completed")` + A refusal from the model. - - `INCOMPLETE("incomplete")` + - `String refusal` - - `INTERPRETING("interpreting")` + The refusal explanation from the model. - - `FAILED("failed")` + - `JsonValue; type "refusal"constant` - - `JsonValue; type "code_interpreter_call"constant` + The type of the refusal. Always `refusal`. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `REFUSAL("refusal")` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `ReasoningText` - - `Optional agent` + - `String text` - The agent that produced this item. + The reasoning text from the model. - - `String agentName` + - `JsonValue; type "reasoning_text"constant` - The canonical name of the agent that produced this item. + The type of the reasoning text. Always `reasoning_text`. - - `LocalShellCall` + - `REASONING_TEXT("reasoning_text")` - - `String id` +### Beta Response Content Part Added Event - The unique ID of the local shell call. +- `class BetaResponseContentPartAddedEvent:` - - `Action action` + Emitted when a new content part is added. - Execute a shell command on the server. + - `long contentIndex` - - `List command` + The index of the content part that was added. - The command to run. + - `String itemId` - - `Env env` + The ID of the output item that the content part was added to. - Environment variables to set for the command. + - `long outputIndex` - - `JsonValue; type "exec"constant` + The index of the output item that the content part was added to. - The type of the local shell action. Always `exec`. + - `Part part` - - `EXEC("exec")` + The content part that was added. - - `Optional timeoutMs` + - `class BetaResponseOutputText:` - Optional timeout in milliseconds for the command. + A text output from the model. - - `Optional user` + - `List annotations` - Optional user to run the command as. + The annotations of the text output. - - `Optional workingDirectory` + - `class FileCitation:` - Optional working directory to run the command in. + A citation to a file. - - `String callId` + - `String fileId` - The unique ID of the local shell tool call generated by the model. + The ID of the file. - - `Status status` + - `String filename` - The status of the local shell call. + The filename of the file cited. - - `IN_PROGRESS("in_progress")` + - `long index` - - `COMPLETED("completed")` + The index of the file in the list of files. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "file_citation"constant` - - `JsonValue; type "local_shell_call"constant` + The type of the file citation. Always `file_citation`. - The type of the local shell call. Always `local_shell_call`. + - `FILE_CITATION("file_citation")` - - `LOCAL_SHELL_CALL("local_shell_call")` + - `class UrlCitation:` - - `Optional agent` + A citation for a web resource used to generate a model response. - The agent that produced this item. + - `long endIndex` - - `String agentName` + The index of the last character of the URL citation in the message. - The canonical name of the agent that produced this item. + - `long startIndex` - - `LocalShellCallOutput` + The index of the first character of the URL citation in the message. - - `String id` + - `String title` - The unique ID of the local shell tool call generated by the model. + The title of the web resource. - - `String output` + - `JsonValue; type "url_citation"constant` - A JSON string of the output of the local shell tool call. + The type of the URL citation. Always `url_citation`. - - `JsonValue; type "local_shell_call_output"constant` + - `URL_CITATION("url_citation")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `String url` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The URL of the web resource. - - `Optional agent` + - `class ContainerFileCitation:` - The agent that produced this item. + A citation for a container file used to generate a model response. - - `String agentName` + - `String containerId` - The canonical name of the agent that produced this item. + The ID of the container file. - - `Optional status` + - `long endIndex` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The index of the last character of the container file citation in the message. - - `IN_PROGRESS("in_progress")` + - `String fileId` - - `COMPLETED("completed")` + The ID of the file. - - `INCOMPLETE("incomplete")` + - `String filename` - - `ShellCall` + The filename of the container file cited. - - `Action action` + - `long startIndex` - The shell commands and limits that describe how to run the tool call. + The index of the first character of the container file citation in the message. - - `List commands` + - `JsonValue; type "container_file_citation"constant` - Ordered shell commands for the execution environment to run. + The type of the container file citation. Always `container_file_citation`. - - `Optional maxOutputLength` + - `CONTAINER_FILE_CITATION("container_file_citation")` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `class FilePath:` - - `Optional timeoutMs` + A path to a file. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `String fileId` - - `String callId` + The ID of the file. - The unique ID of the shell tool call generated by the model. + - `long index` - - `JsonValue; type "shell_call"constant` + The index of the file in the list of files. - The type of the item. Always `shell_call`. + - `JsonValue; type "file_path"constant` - - `SHELL_CALL("shell_call")` + The type of the file path. Always `file_path`. - - `Optional id` + - `FILE_PATH("file_path")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `String text` - - `Optional agent` + The text output from the model. - The agent that produced this item. + - `JsonValue; type "output_text"constant` - - `String agentName` + The type of the output text. Always `output_text`. - The canonical name of the agent that produced this item. + - `OUTPUT_TEXT("output_text")` - - `Optional caller` + - `Optional> logprobs` - The execution context that produced this tool call. + - `String token` - - `JsonValue;` + - `List bytes` - - `JsonValue; type "direct"constant` + - `double logprob` - The caller type. Always `direct`. + - `List topLogprobs` - - `DIRECT("direct")` + - `String token` - - `class Program:` + - `List bytes` - - `String callerId` + - `double logprob` - The call ID of the program item that produced this tool call. + - `class BetaResponseOutputRefusal:` - - `JsonValue; type "program"constant` + A refusal from the model. - The caller type. Always `program`. + - `String refusal` - - `PROGRAM("program")` + The refusal explanation from the model. - - `Optional environment` + - `JsonValue; type "refusal"constant` - The environment to execute the shell commands in. + The type of the refusal. Always `refusal`. - - `class BetaLocalEnvironment:` + - `REFUSAL("refusal")` - - `class BetaContainerReference:` + - `class ReasoningText:` - - `Optional status` + Reasoning text from the model. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `String text` - - `IN_PROGRESS("in_progress")` + The reasoning text from the model. - - `COMPLETED("completed")` + - `JsonValue; type "reasoning_text"constant` - - `INCOMPLETE("incomplete")` + The type of the reasoning text. Always `reasoning_text`. - - `ShellCallOutput` + - `REASONING_TEXT("reasoning_text")` - - `String callId` + - `long sequenceNumber` - The unique ID of the shell tool call generated by the model. + The sequence number of this event. - - `List output` + - `JsonValue; type "response.content_part.added"constant` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The type of the event. Always `response.content_part.added`. - - `Outcome outcome` + - `RESPONSE_CONTENT_PART_ADDED("response.content_part.added")` - The exit or timeout outcome associated with this shell call. + - `Optional agent` - - `JsonValue;` + The agent that owns this multi-agent streaming event. - - `JsonValue; type "timeout"constant` + - `String agentName` - The outcome type. Always `timeout`. + The canonical name of the agent that produced this item. - - `TIMEOUT("timeout")` +### Beta Response Content Part Done Event - - `class Exit:` +- `class BetaResponseContentPartDoneEvent:` - Indicates that the shell commands finished and returned an exit code. + Emitted when a content part is done. - - `long exitCode` + - `long contentIndex` - The exit code returned by the shell process. + The index of the content part that is done. - - `JsonValue; type "exit"constant` + - `String itemId` - The outcome type. Always `exit`. + The ID of the output item that the content part was added to. - - `EXIT("exit")` + - `long outputIndex` - - `String stderr` + The index of the output item that the content part was added to. - Captured stderr output for the shell call. + - `Part part` - - `String stdout` + The content part that is done. - Captured stdout output for the shell call. + - `class BetaResponseOutputText:` - - `JsonValue; type "shell_call_output"constant` + A text output from the model. - The type of the item. Always `shell_call_output`. + - `List annotations` - - `SHELL_CALL_OUTPUT("shell_call_output")` + The annotations of the text output. - - `Optional id` + - `class FileCitation:` - The unique ID of the shell tool call output. Populated when this item is returned via API. + A citation to a file. - - `Optional agent` + - `String fileId` - The agent that produced this item. + The ID of the file. - - `String agentName` + - `String filename` - The canonical name of the agent that produced this item. + The filename of the file cited. - - `Optional caller` + - `long index` - The execution context that produced this tool call. + The index of the file in the list of files. - - `JsonValue;` + - `JsonValue; type "file_citation"constant` - - `JsonValue; type "direct"constant` + The type of the file citation. Always `file_citation`. - The caller type. Always `direct`. + - `FILE_CITATION("file_citation")` - - `DIRECT("direct")` + - `class UrlCitation:` - - `class Program:` + A citation for a web resource used to generate a model response. - - `String callerId` + - `long endIndex` - The call ID of the program item that produced this tool call. + The index of the last character of the URL citation in the message. - - `JsonValue; type "program"constant` + - `long startIndex` - The caller type. Always `program`. + The index of the first character of the URL citation in the message. - - `PROGRAM("program")` + - `String title` - - `Optional maxOutputLength` + The title of the web resource. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `JsonValue; type "url_citation"constant` - - `Optional status` + The type of the URL citation. Always `url_citation`. - The status of the shell call output. + - `URL_CITATION("url_citation")` - - `IN_PROGRESS("in_progress")` + - `String url` - - `COMPLETED("completed")` + The URL of the web resource. - - `INCOMPLETE("incomplete")` + - `class ContainerFileCitation:` - - `ApplyPatchCall` + A citation for a container file used to generate a model response. - - `String callId` + - `String containerId` - The unique ID of the apply patch tool call generated by the model. + The ID of the container file. - - `Operation operation` + - `long endIndex` - The specific create, delete, or update instruction for the apply_patch tool call. + The index of the last character of the container file citation in the message. - - `class CreateFile:` + - `String fileId` - Instruction for creating a new file via the apply_patch tool. + The ID of the file. - - `String diff` + - `String filename` - Unified diff content to apply when creating the file. + The filename of the container file cited. - - `String path` + - `long startIndex` - Path of the file to create relative to the workspace root. + The index of the first character of the container file citation in the message. - - `JsonValue; type "create_file"constant` + - `JsonValue; type "container_file_citation"constant` - The operation type. Always `create_file`. + The type of the container file citation. Always `container_file_citation`. - - `CREATE_FILE("create_file")` + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `class DeleteFile:` + - `class FilePath:` - Instruction for deleting an existing file via the apply_patch tool. + A path to a file. - - `String path` + - `String fileId` - Path of the file to delete relative to the workspace root. + The ID of the file. - - `JsonValue; type "delete_file"constant` + - `long index` - The operation type. Always `delete_file`. + The index of the file in the list of files. - - `DELETE_FILE("delete_file")` + - `JsonValue; type "file_path"constant` - - `class UpdateFile:` + The type of the file path. Always `file_path`. - Instruction for updating an existing file via the apply_patch tool. + - `FILE_PATH("file_path")` - - `String diff` + - `String text` - Unified diff content to apply to the existing file. + The text output from the model. - - `String path` + - `JsonValue; type "output_text"constant` - Path of the file to update relative to the workspace root. + The type of the output text. Always `output_text`. - - `JsonValue; type "update_file"constant` + - `OUTPUT_TEXT("output_text")` - The operation type. Always `update_file`. + - `Optional> logprobs` - - `UPDATE_FILE("update_file")` + - `String token` - - `Status status` + - `List bytes` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `double logprob` - - `IN_PROGRESS("in_progress")` + - `List topLogprobs` - - `COMPLETED("completed")` + - `String token` - - `JsonValue; type "apply_patch_call"constant` + - `List bytes` - The type of the item. Always `apply_patch_call`. + - `double logprob` - - `APPLY_PATCH_CALL("apply_patch_call")` + - `class BetaResponseOutputRefusal:` - - `Optional id` + A refusal from the model. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `String refusal` - - `Optional agent` + The refusal explanation from the model. - The agent that produced this item. + - `JsonValue; type "refusal"constant` - - `String agentName` + The type of the refusal. Always `refusal`. - The canonical name of the agent that produced this item. + - `REFUSAL("refusal")` - - `Optional caller` + - `class ReasoningText:` - The execution context that produced this tool call. + Reasoning text from the model. - - `JsonValue;` + - `String text` - - `JsonValue; type "direct"constant` + The reasoning text from the model. - The caller type. Always `direct`. + - `JsonValue; type "reasoning_text"constant` - - `DIRECT("direct")` + The type of the reasoning text. Always `reasoning_text`. - - `class Program:` + - `REASONING_TEXT("reasoning_text")` - - `String callerId` + - `long sequenceNumber` - The call ID of the program item that produced this tool call. + The sequence number of this event. - - `JsonValue; type "program"constant` + - `JsonValue; type "response.content_part.done"constant` - The caller type. Always `program`. + The type of the event. Always `response.content_part.done`. - - `PROGRAM("program")` + - `RESPONSE_CONTENT_PART_DONE("response.content_part.done")` - - `ApplyPatchCallOutput` + - `Optional agent` - - `String callId` + The agent that owns this multi-agent streaming event. - The unique ID of the apply patch tool call generated by the model. + - `String agentName` - - `Status status` + The canonical name of the agent that produced this item. - The status of the apply patch tool call output. One of `completed` or `failed`. +### Beta Response Conversation Param - - `COMPLETED("completed")` +- `class BetaResponseConversationParam:` - - `FAILED("failed")` + The conversation that this response belongs to. - - `JsonValue; type "apply_patch_call_output"constant` + - `String id` - The type of the item. Always `apply_patch_call_output`. + The unique ID of the conversation. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` +### Beta Response Created Event - - `Optional id` +- `class BetaResponseCreatedEvent:` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + An event that is emitted when a response is created. - - `Optional agent` + - `BetaResponse response` - The agent that produced this item. + The response that was created. - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + Unique identifier for this Response. - - `Optional caller` + - `double createdAt` - The execution context that produced this tool call. + Unix timestamp (in seconds) of when this Response was created. - - `JsonValue;` + - `Optional error` - - `JsonValue; type "direct"constant` + An error object returned when the model fails to generate a Response. - The caller type. Always `direct`. + - `Code code` - - `DIRECT("direct")` + The error code for the response. - - `class Program:` + - `SERVER_ERROR("server_error")` - - `String callerId` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The call ID of the program item that produced this tool call. + - `INVALID_PROMPT("invalid_prompt")` - - `JsonValue; type "program"constant` + - `BIO_POLICY("bio_policy")` - The caller type. Always `program`. + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - `PROGRAM("program")` + - `INVALID_IMAGE("invalid_image")` - - `Optional output` + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - - `McpListTools` + - `INVALID_IMAGE_URL("invalid_image_url")` - - `String id` + - `IMAGE_TOO_LARGE("image_too_large")` - The unique ID of the list. + - `IMAGE_TOO_SMALL("image_too_small")` - - `String serverLabel` + - `IMAGE_PARSE_ERROR("image_parse_error")` - The label of the MCP server. + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - - `List tools` + - `INVALID_IMAGE_MODE("invalid_image_mode")` - The tools available on the server. + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `JsonValue inputSchema` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - The JSON schema describing the tool's input. + - `EMPTY_IMAGE_FILE("empty_image_file")` - - `String name` + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - The name of the tool. + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - - `Optional annotations` + - `String message` - Additional annotations about the tool. + A human-readable description of the error. - - `Optional description` + - `Optional incompleteDetails` - The description of the tool. + Details about why the response is incomplete. - - `JsonValue; type "mcp_list_tools"constant` + - `Optional reason` - The type of the item. Always `mcp_list_tools`. + The reason why the response is incomplete. - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - - `Optional agent` + - `CONTENT_FILTER("content_filter")` - The agent that produced this item. + - `Optional instructions` - - `String agentName` + A system (or developer) message inserted into the model's context. - The canonical name of the agent that produced this item. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `Optional error` + - `String` - Error message if the server could not list tools. + - `List` - - `McpApprovalRequest` + - `class BetaEasyInputMessage:` - - `String id` + 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` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `String text` + + The text input to the model. - The unique ID of the approval request. + - `JsonValue; type "input_text"constant` - - `String arguments` + The type of the input item. Always `input_text`. - A JSON string of arguments for the tool. + - `INPUT_TEXT("input_text")` - - `String name` + - `Optional promptCacheBreakpoint` - The name of the tool to run. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String serverLabel` + - `JsonValue; mode "explicit"constant` - The label of the MCP server making the request. + The breakpoint mode. Always `explicit`. - - `JsonValue; type "mcp_approval_request"constant` + - `EXPLICIT("explicit")` - The type of the item. Always `mcp_approval_request`. + - `class BetaResponseInputImage:` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional agent` + - `Detail detail` - The agent that produced this item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String agentName` + - `LOW("low")` - The canonical name of the agent that produced this item. + - `HIGH("high")` - - `McpApprovalResponse` + - `AUTO("auto")` - - `String approvalRequestId` + - `ORIGINAL("original")` - The ID of the approval request being answered. + - `JsonValue; type "input_image"constant` - - `boolean approve` + The type of the input item. Always `input_image`. - Whether the request was approved. + - `INPUT_IMAGE("input_image")` - - `JsonValue; type "mcp_approval_response"constant` + - `Optional fileId` - The type of the item. Always `mcp_approval_response`. + The ID of the file to be sent to the model. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `Optional imageUrl` - - `Optional id` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The unique ID of the approval response + - `Optional promptCacheBreakpoint` - - `Optional agent` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The agent that produced this item. + - `JsonValue; mode "explicit"constant` - - `String agentName` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `EXPLICIT("explicit")` - - `Optional reason` + - `class BetaResponseInputFile:` - Optional reason for the decision. + A file input to the model. - - `McpCall` + - `JsonValue; type "input_file"constant` - - `String id` + The type of the input item. Always `input_file`. - The unique ID of the tool call. + - `INPUT_FILE("input_file")` - - `String arguments` + - `Optional detail` - A JSON string of the arguments passed to the tool. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `String name` + - `AUTO("auto")` - The name of the tool that was run. + - `LOW("low")` - - `String serverLabel` + - `HIGH("high")` - The label of the MCP server running the tool. + - `Optional fileData` - - `JsonValue; type "mcp_call"constant` + The content of the file to be sent to the model. - The type of the item. Always `mcp_call`. + - `Optional fileId` - - `MCP_CALL("mcp_call")` + The ID of the file to be sent to the model. - - `Optional agent` + - `Optional fileUrl` - The agent that produced this item. + The URL of the file to be sent to the model. - - `String agentName` + - `Optional filename` - The canonical name of the agent that produced this item. + The name of the file to be sent to the model. - - `Optional approvalRequestId` + - `Optional promptCacheBreakpoint` - 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. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional error` + - `JsonValue; mode "explicit"constant` - The error from the tool call, if any. + The breakpoint mode. Always `explicit`. - - `Optional output` + - `EXPLICIT("explicit")` - The output from the tool call. + - `Role role` - - `Optional status` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `USER("user")` - - `IN_PROGRESS("in_progress")` + - `ASSISTANT("assistant")` - - `COMPLETED("completed")` + - `SYSTEM("system")` - - `INCOMPLETE("incomplete")` + - `DEVELOPER("developer")` - - `CALLING("calling")` + - `Optional phase` - - `FAILED("failed")` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class BetaResponseCustomToolCallOutput:` + - `COMMENTARY("commentary")` - The output of a custom tool call from your code, being sent back to the model. + - `FINAL_ANSWER("final_answer")` - - `String callId` + - `Optional type` - The call ID, used to map this custom tool call output to a custom tool call. + The type of the message input. Always `message`. - - `Output output` + - `MESSAGE("message")` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `Message` - - `String` + - `List content` - - `List` + A list of one or many input items to the model, containing different content + types. - `class BetaResponseInputText:` @@ -34300,15 +50826,15 @@ Cancel a response A file input to the model. - - `JsonValue; type "custom_tool_call_output"constant` + - `Role role` - The type of the custom tool call output. Always `custom_tool_call_output`. + The role of the message input. One of `user`, `system`, or `developer`. - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `USER("user")` - - `Optional id` + - `SYSTEM("system")` - The unique ID of the custom tool call output in the OpenAI platform. + - `DEVELOPER("developer")` - `Optional agent` @@ -34318,183 +50844,201 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional caller` + - `Optional status` - The execution context that produced this tool call. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue;` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "direct"constant` + - `COMPLETED("completed")` - The caller type. Always `direct`. + - `INCOMPLETE("incomplete")` - - `DIRECT("direct")` + - `Optional type` - - `class Program:` + The type of the message input. Always set to `message`. - - `String callerId` + - `MESSAGE("message")` - The call ID of the program item that produced this tool call. + - `class BetaResponseOutputMessage:` - - `JsonValue; type "program"constant` + An output message from the model. - The caller type. Always `program`. + - `String id` - - `PROGRAM("program")` + The unique ID of the output message. - - `class BetaResponseCustomToolCall:` + - `List content` - A call to a custom tool created by the model. + The content of the output message. - - `String callId` + - `class BetaResponseOutputText:` - An identifier used to map this custom tool call to a tool call output. + A text output from the model. - - `String input` + - `List annotations` - The input for the custom tool call generated by the model. + The annotations of the text output. - - `String name` + - `class FileCitation:` - The name of the custom tool being called. + A citation to a file. - - `JsonValue; type "custom_tool_call"constant` + - `String fileId` - The type of the custom tool call. Always `custom_tool_call`. + The ID of the file. - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `String filename` - - `Optional id` + The filename of the file cited. - The unique ID of the custom tool call in the OpenAI platform. + - `long index` - - `Optional agent` + The index of the file in the list of files. - The agent that produced this item. + - `JsonValue; type "file_citation"constant` - - `String agentName` + The type of the file citation. Always `file_citation`. - The canonical name of the agent that produced this item. + - `FILE_CITATION("file_citation")` - - `Optional caller` + - `class UrlCitation:` - The execution context that produced this tool call. + A citation for a web resource used to generate a model response. - - `JsonValue;` + - `long endIndex` - - `JsonValue; type "direct"constant` + The index of the last character of the URL citation in the message. - - `DIRECT("direct")` + - `long startIndex` - - `class Program:` + The index of the first character of the URL citation in the message. - - `String callerId` + - `String title` - The call ID of the program item that produced this tool call. + The title of the web resource. - - `JsonValue; type "program"constant` + - `JsonValue; type "url_citation"constant` - - `PROGRAM("program")` + The type of the URL citation. Always `url_citation`. - - `Optional namespace` + - `URL_CITATION("url_citation")` - The namespace of the custom tool being called. + - `String url` - - `CompactionTrigger` + The URL of the web resource. - - `JsonValue; type "compaction_trigger"constant` + - `class ContainerFileCitation:` - The type of the item. Always `compaction_trigger`. + A citation for a container file used to generate a model response. - - `COMPACTION_TRIGGER("compaction_trigger")` + - `String containerId` - - `Optional agent` + The ID of the container file. - The agent that produced this item. + - `long endIndex` - - `String agentName` + The index of the last character of the container file citation in the message. - The canonical name of the agent that produced this item. + - `String fileId` - - `ItemReference` + The ID of the file. - - `String id` + - `String filename` - The ID of the item to reference. + The filename of the container file cited. - - `Optional agent` + - `long startIndex` - The agent that produced this item. + The index of the first character of the container file citation in the message. - - `String agentName` + - `JsonValue; type "container_file_citation"constant` - The canonical name of the agent that produced this item. + The type of the container file citation. Always `container_file_citation`. - - `Optional type` + - `CONTAINER_FILE_CITATION("container_file_citation")` - The type of item to reference. Always `item_reference`. + - `class FilePath:` - - `ITEM_REFERENCE("item_reference")` + A path to a file. - - `Program` + - `String fileId` - - `String id` + The ID of the file. - The unique ID of this program item. + - `long index` - - `String callId` + The index of the file in the list of files. - The stable call ID of the program item. + - `JsonValue; type "file_path"constant` - - `String code` + The type of the file path. Always `file_path`. - The JavaScript source executed by programmatic tool calling. + - `FILE_PATH("file_path")` - - `String fingerprint` + - `String text` - Opaque program replay fingerprint that must be round-tripped. + The text output from the model. - - `JsonValue; type "program"constant` + - `JsonValue; type "output_text"constant` - The item type. Always `program`. + The type of the output text. Always `output_text`. - - `PROGRAM("program")` + - `OUTPUT_TEXT("output_text")` - - `Optional agent` + - `Optional> logprobs` - The agent that produced this item. + - `String token` - - `String agentName` + - `List bytes` - The canonical name of the agent that produced this item. + - `double logprob` - - `ProgramOutput` + - `List topLogprobs` - - `String id` + - `String token` - The unique ID of this program output item. + - `List bytes` - - `String callId` + - `double logprob` - The call ID of the program item. + - `class BetaResponseOutputRefusal:` - - `String result` + A refusal from the model. - The result produced by the program item. + - `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 terminal status of the program output. + 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 "program_output"constant` + - `JsonValue; type "message"constant` - The item type. Always `program_output`. + The type of the output message. Always `message`. - - `PROGRAM_OUTPUT("program_output")` + - `MESSAGE("message")` - `Optional agent` @@ -34504,506 +51048,510 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional metadata` + - `Optional phase` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `COMMENTARY("commentary")` - - `Model model` + - `FINAL_ANSWER("final_answer")` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `class BetaResponseFileSearchToolCall:` - - `GPT_5_6_SOL("gpt-5.6-sol")` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `GPT_5_6_TERRA("gpt-5.6-terra")` + - `String id` - - `GPT_5_6_LUNA("gpt-5.6-luna")` + The unique ID of the file search tool call. - - `GPT_5_4("gpt-5.4")` + - `List queries` - - `GPT_5_4_MINI("gpt-5.4-mini")` + The queries used to search for files. - - `GPT_5_4_NANO("gpt-5.4-nano")` + - `Status status` - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + - `IN_PROGRESS("in_progress")` - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `SEARCHING("searching")` - - `GPT_5_2("gpt-5.2")` + - `COMPLETED("completed")` - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + - `INCOMPLETE("incomplete")` - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + - `FAILED("failed")` - - `GPT_5_2_PRO("gpt-5.2-pro")` + - `JsonValue; type "file_search_call"constant` - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + The type of the file search tool call. Always `file_search_call`. - - `GPT_5_1("gpt-5.1")` + - `FILE_SEARCH_CALL("file_search_call")` - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `Optional agent` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + The agent that produced this item. - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `String agentName` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + The canonical name of the agent that produced this item. - - `GPT_5("gpt-5")` + - `Optional> results` - - `GPT_5_MINI("gpt-5-mini")` + The results of the file search tool call. - - `GPT_5_NANO("gpt-5-nano")` + - `Optional attributes` - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - `String` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `double` - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `boolean` - - `GPT_4_1("gpt-4.1")` + - `Optional fileId` - - `GPT_4_1_MINI("gpt-4.1-mini")` + The unique ID of the file. - - `GPT_4_1_NANO("gpt-4.1-nano")` + - `Optional filename` - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + The name of the file. - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + - `Optional score` - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + The relevance score of the file - a value between 0 and 1. - - `O4_MINI("o4-mini")` + - `Optional text` - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + The text that was retrieved from the file. - - `O3("o3")` + - `class BetaResponseComputerToolCall:` - - `O3_2025_04_16("o3-2025-04-16")` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `O3_MINI("o3-mini")` + - `String id` - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + The unique ID of the computer call. - - `O1("o1")` + - `String callId` - - `O1_2024_12_17("o1-2024-12-17")` + An identifier used when responding to the tool call with output. - - `O1_PREVIEW("o1-preview")` + - `List pendingSafetyChecks` - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + The pending safety checks for the computer call. - - `O1_MINI("o1-mini")` + - `String id` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + The ID of the pending safety check. - - `GPT_4O("gpt-4o")` + - `Optional code` - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + The type of the pending safety check. - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + - `Optional message` - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + Details about the pending safety check. - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + - `Status status` - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + - `IN_PROGRESS("in_progress")` - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + - `COMPLETED("completed")` - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + - `INCOMPLETE("incomplete")` - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + - `Type type` - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + The type of the computer call. Always `computer_call`. - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + - `COMPUTER_CALL("computer_call")` - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `Optional action` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + A click action. - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `Click` - - `CODEX_MINI_LATEST("codex-mini-latest")` + - `Button button` - - `GPT_4O_MINI("gpt-4o-mini")` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + - `LEFT("left")` - - `GPT_4_TURBO("gpt-4-turbo")` + - `RIGHT("right")` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `WHEEL("wheel")` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + - `BACK("back")` - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + - `FORWARD("forward")` - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `JsonValue; type "click"constant` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + Specifies the event type. For a click action, this property is always `click`. - - `GPT_4("gpt-4")` + - `CLICK("click")` - - `GPT_4_0314("gpt-4-0314")` + - `long x` - - `GPT_4_0613("gpt-4-0613")` + The x-coordinate where the click occurred. - - `GPT_4_32K("gpt-4-32k")` + - `long y` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + The y-coordinate where the click occurred. - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `Optional> keys` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + The keys being held while clicking. - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `DoubleClick` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `Optional> keys` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + The keys being held while double-clicking. - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `JsonValue; type "double_click"constant` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + - `DOUBLE_CLICK("double_click")` - - `O1_PRO("o1-pro")` + - `long x` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + The x-coordinate where the double click occurred. - - `O3_PRO("o3-pro")` + - `long y` - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + The y-coordinate where the double click occurred. - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `Drag` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + - `List path` - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `long x` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + The x-coordinate. - - `GPT_5_CODEX("gpt-5-codex")` + - `long y` - - `GPT_5_PRO("gpt-5-pro")` + The y-coordinate. - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `JsonValue; type "drag"constant` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `JsonValue; object_ "response"constant` + - `DRAG("drag")` - The object type of this resource - always set to `response`. + - `Optional> keys` - - `RESPONSE("response")` + The keys being held while dragging the mouse. - - `List output` + - `Keypress` - An array of content items generated by the model. + - `List keys` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `class BetaResponseOutputMessage:` + - `JsonValue; type "keypress"constant` - An output message from the model. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `class BetaResponseFileSearchToolCall:` + - `KEYPRESS("keypress")` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `Move` - - `class BetaResponseFunctionToolCall:` + - `JsonValue; type "move"constant` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Specifies the event type. For a move action, this property is always set to `move`. - - `class BetaResponseFunctionToolCallOutputItem:` + - `MOVE("move")` - - `String id` + - `long x` - The unique ID of the function call tool output. + The x-coordinate to move to. - - `String callId` + - `long y` - The unique ID of the function tool call generated by the model. + The y-coordinate to move to. - - `Output output` + - `Optional> keys` - The output from the function call generated by your code. - Can be a string or an list of output content. + The keys being held while moving the mouse. - - `String` + - `JsonValue;` - - `List` + - `JsonValue; type "screenshot"constant` - - `class BetaResponseInputText:` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - A text input to the model. + - `SCREENSHOT("screenshot")` - - `class BetaResponseInputImage:` + - `Scroll` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `long scrollX` - - `class BetaResponseInputFile:` + The horizontal scroll distance. - A file input to the model. + - `long scrollY` - - `Status status` + The vertical scroll distance. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `JsonValue; type "scroll"constant` - - `IN_PROGRESS("in_progress")` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `COMPLETED("completed")` + - `SCROLL("scroll")` - - `INCOMPLETE("incomplete")` + - `long x` - - `JsonValue; type "function_call_output"constant` + The x-coordinate where the scroll occurred. - The type of the function tool call output. Always `function_call_output`. + - `long y` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + The y-coordinate where the scroll occurred. - - `Optional agent` + - `Optional> keys` - The agent that produced this item. + The keys being held while scrolling. - - `String agentName` + - `Type` - The canonical name of the agent that produced this item. + - `String text` - - `Optional caller` + The text to type. - The execution context that produced this tool call. + - `JsonValue; type "type"constant` - - `JsonValue;` + Specifies the event type. For a type action, this property is always set to `type`. - - `JsonValue; type "direct"constant` + - `TYPE("type")` - The caller type. Always `direct`. + - `JsonValue;` - - `DIRECT("direct")` + - `JsonValue; type "wait"constant` - - `class Program:` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `String callerId` + - `WAIT("wait")` - The call ID of the program item that produced this tool call. + - `Optional> actions` - - `JsonValue; type "program"constant` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The caller type. Always `program`. + - `Click` - - `PROGRAM("program")` + - `DoubleClick` - - `Optional createdBy` + - `Drag` - The identifier of the actor that created the item. + - `Keypress` - - `AgentMessage` + - `Move` - - `String id` + - `JsonValue;` - The unique ID of the agent message. + - `Scroll` - - `String author` + - `Type` - The sending agent identity. + - `JsonValue;` - - `List content` + - `Optional agent` - Encrypted content sent between agents. + The agent that produced this item. - - `class BetaResponseInputText:` + - `String agentName` - A text input to the model. + The canonical name of the agent that produced this item. - - `class BetaResponseOutputText:` + - `ComputerCallOutput` - A text output from the model. + - `String callId` - - `class Text:` + The ID of the computer tool call that produced the output. - A text content. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `String text` + A computer screenshot image used with the computer use tool. - - `JsonValue; type "text"constant` + - `JsonValue; type "computer_screenshot"constant` - - `TEXT("text")` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `class SummaryText:` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - A summary text from the model. + - `Optional fileId` - - `String text` + The identifier of an uploaded file that contains the screenshot. - A summary of the reasoning output from the model so far. + - `Optional imageUrl` - - `JsonValue; type "summary_text"constant` + The URL of the screenshot image. - The type of the object. Always `summary_text`. + - `JsonValue; type "computer_call_output"constant` - - `SUMMARY_TEXT("summary_text")` + The type of the computer tool call output. Always `computer_call_output`. - - `class ReasoningText:` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - Reasoning text from the model. + - `Optional id` - - `String text` + The ID of the computer tool call output. - The reasoning text from the model. + - `Optional> acknowledgedSafetyChecks` - - `JsonValue; type "reasoning_text"constant` + The safety checks reported by the API that have been acknowledged by the developer. - The type of the reasoning text. Always `reasoning_text`. + - `String id` - - `REASONING_TEXT("reasoning_text")` + The ID of the pending safety check. - - `class BetaResponseOutputRefusal:` + - `Optional code` - A refusal from the model. + The type of the pending safety check. - - `class BetaResponseInputImage:` + - `Optional message` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Details about the pending safety check. - - `class ComputerScreenshot:` + - `Optional agent` - A screenshot of a computer. + The agent that produced this item. - - `Detail detail` + - `String agentName` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The canonical name of the agent that produced this item. - - `LOW("low")` + - `Optional status` - - `HIGH("high")` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `AUTO("auto")` + - `IN_PROGRESS("in_progress")` - - `ORIGINAL("original")` + - `COMPLETED("completed")` - - `Optional fileId` + - `INCOMPLETE("incomplete")` - The identifier of an uploaded file that contains the screenshot. + - `class BetaResponseFunctionWebSearch:` - - `Optional imageUrl` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The URL of the screenshot image. + - `String id` - - `JsonValue; type "computer_screenshot"constant` + The unique ID of the web search tool call. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `Action action` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `Optional promptCacheBreakpoint` + - `class Search:` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Action type "search" - Performs a web search query. - - `JsonValue; mode "explicit"constant` + - `JsonValue; type "search"constant` - The breakpoint mode. Always `explicit`. + The action type. - - `EXPLICIT("explicit")` + - `SEARCH("search")` - - `class BetaResponseInputFile:` + - `Optional> queries` - A file input to the model. + The search queries. - - `class EncryptedContent:` + - `Optional query` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The search query. - - `String encryptedContent` + - `Optional> sources` - Opaque encrypted content. + The sources used in the search. - - `JsonValue; type "encrypted_content"constant` + - `JsonValue; type "url"constant` - The type of the input item. Always `encrypted_content`. + The type of source. Always `url`. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `URL("url")` - - `String recipient` + - `String url` - The destination agent identity. + The URL of the source. - - `JsonValue; type "agent_message"constant` + - `class OpenPage:` - The type of the item. Always `agent_message`. + Action type "open_page" - Opens a specific URL from search results. - - `AGENT_MESSAGE("agent_message")` + - `JsonValue; type "open_page"constant` - - `Optional agent` + The action type. - The agent that produced this item. + - `OPEN_PAGE("open_page")` - - `String agentName` + - `Optional url` - The canonical name of the agent that produced this item. + The URL opened by the model. - - `MultiAgentCall` + - `class FindInPage:` - - `String id` + Action type "find_in_page": Searches for a pattern within a loaded page. - The unique ID of the multi-agent call item. + - `String pattern` - - `Action action` + The pattern or text to search for within the page. - The multi-agent action to execute. + - `JsonValue; type "find_in_page"constant` - - `SPAWN_AGENT("spawn_agent")` + The action type. - - `INTERRUPT_AGENT("interrupt_agent")` + - `FIND_IN_PAGE("find_in_page")` - - `LIST_AGENTS("list_agents")` + - `String url` - - `SEND_MESSAGE("send_message")` + The URL of the page searched for the pattern. - - `FOLLOWUP_TASK("followup_task")` + - `Status status` - - `WAIT_AGENT("wait_agent")` + The status of the web search tool call. - - `String arguments` + - `IN_PROGRESS("in_progress")` - The JSON string of arguments generated for the action. + - `SEARCHING("searching")` - - `String callId` + - `COMPLETED("completed")` - The unique ID linking this call to its output. + - `FAILED("failed")` - - `JsonValue; type "multi_agent_call"constant` + - `JsonValue; type "web_search_call"constant` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the web search tool call. Always `web_search_call`. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `WEB_SEARCH_CALL("web_search_call")` - `Optional agent` @@ -35013,202 +51561,209 @@ Cancel a response The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `String id` + - `class BetaResponseFunctionToolCall:` - The unique ID of the multi-agent call output item. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `Action action` + - `String arguments` - The multi-agent action that produced this result. + A JSON string of the arguments to pass to the function. - - `SPAWN_AGENT("spawn_agent")` + - `String callId` - - `INTERRUPT_AGENT("interrupt_agent")` + The unique ID of the function tool call generated by the model. - - `LIST_AGENTS("list_agents")` + - `String name` - - `SEND_MESSAGE("send_message")` + The name of the function to run. - - `FOLLOWUP_TASK("followup_task")` + - `JsonValue; type "function_call"constant` - - `WAIT_AGENT("wait_agent")` + The type of the function tool call. Always `function_call`. - - `String callId` + - `FUNCTION_CALL("function_call")` - The unique ID of the multi-agent call. + - `Optional id` - - `List output` + The unique ID of the function tool call. - Text output returned by the multi-agent action. + - `Optional agent` - - `List annotations` + The agent that produced this item. - The annotations of the text output. + - `String agentName` - - `String text` + The canonical name of the agent that produced this item. - The text output from the model. + - `Optional caller` - - `JsonValue; type "output_text"constant` + The execution context that produced this tool call. - The type of the output text. Always `output_text`. + - `JsonValue;` - - `Optional> logprobs` + - `JsonValue; type "direct"constant` - - `JsonValue; type "multi_agent_call_output"constant` + - `DIRECT("direct")` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `class Program:` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `String callerId` - - `Optional agent` + The call ID of the program item that produced this tool call. - The agent that produced this item. + - `JsonValue; type "program"constant` - - `String agentName` + - `PROGRAM("program")` - The canonical name of the agent that produced this item. + - `Optional namespace` - - `class BetaResponseFunctionWebSearch:` + The namespace of the function to run. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Optional status` - - `class BetaResponseComputerToolCall:` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `IN_PROGRESS("in_progress")` - - `class BetaResponseComputerToolCallOutputItem:` + - `COMPLETED("completed")` - - `String id` + - `INCOMPLETE("incomplete")` - The unique ID of the computer call tool output. + - `FunctionCallOutput` - `String callId` - The ID of the computer tool call that produced the output. + The unique ID of the function tool call generated by the model. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `Output output` - A computer screenshot image used with the computer use tool. + Text, image, or file output of the function tool call. - - `Status status` + - `String` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `List` - - `COMPLETED("completed")` + - `class BetaResponseInputTextContent:` - - `INCOMPLETE("incomplete")` + A text input to the model. - - `FAILED("failed")` + - `String text` - - `IN_PROGRESS("in_progress")` + The text input to the model. - - `JsonValue; type "computer_call_output"constant` + - `JsonValue; type "input_text"constant` - The type of the computer tool call output. Always `computer_call_output`. + The type of the input item. Always `input_text`. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `INPUT_TEXT("input_text")` - - `Optional> acknowledgedSafetyChecks` + - `Optional promptCacheBreakpoint` - The safety checks reported by the API that have been acknowledged by the - developer. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String id` + - `JsonValue; mode "explicit"constant` - The ID of the pending safety check. + The breakpoint mode. Always `explicit`. - - `Optional code` + - `EXPLICIT("explicit")` - The type of the pending safety check. + - `class BetaResponseInputImageContent:` - - `Optional message` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - Details about the pending safety check. + - `JsonValue; type "input_image"constant` - - `Optional agent` + The type of the input item. Always `input_image`. - The agent that produced this item. + - `INPUT_IMAGE("input_image")` - - `String agentName` + - `Optional detail` - The canonical name of the agent that produced this item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Optional createdBy` + - `LOW("low")` - The identifier of the actor that created the item. + - `HIGH("high")` - - `class BetaResponseReasoningItem:` + - `AUTO("auto")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `ORIGINAL("original")` - - `Program` + - `Optional fileId` - - `String id` + The ID of the file to be sent to the model. - The unique ID of the program item. + - `Optional imageUrl` - - `String callId` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The stable call ID of the program item. + - `Optional promptCacheBreakpoint` - - `String code` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The JavaScript source executed by programmatic tool calling. + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` + + - `class BetaResponseInputFileContent:` + + A file input to the model. + + - `JsonValue; type "input_file"constant` + + The type of the input item. Always `input_file`. + + - `INPUT_FILE("input_file")` - - `String fingerprint` + - `Optional detail` - Opaque program replay fingerprint that must be round-tripped. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `JsonValue; type "program"constant` + - `AUTO("auto")` - The type of the item. Always `program`. + - `LOW("low")` - - `PROGRAM("program")` + - `HIGH("high")` - - `Optional agent` + - `Optional fileData` - The agent that produced this item. + The base64-encoded data of the file to be sent to the model. - - `String agentName` + - `Optional fileId` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. - - `ProgramOutput` + - `Optional fileUrl` - - `String id` + The URL of the file to be sent to the model. - The unique ID of the program output item. + - `Optional filename` - - `String callId` + The name of the file to be sent to the model. - The call ID of the program item. + - `Optional promptCacheBreakpoint` - - `String result` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The result produced by the program item. + - `JsonValue; mode "explicit"constant` - - `Status status` + The breakpoint mode. Always `explicit`. - The terminal status of the program output item. + - `EXPLICIT("explicit")` - - `COMPLETED("completed")` + - `JsonValue; type "function_call_output"constant` - - `INCOMPLETE("incomplete")` + The type of the function tool call output. Always `function_call_output`. - - `JsonValue; type "program_output"constant` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - The type of the item. Always `program_output`. + - `Optional id` - - `PROGRAM_OUTPUT("program_output")` + The unique ID of the function tool call output. Populated when this item is returned via API. - `Optional agent` @@ -35218,31 +51773,33 @@ Cancel a response The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall:` + - `Optional caller` - - `String id` + The execution context that produced this tool call. - The unique ID of the tool search call item. + - `JsonValue;` - - `JsonValue arguments` + - `JsonValue; type "direct"constant` - Arguments used for the tool search call. + The caller type. Always `direct`. - - `Optional callId` + - `DIRECT("direct")` - The unique ID of the tool search call generated by the model. + - `class Program:` - - `Execution execution` + - `String callerId` - Whether tool search was executed by the server or by the client. + The call ID of the program item that produced this tool call. - - `SERVER("server")` + - `JsonValue; type "program"constant` - - `CLIENT("client")` + The caller type. Always `program`. - - `Status status` + - `PROGRAM("program")` - The status of the tool search call item that was recorded. + - `Optional status` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -35250,219 +51807,225 @@ Cancel a response - `INCOMPLETE("incomplete")` - - `JsonValue; type "tool_search_call"constant` + - `AgentMessage` - The type of the item. Always `tool_search_call`. + - `String author` - - `TOOL_SEARCH_CALL("tool_search_call")` + The sending agent identity. - - `Optional agent` + - `List content` - The agent that produced this item. + Plaintext, image, or encrypted content sent between agents. - - `String agentName` + - `class BetaResponseInputTextContent:` - The canonical name of the agent that produced this item. + A text input to the model. - - `Optional createdBy` + - `class BetaResponseInputImageContent:` - The identifier of the actor that created the item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class BetaResponseToolSearchOutputItem:` + - `class EncryptedContent:` - - `String id` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The unique ID of the tool search output item. + - `String encryptedContent` - - `Optional callId` + Opaque encrypted content. - The unique ID of the tool search call generated by the model. + - `JsonValue; type "encrypted_content"constant` - - `Execution execution` + The type of the input item. Always `encrypted_content`. - Whether tool search was executed by the server or by the client. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `SERVER("server")` + - `String recipient` - - `CLIENT("client")` + The destination agent identity. - - `Status status` + - `JsonValue; type "agent_message"constant` - The status of the tool search output item that was recorded. + The item type. Always `agent_message`. - - `IN_PROGRESS("in_progress")` + - `AGENT_MESSAGE("agent_message")` - - `COMPLETED("completed")` + - `Optional id` - - `INCOMPLETE("incomplete")` + The unique ID of this agent message item. - - `List tools` + - `Optional agent` - The loaded tool definitions returned by tool search. + The agent that produced this item. - - `class BetaFunctionTool:` + - `String agentName` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool:` + - `MultiAgentCall` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `Action action` - - `class BetaComputerTool:` + The multi-agent action that was executed. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `SPAWN_AGENT("spawn_agent")` - - `class BetaComputerUsePreviewTool:` + - `INTERRUPT_AGENT("interrupt_agent")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `LIST_AGENTS("list_agents")` - - `class BetaWebSearchTool:` + - `SEND_MESSAGE("send_message")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `FOLLOWUP_TASK("followup_task")` - - `Mcp` + - `WAIT_AGENT("wait_agent")` - - `CodeInterpreter` + - `String arguments` - - `JsonValue;` + The action arguments as a JSON string. - - `ImageGeneration` + - `String callId` - - `JsonValue;` + The unique ID linking this call to its output. - - `class BetaFunctionShellTool:` + - `JsonValue; type "multi_agent_call"constant` - A tool that allows the model to execute shell commands. + The item type. Always `multi_agent_call`. - - `class BetaCustomTool:` + - `MULTI_AGENT_CALL("multi_agent_call")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Optional id` - - `class BetaNamespaceTool:` + The unique ID of this multi-agent call. - Groups function/custom tools under a shared namespace. + - `Optional agent` - - `class BetaToolSearchTool:` + The agent that produced this item. - Hosted or BYOT tool search configuration for deferred tools. + - `String agentName` - - `class BetaWebSearchPreviewTool:` + The canonical name of the agent that produced this item. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `MultiAgentCallOutput` - - `class BetaApplyPatchTool:` + - `Action action` - Allows the assistant to create, delete, or update files using unified diffs. + The multi-agent action that produced this result. - - `JsonValue; type "tool_search_output"constant` + - `SPAWN_AGENT("spawn_agent")` - The type of the item. Always `tool_search_output`. + - `INTERRUPT_AGENT("interrupt_agent")` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `LIST_AGENTS("list_agents")` - - `Optional agent` + - `SEND_MESSAGE("send_message")` - The agent that produced this item. + - `FOLLOWUP_TASK("followup_task")` - - `String agentName` + - `WAIT_AGENT("wait_agent")` - The canonical name of the agent that produced this item. + - `String callId` - - `Optional createdBy` + The unique ID of the multi-agent call. - The identifier of the actor that created the item. + - `List output` - - `AdditionalTools` + Text output returned by the multi-agent action. - - `String id` + - `String text` - The unique ID of the additional tools item. + The text content. - - `Role role` + - `JsonValue; type "output_text"constant` - The role that provided the additional tools. + The content type. Always `output_text`. - - `UNKNOWN("unknown")` + - `OUTPUT_TEXT("output_text")` - - `USER("user")` + - `Optional annotations` - - `ASSISTANT("assistant")` + Citations associated with the text content. - - `SYSTEM("system")` + - `List` - - `CRITIC("critic")` + - `String fileId` - - `DISCRIMINATOR("discriminator")` + The ID of the file. - - `DEVELOPER("developer")` + - `String filename` - - `TOOL("tool")` + The filename of the file cited. - - `List tools` + - `long index` - The additional tool definitions made available at this item. + The index of the file in the list of files. - - `class BetaFunctionTool:` + - `JsonValue; type "file_citation"constant` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The citation type. Always `file_citation`. - - `class BetaFileSearchTool:` + - `FILE_CITATION("file_citation")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `List` - - `class BetaComputerTool:` + - `long endIndex` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the last character of the citation in the message. - - `class BetaComputerUsePreviewTool:` + - `long startIndex` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the first character of the citation in the message. - - `class BetaWebSearchTool:` + - `String title` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The title of the cited resource. - - `Mcp` + - `JsonValue; type "url_citation"constant` - - `CodeInterpreter` + The citation type. Always `url_citation`. - - `JsonValue;` + - `URL_CITATION("url_citation")` - - `ImageGeneration` + - `String url` - - `JsonValue;` + The URL of the cited resource. - - `class BetaFunctionShellTool:` + - `List` - A tool that allows the model to execute shell commands. + - `String containerId` - - `class BetaCustomTool:` + The ID of the container. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `long endIndex` - - `class BetaNamespaceTool:` + The index of the last character of the citation in the message. - Groups function/custom tools under a shared namespace. + - `String fileId` - - `class BetaToolSearchTool:` + The ID of the container file. - Hosted or BYOT tool search configuration for deferred tools. + - `String filename` - - `class BetaWebSearchPreviewTool:` + The filename of the container file cited. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `long startIndex` - - `class BetaApplyPatchTool:` + The index of the first character of the citation in the message. - Allows the assistant to create, delete, or update files using unified diffs. + - `JsonValue; type "container_file_citation"constant` - - `JsonValue; type "additional_tools"constant` + The citation type. Always `container_file_citation`. - The type of the item. Always `additional_tools`. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `ADDITIONAL_TOOLS("additional_tools")` + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. - `Optional agent` @@ -35472,23 +52035,21 @@ Cancel a response The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `ToolSearchCall` - - `String id` + - `JsonValue arguments` - The unique ID of the compaction item. + The arguments supplied to the tool search call. - - `String encryptedContent` + - `JsonValue; type "tool_search_call"constant` - The encrypted content that was produced by compaction. + The item type. Always `tool_search_call`. - - `JsonValue; type "compaction"constant` + - `TOOL_SEARCH_CALL("tool_search_call")` - The type of the item. Always `compaction`. + - `Optional id` - - `COMPACTION("compaction")` + The unique ID of this tool search call. - `Optional agent` @@ -35498,2082 +52059,1919 @@ Cancel a response The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. + - `Optional callId` - - `ImageGenerationCall` + The unique ID of the tool search call generated by the model. - - `String id` + - `Optional execution` - The unique ID of the image generation call. + Whether tool search was executed by the server or by the client. - - `Optional result` + - `SERVER("server")` - The generated image encoded in base64. + - `CLIENT("client")` - - `Status status` + - `Optional status` - The status of the image generation call. + The status of the tool search call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - - `GENERATING("generating")` + - `INCOMPLETE("incomplete")` - - `FAILED("failed")` + - `class BetaResponseToolSearchOutputItemParam:` - - `JsonValue; type "image_generation_call"constant` + - `List tools` - The type of the image generation call. Always `image_generation_call`. + The loaded tool definitions returned by the tool search output. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `class BetaFunctionTool:` - - `Optional agent` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The agent that produced this item. + - `String name` - - `String agentName` + The name of the function to call. - The canonical name of the agent that produced this item. + - `Optional parameters` - - `class BetaResponseCodeInterpreterToolCall:` + A JSON schema object describing the parameters of the function. - A tool call to run code. + - `Optional strict` - - `LocalShellCall` + Whether strict parameter validation is enforced for this function tool. - - `String id` + - `JsonValue; type "function"constant` - The unique ID of the local shell call. + The type of the function tool. Always `function`. - - `Action action` + - `FUNCTION("function")` - Execute a shell command on the server. + - `Optional> allowedCallers` - - `List command` + The tool invocation context(s). - The command to run. + - `DIRECT("direct")` - - `Env env` + - `PROGRAMMATIC("programmatic")` - Environment variables to set for the command. + - `Optional deferLoading` - - `JsonValue; type "exec"constant` + Whether this function is deferred and loaded via tool search. - The type of the local shell action. Always `exec`. + - `Optional description` - - `EXEC("exec")` + A description of the function. Used by the model to determine whether or not to call the function. - - `Optional timeoutMs` + - `Optional outputSchema` - Optional timeout in milliseconds for the command. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `Optional user` + - `class BetaFileSearchTool:` - Optional user to run the command as. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional workingDirectory` + - `JsonValue; type "file_search"constant` - Optional working directory to run the command in. + The type of the file search tool. Always `file_search`. - - `String callId` + - `FILE_SEARCH("file_search")` - The unique ID of the local shell tool call generated by the model. + - `List vectorStoreIds` - - `Status status` + The IDs of the vector stores to search. - The status of the local shell call. + - `Optional filters` - - `IN_PROGRESS("in_progress")` + A filter to apply. - - `COMPLETED("completed")` + - `class ComparisonFilter:` - - `INCOMPLETE("incomplete")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `JsonValue; type "local_shell_call"constant` + - `String key` - The type of the local shell call. Always `local_shell_call`. + The key to compare against the value. - - `LOCAL_SHELL_CALL("local_shell_call")` + - `Type type` - - `Optional agent` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The agent that produced this item. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `String agentName` + - `EQ("eq")` - The canonical name of the agent that produced this item. + - `NE("ne")` - - `LocalShellCallOutput` + - `GT("gt")` - - `String id` + - `GTE("gte")` - The unique ID of the local shell tool call generated by the model. + - `LT("lt")` - - `String output` + - `LTE("lte")` - A JSON string of the output of the local shell tool call. + - `IN("in")` - - `JsonValue; type "local_shell_call_output"constant` + - `NIN("nin")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `Value value` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The value to compare against the attribute key; supports string, number, or boolean types. - - `Optional agent` + - `String` - The agent that produced this item. + - `double` - - `String agentName` + - `boolean` - The canonical name of the agent that produced this item. + - `List` - - `Optional status` + - `String` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `double` - - `IN_PROGRESS("in_progress")` + - `class CompoundFilter:` - - `COMPLETED("completed")` + Combine multiple filters using `and` or `or`. - - `INCOMPLETE("incomplete")` + - `List filters` - - `class BetaResponseFunctionShellToolCall:` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - A tool call that executes one or more shell commands in a managed environment. + - `class ComparisonFilter:` - - `String id` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `String key` - - `Action action` + The key to compare against the value. - The shell commands and limits that describe how to run the tool call. + - `Type type` - - `List commands` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `Optional maxOutputLength` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Optional maximum number of characters to return from each command. + - `EQ("eq")` - - `Optional timeoutMs` + - `NE("ne")` - Optional timeout in milliseconds for the commands. + - `GT("gt")` - - `String callId` + - `GTE("gte")` - The unique ID of the shell tool call generated by the model. + - `LT("lt")` - - `Optional environment` + - `LTE("lte")` - Represents the use of a local environment to perform shell actions. + - `IN("in")` - - `class BetaResponseLocalEnvironment:` + - `NIN("nin")` - Represents the use of a local environment to perform shell actions. + - `Value value` - - `JsonValue; type "local"constant` + The value to compare against the attribute key; supports string, number, or boolean types. - The environment type. Always `local`. + - `String` - - `LOCAL("local")` + - `double` - - `class BetaResponseContainerReference:` + - `boolean` - Represents a container created with /v1/containers. + - `List` - - `String containerId` + - `String` - - `JsonValue; type "container_reference"constant` + - `double` - The environment type. Always `container_reference`. + - `JsonValue` - - `CONTAINER_REFERENCE("container_reference")` + - `Type type` - - `Status status` + Type of operation: `and` or `or`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `AND("and")` - - `IN_PROGRESS("in_progress")` + - `OR("or")` - - `COMPLETED("completed")` + - `Optional maxNumResults` - - `INCOMPLETE("incomplete")` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `JsonValue; type "shell_call"constant` + - `Optional rankingOptions` - The type of the item. Always `shell_call`. + Ranking options for search. - - `SHELL_CALL("shell_call")` + - `Optional hybridSearch` - - `Optional agent` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The agent that produced this item. + - `double embeddingWeight` - - `String agentName` + The weight of the embedding in the reciprocal ranking fusion. - The canonical name of the agent that produced this item. + - `double textWeight` - - `Optional caller` + The weight of the text in the reciprocal ranking fusion. - The execution context that produced this tool call. + - `Optional ranker` - - `JsonValue;` + The ranker to use for the file search. - - `JsonValue; type "direct"constant` + - `AUTO("auto")` - - `DIRECT("direct")` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `class Program:` + - `Optional scoreThreshold` - - `String callerId` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The call ID of the program item that produced this tool call. + - `class BetaComputerTool:` - - `JsonValue; type "program"constant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `PROGRAM("program")` + - `JsonValue; type "computer"constant` - - `Optional createdBy` + The type of the computer tool. Always `computer`. - The ID of the entity that created this tool call. + - `COMPUTER("computer")` - - `class BetaResponseFunctionShellToolCallOutput:` + - `class BetaComputerUsePreviewTool:` - The output of a shell tool call that was emitted. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String id` + - `long displayHeight` - The unique ID of the shell call output. Populated when this item is returned via API. + The height of the computer display. - - `String callId` + - `long displayWidth` - The unique ID of the shell tool call generated by the model. + The width of the computer display. - - `Optional maxOutputLength` + - `Environment environment` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The type of computer environment to control. - - `List output` + - `WINDOWS("windows")` - An array of shell call output contents + - `MAC("mac")` - - `Outcome outcome` + - `LINUX("linux")` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `UBUNTU("ubuntu")` - - `JsonValue;` + - `BROWSER("browser")` - - `JsonValue; type "timeout"constant` + - `JsonValue; type "computer_use_preview"constant` - The outcome type. Always `timeout`. + The type of the computer use tool. Always `computer_use_preview`. - - `TIMEOUT("timeout")` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `class Exit:` + - `class BetaWebSearchTool:` - Indicates that the shell commands finished and returned an exit code. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `long exitCode` + - `Type type` - Exit code from the shell process. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `JsonValue; type "exit"constant` + - `WEB_SEARCH("web_search")` - The outcome type. Always `exit`. + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `EXIT("exit")` + - `Optional filters` - - `String stderr` + Filters for the search. - The standard error output that was captured. + - `Optional> allowedDomains` - - `String stdout` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The standard output that was captured. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `Optional createdBy` + - `Optional searchContextSize` - The identifier of the actor that created the item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Status status` + - `LOW("low")` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `MEDIUM("medium")` - - `IN_PROGRESS("in_progress")` + - `HIGH("high")` - - `COMPLETED("completed")` + - `Optional userLocation` - - `INCOMPLETE("incomplete")` + The approximate location of the user. - - `JsonValue; type "shell_call_output"constant` + - `Optional city` - The type of the shell call output. Always `shell_call_output`. + Free text input for the city of the user, e.g. `San Francisco`. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional country` - - `Optional agent` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The agent that produced this item. + - `Optional region` - - `String agentName` + Free text input for the region of the user, e.g. `California`. - The canonical name of the agent that produced this item. + - `Optional timezone` - - `Optional caller` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The execution context that produced this tool call. + - `Optional type` - - `JsonValue;` + The type of location approximation. Always `approximate`. - - `JsonValue; type "direct"constant` + - `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> allowedCallers` + + The tool invocation context(s). - `DIRECT("direct")` - - `class Program:` + - `PROGRAMMATIC("programmatic")` - - `String callerId` + - `Optional allowedTools` - The call ID of the program item that produced this tool call. + List of allowed tool names or a filter object. - - `JsonValue; type "program"constant` + - `List` - - `PROGRAM("program")` + - `class McpToolFilter:` - - `Optional createdBy` + A filter object to specify which tools are allowed. - The identifier of the actor that created the item. + - `Optional readOnly` - - `class BetaResponseApplyPatchToolCall:` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A tool call that applies file diffs by creating, deleting, or updating files. + - `Optional> toolNames` - - `String id` + List of allowed tool names. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `Optional authorization` - - `String callId` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The unique ID of the apply patch tool call generated by the model. + - `Optional connectorId` - - `Operation operation` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Currently supported `connector_id` values are: - - `class CreateFile:` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - Instruction describing how to create a file via the apply_patch tool. + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `String diff` + - `CONNECTOR_GMAIL("connector_gmail")` - Diff to apply. + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `String path` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - Path of the file to create. + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `JsonValue; type "create_file"constant` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - Create a new file with the provided diff. + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `CREATE_FILE("create_file")` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `class DeleteFile:` + - `Optional deferLoading` - Instruction describing how to delete a file via the apply_patch tool. + Whether this MCP tool is deferred and discovered via tool search. - - `String path` + - `Optional headers` - Path of the file to delete. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `JsonValue; type "delete_file"constant` + - `Optional requireApproval` - Delete the specified file. + Specify which of the MCP server's tools require approval. - - `DELETE_FILE("delete_file")` + - `class McpToolApprovalFilter:` - - `class UpdateFile:` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Instruction describing how to update a file via the apply_patch tool. + - `Optional always` - - `String diff` + A filter object to specify which tools are allowed. - Diff to apply. + - `Optional readOnly` - - `String path` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Path of the file to update. + - `Optional> toolNames` - - `JsonValue; type "update_file"constant` + List of allowed tool names. - Update an existing file with the provided diff. + - `Optional never` - - `UPDATE_FILE("update_file")` + A filter object to specify which tools are allowed. - - `Status status` + - `Optional readOnly` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `IN_PROGRESS("in_progress")` + - `Optional> toolNames` - - `COMPLETED("completed")` + List of allowed tool names. - - `JsonValue; type "apply_patch_call"constant` + - `enum McpToolApprovalSetting:` - The type of the item. Always `apply_patch_call`. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `ALWAYS("always")` - - `Optional agent` + - `NEVER("never")` - The agent that produced this item. + - `Optional serverDescription` - - `String agentName` + Optional description of the MCP server, used to provide more context. - The canonical name of the agent that produced this item. + - `Optional serverUrl` - - `Optional caller` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The execution context that produced this tool call. + - `Optional tunnelId` - - `JsonValue;` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `JsonValue; type "direct"constant` + - `CodeInterpreter` - - `DIRECT("direct")` + - `Container container` - - `class Program:` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `String callerId` + - `String` - The call ID of the program item that produced this tool call. + - `class CodeInterpreterToolAuto:` - - `JsonValue; type "program"constant` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `PROGRAM("program")` + - `JsonValue; type "auto"constant` - - `Optional createdBy` + Always `auto`. - The ID of the entity that created this tool call. + - `AUTO("auto")` - - `class BetaResponseApplyPatchToolCallOutput:` + - `Optional> fileIds` - The output emitted by an apply patch tool call. + An optional list of uploaded files to make available to your code. - - `String id` + - `Optional memoryLimit` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The memory limit for the code interpreter container. - - `String callId` + - `_1G("1g")` - The unique ID of the apply patch tool call generated by the model. + - `_4G("4g")` - - `Status status` + - `_16G("16g")` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `_64G("64g")` - - `COMPLETED("completed")` + - `Optional networkPolicy` - - `FAILED("failed")` + Network access policy for the container. - - `JsonValue; type "apply_patch_call_output"constant` + - `class BetaContainerNetworkPolicyDisabled:` - The type of the item. Always `apply_patch_call_output`. + - `JsonValue; type "disabled"constant` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + Disable outbound network access. Always `disabled`. - - `Optional agent` + - `DISABLED("disabled")` - The agent that produced this item. + - `class BetaContainerNetworkPolicyAllowlist:` - - `String agentName` + - `List allowedDomains` - The canonical name of the agent that produced this item. + A list of allowed domains when type is `allowlist`. - - `Optional caller` + - `JsonValue; type "allowlist"constant` - The execution context that produced this tool call. + Allow outbound network access only to specified domains. Always `allowlist`. - - `JsonValue;` + - `ALLOWLIST("allowlist")` - - `JsonValue; type "direct"constant` + - `Optional> domainSecrets` - - `DIRECT("direct")` + Optional domain-scoped secrets for allowlisted domains. - - `class Program:` + - `String domain` - - `String callerId` + The domain associated with the secret. - The call ID of the program item that produced this tool call. + - `String name` - - `JsonValue; type "program"constant` + The name of the secret to inject for the domain. - - `PROGRAM("program")` + - `String value` - - `Optional createdBy` + The secret value to inject for the domain. - The ID of the entity that created this tool call output. + - `JsonValue; type "code_interpreter"constant` - - `Optional output` + The type of the code interpreter tool. Always `code_interpreter`. - Optional textual output returned by the apply patch tool. + - `CODE_INTERPRETER("code_interpreter")` - - `McpCall` + - `Optional> allowedCallers` - - `String id` + The tool invocation context(s). - The unique ID of the tool call. + - `DIRECT("direct")` - - `String arguments` + - `PROGRAMMATIC("programmatic")` - A JSON string of the arguments passed to the tool. + - `JsonValue;` - - `String name` + - `JsonValue; type "programmatic_tool_calling"constant` - The name of the tool that was run. + The type of the tool. Always `programmatic_tool_calling`. - - `String serverLabel` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - The label of the MCP server running the tool. + - `ImageGeneration` - - `JsonValue; type "mcp_call"constant` + - `JsonValue; type "image_generation"constant` - The type of the item. Always `mcp_call`. + The type of the image generation tool. Always `image_generation`. - - `MCP_CALL("mcp_call")` + - `IMAGE_GENERATION("image_generation")` - - `Optional agent` + - `Optional action` - The agent that produced this item. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `String agentName` + - `GENERATE("generate")` - The canonical name of the agent that produced this item. + - `EDIT("edit")` - - `Optional approvalRequestId` + - `AUTO("auto")` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `Optional background` - - `Optional error` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - The error from the tool call, if any. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `Optional output` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The output from the tool call. + - `TRANSPARENT("transparent")` - - `Optional status` + - `OPAQUE("opaque")` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `AUTO("auto")` - - `IN_PROGRESS("in_progress")` + - `Optional inputFidelity` - - `COMPLETED("completed")` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `INCOMPLETE("incomplete")` + - `HIGH("high")` - - `CALLING("calling")` + - `LOW("low")` - - `FAILED("failed")` + - `Optional inputImageMask` - - `McpListTools` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `String id` + - `Optional fileId` - The unique ID of the list. + File ID for the mask image. - - `String serverLabel` + - `Optional imageUrl` - The label of the MCP server. + Base64-encoded mask image. - - `List tools` + - `Optional model` - The tools available on the server. + The image generation model to use. Default: `gpt-image-1`. - - `JsonValue inputSchema` + - `GPT_IMAGE_1("gpt-image-1")` - The JSON schema describing the tool's input. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `String name` + - `GPT_IMAGE_2("gpt-image-2")` - The name of the tool. + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `Optional annotations` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - Additional annotations about the tool. + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `Optional description` + - `Optional moderation` - The description of the tool. + Moderation level for the generated image. Default: `auto`. - - `JsonValue; type "mcp_list_tools"constant` + - `AUTO("auto")` - The type of the item. Always `mcp_list_tools`. + - `LOW("low")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `Optional outputCompression` - - `Optional agent` + Compression level for the output image. Default: 100. - The agent that produced this item. + - `Optional outputFormat` - - `String agentName` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The canonical name of the agent that produced this item. + - `PNG("png")` - - `Optional error` + - `WEBP("webp")` - Error message if the server could not list tools. + - `JPEG("jpeg")` - - `McpApprovalRequest` + - `Optional partialImages` - - `String id` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The unique ID of the approval request. + - `Optional quality` - - `String arguments` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A JSON string of arguments for the tool. + - `LOW("low")` - - `String name` + - `MEDIUM("medium")` - The name of the tool to run. + - `HIGH("high")` - - `String serverLabel` + - `AUTO("auto")` - The label of the MCP server making the request. + - `Optional size` - - `JsonValue; type "mcp_approval_request"constant` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The type of the item. Always `mcp_approval_request`. + - `_1024X1024("1024x1024")` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `_1024X1536("1024x1536")` - - `Optional agent` + - `_1536X1024("1536x1024")` - The agent that produced this item. + - `AUTO("auto")` - - `String agentName` + - `JsonValue;` - The canonical name of the agent that produced this item. + - `JsonValue; type "local_shell"constant` - - `McpApprovalResponse` + The type of the local shell tool. Always `local_shell`. - - `String id` + - `LOCAL_SHELL("local_shell")` - The unique ID of the approval response + - `class BetaFunctionShellTool:` - - `String approvalRequestId` + A tool that allows the model to execute shell commands. - The ID of the approval request being answered. + - `JsonValue; type "shell"constant` - - `boolean approve` + The type of the shell tool. Always `shell`. - Whether the request was approved. + - `SHELL("shell")` - - `JsonValue; type "mcp_approval_response"constant` + - `Optional> allowedCallers` - The type of the item. Always `mcp_approval_response`. + The tool invocation context(s). - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `DIRECT("direct")` - - `Optional agent` + - `PROGRAMMATIC("programmatic")` - The agent that produced this item. + - `Optional environment` - - `String agentName` + - `class BetaContainerAuto:` - The canonical name of the agent that produced this item. + - `JsonValue; type "container_auto"constant` - - `Optional reason` + Automatically creates a container for this request - Optional reason for the decision. + - `CONTAINER_AUTO("container_auto")` - - `class BetaResponseCustomToolCall:` + - `Optional> fileIds` - A call to a custom tool created by the model. + An optional list of uploaded files to make available to your code. - - `class BetaResponseCustomToolCallOutputItem:` + - `Optional memoryLimit` - The output of a custom tool call from your code, being sent back to the model. + The memory limit for the container. - - `String id` + - `_1G("1g")` - The unique ID of the custom tool call output item. + - `_4G("4g")` - - `Status status` + - `_16G("16g")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `_64G("64g")` - - `IN_PROGRESS("in_progress")` + - `Optional networkPolicy` - - `COMPLETED("completed")` + Network access policy for the container. - - `INCOMPLETE("incomplete")` + - `class BetaContainerNetworkPolicyDisabled:` - - `Optional createdBy` + - `class BetaContainerNetworkPolicyAllowlist:` - The identifier of the actor that created the item. + - `Optional> skills` - - `boolean parallelToolCalls` + An optional list of skills referenced by id or inline data. - Whether to allow the model to run tool calls in parallel. + - `class BetaSkillReference:` - - `Optional temperature` + - `String skillId` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + The ID of the referenced skill. - - `ToolChoice toolChoice` + - `JsonValue; type "skill_reference"constant` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + References a skill created with the /v1/skills endpoint. - - `enum BetaToolChoiceOptions:` + - `SKILL_REFERENCE("skill_reference")` - Controls which (if any) tool is called by the model. + - `Optional version` - `none` means the model will not call any tool and instead generates a message. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `class BetaInlineSkill:` - `required` means the model must call one or more tools. + - `String description` - - `NONE("none")` + The description of the skill. - - `AUTO("auto")` + - `String name` - - `REQUIRED("required")` + The name of the skill. - - `class BetaToolChoiceAllowed:` + - `BetaInlineSkillSource source` - Constrains the tools available to the model to a pre-defined set. + Inline skill payload - - `Mode mode` + - `String data` - Constrains the tools available to the model to a pre-defined set. + Base64-encoded skill zip bundle. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `JsonValue; mediaType "application/zip"constant` - `required` requires the model to call one or more of the allowed tools. + The media type of the inline skill payload. Must be `application/zip`. - - `AUTO("auto")` + - `APPLICATION_ZIP("application/zip")` - - `REQUIRED("required")` + - `JsonValue; type "base64"constant` - - `List tools` + The type of the inline skill source. Must be `base64`. - A list of tool definitions that the model should be allowed to call. + - `BASE64("base64")` - For the Responses API, the list of tool definitions might look like: + - `JsonValue; type "inline"constant` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + Defines an inline skill for this request. - - `JsonValue; type "allowed_tools"constant` + - `INLINE("inline")` - Allowed tool configuration type. Always `allowed_tools`. + - `class BetaLocalEnvironment:` - - `ALLOWED_TOOLS("allowed_tools")` + - `JsonValue; type "local"constant` - - `class BetaToolChoiceTypes:` + Use a local computer environment. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `LOCAL("local")` - - `Type type` + - `Optional> skills` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + An optional list of skills. - Allowed values are: + - `String description` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The description of the skill. - - `FILE_SEARCH("file_search")` + - `String name` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + The name of the skill. - - `COMPUTER("computer")` + - `String path` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The path to the directory containing the skill. - - `COMPUTER_USE("computer_use")` + - `class BetaContainerReference:` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `String containerId` - - `IMAGE_GENERATION("image_generation")` + The ID of the referenced container. - - `CODE_INTERPRETER("code_interpreter")` + - `JsonValue; type "container_reference"constant` - - `class BetaToolChoiceFunction:` + References a container created with the /v1/containers endpoint - Use this option to force the model to call a specific function. + - `CONTAINER_REFERENCE("container_reference")` - - `String name` + - `class BetaCustomTool:` - The name of the function to call. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `JsonValue; type "function"constant` + - `String name` - For function calling, the type is always `function`. + The name of the custom tool, used to identify it in tool calls. - - `FUNCTION("function")` + - `JsonValue; type "custom"constant` - - `class BetaToolChoiceMcp:` + The type of the custom tool. Always `custom`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `CUSTOM("custom")` - - `String serverLabel` + - `Optional> allowedCallers` - The label of the MCP server to use. + The tool invocation context(s). - - `JsonValue; type "mcp"constant` + - `DIRECT("direct")` - For MCP tools, the type is always `mcp`. + - `PROGRAMMATIC("programmatic")` - - `MCP("mcp")` + - `Optional deferLoading` - - `Optional name` + Whether this tool should be deferred and discovered via tool search. - The name of the tool to call on the server. + - `Optional description` - - `class BetaToolChoiceCustom:` + Optional description of the custom tool, used to provide more context. - Use this option to force the model to call a specific custom tool. + - `Optional format` - - `String name` + The input format for the custom tool. Default is unconstrained text. - The name of the custom tool to call. + - `JsonValue;` - - `JsonValue; type "custom"constant` + - `JsonValue; type "text"constant` - For custom tool calling, the type is always `custom`. + Unconstrained text format. Always `text`. - - `CUSTOM("custom")` + - `TEXT("text")` - - `JsonValue;` + - `class Grammar:` - - `JsonValue; type "programmatic_tool_calling"constant` + A grammar defined by the user. - The tool to call. Always `programmatic_tool_calling`. + - `String definition` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + The grammar definition. - - `class BetaToolChoiceApplyPatch:` + - `Syntax syntax` - Forces the model to call the apply_patch tool when executing a tool call. + The syntax of the grammar definition. One of `lark` or `regex`. - - `JsonValue; type "apply_patch"constant` + - `LARK("lark")` - The tool to call. Always `apply_patch`. + - `REGEX("regex")` - - `APPLY_PATCH("apply_patch")` + - `JsonValue; type "grammar"constant` - - `class BetaToolChoiceShell:` + Grammar format. Always `grammar`. - Forces the model to call the shell tool when a tool call is required. + - `GRAMMAR("grammar")` - - `JsonValue; type "shell"constant` + - `class BetaNamespaceTool:` - The tool to call. Always `shell`. + Groups function/custom tools under a shared namespace. - - `SHELL("shell")` + - `String description` - - `List tools` + A description of the namespace shown to the model. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `String name` - We support the following categories of tools: + The namespace name used in tool calls (for example, `crm`). - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `List tools` - - `class BetaFunctionTool:` + The function/custom tools available inside this namespace. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class Function:` - - `class BetaFileSearchTool:` + - `String name` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `JsonValue; type "function"constant` - - `class BetaComputerTool:` + - `FUNCTION("function")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional> allowedCallers` - - `class BetaComputerUsePreviewTool:` + The tool invocation context(s). - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `DIRECT("direct")` - - `class BetaWebSearchTool:` + - `PROGRAMMATIC("programmatic")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional deferLoading` - - `Mcp` + Whether this function should be deferred and discovered via tool search. - - `CodeInterpreter` + - `Optional description` - - `JsonValue;` + - `Optional outputSchema` - - `ImageGeneration` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `JsonValue;` + - `Optional parameters` - - `class BetaFunctionShellTool:` + - `Optional strict` - A tool that allows the model to execute shell commands. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - `class BetaCustomTool:` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class BetaNamespaceTool:` + - `JsonValue; type "namespace"constant` - Groups function/custom tools under a shared namespace. + The type of the tool. Always `namespace`. + + - `NAMESPACE("namespace")` - `class BetaToolSearchTool:` Hosted or BYOT tool search configuration for deferred tools. - - `class BetaWebSearchPreviewTool:` + - `JsonValue; type "tool_search"constant` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of the tool. Always `tool_search`. - - `class BetaApplyPatchTool:` + - `TOOL_SEARCH("tool_search")` - Allows the assistant to create, delete, or update files using unified diffs. + - `Optional description` - - `Optional topP` + Description shown to the model for a client-executed tool search tool. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `Optional execution` - We generally recommend altering this or `temperature` but not both. + Whether tool search is executed by the server or by the client. - - `Optional background` + - `SERVER("server")` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `CLIENT("client")` - - `Optional completedAt` + - `Optional parameters` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + Parameter schema for a client-executed tool search tool. - - `Optional conversation` + - `class BetaWebSearchPreviewTool:` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String id` + - `Type type` - The unique ID of the conversation that this response was associated with. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `Optional maxOutputTokens` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `Optional maxToolCalls` + - `Optional> searchContentTypes` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `TEXT("text")` - - `Optional moderation` + - `IMAGE("image")` - Moderation results for the response input and output, if moderated completions were requested. + - `Optional searchContextSize` - - `Input input` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Moderation for the response input. + - `LOW("low")` - - `class ModerationResult:` + - `MEDIUM("medium")` - A moderation result produced for the response input or output. + - `HIGH("high")` - - `Categories categories` + - `Optional userLocation` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The user's location. - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `JsonValue; type "approximate"constant` - Which modalities of input are reflected by the score for each category. + The type of location approximation. Always `approximate`. - - `TEXT("text")` + - `APPROXIMATE("approximate")` - - `IMAGE("image")` + - `Optional city` - - `CategoryScores categoryScores` + Free text input for the city of the user, e.g. `San Francisco`. - A dictionary of moderation categories to scores. + - `Optional country` - - `boolean flagged` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A boolean indicating whether the content was flagged by any category. + - `Optional region` - - `String model` + Free text input for the region of the user, e.g. `California`. - The moderation model that produced this result. + - `Optional timezone` - - `JsonValue; type "moderation_result"constant` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The object type, which was always `moderation_result` for successful moderation results. + - `class BetaApplyPatchTool:` - - `MODERATION_RESULT("moderation_result")` + Allows the assistant to create, delete, or update files using unified diffs. - - `class Error:` + - `JsonValue; type "apply_patch"constant` - An error produced while attempting moderation for the response input or output. + The type of the tool. Always `apply_patch`. - - `String code` + - `APPLY_PATCH("apply_patch")` - The error code. + - `Optional> allowedCallers` - - `String message` + The tool invocation context(s). - The error message. + - `DIRECT("direct")` - - `JsonValue; type "error"constant` + - `PROGRAMMATIC("programmatic")` - The object type, which was always `error` for moderation failures. + - `JsonValue; type "tool_search_output"constant` - - `ERROR("error")` + The item type. Always `tool_search_output`. - - `Output output` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - Moderation for the response output. + - `Optional id` - - `class ModerationResult:` + The unique ID of this tool search output. - A moderation result produced for the response input or output. + - `Optional agent` - - `Categories categories` + The agent that produced this item. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `String agentName` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + The canonical name of the agent that produced this item. - Which modalities of input are reflected by the score for each category. + - `Optional callId` - - `TEXT("text")` + The unique ID of the tool search call generated by the model. - - `IMAGE("image")` + - `Optional execution` - - `CategoryScores categoryScores` + Whether tool search was executed by the server or by the client. - A dictionary of moderation categories to scores. + - `SERVER("server")` - - `boolean flagged` + - `CLIENT("client")` - A boolean indicating whether the content was flagged by any category. + - `Optional status` - - `String model` + The status of the tool search output. - The moderation model that produced this result. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "moderation_result"constant` + - `COMPLETED("completed")` - The object type, which was always `moderation_result` for successful moderation results. + - `INCOMPLETE("incomplete")` - - `MODERATION_RESULT("moderation_result")` + - `AdditionalTools` - - `class Error:` + - `JsonValue; role "developer"constant` - An error produced while attempting moderation for the response input or output. + The role that provided the additional tools. Only `developer` is supported. - - `String code` + - `DEVELOPER("developer")` - The error code. + - `List tools` - - `String message` + A list of additional tools made available at this item. - The error message. + - `class BetaFunctionTool:` - - `JsonValue; type "error"constant` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The object type, which was always `error` for moderation failures. + - `class BetaFileSearchTool:` - - `ERROR("error")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional previousResponseId` + - `class BetaComputerTool:` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional prompt` + - `class BetaComputerUsePreviewTool:` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String id` + - `class BetaWebSearchTool:` - The unique identifier of the prompt template to use. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional variables` + - `Mcp` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `CodeInterpreter` - - `String` + - `JsonValue;` - - `class BetaResponseInputText:` + - `ImageGeneration` - A text input to the model. + - `JsonValue;` - - `class BetaResponseInputImage:` + - `class BetaFunctionShellTool:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A tool that allows the model to execute shell commands. - - `class BetaResponseInputFile:` + - `class BetaCustomTool:` - A file input to the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional version` + - `class BetaNamespaceTool:` - Optional version of the prompt template. + Groups function/custom tools under a shared namespace. - - `Optional promptCacheKey` + - `class BetaToolSearchTool:` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Hosted or BYOT tool search configuration for deferred tools. - - `Optional promptCacheOptions` + - `class BetaWebSearchPreviewTool:` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Mode mode` + - `class BetaApplyPatchTool:` - Whether implicit prompt-cache breakpoints were enabled. + Allows the assistant to create, delete, or update files using unified diffs. - - `IMPLICIT("implicit")` + - `JsonValue; type "additional_tools"constant` - - `EXPLICIT("explicit")` + The item type. Always `additional_tools`. - - `Ttl ttl` + - `ADDITIONAL_TOOLS("additional_tools")` - The minimum lifetime applied to each cache breakpoint. + - `Optional id` - - `_30M("30m")` + The unique ID of this additional tools item. - - `Optional promptCacheRetention` + - `Optional agent` - Deprecated. Use `prompt_cache_options.ttl` instead. + The agent that produced this item. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `String agentName` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The canonical name of the agent that produced this item. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `class BetaResponseReasoningItem:` - - `IN_MEMORY("in_memory")` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `_24H("24h")` + - `String id` - - `Optional reasoning` + The unique identifier of the reasoning content. - **gpt-5 and o-series models only** + - `List summary` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Reasoning summary content. - - `Optional context` + - `String text` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + A summary of the reasoning output from the model so far. - - `AUTO("auto")` + - `JsonValue; type "summary_text"constant` - - `CURRENT_TURN("current_turn")` + The type of the object. Always `summary_text`. - - `ALL_TURNS("all_turns")` + - `SUMMARY_TEXT("summary_text")` - - `Optional effort` + - `JsonValue; type "reasoning"constant` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The type of the object. Always `reasoning`. - - `NONE("none")` + - `REASONING("reasoning")` - - `MINIMAL("minimal")` + - `Optional agent` - - `LOW("low")` + The agent that produced this item. - - `MEDIUM("medium")` + - `String agentName` - - `HIGH("high")` + The canonical name of the agent that produced this item. - - `XHIGH("xhigh")` + - `Optional> content` - - `MAX("max")` + Reasoning text content. - - `Optional generateSummary` + - `String text` - **Deprecated:** use `summary` instead. + The reasoning text from the model. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `JsonValue; type "reasoning_text"constant` - - `AUTO("auto")` + The type of the reasoning text. Always `reasoning_text`. - - `CONCISE("concise")` + - `REASONING_TEXT("reasoning_text")` - - `DETAILED("detailed")` + - `Optional encryptedContent` - - `Optional mode` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - Controls the reasoning execution mode for the request. + - `Optional status` - When returned on a response, this is the effective execution mode. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `STANDARD("standard")` + - `IN_PROGRESS("in_progress")` - - `PRO("pro")` + - `COMPLETED("completed")` - - `Optional summary` + - `INCOMPLETE("incomplete")` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `class BetaResponseCompactionItemParam:` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `AUTO("auto")` + - `String encryptedContent` - - `CONCISE("concise")` + The encrypted content of the compaction summary. - - `DETAILED("detailed")` + - `JsonValue; type "compaction"constant` - - `Optional safetyIdentifier` + The type of the item. Always `compaction`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `COMPACTION("compaction")` - - `Optional serviceTier` + - `Optional id` - Specifies the processing type used for serving the request. + The ID of the compaction item. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `Optional agent` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The agent that produced this item. - - `AUTO("auto")` + - `String agentName` - - `DEFAULT("default")` + The canonical name of the agent that produced this item. - - `FLEX("flex")` + - `ImageGenerationCall` - - `SCALE("scale")` + - `String id` - - `PRIORITY("priority")` + The unique ID of the image generation call. - - `Optional status` + - `Optional result` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The generated image encoded in base64. - - `COMPLETED("completed")` + - `Status status` - - `FAILED("failed")` + The status of the image generation call. - `IN_PROGRESS("in_progress")` - - `CANCELLED("cancelled")` - - - `QUEUED("queued")` + - `COMPLETED("completed")` - - `INCOMPLETE("incomplete")` + - `GENERATING("generating")` - - `Optional text` + - `FAILED("failed")` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `JsonValue; type "image_generation_call"constant` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The type of the image generation call. Always `image_generation_call`. - - `Optional format` + - `IMAGE_GENERATION_CALL("image_generation_call")` - An object specifying the format that the model must output. + - `Optional agent` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The agent that produced this item. - The default format is `{ "type": "text" }` with no additional options. + - `String agentName` - **Not recommended for gpt-4o and newer models:** + The canonical name of the agent that produced this item. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `class BetaResponseCodeInterpreterToolCall:` - - `JsonValue;` + A tool call to run code. - - `JsonValue; type "text"constant` + - `String id` - The type of response format being defined. Always `text`. + The unique ID of the code interpreter tool call. - - `TEXT("text")` + - `Optional code` - - `class BetaResponseFormatTextJsonSchemaConfig:` + The code to run, or null if not available. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `String containerId` - - `String name` + The ID of the container used to run the code. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `Optional> outputs` - - `Schema schema` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `class Logs:` - - `JsonValue; type "json_schema"constant` + The logs output from the code interpreter. - The type of response format being defined. Always `json_schema`. + - `String logs` - - `JSON_SCHEMA("json_schema")` + The logs output from the code interpreter. - - `Optional description` + - `JsonValue; type "logs"constant` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The type of the output. Always `logs`. - - `Optional strict` + - `LOGS("logs")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `class Image:` - - `JsonValue;` + The image output from the code interpreter. - - `JsonValue; type "json_object"constant` + - `JsonValue; type "image"constant` - The type of response format being defined. Always `json_object`. + The type of the output. Always `image`. - - `JSON_OBJECT("json_object")` + - `IMAGE("image")` - - `Optional verbosity` + - `String url` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The URL of the image output from the code interpreter. - - `LOW("low")` + - `Status status` - - `MEDIUM("medium")` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `HIGH("high")` + - `IN_PROGRESS("in_progress")` - - `Optional topLogprobs` + - `COMPLETED("completed")` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `INCOMPLETE("incomplete")` - - `Optional truncation` + - `INTERPRETING("interpreting")` - The truncation strategy to use for the model response. + - `FAILED("failed")` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `JsonValue; type "code_interpreter_call"constant` - - `AUTO("auto")` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `DISABLED("disabled")` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `Optional usage` + - `Optional agent` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The agent that produced this item. - - `long inputTokens` + - `String agentName` - The number of input tokens. + The canonical name of the agent that produced this item. - - `InputTokensDetails inputTokensDetails` + - `LocalShellCall` - A detailed breakdown of the input tokens. + - `String id` - - `long cacheWriteTokens` + The unique ID of the local shell call. - The number of input tokens that were written to the cache. + - `Action action` - - `long cachedTokens` + Execute a shell command on the server. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `List command` - - `long outputTokens` + The command to run. - The number of output tokens. + - `Env env` - - `OutputTokensDetails outputTokensDetails` + Environment variables to set for the command. - A detailed breakdown of the output tokens. + - `JsonValue; type "exec"constant` - - `long reasoningTokens` + The type of the local shell action. Always `exec`. - The number of reasoning tokens. + - `EXEC("exec")` - - `long totalTokens` + - `Optional timeoutMs` - The total number of tokens used. + Optional timeout in milliseconds for the command. - `Optional user` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - -### Example - -```java -package com.openai.example; - -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.responses.BetaResponse; -import com.openai.models.beta.responses.ResponseCancelParams; + Optional user to run the command as. -public final class Main { - private Main() {} + - `Optional workingDirectory` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + Optional working directory to run the command in. - BetaResponse betaResponse = client.beta().responses().cancel("resp_677efb5139a88190b512bc3fef8e535d"); - } -} -``` + - `String callId` -#### Response + The unique ID of the local shell tool call generated by the model. -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + - `Status status` -## Compact a response + The status of the local shell call. -`BetaCompactedResponse beta().responses().compact(ResponseCompactParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` + - `IN_PROGRESS("in_progress")` -**post** `/responses/compact?beta=true` + - `COMPLETED("completed")` -Compact a response + - `INCOMPLETE("incomplete")` -### Parameters + - `JsonValue; type "local_shell_call"constant` -- `ResponseCompactParams params` + The type of the local shell call. Always `local_shell_call`. - - `Optional> betas` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + - `Optional agent` - - `Optional model` + The agent that produced this item. - Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. + - `String agentName` - - `GPT_5_6_SOL("gpt-5.6-sol")` + The canonical name of the agent that produced this item. - - `GPT_5_6_TERRA("gpt-5.6-terra")` + - `LocalShellCallOutput` - - `GPT_5_6_LUNA("gpt-5.6-luna")` + - `String id` - - `GPT_5_4("gpt-5.4")` + The unique ID of the local shell tool call generated by the model. - - `GPT_5_4_MINI("gpt-5.4-mini")` + - `String output` - - `GPT_5_4_NANO("gpt-5.4-nano")` + A JSON string of the output of the local shell tool call. - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `JsonValue; type "local_shell_call_output"constant` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `GPT_5_2("gpt-5.2")` + - `Optional agent` - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + The agent that produced this item. - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + - `String agentName` - - `GPT_5_2_PRO("gpt-5.2-pro")` + The canonical name of the agent that produced this item. - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + - `Optional status` - - `GPT_5_1("gpt-5.1")` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `IN_PROGRESS("in_progress")` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + - `COMPLETED("completed")` - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `INCOMPLETE("incomplete")` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + - `ShellCall` - - `GPT_5("gpt-5")` + - `Action action` - - `GPT_5_MINI("gpt-5-mini")` + The shell commands and limits that describe how to run the tool call. - - `GPT_5_NANO("gpt-5-nano")` + - `List commands` - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + Ordered shell commands for the execution environment to run. - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - `Optional maxOutputLength` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `Optional timeoutMs` - - `GPT_4_1("gpt-4.1")` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `GPT_4_1_MINI("gpt-4.1-mini")` + - `String callId` - - `GPT_4_1_NANO("gpt-4.1-nano")` + The unique ID of the shell tool call generated by the model. - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `JsonValue; type "shell_call"constant` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + The type of the item. Always `shell_call`. - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + - `SHELL_CALL("shell_call")` - - `O4_MINI("o4-mini")` + - `Optional id` - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `O3("o3")` + - `Optional agent` - - `O3_2025_04_16("o3-2025-04-16")` + The agent that produced this item. - - `O3_MINI("o3-mini")` + - `String agentName` - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + The canonical name of the agent that produced this item. - - `O1("o1")` + - `Optional caller` - - `O1_2024_12_17("o1-2024-12-17")` + The execution context that produced this tool call. - - `O1_PREVIEW("o1-preview")` + - `JsonValue;` - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + - `JsonValue; type "direct"constant` - - `O1_MINI("o1-mini")` + The caller type. Always `direct`. - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + - `DIRECT("direct")` - - `GPT_4O("gpt-4o")` + - `class Program:` - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + - `String callerId` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + The call ID of the program item that produced this tool call. - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + - `JsonValue; type "program"constant` - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + The caller type. Always `program`. - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + - `PROGRAM("program")` - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + - `Optional environment` - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + The environment to execute the shell commands in. - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + - `class BetaLocalEnvironment:` - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + - `class BetaContainerReference:` - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + - `Optional status` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `IN_PROGRESS("in_progress")` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + - `COMPLETED("completed")` - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `INCOMPLETE("incomplete")` - - `CODEX_MINI_LATEST("codex-mini-latest")` + - `ShellCallOutput` - - `GPT_4O_MINI("gpt-4o-mini")` + - `String callId` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + The unique ID of the shell tool call generated by the model. - - `GPT_4_TURBO("gpt-4-turbo")` + - `List output` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + - `Outcome outcome` - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + The exit or timeout outcome associated with this shell call. - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `JsonValue;` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + - `JsonValue; type "timeout"constant` - - `GPT_4("gpt-4")` + The outcome type. Always `timeout`. - - `GPT_4_0314("gpt-4-0314")` + - `TIMEOUT("timeout")` - - `GPT_4_0613("gpt-4-0613")` + - `class Exit:` - - `GPT_4_32K("gpt-4-32k")` + Indicates that the shell commands finished and returned an exit code. - - `GPT_4_32K_0314("gpt-4-32k-0314")` + - `long exitCode` - - `GPT_4_32K_0613("gpt-4-32k-0613")` + The exit code returned by the shell process. - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `JsonValue; type "exit"constant` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + The outcome type. Always `exit`. - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `EXIT("exit")` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `String stderr` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + Captured stderr output for the shell call. - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `String stdout` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + Captured stdout output for the shell call. - - `O1_PRO("o1-pro")` + - `JsonValue; type "shell_call_output"constant` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + The type of the item. Always `shell_call_output`. - - `O3_PRO("o3-pro")` + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `Optional id` - - `O3_DEEP_RESEARCH("o3-deep-research")` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + - `Optional agent` - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + The agent that produced this item. - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `String agentName` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + The canonical name of the agent that produced this item. - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `Optional caller` - - `GPT_5_CODEX("gpt-5-codex")` + The execution context that produced this tool call. - - `GPT_5_PRO("gpt-5-pro")` + - `JsonValue;` - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `JsonValue; type "direct"constant` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + The caller type. Always `direct`. - - `Optional input` + - `DIRECT("direct")` - Text, image, or file inputs to the model, used to generate a response + - `class Program:` - - `String` + - `String callerId` - - `List` + The call ID of the program item that produced this tool call. - - `class BetaEasyInputMessage:` + - `JsonValue; type "program"constant` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The caller type. Always `program`. - - `Content content` + - `PROGRAM("program")` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `Optional maxOutputLength` - - `String` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `List` + - `Optional status` - - `class BetaResponseInputText:` + The status of the shell call output. - A text input to the model. + - `IN_PROGRESS("in_progress")` - - `String text` + - `COMPLETED("completed")` - The text input to the model. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "input_text"constant` + - `ApplyPatchCall` - The type of the input item. Always `input_text`. + - `String callId` - - `INPUT_TEXT("input_text")` + The unique ID of the apply patch tool call generated by the model. - - `Optional promptCacheBreakpoint` + - `Operation operation` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The specific create, delete, or update instruction for the apply_patch tool call. - - `JsonValue; mode "explicit"constant` + - `class CreateFile:` - The breakpoint mode. Always `explicit`. + Instruction for creating a new file via the apply_patch tool. - - `EXPLICIT("explicit")` + - `String diff` - - `class BetaResponseInputImage:` + Unified diff content to apply when creating the file. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `String path` - - `Detail detail` + Path of the file to create relative to the workspace root. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `JsonValue; type "create_file"constant` - - `LOW("low")` + The operation type. Always `create_file`. - - `HIGH("high")` + - `CREATE_FILE("create_file")` - - `AUTO("auto")` + - `class DeleteFile:` - - `ORIGINAL("original")` + Instruction for deleting an existing file via the apply_patch tool. - - `JsonValue; type "input_image"constant` + - `String path` - The type of the input item. Always `input_image`. + Path of the file to delete relative to the workspace root. - - `INPUT_IMAGE("input_image")` + - `JsonValue; type "delete_file"constant` - - `Optional fileId` + The operation type. Always `delete_file`. - The ID of the file to be sent to the model. + - `DELETE_FILE("delete_file")` - - `Optional imageUrl` + - `class UpdateFile:` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Instruction for updating an existing file via the apply_patch tool. - - `Optional promptCacheBreakpoint` + - `String diff` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Unified diff content to apply to the existing file. - - `JsonValue; mode "explicit"constant` + - `String path` - The breakpoint mode. Always `explicit`. + Path of the file to update relative to the workspace root. - - `EXPLICIT("explicit")` + - `JsonValue; type "update_file"constant` - - `class BetaResponseInputFile:` + The operation type. Always `update_file`. - A file input to the model. + - `UPDATE_FILE("update_file")` - - `JsonValue; type "input_file"constant` + - `Status status` - The type of the input item. Always `input_file`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `INPUT_FILE("input_file")` + - `IN_PROGRESS("in_progress")` - - `Optional detail` + - `COMPLETED("completed")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `JsonValue; type "apply_patch_call"constant` - - `AUTO("auto")` + The type of the item. Always `apply_patch_call`. - - `LOW("low")` + - `APPLY_PATCH_CALL("apply_patch_call")` - - `HIGH("high")` + - `Optional id` - - `Optional fileData` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The content of the file to be sent to the model. + - `Optional agent` - - `Optional fileId` + The agent that produced this item. - The ID of the file to be sent to the model. + - `String agentName` - - `Optional fileUrl` + The canonical name of the agent that produced this item. - The URL of the file to be sent to the model. + - `Optional caller` - - `Optional filename` + The execution context that produced this tool call. - The name of the file to be sent to the model. + - `JsonValue;` - - `Optional promptCacheBreakpoint` + - `JsonValue; type "direct"constant` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The caller type. Always `direct`. - - `JsonValue; mode "explicit"constant` + - `DIRECT("direct")` - The breakpoint mode. Always `explicit`. + - `class Program:` - - `EXPLICIT("explicit")` + - `String callerId` - - `Role role` + The call ID of the program item that produced this tool call. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `JsonValue; type "program"constant` - - `USER("user")` + The caller type. Always `program`. - - `ASSISTANT("assistant")` + - `PROGRAM("program")` - - `SYSTEM("system")` + - `ApplyPatchCallOutput` - - `DEVELOPER("developer")` + - `String callId` - - `Optional phase` + The unique ID of the apply patch tool call generated by the model. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `Status status` - - `COMMENTARY("commentary")` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `Optional type` + - `COMPLETED("completed")` - The type of the message input. Always `message`. + - `FAILED("failed")` - - `MESSAGE("message")` + - `JsonValue; type "apply_patch_call_output"constant` - - `Message` + The type of the item. Always `apply_patch_call_output`. - - `List content` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - A list of one or many input items to the model, containing different content - types. + - `Optional id` - - `class BetaResponseInputText:` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A text input to the model. + - `Optional agent` - - `class BetaResponseInputImage:` + The agent that produced this item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `String agentName` - - `class BetaResponseInputFile:` + The canonical name of the agent that produced this item. - A file input to the model. + - `Optional caller` - - `Role role` + The execution context that produced this tool call. - The role of the message input. One of `user`, `system`, or `developer`. + - `JsonValue;` - - `USER("user")` + - `JsonValue; type "direct"constant` - - `SYSTEM("system")` + The caller type. Always `direct`. - - `DEVELOPER("developer")` + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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 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 annotations` + + Additional annotations about the tool. + + - `Optional 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 agent` @@ -37583,201 +53981,229 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional status` + - `Optional error` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Error message if the server could not list tools. - - `IN_PROGRESS("in_progress")` + - `McpApprovalRequest` - - `COMPLETED("completed")` + - `String id` - - `INCOMPLETE("incomplete")` + The unique ID of the approval request. - - `Optional type` + - `String arguments` - The type of the message input. Always set to `message`. + A JSON string of arguments for the tool. - - `MESSAGE("message")` + - `String name` - - `class BetaResponseOutputMessage:` + The name of the tool to run. - An output message from the model. + - `String serverLabel` - - `String id` + The label of the MCP server making the request. - The unique ID of the output message. + - `JsonValue; type "mcp_approval_request"constant` - - `List content` + The type of the item. Always `mcp_approval_request`. - The content of the output message. + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `class BetaResponseOutputText:` + - `Optional agent` - A text output from the model. + The agent that produced this item. - - `List annotations` + - `String agentName` - The annotations of the text output. + The canonical name of the agent that produced this item. - - `class FileCitation:` + - `McpApprovalResponse` - A citation to a file. + - `String approvalRequestId` - - `String fileId` + The ID of the approval request being answered. - The ID of the file. + - `boolean approve` - - `String filename` + Whether the request was approved. - The filename of the file cited. + - `JsonValue; type "mcp_approval_response"constant` - - `long index` + The type of the item. Always `mcp_approval_response`. - The index of the file in the list of files. + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `JsonValue; type "file_citation"constant` + - `Optional id` - The type of the file citation. Always `file_citation`. + The unique ID of the approval response - - `FILE_CITATION("file_citation")` + - `Optional agent` - - `class UrlCitation:` + The agent that produced this item. - A citation for a web resource used to generate a model response. + - `String agentName` - - `long endIndex` + The canonical name of the agent that produced this item. - The index of the last character of the URL citation in the message. + - `Optional reason` - - `long startIndex` + Optional reason for the decision. - The index of the first character of the URL citation in the message. + - `McpCall` - - `String title` + - `String id` - The title of the web resource. + The unique ID of the tool call. - - `JsonValue; type "url_citation"constant` + - `String arguments` - The type of the URL citation. Always `url_citation`. + A JSON string of the arguments passed to the tool. - - `URL_CITATION("url_citation")` + - `String name` - - `String url` + The name of the tool that was run. - The URL of the web resource. + - `String serverLabel` - - `class ContainerFileCitation:` + The label of the MCP server running the tool. - A citation for a container file used to generate a model response. + - `JsonValue; type "mcp_call"constant` - - `String containerId` + The type of the item. Always `mcp_call`. - The ID of the container file. + - `MCP_CALL("mcp_call")` - - `long endIndex` + - `Optional agent` - The index of the last character of the container file citation in the message. + The agent that produced this item. - - `String fileId` + - `String agentName` - The ID of the file. + The canonical name of the agent that produced this item. - - `String filename` + - `Optional approvalRequestId` - The filename of the container file cited. + 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. - - `long startIndex` + - `Optional error` - The index of the first character of the container file citation in the message. + The error from the tool call, if any. - - `JsonValue; type "container_file_citation"constant` + - `Optional output` - The type of the container file citation. Always `container_file_citation`. + The output from the tool call. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `Optional status` - - `class FilePath:` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - A path to a file. + - `IN_PROGRESS("in_progress")` - - `String fileId` + - `COMPLETED("completed")` - The ID of the file. + - `INCOMPLETE("incomplete")` - - `long index` + - `CALLING("calling")` - The index of the file in the list of files. + - `FAILED("failed")` - - `JsonValue; type "file_path"constant` + - `class BetaResponseCustomToolCallOutput:` - The type of the file path. Always `file_path`. + The output of a custom tool call from your code, being sent back to the model. - - `FILE_PATH("file_path")` + - `String callId` - - `String text` + The call ID, used to map this custom tool call output to a custom tool call. - The text output from the model. + - `Output output` - - `JsonValue; type "output_text"constant` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The type of the output text. Always `output_text`. + - `String` - - `OUTPUT_TEXT("output_text")` + - `List` - - `Optional> logprobs` + - `class BetaResponseInputText:` - - `String token` + A text input to the model. - - `List bytes` + - `class BetaResponseInputImage:` - - `double logprob` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `List topLogprobs` + - `class BetaResponseInputFile:` - - `String token` + A file input to the model. - - `List bytes` + - `JsonValue; type "custom_tool_call_output"constant` - - `double logprob` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `class BetaResponseOutputRefusal:` + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - A refusal from the model. + - `Optional id` - - `String refusal` + The unique ID of the custom tool call output in the OpenAI platform. - The refusal explanation from the model. + - `Optional agent` - - `JsonValue; type "refusal"constant` + The agent that produced this item. - The type of the refusal. Always `refusal`. + - `String agentName` - - `REFUSAL("refusal")` + The canonical name of the agent that produced this item. - - `JsonValue; role "assistant"constant` + - `Optional caller` - The role of the output message. Always `assistant`. + The execution context that produced this tool call. - - `ASSISTANT("assistant")` + - `JsonValue;` - - `Status status` + - `JsonValue; type "direct"constant` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The caller type. Always `direct`. - - `IN_PROGRESS("in_progress")` + - `DIRECT("direct")` - - `COMPLETED("completed")` + - `class Program:` - - `INCOMPLETE("incomplete")` + - `String callerId` - - `JsonValue; type "message"constant` + The call ID of the program item that produced this tool call. - The type of the output message. Always `message`. + - `JsonValue; type "program"constant` - - `MESSAGE("message")` + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `class BetaResponseCustomToolCall:` + + 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 id` + + The unique ID of the custom tool call in the OpenAI platform. - `Optional agent` @@ -37787,47 +54213,89 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional phase` + - `Optional caller` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The execution context that produced this tool call. - - `COMMENTARY("commentary")` + - `JsonValue;` - - `class BetaResponseFileSearchToolCall:` + - `JsonValue; type "direct"constant` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the custom tool being called. + + - `CompactionTrigger` + + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` - `String id` - The unique ID of the file search tool call. + The ID of the item to reference. - - `List queries` + - `Optional agent` - The queries used to search for files. + The agent that produced this item. - - `Status status` + - `String agentName` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The canonical name of the agent that produced this item. - - `IN_PROGRESS("in_progress")` + - `Optional type` - - `SEARCHING("searching")` + The type of item to reference. Always `item_reference`. - - `COMPLETED("completed")` + - `ITEM_REFERENCE("item_reference")` - - `INCOMPLETE("incomplete")` + - `Program` - - `FAILED("failed")` + - `String id` - - `JsonValue; type "file_search_call"constant` + The unique ID of this program item. - The type of the file search tool call. Always `file_search_call`. + - `String callId` - - `FILE_SEARCH_CALL("file_search_call")` + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The item type. Always `program`. + + - `PROGRAM("program")` - `Optional agent` @@ -37837,285 +54305,326 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional> results` + - `ProgramOutput` - The results of the file search tool call. + - `String id` - - `Optional attributes` + The unique ID of this program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The item type. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional 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, booleans, or numbers. + format, and querying for objects via API or the dashboard. - - `String` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `double` + - `Model model` - - `boolean` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `Optional fileId` + - `GPT_5_6_SOL("gpt-5.6-sol")` - The unique ID of the file. + - `GPT_5_6_TERRA("gpt-5.6-terra")` - - `Optional filename` + - `GPT_5_6_LUNA("gpt-5.6-luna")` - The name of the file. + - `GPT_5_4("gpt-5.4")` - - `Optional score` + - `GPT_5_4_MINI("gpt-5.4-mini")` - The relevance score of the file - a value between 0 and 1. + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `Optional text` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - The text that was retrieved from the file. + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - `class BetaResponseComputerToolCall:` + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `GPT_5_2("gpt-5.2")` - - `String id` + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - The unique ID of the computer call. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - `String callId` + - `GPT_5_2_PRO("gpt-5.2-pro")` - An identifier used when responding to the tool call with output. + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `List pendingSafetyChecks` + - `GPT_5_1("gpt-5.1")` - The pending safety checks for the computer call. + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - `String id` + - `GPT_5_1_CODEX("gpt-5.1-codex")` - The ID of the pending safety check. + - `GPT_5_1_MINI("gpt-5.1-mini")` - - `Optional code` + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - The type of the pending safety check. + - `GPT_5("gpt-5")` - - `Optional message` + - `GPT_5_MINI("gpt-5-mini")` - Details about the pending safety check. + - `GPT_5_NANO("gpt-5-nano")` - - `Status status` + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `IN_PROGRESS("in_progress")` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - `COMPLETED("completed")` + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `INCOMPLETE("incomplete")` + - `GPT_4_1("gpt-4.1")` - - `Type type` + - `GPT_4_1_MINI("gpt-4.1-mini")` - The type of the computer call. Always `computer_call`. + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `COMPUTER_CALL("computer_call")` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - `Optional action` + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - A click action. + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - - `Click` + - `O4_MINI("o4-mini")` - - `Button button` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `O3("o3")` - - `LEFT("left")` + - `O3_2025_04_16("o3-2025-04-16")` - - `RIGHT("right")` + - `O3_MINI("o3-mini")` - - `WHEEL("wheel")` + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - `BACK("back")` + - `O1("o1")` - - `FORWARD("forward")` + - `O1_2024_12_17("o1-2024-12-17")` - - `JsonValue; type "click"constant` + - `O1_PREVIEW("o1-preview")` - Specifies the event type. For a click action, this property is always `click`. + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - - `CLICK("click")` + - `O1_MINI("o1-mini")` - - `long x` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - The x-coordinate where the click occurred. + - `GPT_4O("gpt-4o")` - - `long y` + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - The y-coordinate where the click occurred. + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - `Optional> keys` + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - The keys being held while clicking. + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - `DoubleClick` + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - `Optional> keys` + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - The keys being held while double-clicking. + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - - `JsonValue; type "double_click"constant` + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - `DOUBLE_CLICK("double_click")` + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `long x` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - The x-coordinate where the double click occurred. + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - - `long y` + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - The y-coordinate where the double click occurred. + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - `Drag` + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `List path` + - `GPT_4O_MINI("gpt-4o-mini")` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `GPT_4_TURBO("gpt-4-turbo")` - - `long x` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - The x-coordinate. + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `long y` + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - The y-coordinate. + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - - `JsonValue; type "drag"constant` + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `GPT_4("gpt-4")` - - `DRAG("drag")` + - `GPT_4_0314("gpt-4-0314")` - - `Optional> keys` + - `GPT_4_0613("gpt-4-0613")` - The keys being held while dragging the mouse. + - `GPT_4_32K("gpt-4-32k")` - - `Keypress` + - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `List keys` + - `GPT_4_32K_0613("gpt-4-32k-0613")` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - - `JsonValue; type "keypress"constant` + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - - `KEYPRESS("keypress")` + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `Move` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - - `JsonValue; type "move"constant` + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - Specifies the event type. For a move action, this property is always set to `move`. + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - - `MOVE("move")` + - `O1_PRO("o1-pro")` - - `long x` + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - The x-coordinate to move to. + - `O3_PRO("o3-pro")` - - `long y` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - The y-coordinate to move to. + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `Optional> keys` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - The keys being held while moving the mouse. + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - - `JsonValue;` + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - - `JsonValue; type "screenshot"constant` + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - - `SCREENSHOT("screenshot")` + - `GPT_5_CODEX("gpt-5-codex")` - - `Scroll` + - `GPT_5_PRO("gpt-5-pro")` - - `long scrollX` + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - The horizontal scroll distance. + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - - `long scrollY` + - `JsonValue; object_ "response"constant` - The vertical scroll distance. + The object type of this resource - always set to `response`. - - `JsonValue; type "scroll"constant` + - `RESPONSE("response")` + + - `List output` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `class BetaResponseOutputMessage:` - - `SCROLL("scroll")` + An output message from the model. - - `long x` + - `class BetaResponseFileSearchToolCall:` - The x-coordinate where the scroll occurred. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `long y` + - `class BetaResponseFunctionToolCall:` - The y-coordinate where the scroll occurred. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `Optional> keys` + - `class BetaResponseFunctionToolCallOutputItem:` - The keys being held while scrolling. + - `String id` - - `Type` + The unique ID of the function call tool output. - - `String text` + - `String callId` - The text to type. + The unique ID of the function tool call generated by the model. - - `JsonValue; type "type"constant` + - `Output output` - Specifies the event type. For a type action, this property is always set to `type`. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `TYPE("type")` + - `String` - - `JsonValue;` + - `List` - - `JsonValue; type "wait"constant` + - `class BetaResponseInputText:` - Specifies the event type. For a wait action, this property is always set to `wait`. + A text input to the model. - - `WAIT("wait")` + - `class BetaResponseInputImage:` - - `Optional> actions` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `class BetaResponseInputFile:` - - `Click` + A file input to the model. - - `DoubleClick` + - `Status status` - - `Drag` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Keypress` + - `IN_PROGRESS("in_progress")` - - `Move` + - `COMPLETED("completed")` - - `JsonValue;` + - `INCOMPLETE("incomplete")` - - `Scroll` + - `JsonValue; type "function_call_output"constant` - - `Type` + The type of the function tool call output. Always `function_call_output`. - - `JsonValue;` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional agent` @@ -38125,170 +54634,169 @@ Compact a response The canonical name of the agent that produced this item. - - `ComputerCallOutput` + - `Optional caller` - - `String callId` + The execution context that produced this tool call. - The ID of the computer tool call that produced the output. + - `JsonValue;` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `JsonValue; type "direct"constant` - A computer screenshot image used with the computer use tool. + The caller type. Always `direct`. - - `JsonValue; type "computer_screenshot"constant` + - `DIRECT("direct")` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `class Program:` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `String callerId` - - `Optional fileId` + The call ID of the program item that produced this tool call. - The identifier of an uploaded file that contains the screenshot. + - `JsonValue; type "program"constant` - - `Optional imageUrl` + The caller type. Always `program`. - The URL of the screenshot image. + - `PROGRAM("program")` - - `JsonValue; type "computer_call_output"constant` + - `Optional createdBy` - The type of the computer tool call output. Always `computer_call_output`. + The identifier of the actor that created the item. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `AgentMessage` - - `Optional id` + - `String id` - The ID of the computer tool call output. + The unique ID of the agent message. - - `Optional> acknowledgedSafetyChecks` + - `String author` - The safety checks reported by the API that have been acknowledged by the developer. + The sending agent identity. - - `String id` + - `List content` - The ID of the pending safety check. + Encrypted content sent between agents. - - `Optional code` + - `class BetaResponseInputText:` - The type of the pending safety check. + A text input to the model. - - `Optional message` + - `class BetaResponseOutputText:` - Details about the pending safety check. + A text output from the model. - - `Optional agent` + - `class Text:` - The agent that produced this item. + A text content. - - `String agentName` + - `String text` - The canonical name of the agent that produced this item. + - `JsonValue; type "text"constant` - - `Optional status` + - `TEXT("text")` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `class SummaryText:` - - `IN_PROGRESS("in_progress")` + A summary text from the model. - - `COMPLETED("completed")` + - `String text` - - `INCOMPLETE("incomplete")` + A summary of the reasoning output from the model so far. - - `class BetaResponseFunctionWebSearch:` + - `JsonValue; type "summary_text"constant` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The type of the object. Always `summary_text`. - - `String id` + - `SUMMARY_TEXT("summary_text")` - The unique ID of the web search tool call. + - `class ReasoningText:` - - `Action action` + Reasoning text from the model. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `String text` - - `class Search:` + The reasoning text from the model. - Action type "search" - Performs a web search query. + - `JsonValue; type "reasoning_text"constant` - - `JsonValue; type "search"constant` + The type of the reasoning text. Always `reasoning_text`. - The action type. + - `REASONING_TEXT("reasoning_text")` - - `SEARCH("search")` + - `class BetaResponseOutputRefusal:` - - `Optional> queries` + A refusal from the model. - The search queries. + - `class BetaResponseInputImage:` - - `Optional query` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The search query. + - `class ComputerScreenshot:` - - `Optional> sources` + A screenshot of a computer. - The sources used in the search. + - `Detail detail` - - `JsonValue; type "url"constant` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of source. Always `url`. + - `LOW("low")` - - `URL("url")` + - `HIGH("high")` - - `String url` + - `AUTO("auto")` - The URL of the source. + - `ORIGINAL("original")` - - `class OpenPage:` + - `Optional fileId` - Action type "open_page" - Opens a specific URL from search results. + The identifier of an uploaded file that contains the screenshot. - - `JsonValue; type "open_page"constant` + - `Optional imageUrl` - The action type. + The URL of the screenshot image. - - `OPEN_PAGE("open_page")` + - `JsonValue; type "computer_screenshot"constant` - - `Optional url` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The URL opened by the model. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `class FindInPage:` + - `Optional promptCacheBreakpoint` - Action type "find_in_page": Searches for a pattern within a loaded page. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String pattern` + - `JsonValue; mode "explicit"constant` - The pattern or text to search for within the page. + The breakpoint mode. Always `explicit`. - - `JsonValue; type "find_in_page"constant` + - `EXPLICIT("explicit")` - The action type. + - `class BetaResponseInputFile:` - - `FIND_IN_PAGE("find_in_page")` + A file input to the model. - - `String url` + - `class EncryptedContent:` - The URL of the page searched for the pattern. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `Status status` + - `String encryptedContent` - The status of the web search tool call. + Opaque encrypted content. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "encrypted_content"constant` - - `SEARCHING("searching")` + The type of the input item. Always `encrypted_content`. - - `COMPLETED("completed")` + - `ENCRYPTED_CONTENT("encrypted_content")` - - `FAILED("failed")` + - `String recipient` - - `JsonValue; type "web_search_call"constant` + The destination agent identity. - The type of the web search tool call. Always `web_search_call`. + - `JsonValue; type "agent_message"constant` - - `WEB_SEARCH_CALL("web_search_call")` + The type of the item. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` - `Optional agent` @@ -38298,209 +54806,210 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall:` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - - `String arguments` + - `MultiAgentCall` - A JSON string of the arguments to pass to the function. + - `String id` - - `String callId` + The unique ID of the multi-agent call item. - The unique ID of the function tool call generated by the model. + - `Action action` - - `String name` + The multi-agent action to execute. - The name of the function to run. + - `SPAWN_AGENT("spawn_agent")` - - `JsonValue; type "function_call"constant` + - `INTERRUPT_AGENT("interrupt_agent")` - The type of the function tool call. Always `function_call`. + - `LIST_AGENTS("list_agents")` - - `FUNCTION_CALL("function_call")` + - `SEND_MESSAGE("send_message")` - - `Optional id` + - `FOLLOWUP_TASK("followup_task")` - The unique ID of the function tool call. + - `WAIT_AGENT("wait_agent")` - - `Optional agent` + - `String arguments` - The agent that produced this item. + The JSON string of arguments generated for the action. - - `String agentName` + - `String callId` - The canonical name of the agent that produced this item. + The unique ID linking this call to its output. - - `Optional caller` + - `JsonValue; type "multi_agent_call"constant` - The execution context that produced this tool call. + The type of the multi-agent call. Always `multi_agent_call`. - - `JsonValue;` + - `MULTI_AGENT_CALL("multi_agent_call")` - - `JsonValue; type "direct"constant` + - `Optional agent` - - `DIRECT("direct")` + The agent that produced this item. - - `class Program:` + - `String agentName` - - `String callerId` + The canonical name of the agent that produced this item. - The call ID of the program item that produced this tool call. + - `MultiAgentCallOutput` - - `JsonValue; type "program"constant` + - `String id` - - `PROGRAM("program")` + The unique ID of the multi-agent call output item. - - `Optional namespace` + - `Action action` - The namespace of the function to run. + The multi-agent action that produced this result. - - `Optional status` + - `SPAWN_AGENT("spawn_agent")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `INTERRUPT_AGENT("interrupt_agent")` - - `IN_PROGRESS("in_progress")` + - `LIST_AGENTS("list_agents")` - - `COMPLETED("completed")` + - `SEND_MESSAGE("send_message")` - - `INCOMPLETE("incomplete")` + - `FOLLOWUP_TASK("followup_task")` - - `FunctionCallOutput` + - `WAIT_AGENT("wait_agent")` - `String callId` - The unique ID of the function tool call generated by the model. + The unique ID of the multi-agent call. - - `Output output` + - `List output` - Text, image, or file output of the function tool call. + Text output returned by the multi-agent action. - - `String` + - `List annotations` - - `List` + The annotations of the text output. - - `class BetaResponseInputTextContent:` + - `String text` - A text input to the model. + The text output from the model. - - `String text` + - `JsonValue; type "output_text"constant` - The text input to the model. + The type of the output text. Always `output_text`. - - `JsonValue; type "input_text"constant` + - `Optional> logprobs` - The type of the input item. Always `input_text`. + - `JsonValue; type "multi_agent_call_output"constant` - - `INPUT_TEXT("input_text")` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `Optional promptCacheBreakpoint` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional agent` - - `JsonValue; mode "explicit"constant` + The agent that produced this item. - The breakpoint mode. Always `explicit`. + - `String agentName` - - `EXPLICIT("explicit")` + The canonical name of the agent that produced this item. - - `class BetaResponseInputImageContent:` + - `class BetaResponseFunctionWebSearch:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `JsonValue; type "input_image"constant` + - `class BetaResponseComputerToolCall:` - The type of the input item. Always `input_image`. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `INPUT_IMAGE("input_image")` + - `class BetaResponseComputerToolCallOutputItem:` - - `Optional detail` + - `String id` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The unique ID of the computer call tool output. - - `LOW("low")` + - `String callId` - - `HIGH("high")` + The ID of the computer tool call that produced the output. - - `AUTO("auto")` + - `BetaResponseComputerToolCallOutputScreenshot output` - - `ORIGINAL("original")` + A computer screenshot image used with the computer use tool. - - `Optional fileId` + - `Status status` - The ID of the file to be sent to the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `Optional imageUrl` + - `COMPLETED("completed")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `INCOMPLETE("incomplete")` - - `Optional promptCacheBreakpoint` + - `FAILED("failed")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `IN_PROGRESS("in_progress")` - - `JsonValue; mode "explicit"constant` + - `JsonValue; type "computer_call_output"constant` - The breakpoint mode. Always `explicit`. + The type of the computer tool call output. Always `computer_call_output`. - - `EXPLICIT("explicit")` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `class BetaResponseInputFileContent:` + - `Optional> acknowledgedSafetyChecks` - A file input to the model. + The safety checks reported by the API that have been acknowledged by the + developer. - - `JsonValue; type "input_file"constant` + - `String id` - The type of the input item. Always `input_file`. + The ID of the pending safety check. - - `INPUT_FILE("input_file")` + - `Optional code` - - `Optional detail` + The type of the pending safety check. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `Optional message` - - `AUTO("auto")` + Details about the pending safety check. - - `LOW("low")` + - `Optional agent` - - `HIGH("high")` + The agent that produced this item. - - `Optional fileData` + - `String agentName` - The base64-encoded data of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `Optional fileId` + - `Optional createdBy` - The ID of the file to be sent to the model. + The identifier of the actor that created the item. - - `Optional fileUrl` + - `class BetaResponseReasoningItem:` - The URL of the file to be sent to the model. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `Optional filename` + - `Program` - The name of the file to be sent to the model. + - `String id` - - `Optional promptCacheBreakpoint` + The unique ID of the program item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String callId` - - `JsonValue; mode "explicit"constant` + The stable call ID of the program item. - The breakpoint mode. Always `explicit`. + - `String code` - - `EXPLICIT("explicit")` + The JavaScript source executed by programmatic tool calling. - - `JsonValue; type "function_call_output"constant` + - `String fingerprint` - The type of the function tool call output. Always `function_call_output`. + Opaque program replay fingerprint that must be round-tripped. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `JsonValue; type "program"constant` - - `Optional id` + The type of the item. Always `program`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `PROGRAM("program")` - `Optional agent` @@ -38510,85 +55019,79 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` + - `ProgramOutput` - The caller type. Always `direct`. + - `String id` - - `DIRECT("direct")` + The unique ID of the program output item. - - `class Program:` + - `String callId` - - `String callerId` + The call ID of the program item. - The call ID of the program item that produced this tool call. + - `String result` - - `JsonValue; type "program"constant` + The result produced by the program item. - The caller type. Always `program`. + - `Status status` - - `PROGRAM("program")` + The terminal status of the program output item. - - `Optional status` + - `COMPLETED("completed")` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `INCOMPLETE("incomplete")` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "program_output"constant` - - `COMPLETED("completed")` + The type of the item. Always `program_output`. - - `INCOMPLETE("incomplete")` + - `PROGRAM_OUTPUT("program_output")` - - `AgentMessage` + - `Optional agent` - - `String author` + The agent that produced this item. - The sending agent identity. + - `String agentName` - - `List content` + The canonical name of the agent that produced this item. - Plaintext, image, or encrypted content sent between agents. + - `class BetaResponseToolSearchCall:` - - `class BetaResponseInputTextContent:` + - `String id` - A text input to the model. + The unique ID of the tool search call item. - - `class BetaResponseInputImageContent:` + - `JsonValue arguments` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + Arguments used for the tool search call. - - `class EncryptedContent:` + - `Optional callId` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The unique ID of the tool search call generated by the model. - - `String encryptedContent` + - `Execution execution` - Opaque encrypted content. + Whether tool search was executed by the server or by the client. - - `JsonValue; type "encrypted_content"constant` + - `SERVER("server")` - The type of the input item. Always `encrypted_content`. + - `CLIENT("client")` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `Status status` - - `String recipient` + The status of the tool search call item that was recorded. - The destination agent identity. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "agent_message"constant` + - `COMPLETED("completed")` - The item type. Always `agent_message`. + - `INCOMPLETE("incomplete")` - - `AGENT_MESSAGE("agent_message")` + - `JsonValue; type "tool_search_call"constant` - - `Optional id` + The type of the item. Always `tool_search_call`. - The unique ID of this agent message item. + - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional agent` @@ -38598,1753 +55101,1765 @@ Compact a response The canonical name of the agent that produced this item. - - `MultiAgentCall` - - - `Action action` - - The multi-agent action that was executed. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` - - - `SEND_MESSAGE("send_message")` - - - `FOLLOWUP_TASK("followup_task")` - - - `WAIT_AGENT("wait_agent")` - - - `String arguments` - - The action arguments as a JSON string. - - - `String callId` + - `Optional createdBy` - The unique ID linking this call to its output. + The identifier of the actor that created the item. - - `JsonValue; type "multi_agent_call"constant` + - `class BetaResponseToolSearchOutputItem:` - The item type. Always `multi_agent_call`. + - `String id` - - `MULTI_AGENT_CALL("multi_agent_call")` + The unique ID of the tool search output item. - - `Optional id` + - `Optional callId` - The unique ID of this multi-agent call. + The unique ID of the tool search call generated by the model. - - `Optional agent` + - `Execution execution` - The agent that produced this item. + Whether tool search was executed by the server or by the client. - - `String agentName` + - `SERVER("server")` - The canonical name of the agent that produced this item. + - `CLIENT("client")` - - `MultiAgentCallOutput` + - `Status status` - - `Action action` + The status of the tool search output item that was recorded. - The multi-agent action that produced this result. + - `IN_PROGRESS("in_progress")` - - `SPAWN_AGENT("spawn_agent")` + - `COMPLETED("completed")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `INCOMPLETE("incomplete")` - - `LIST_AGENTS("list_agents")` + - `List tools` - - `SEND_MESSAGE("send_message")` + The loaded tool definitions returned by tool search. - - `FOLLOWUP_TASK("followup_task")` + - `class BetaFunctionTool:` - - `WAIT_AGENT("wait_agent")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String callId` + - `class BetaFileSearchTool:` - The unique ID of the multi-agent call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `List output` + - `class BetaComputerTool:` - Text output returned by the multi-agent action. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String text` + - `class BetaComputerUsePreviewTool:` - The text content. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; type "output_text"constant` + - `class BetaWebSearchTool:` - The content type. Always `output_text`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `OUTPUT_TEXT("output_text")` + - `Mcp` - - `Optional annotations` + - `CodeInterpreter` - Citations associated with the text content. + - `JsonValue;` - - `List` + - `ImageGeneration` - - `String fileId` + - `JsonValue;` - The ID of the file. + - `class BetaFunctionShellTool:` - - `String filename` + A tool that allows the model to execute shell commands. - The filename of the file cited. + - `class BetaCustomTool:` - - `long index` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The index of the file in the list of files. + - `class BetaNamespaceTool:` - - `JsonValue; type "file_citation"constant` + Groups function/custom tools under a shared namespace. - The citation type. Always `file_citation`. + - `class BetaToolSearchTool:` - - `FILE_CITATION("file_citation")` + Hosted or BYOT tool search configuration for deferred tools. - - `List` + - `class BetaWebSearchPreviewTool:` - - `long endIndex` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The index of the last character of the citation in the message. + - `class BetaApplyPatchTool:` - - `long startIndex` + Allows the assistant to create, delete, or update files using unified diffs. - The index of the first character of the citation in the message. + - `JsonValue; type "tool_search_output"constant` - - `String title` + The type of the item. Always `tool_search_output`. - The title of the cited resource. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `JsonValue; type "url_citation"constant` + - `Optional agent` - The citation type. Always `url_citation`. + The agent that produced this item. - - `URL_CITATION("url_citation")` + - `String agentName` - - `String url` + The canonical name of the agent that produced this item. - The URL of the cited resource. + - `Optional createdBy` - - `List` + The identifier of the actor that created the item. - - `String containerId` + - `AdditionalTools` - The ID of the container. + - `String id` - - `long endIndex` + The unique ID of the additional tools item. - The index of the last character of the citation in the message. + - `Role role` - - `String fileId` + The role that provided the additional tools. - The ID of the container file. + - `UNKNOWN("unknown")` - - `String filename` + - `USER("user")` - The filename of the container file cited. + - `ASSISTANT("assistant")` - - `long startIndex` + - `SYSTEM("system")` - The index of the first character of the citation in the message. + - `CRITIC("critic")` - - `JsonValue; type "container_file_citation"constant` + - `DISCRIMINATOR("discriminator")` - The citation type. Always `container_file_citation`. + - `DEVELOPER("developer")` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `TOOL("tool")` - - `JsonValue; type "multi_agent_call_output"constant` + - `List tools` - The item type. Always `multi_agent_call_output`. + The additional tool definitions made available at this item. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `class BetaFunctionTool:` - - `Optional id` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The unique ID of this multi-agent call output. + - `class BetaFileSearchTool:` - - `Optional agent` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The agent that produced this item. + - `class BetaComputerTool:` - - `String agentName` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The canonical name of the agent that produced this item. + - `class BetaComputerUsePreviewTool:` - - `ToolSearchCall` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue arguments` + - `class BetaWebSearchTool:` - The arguments supplied to the tool search call. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue; type "tool_search_call"constant` + - `Mcp` - The item type. Always `tool_search_call`. + - `CodeInterpreter` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `JsonValue;` - - `Optional id` + - `ImageGeneration` - The unique ID of this tool search call. + - `JsonValue;` - - `Optional agent` + - `class BetaFunctionShellTool:` - The agent that produced this item. + A tool that allows the model to execute shell commands. - - `String agentName` + - `class BetaCustomTool:` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional callId` + - `class BetaNamespaceTool:` - The unique ID of the tool search call generated by the model. + Groups function/custom tools under a shared namespace. - - `Optional execution` + - `class BetaToolSearchTool:` - Whether tool search was executed by the server or by the client. + Hosted or BYOT tool search configuration for deferred tools. - - `SERVER("server")` + - `class BetaWebSearchPreviewTool:` - - `CLIENT("client")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional status` + - `class BetaApplyPatchTool:` - The status of the tool search call. + Allows the assistant to create, delete, or update files using unified diffs. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "additional_tools"constant` - - `COMPLETED("completed")` + The type of the item. Always `additional_tools`. - - `INCOMPLETE("incomplete")` + - `ADDITIONAL_TOOLS("additional_tools")` - - `class BetaResponseToolSearchOutputItemParam:` + - `Optional agent` - - `List tools` + The agent that produced this item. - The loaded tool definitions returned by the tool search output. + - `String agentName` - - `class BetaFunctionTool:` + The canonical name of the agent that produced this item. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class BetaResponseCompactionItem:` - - `String name` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The name of the function to call. + - `String id` - - `Optional parameters` + The unique ID of the compaction item. - A JSON schema object describing the parameters of the function. + - `String encryptedContent` - - `Optional strict` + The encrypted content that was produced by compaction. - Whether strict parameter validation is enforced for this function tool. + - `JsonValue; type "compaction"constant` - - `JsonValue; type "function"constant` + The type of the item. Always `compaction`. - The type of the function tool. Always `function`. + - `COMPACTION("compaction")` - - `FUNCTION("function")` + - `Optional agent` - - `Optional> allowedCallers` + The agent that produced this item. - The tool invocation context(s). + - `String agentName` - - `DIRECT("direct")` + The canonical name of the agent that produced this item. - - `PROGRAMMATIC("programmatic")` + - `Optional createdBy` - - `Optional deferLoading` + The identifier of the actor that created the item. - Whether this function is deferred and loaded via tool search. + - `ImageGenerationCall` - - `Optional description` + - `String id` - A description of the function. Used by the model to determine whether or not to call the function. + The unique ID of the image generation call. - - `Optional outputSchema` + - `Optional result` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The generated image encoded in base64. - - `class BetaFileSearchTool:` + - `Status status` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The status of the image generation call. - - `JsonValue; type "file_search"constant` + - `IN_PROGRESS("in_progress")` - The type of the file search tool. Always `file_search`. + - `COMPLETED("completed")` - - `FILE_SEARCH("file_search")` + - `GENERATING("generating")` - - `List vectorStoreIds` + - `FAILED("failed")` - The IDs of the vector stores to search. + - `JsonValue; type "image_generation_call"constant` - - `Optional filters` + The type of the image generation call. Always `image_generation_call`. - A filter to apply. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `class ComparisonFilter:` + - `Optional agent` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The agent that produced this item. - - `String key` + - `String agentName` - The key to compare against the value. + The canonical name of the agent that produced this item. - - `Type type` + - `class BetaResponseCodeInterpreterToolCall:` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A tool call to run code. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `LocalShellCall` - - `EQ("eq")` + - `String id` - - `NE("ne")` + The unique ID of the local shell call. - - `GT("gt")` + - `Action action` - - `GTE("gte")` + Execute a shell command on the server. - - `LT("lt")` + - `List command` - - `LTE("lte")` + The command to run. - - `IN("in")` + - `Env env` - - `NIN("nin")` + Environment variables to set for the command. - - `Value value` + - `JsonValue; type "exec"constant` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of the local shell action. Always `exec`. - - `String` + - `EXEC("exec")` - - `double` + - `Optional timeoutMs` - - `boolean` + Optional timeout in milliseconds for the command. - - `List` + - `Optional user` - - `class CompoundFilter:` + Optional user to run the command as. - Combine multiple filters using `and` or `or`. + - `Optional workingDirectory` - - `List filters` + Optional working directory to run the command in. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `String callId` - - `class ComparisonFilter:` + The unique ID of the local shell tool call generated by the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `Status status` - - `String key` + The status of the local shell call. - The key to compare against the value. + - `IN_PROGRESS("in_progress")` - - `Type type` + - `COMPLETED("completed")` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `INCOMPLETE("incomplete")` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `JsonValue; type "local_shell_call"constant` - - `EQ("eq")` + The type of the local shell call. Always `local_shell_call`. - - `NE("ne")` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `GT("gt")` + - `Optional agent` - - `GTE("gte")` + The agent that produced this item. - - `LT("lt")` + - `String agentName` - - `LTE("lte")` + The canonical name of the agent that produced this item. - - `IN("in")` + - `LocalShellCallOutput` - - `NIN("nin")` + - `String id` - - `Value value` + The unique ID of the local shell tool call generated by the model. - The value to compare against the attribute key; supports string, number, or boolean types. + - `String output` - - `String` + A JSON string of the output of the local shell tool call. - - `double` + - `JsonValue; type "local_shell_call_output"constant` - - `boolean` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `List` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `JsonValue` + - `Optional agent` - - `Type type` + The agent that produced this item. - Type of operation: `and` or `or`. + - `String agentName` - - `AND("and")` + The canonical name of the agent that produced this item. - - `OR("or")` + - `Optional status` - - `Optional maxNumResults` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `IN_PROGRESS("in_progress")` - - `Optional rankingOptions` + - `COMPLETED("completed")` - Ranking options for search. + - `INCOMPLETE("incomplete")` - - `Optional hybridSearch` + - `class BetaResponseFunctionShellToolCall:` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + A tool call that executes one or more shell commands in a managed environment. - - `double embeddingWeight` + - `String id` - The weight of the embedding in the reciprocal ranking fusion. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `double textWeight` + - `Action action` - The weight of the text in the reciprocal ranking fusion. + The shell commands and limits that describe how to run the tool call. - - `Optional ranker` + - `List commands` - The ranker to use for the file search. + - `Optional maxOutputLength` - - `AUTO("auto")` + Optional maximum number of characters to return from each command. - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `Optional timeoutMs` - - `Optional scoreThreshold` + Optional timeout in milliseconds for the commands. - 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. + - `String callId` - - `class BetaComputerTool:` + The unique ID of the shell tool call generated by the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional environment` - - `JsonValue; type "computer"constant` + Represents the use of a local environment to perform shell actions. - The type of the computer tool. Always `computer`. + - `class BetaResponseLocalEnvironment:` - - `COMPUTER("computer")` + Represents the use of a local environment to perform shell actions. - - `class BetaComputerUsePreviewTool:` + - `JsonValue; type "local"constant` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The environment type. Always `local`. - - `long displayHeight` + - `LOCAL("local")` - The height of the computer display. + - `class BetaResponseContainerReference:` - - `long displayWidth` + Represents a container created with /v1/containers. - The width of the computer display. + - `String containerId` - - `Environment environment` + - `JsonValue; type "container_reference"constant` - The type of computer environment to control. + The environment type. Always `container_reference`. - - `WINDOWS("windows")` + - `CONTAINER_REFERENCE("container_reference")` - - `MAC("mac")` + - `Status status` - - `LINUX("linux")` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `UBUNTU("ubuntu")` + - `IN_PROGRESS("in_progress")` - - `BROWSER("browser")` + - `COMPLETED("completed")` - - `JsonValue; type "computer_use_preview"constant` + - `INCOMPLETE("incomplete")` - The type of the computer use tool. Always `computer_use_preview`. + - `JsonValue; type "shell_call"constant` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The type of the item. Always `shell_call`. - - `class BetaWebSearchTool:` + - `SHELL_CALL("shell_call")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional agent` - - `Type type` + The agent that produced this item. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `String agentName` - - `WEB_SEARCH("web_search")` + The canonical name of the agent that produced this item. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `Optional caller` - - `Optional filters` + The execution context that produced this tool call. - Filters for the search. + - `JsonValue;` - - `Optional> allowedDomains` + - `JsonValue; type "direct"constant` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `DIRECT("direct")` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `class Program:` - - `Optional searchContextSize` + - `String callerId` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The call ID of the program item that produced this tool call. - - `LOW("low")` + - `JsonValue; type "program"constant` - - `MEDIUM("medium")` + - `PROGRAM("program")` - - `HIGH("high")` + - `Optional createdBy` - - `Optional userLocation` + The ID of the entity that created this tool call. - The approximate location of the user. + - `class BetaResponseFunctionShellToolCallOutput:` - - `Optional city` + The output of a shell tool call that was emitted. - Free text input for the city of the user, e.g. `San Francisco`. + - `String id` - - `Optional country` + The unique ID of the shell call output. Populated when this item is returned via API. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `String callId` - - `Optional region` + The unique ID of the shell tool call generated by the model. - Free text input for the region of the user, e.g. `California`. + - `Optional maxOutputLength` - - `Optional timezone` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `List output` - - `Optional type` + An array of shell call output contents - The type of location approximation. Always `approximate`. + - `Outcome outcome` - - `APPROXIMATE("approximate")` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `Mcp` + - `JsonValue;` - - `String serverLabel` + - `JsonValue; type "timeout"constant` - A label for this MCP server, used to identify it in tool calls. + The outcome type. Always `timeout`. - - `JsonValue; type "mcp"constant` + - `TIMEOUT("timeout")` - The type of the MCP tool. Always `mcp`. + - `class Exit:` - - `MCP("mcp")` + Indicates that the shell commands finished and returned an exit code. - - `Optional> allowedCallers` + - `long exitCode` - The tool invocation context(s). + Exit code from the shell process. - - `DIRECT("direct")` + - `JsonValue; type "exit"constant` - - `PROGRAMMATIC("programmatic")` + The outcome type. Always `exit`. - - `Optional allowedTools` + - `EXIT("exit")` - List of allowed tool names or a filter object. + - `String stderr` - - `List` + The standard error output that was captured. - - `class McpToolFilter:` + - `String stdout` - A filter object to specify which tools are allowed. + The standard output that was captured. - - `Optional readOnly` + - `Optional createdBy` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The identifier of the actor that created the item. - - `Optional> toolNames` + - `Status status` - List of allowed tool names. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `Optional authorization` + - `IN_PROGRESS("in_progress")` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `COMPLETED("completed")` - - `Optional connectorId` + - `INCOMPLETE("incomplete")` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `JsonValue; type "shell_call_output"constant` - Currently supported `connector_id` values are: + The type of the shell call output. Always `shell_call_output`. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `Optional agent` - - `CONNECTOR_GMAIL("connector_gmail")` + The agent that produced this item. - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `String agentName` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + The canonical name of the agent that produced this item. - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `Optional caller` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + The execution context that produced this tool call. - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `JsonValue;` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `JsonValue; type "direct"constant` - - `Optional deferLoading` + - `DIRECT("direct")` - Whether this MCP tool is deferred and discovered via tool search. + - `class Program:` - - `Optional headers` + - `String callerId` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The call ID of the program item that produced this tool call. - - `Optional requireApproval` + - `JsonValue; type "program"constant` - Specify which of the MCP server's tools require approval. + - `PROGRAM("program")` - - `class McpToolApprovalFilter:` + - `Optional createdBy` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The identifier of the actor that created the item. - - `Optional always` + - `class BetaResponseApplyPatchToolCall:` - A filter object to specify which tools are allowed. + A tool call that applies file diffs by creating, deleting, or updating files. - - `Optional readOnly` + - `String id` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `Optional> toolNames` + - `String callId` - List of allowed tool names. + The unique ID of the apply patch tool call generated by the model. - - `Optional never` + - `Operation operation` - A filter object to specify which tools are allowed. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `Optional readOnly` + - `class CreateFile:` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Instruction describing how to create a file via the apply_patch tool. - - `Optional> toolNames` + - `String diff` - List of allowed tool names. + Diff to apply. - - `enum McpToolApprovalSetting:` + - `String path` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + Path of the file to create. - - `ALWAYS("always")` + - `JsonValue; type "create_file"constant` - - `NEVER("never")` + Create a new file with the provided diff. - - `Optional serverDescription` + - `CREATE_FILE("create_file")` - Optional description of the MCP server, used to provide more context. + - `class DeleteFile:` - - `Optional serverUrl` + Instruction describing how to delete a file via the apply_patch tool. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `String path` - - `Optional tunnelId` + Path of the file to delete. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `JsonValue; type "delete_file"constant` - - `CodeInterpreter` + Delete the specified file. - - `Container container` + - `DELETE_FILE("delete_file")` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `class UpdateFile:` - - `String` + Instruction describing how to update a file via the apply_patch tool. - - `class CodeInterpreterToolAuto:` + - `String diff` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Diff to apply. - - `JsonValue; type "auto"constant` + - `String path` - Always `auto`. + Path of the file to update. - - `AUTO("auto")` + - `JsonValue; type "update_file"constant` - - `Optional> fileIds` + Update an existing file with the provided diff. - An optional list of uploaded files to make available to your code. + - `UPDATE_FILE("update_file")` - - `Optional memoryLimit` + - `Status status` - The memory limit for the code interpreter container. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `_1G("1g")` + - `IN_PROGRESS("in_progress")` - - `_4G("4g")` + - `COMPLETED("completed")` - - `_16G("16g")` + - `JsonValue; type "apply_patch_call"constant` - - `_64G("64g")` + The type of the item. Always `apply_patch_call`. - - `Optional networkPolicy` + - `APPLY_PATCH_CALL("apply_patch_call")` - Network access policy for the container. + - `Optional agent` - - `class BetaContainerNetworkPolicyDisabled:` + The agent that produced this item. - - `JsonValue; type "disabled"constant` + - `String agentName` - Disable outbound network access. Always `disabled`. + The canonical name of the agent that produced this item. - - `DISABLED("disabled")` + - `Optional caller` - - `class BetaContainerNetworkPolicyAllowlist:` + The execution context that produced this tool call. - - `List allowedDomains` + - `JsonValue;` - A list of allowed domains when type is `allowlist`. + - `JsonValue; type "direct"constant` - - `JsonValue; type "allowlist"constant` + - `DIRECT("direct")` - Allow outbound network access only to specified domains. Always `allowlist`. + - `class Program:` - - `ALLOWLIST("allowlist")` + - `String callerId` - - `Optional> domainSecrets` + The call ID of the program item that produced this tool call. - Optional domain-scoped secrets for allowlisted domains. + - `JsonValue; type "program"constant` - - `String domain` + - `PROGRAM("program")` - The domain associated with the secret. + - `Optional createdBy` - - `String name` + The ID of the entity that created this tool call. - The name of the secret to inject for the domain. + - `class BetaResponseApplyPatchToolCallOutput:` - - `String value` + The output emitted by an apply patch tool call. - The secret value to inject for the domain. + - `String id` - - `JsonValue; type "code_interpreter"constant` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The type of the code interpreter tool. Always `code_interpreter`. + - `String callId` - - `CODE_INTERPRETER("code_interpreter")` + The unique ID of the apply patch tool call generated by the model. - - `Optional> allowedCallers` + - `Status status` - The tool invocation context(s). + The status of the apply patch tool call output. One of `completed` or `failed`. - - `DIRECT("direct")` + - `COMPLETED("completed")` - - `PROGRAMMATIC("programmatic")` + - `FAILED("failed")` - - `JsonValue;` + - `JsonValue; type "apply_patch_call_output"constant` - - `JsonValue; type "programmatic_tool_calling"constant` + The type of the item. Always `apply_patch_call_output`. - The type of the tool. Always `programmatic_tool_calling`. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional agent` - - `ImageGeneration` + The agent that produced this item. - - `JsonValue; type "image_generation"constant` + - `String agentName` - The type of the image generation tool. Always `image_generation`. + The canonical name of the agent that produced this item. - - `IMAGE_GENERATION("image_generation")` + - `Optional caller` - - `Optional action` + The execution context that produced this tool call. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `JsonValue;` - - `GENERATE("generate")` + - `JsonValue; type "direct"constant` - - `EDIT("edit")` + - `DIRECT("direct")` - - `AUTO("auto")` + - `class Program:` - - `Optional background` + - `String callerId` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The call ID of the program item that produced this tool call. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `JsonValue; type "program"constant` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `PROGRAM("program")` - - `TRANSPARENT("transparent")` + - `Optional createdBy` - - `OPAQUE("opaque")` + The ID of the entity that created this tool call output. - - `AUTO("auto")` + - `Optional output` - - `Optional inputFidelity` + Optional textual output returned by the apply patch tool. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `McpCall` - - `HIGH("high")` + - `String id` - - `LOW("low")` + The unique ID of the tool call. - - `Optional inputImageMask` + - `String arguments` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A JSON string of the arguments passed to the tool. - - `Optional fileId` + - `String name` - File ID for the mask image. + The name of the tool that was run. - - `Optional imageUrl` + - `String serverLabel` - Base64-encoded mask image. + The label of the MCP server running the tool. - - `Optional model` + - `JsonValue; type "mcp_call"constant` - The image generation model to use. Default: `gpt-image-1`. + The type of the item. Always `mcp_call`. - - `GPT_IMAGE_1("gpt-image-1")` + - `MCP_CALL("mcp_call")` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `Optional agent` - - `GPT_IMAGE_2("gpt-image-2")` + The agent that produced this item. - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + - `String agentName` - - `GPT_IMAGE_1_5("gpt-image-1.5")` + The canonical name of the agent that produced this item. - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `Optional approvalRequestId` - - `Optional moderation` + 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. - Moderation level for the generated image. Default: `auto`. + - `Optional error` - - `AUTO("auto")` + The error from the tool call, if any. - - `LOW("low")` + - `Optional output` - - `Optional outputCompression` + The output from the tool call. - Compression level for the output image. Default: 100. + - `Optional status` - - `Optional outputFormat` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `IN_PROGRESS("in_progress")` - - `PNG("png")` + - `COMPLETED("completed")` - - `WEBP("webp")` + - `INCOMPLETE("incomplete")` - - `JPEG("jpeg")` + - `CALLING("calling")` - - `Optional partialImages` + - `FAILED("failed")` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `McpListTools` - - `Optional quality` + - `String id` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The unique ID of the list. - - `LOW("low")` + - `String serverLabel` - - `MEDIUM("medium")` + The label of the MCP server. - - `HIGH("high")` + - `List tools` - - `AUTO("auto")` + The tools available on the server. - - `Optional size` + - `JsonValue inputSchema` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The JSON schema describing the tool's input. - - `_1024X1024("1024x1024")` + - `String name` - - `_1024X1536("1024x1536")` + The name of the tool. - - `_1536X1024("1536x1024")` + - `Optional annotations` - - `AUTO("auto")` + Additional annotations about the tool. - - `JsonValue;` + - `Optional description` - - `JsonValue; type "local_shell"constant` + The description of the tool. - The type of the local shell tool. Always `local_shell`. + - `JsonValue; type "mcp_list_tools"constant` - - `LOCAL_SHELL("local_shell")` + The type of the item. Always `mcp_list_tools`. - - `class BetaFunctionShellTool:` + - `MCP_LIST_TOOLS("mcp_list_tools")` - A tool that allows the model to execute shell commands. + - `Optional agent` - - `JsonValue; type "shell"constant` + The agent that produced this item. - The type of the shell tool. Always `shell`. + - `String agentName` - - `SHELL("shell")` + The canonical name of the agent that produced this item. - - `Optional> allowedCallers` + - `Optional error` - The tool invocation context(s). + Error message if the server could not list tools. - - `DIRECT("direct")` + - `McpApprovalRequest` - - `PROGRAMMATIC("programmatic")` + - `String id` - - `Optional environment` + The unique ID of the approval request. - - `class BetaContainerAuto:` + - `String arguments` - - `JsonValue; type "container_auto"constant` + A JSON string of arguments for the tool. - Automatically creates a container for this request + - `String name` - - `CONTAINER_AUTO("container_auto")` + The name of the tool to run. - - `Optional> fileIds` + - `String serverLabel` - An optional list of uploaded files to make available to your code. + The label of the MCP server making the request. - - `Optional memoryLimit` + - `JsonValue; type "mcp_approval_request"constant` - The memory limit for the container. + The type of the item. Always `mcp_approval_request`. - - `_1G("1g")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `_4G("4g")` + - `Optional agent` - - `_16G("16g")` + The agent that produced this item. - - `_64G("64g")` + - `String agentName` - - `Optional networkPolicy` + The canonical name of the agent that produced this item. - Network access policy for the container. + - `McpApprovalResponse` - - `class BetaContainerNetworkPolicyDisabled:` + - `String id` - - `class BetaContainerNetworkPolicyAllowlist:` + The unique ID of the approval response - - `Optional> skills` + - `String approvalRequestId` - An optional list of skills referenced by id or inline data. + The ID of the approval request being answered. - - `class BetaSkillReference:` + - `boolean approve` - - `String skillId` + Whether the request was approved. - The ID of the referenced skill. + - `JsonValue; type "mcp_approval_response"constant` - - `JsonValue; type "skill_reference"constant` + The type of the item. Always `mcp_approval_response`. - References a skill created with the /v1/skills endpoint. + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `SKILL_REFERENCE("skill_reference")` + - `Optional agent` - - `Optional version` + The agent that produced this item. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `String agentName` - - `class BetaInlineSkill:` + The canonical name of the agent that produced this item. - - `String description` + - `Optional reason` - The description of the skill. + Optional reason for the decision. - - `String name` + - `class BetaResponseCustomToolCall:` - The name of the skill. + A call to a custom tool created by the model. - - `BetaInlineSkillSource source` + - `class BetaResponseCustomToolCallOutputItem:` - Inline skill payload + The output of a custom tool call from your code, being sent back to the model. - - `String data` + - `String id` - Base64-encoded skill zip bundle. + The unique ID of the custom tool call output item. - - `JsonValue; mediaType "application/zip"constant` + - `Status status` - The media type of the inline skill payload. Must be `application/zip`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `APPLICATION_ZIP("application/zip")` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "base64"constant` + - `COMPLETED("completed")` - The type of the inline skill source. Must be `base64`. + - `INCOMPLETE("incomplete")` - - `BASE64("base64")` + - `Optional createdBy` - - `JsonValue; type "inline"constant` + The identifier of the actor that created the item. - Defines an inline skill for this request. + - `boolean parallelToolCalls` - - `INLINE("inline")` + Whether to allow the model to run tool calls in parallel. - - `class BetaLocalEnvironment:` + - `Optional temperature` - - `JsonValue; type "local"constant` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - Use a local computer environment. + - `ToolChoice toolChoice` - - `LOCAL("local")` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `Optional> skills` + - `enum BetaToolChoiceOptions:` - An optional list of skills. + Controls which (if any) tool is called by the model. - - `String description` + `none` means the model will not call any tool and instead generates a message. - The description of the skill. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `String name` + `required` means the model must call one or more tools. - The name of the skill. + - `NONE("none")` - - `String path` + - `AUTO("auto")` - The path to the directory containing the skill. + - `REQUIRED("required")` - - `class BetaContainerReference:` + - `class BetaToolChoiceAllowed:` - - `String containerId` + Constrains the tools available to the model to a pre-defined set. - The ID of the referenced container. + - `Mode mode` - - `JsonValue; type "container_reference"constant` + Constrains the tools available to the model to a pre-defined set. - References a container created with the /v1/containers endpoint + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `CONTAINER_REFERENCE("container_reference")` + `required` requires the model to call one or more of the allowed tools. - - `class BetaCustomTool:` + - `AUTO("auto")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `REQUIRED("required")` - - `String name` + - `List tools` - The name of the custom tool, used to identify it in tool calls. + A list of tool definitions that the model should be allowed to call. - - `JsonValue; type "custom"constant` + For the Responses API, the list of tool definitions might look like: - The type of the custom tool. Always `custom`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `CUSTOM("custom")` + - `JsonValue; type "allowed_tools"constant` - - `Optional> allowedCallers` + Allowed tool configuration type. Always `allowed_tools`. - The tool invocation context(s). + - `ALLOWED_TOOLS("allowed_tools")` - - `DIRECT("direct")` + - `class BetaToolChoiceTypes:` - - `PROGRAMMATIC("programmatic")` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `Optional deferLoading` + - `Type type` - Whether this tool should be deferred and discovered via tool search. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `Optional description` + Allowed values are: - Optional description of the custom tool, used to provide more context. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `Optional format` + - `FILE_SEARCH("file_search")` - The input format for the custom tool. Default is unconstrained text. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `JsonValue;` + - `COMPUTER("computer")` - - `JsonValue; type "text"constant` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - Unconstrained text format. Always `text`. + - `COMPUTER_USE("computer_use")` - - `TEXT("text")` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `class Grammar:` + - `IMAGE_GENERATION("image_generation")` - A grammar defined by the user. + - `CODE_INTERPRETER("code_interpreter")` - - `String definition` + - `class BetaToolChoiceFunction:` - The grammar definition. + Use this option to force the model to call a specific function. - - `Syntax syntax` + - `String name` - The syntax of the grammar definition. One of `lark` or `regex`. + The name of the function to call. - - `LARK("lark")` + - `JsonValue; type "function"constant` - - `REGEX("regex")` + For function calling, the type is always `function`. - - `JsonValue; type "grammar"constant` + - `FUNCTION("function")` - Grammar format. Always `grammar`. + - `class BetaToolChoiceMcp:` - - `GRAMMAR("grammar")` + Use this option to force the model to call a specific tool on a remote MCP server. - - `class BetaNamespaceTool:` + - `String serverLabel` - Groups function/custom tools under a shared namespace. + The label of the MCP server to use. - - `String description` + - `JsonValue; type "mcp"constant` - A description of the namespace shown to the model. + For MCP tools, the type is always `mcp`. - - `String name` + - `MCP("mcp")` - The namespace name used in tool calls (for example, `crm`). + - `Optional name` - - `List tools` + The name of the tool to call on the server. - The function/custom tools available inside this namespace. + - `class BetaToolChoiceCustom:` - - `class Function:` + Use this option to force the model to call a specific custom tool. - `String name` - - `JsonValue; type "function"constant` - - - `FUNCTION("function")` + The name of the custom tool to call. - - `Optional> allowedCallers` + - `JsonValue; type "custom"constant` - The tool invocation context(s). + For custom tool calling, the type is always `custom`. - - `DIRECT("direct")` + - `CUSTOM("custom")` - - `PROGRAMMATIC("programmatic")` + - `JsonValue;` - - `Optional deferLoading` + - `JsonValue; type "programmatic_tool_calling"constant` - Whether this function should be deferred and discovered via tool search. + The tool to call. Always `programmatic_tool_calling`. - - `Optional description` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `Optional outputSchema` + - `class BetaToolChoiceApplyPatch:` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Forces the model to call the apply_patch tool when executing a tool call. - - `Optional parameters` + - `JsonValue; type "apply_patch"constant` - - `Optional strict` + The tool to call. Always `apply_patch`. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `APPLY_PATCH("apply_patch")` - - `class BetaCustomTool:` + - `class BetaToolChoiceShell:` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Forces the model to call the shell tool when a tool call is required. - - `JsonValue; type "namespace"constant` + - `JsonValue; type "shell"constant` - The type of the tool. Always `namespace`. + The tool to call. Always `shell`. - - `NAMESPACE("namespace")` + - `SHELL("shell")` - - `class BetaToolSearchTool:` + - `List tools` - Hosted or BYOT tool search configuration for deferred tools. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `JsonValue; type "tool_search"constant` + We support the following categories of tools: - The type of the tool. Always `tool_search`. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `TOOL_SEARCH("tool_search")` + - `class BetaFunctionTool:` - - `Optional description` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Description shown to the model for a client-executed tool search tool. + - `class BetaFileSearchTool:` - - `Optional execution` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - Whether tool search is executed by the server or by the client. + - `class BetaComputerTool:` - - `SERVER("server")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `CLIENT("client")` + - `class BetaComputerUsePreviewTool:` - - `Optional parameters` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Parameter schema for a client-executed tool search tool. + - `class BetaWebSearchTool:` - - `class BetaWebSearchPreviewTool:` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Mcp` - - `Type type` + - `CodeInterpreter` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `JsonValue;` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `ImageGeneration` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `JsonValue;` - - `Optional> searchContentTypes` + - `class BetaFunctionShellTool:` - - `TEXT("text")` + A tool that allows the model to execute shell commands. - - `IMAGE("image")` + - `class BetaCustomTool:` - - `Optional searchContextSize` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `class BetaNamespaceTool:` - - `LOW("low")` + Groups function/custom tools under a shared namespace. - - `MEDIUM("medium")` + - `class BetaToolSearchTool:` - - `HIGH("high")` + Hosted or BYOT tool search configuration for deferred tools. - - `Optional userLocation` + - `class BetaWebSearchPreviewTool:` - The user's location. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue; type "approximate"constant` + - `class BetaApplyPatchTool:` - The type of location approximation. Always `approximate`. + Allows the assistant to create, delete, or update files using unified diffs. - - `APPROXIMATE("approximate")` + - `Optional topP` - - `Optional city` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - Free text input for the city of the user, e.g. `San Francisco`. + We generally recommend altering this or `temperature` but not both. - - `Optional country` + - `Optional background` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `Optional region` + - `Optional completedAt` - Free text input for the region of the user, e.g. `California`. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Optional timezone` + - `Optional conversation` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `class BetaApplyPatchTool:` + - `String id` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the conversation that this response was associated with. - - `JsonValue; type "apply_patch"constant` + - `Optional maxOutputTokens` - The type of the tool. Always `apply_patch`. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `APPLY_PATCH("apply_patch")` + - `Optional maxToolCalls` - - `Optional> allowedCallers` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The tool invocation context(s). + - `Optional moderation` - - `DIRECT("direct")` + Moderation results for the response input and output, if moderated completions were requested. - - `PROGRAMMATIC("programmatic")` + - `Input input` - - `JsonValue; type "tool_search_output"constant` + Moderation for the response input. - The item type. Always `tool_search_output`. + - `class ModerationResult:` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + A moderation result produced for the response input or output. - - `Optional id` + - `Categories categories` - The unique ID of this tool search output. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `Optional agent` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - The agent that produced this item. + Which modalities of input are reflected by the score for each category. - - `String agentName` + - `TEXT("text")` - The canonical name of the agent that produced this item. + - `IMAGE("image")` - - `Optional callId` + - `CategoryScores categoryScores` - The unique ID of the tool search call generated by the model. + A dictionary of moderation categories to scores. - - `Optional execution` + - `boolean flagged` - Whether tool search was executed by the server or by the client. + A boolean indicating whether the content was flagged by any category. - - `SERVER("server")` + - `String model` - - `CLIENT("client")` + The moderation model that produced this result. - - `Optional status` + - `JsonValue; type "moderation_result"constant` - The status of the tool search output. + The object type, which was always `moderation_result` for successful moderation results. - - `IN_PROGRESS("in_progress")` + - `MODERATION_RESULT("moderation_result")` - - `COMPLETED("completed")` + - `class Error:` - - `INCOMPLETE("incomplete")` + An error produced while attempting moderation for the response input or output. - - `AdditionalTools` + - `String code` - - `JsonValue; role "developer"constant` + The error code. - The role that provided the additional tools. Only `developer` is supported. + - `String message` - - `DEVELOPER("developer")` + The error message. - - `List tools` + - `JsonValue; type "error"constant` - A list of additional tools made available at this item. + The object type, which was always `error` for moderation failures. - - `class BetaFunctionTool:` + - `ERROR("error")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Output output` - - `class BetaFileSearchTool:` + Moderation for the response output. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class ModerationResult:` - - `class BetaComputerTool:` + A moderation result produced for the response input or output. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Categories categories` - - `class BetaComputerUsePreviewTool:` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `class BetaWebSearchTool:` + Which modalities of input are reflected by the score for each category. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `TEXT("text")` - - `Mcp` + - `IMAGE("image")` - - `CodeInterpreter` + - `CategoryScores categoryScores` - - `JsonValue;` + A dictionary of moderation categories to scores. - - `ImageGeneration` + - `boolean flagged` - - `JsonValue;` + A boolean indicating whether the content was flagged by any category. - - `class BetaFunctionShellTool:` + - `String model` - A tool that allows the model to execute shell commands. + The moderation model that produced this result. - - `class BetaCustomTool:` + - `JsonValue; type "moderation_result"constant` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The object type, which was always `moderation_result` for successful moderation results. - - `class BetaNamespaceTool:` + - `MODERATION_RESULT("moderation_result")` - Groups function/custom tools under a shared namespace. + - `class Error:` - - `class BetaToolSearchTool:` + An error produced while attempting moderation for the response input or output. - Hosted or BYOT tool search configuration for deferred tools. + - `String code` - - `class BetaWebSearchPreviewTool:` + The error code. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String message` - - `class BetaApplyPatchTool:` + The error message. - Allows the assistant to create, delete, or update files using unified diffs. + - `JsonValue; type "error"constant` - - `JsonValue; type "additional_tools"constant` + The object type, which was always `error` for moderation failures. - The item type. Always `additional_tools`. + - `ERROR("error")` - - `ADDITIONAL_TOOLS("additional_tools")` + - `Optional previousResponseId` - - `Optional id` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The unique ID of this additional tools item. + - `Optional prompt` - - `Optional agent` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The agent that produced this item. + - `String id` - - `String agentName` + The unique identifier of the prompt template to use. - The canonical name of the agent that produced this item. + - `Optional variables` - - `class BetaResponseReasoningItem:` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `String` - - `String id` + - `class BetaResponseInputText:` - The unique identifier of the reasoning content. + A text input to the model. - - `List summary` + - `class BetaResponseInputImage:` - Reasoning summary content. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `String text` + - `class BetaResponseInputFile:` - A summary of the reasoning output from the model so far. + A file input to the model. - - `JsonValue; type "summary_text"constant` + - `Optional version` - The type of the object. Always `summary_text`. + Optional version of the prompt template. - - `SUMMARY_TEXT("summary_text")` + - `Optional promptCacheKey` - - `JsonValue; type "reasoning"constant` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The type of the object. Always `reasoning`. + - `Optional promptCacheOptions` - - `REASONING("reasoning")` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `Optional agent` + - `Mode mode` - The agent that produced this item. + Whether implicit prompt-cache breakpoints were enabled. - - `String agentName` + - `IMPLICIT("implicit")` - The canonical name of the agent that produced this item. + - `EXPLICIT("explicit")` - - `Optional> content` + - `Ttl ttl` - Reasoning text content. + The minimum lifetime applied to each cache breakpoint. - - `String text` + - `_30M("30m")` - The reasoning text from the model. + - `Optional promptCacheRetention` - - `JsonValue; type "reasoning_text"constant` + Deprecated. Use `prompt_cache_options.ttl` instead. - The type of the reasoning text. Always `reasoning_text`. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `REASONING_TEXT("reasoning_text")` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `Optional encryptedContent` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `IN_MEMORY("in_memory")` - - `Optional status` + - `_24H("24h")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional reasoning` - - `IN_PROGRESS("in_progress")` + **gpt-5 and o-series models only** - - `COMPLETED("completed")` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `INCOMPLETE("incomplete")` + - `Optional context` - - `class BetaResponseCompactionItemParam:` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `AUTO("auto")` - - `String encryptedContent` + - `CURRENT_TURN("current_turn")` - The encrypted content of the compaction summary. + - `ALL_TURNS("all_turns")` - - `JsonValue; type "compaction"constant` + - `Optional effort` - The type of the item. Always `compaction`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `COMPACTION("compaction")` + - `NONE("none")` - - `Optional id` + - `MINIMAL("minimal")` - The ID of the compaction item. + - `LOW("low")` - - `Optional agent` + - `MEDIUM("medium")` - The agent that produced this item. + - `HIGH("high")` - - `String agentName` + - `XHIGH("xhigh")` - The canonical name of the agent that produced this item. + - `MAX("max")` - - `ImageGenerationCall` + - `Optional generateSummary` - - `String id` + **Deprecated:** use `summary` instead. - The unique ID of the image generation call. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `Optional result` + - `AUTO("auto")` - The generated image encoded in base64. + - `CONCISE("concise")` - - `Status status` + - `DETAILED("detailed")` - The status of the image generation call. + - `Optional mode` - - `IN_PROGRESS("in_progress")` + Controls the reasoning execution mode for the request. - - `COMPLETED("completed")` + When returned on a response, this is the effective execution mode. - - `GENERATING("generating")` + - `STANDARD("standard")` - - `FAILED("failed")` + - `PRO("pro")` - - `JsonValue; type "image_generation_call"constant` + - `Optional summary` - The type of the image generation call. Always `image_generation_call`. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `Optional agent` + - `AUTO("auto")` - The agent that produced this item. + - `CONCISE("concise")` - - `String agentName` + - `DETAILED("detailed")` - The canonical name of the agent that produced this item. + - `Optional safetyIdentifier` - - `class BetaResponseCodeInterpreterToolCall:` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - A tool call to run code. + - `Optional serviceTier` - - `String id` + Specifies the processing type used for serving the request. - The unique ID of the code interpreter tool call. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `Optional code` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The code to run, or null if not available. + - `AUTO("auto")` - - `String containerId` + - `DEFAULT("default")` - The ID of the container used to run the code. + - `FLEX("flex")` - - `Optional> outputs` + - `SCALE("scale")` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `PRIORITY("priority")` - - `class Logs:` + - `Optional status` - The logs output from the code interpreter. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `String logs` + - `COMPLETED("completed")` - The logs output from the code interpreter. + - `FAILED("failed")` - - `JsonValue; type "logs"constant` + - `IN_PROGRESS("in_progress")` - The type of the output. Always `logs`. + - `CANCELLED("cancelled")` - - `LOGS("logs")` + - `QUEUED("queued")` - - `class Image:` + - `INCOMPLETE("incomplete")` - The image output from the code interpreter. + - `Optional text` - - `JsonValue; type "image"constant` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The type of the output. Always `image`. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `IMAGE("image")` + - `Optional format` - - `String url` + An object specifying the format that the model must output. - The URL of the image output from the code interpreter. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Status status` + The default format is `{ "type": "text" }` with no additional options. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + **Not recommended for gpt-4o and newer models:** - - `IN_PROGRESS("in_progress")` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `COMPLETED("completed")` + - `JsonValue;` - - `INCOMPLETE("incomplete")` + - `JsonValue; type "text"constant` - - `INTERPRETING("interpreting")` + The type of response format being defined. Always `text`. - - `FAILED("failed")` + - `TEXT("text")` - - `JsonValue; type "code_interpreter_call"constant` + - `class BetaResponseFormatTextJsonSchemaConfig:` - The type of the code interpreter tool call. Always `code_interpreter_call`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `String name` - - `Optional agent` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The agent that produced this item. + - `Schema schema` - - `String agentName` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The canonical name of the agent that produced this item. + - `JsonValue; type "json_schema"constant` - - `LocalShellCall` + The type of response format being defined. Always `json_schema`. - - `String id` + - `JSON_SCHEMA("json_schema")` - The unique ID of the local shell call. + - `Optional description` - - `Action action` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Execute a shell command on the server. + - `Optional strict` - - `List command` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The command to run. + - `JsonValue;` - - `Env env` + - `JsonValue; type "json_object"constant` - Environment variables to set for the command. + The type of response format being defined. Always `json_object`. - - `JsonValue; type "exec"constant` + - `JSON_OBJECT("json_object")` - The type of the local shell action. Always `exec`. + - `Optional verbosity` - - `EXEC("exec")` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `Optional timeoutMs` + - `LOW("low")` - Optional timeout in milliseconds for the command. + - `MEDIUM("medium")` - - `Optional user` + - `HIGH("high")` - Optional user to run the command as. + - `Optional topLogprobs` - - `Optional workingDirectory` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - Optional working directory to run the command in. + - `Optional truncation` - - `String callId` + The truncation strategy to use for the model response. - The unique ID of the local shell tool call generated by the model. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `Status status` + - `AUTO("auto")` - The status of the local shell call. + - `DISABLED("disabled")` - - `IN_PROGRESS("in_progress")` + - `Optional usage` - - `COMPLETED("completed")` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `INCOMPLETE("incomplete")` + - `long inputTokens` - - `JsonValue; type "local_shell_call"constant` + The number of input tokens. - The type of the local shell call. Always `local_shell_call`. + - `InputTokensDetails inputTokensDetails` - - `LOCAL_SHELL_CALL("local_shell_call")` + A detailed breakdown of the input tokens. - - `Optional agent` + - `long cacheWriteTokens` - The agent that produced this item. + The number of input tokens that were written to the cache. - - `String agentName` + - `long cachedTokens` - The canonical name of the agent that produced this item. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `LocalShellCallOutput` + - `long outputTokens` - - `String id` + The number of output tokens. - The unique ID of the local shell tool call generated by the model. + - `OutputTokensDetails outputTokensDetails` - - `String output` + A detailed breakdown of the output tokens. - A JSON string of the output of the local shell tool call. + - `long reasoningTokens` - - `JsonValue; type "local_shell_call_output"constant` + The number of reasoning tokens. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `long totalTokens` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The total number of tokens used. - - `Optional agent` + - `Optional user` - The agent that produced this item. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `String agentName` + - `long sequenceNumber` - The canonical name of the agent that produced this item. + The sequence number for this event. - - `Optional status` + - `JsonValue; type "response.created"constant` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The type of the event. Always `response.created`. - - `IN_PROGRESS("in_progress")` + - `RESPONSE_CREATED("response.created")` - - `COMPLETED("completed")` + - `Optional agent` - - `INCOMPLETE("incomplete")` + The agent that owns this multi-agent streaming event. - - `ShellCall` + - `String agentName` - - `Action action` + The canonical name of the agent that produced this item. - The shell commands and limits that describe how to run the tool call. +### Beta Response Custom Tool Call - - `List commands` +- `class BetaResponseCustomToolCall:` - Ordered shell commands for the execution environment to run. + A call to a custom tool created by the model. - - `Optional maxOutputLength` + - `String callId` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + An identifier used to map this custom tool call to a tool call output. - - `Optional timeoutMs` + - `String input` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The input for the custom tool call generated by the model. - - `String callId` + - `String name` - The unique ID of the shell tool call generated by the model. + The name of the custom tool being called. - - `JsonValue; type "shell_call"constant` + - `JsonValue; type "custom_tool_call"constant` - The type of the item. Always `shell_call`. + The type of the custom tool call. Always `custom_tool_call`. - - `SHELL_CALL("shell_call")` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - `Optional id` - The unique ID of the shell tool call. Populated when this item is returned via API. + The unique ID of the custom tool call in the OpenAI platform. - `Optional agent` @@ -40362,8 +56877,6 @@ Compact a response - `JsonValue; type "direct"constant` - The caller type. Always `direct`. - - `DIRECT("direct")` - `class Program:` @@ -40374,261 +56887,247 @@ Compact a response - `JsonValue; type "program"constant` - The caller type. Always `program`. - - `PROGRAM("program")` - - `Optional environment` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment:` + - `Optional namespace` - - `class BetaContainerReference:` + The namespace of the custom tool being called. - - `Optional status` +### Beta Response Custom Tool Call Input Delta Event - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. +- `class BetaResponseCustomToolCallInputDeltaEvent:` - - `IN_PROGRESS("in_progress")` + Event representing a delta (partial update) to the input of a custom tool call. - - `COMPLETED("completed")` + - `String delta` - - `INCOMPLETE("incomplete")` + The incremental input data (delta) for the custom tool call. - - `ShellCallOutput` + - `String itemId` - - `String callId` + Unique identifier for the API item associated with this event. - The unique ID of the shell tool call generated by the model. + - `long outputIndex` - - `List output` + The index of the output this delta applies to. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `long sequenceNumber` - - `Outcome outcome` + The sequence number of this event. - The exit or timeout outcome associated with this shell call. + - `JsonValue; type "response.custom_tool_call_input.delta"constant` - - `JsonValue;` + The event type identifier. - - `JsonValue; type "timeout"constant` + - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DELTA("response.custom_tool_call_input.delta")` - The outcome type. Always `timeout`. + - `Optional agent` - - `TIMEOUT("timeout")` + The agent that owns this multi-agent streaming event. - - `class Exit:` + - `String agentName` - Indicates that the shell commands finished and returned an exit code. + The canonical name of the agent that produced this item. - - `long exitCode` +### Beta Response Custom Tool Call Input Done Event - The exit code returned by the shell process. +- `class BetaResponseCustomToolCallInputDoneEvent:` - - `JsonValue; type "exit"constant` + Event indicating that input for a custom tool call is complete. - The outcome type. Always `exit`. + - `String input` - - `EXIT("exit")` + The complete input data for the custom tool call. - - `String stderr` + - `String itemId` - Captured stderr output for the shell call. + Unique identifier for the API item associated with this event. - - `String stdout` + - `long outputIndex` - Captured stdout output for the shell call. + The index of the output this event applies to. - - `JsonValue; type "shell_call_output"constant` + - `long sequenceNumber` - The type of the item. Always `shell_call_output`. + The sequence number of this event. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `JsonValue; type "response.custom_tool_call_input.done"constant` - - `Optional id` + The event type identifier. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DONE("response.custom_tool_call_input.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` +### Beta Response Custom Tool Call Item - - `class Program:` +- `class BetaResponseCustomToolCallItem:` - - `String callerId` + A call to a custom tool created by the model. - The call ID of the program item that produced this tool call. + - `String id` - - `JsonValue; type "program"constant` + The unique ID of the custom tool call item. - The caller type. Always `program`. + - `Status status` - - `PROGRAM("program")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional maxOutputLength` + - `IN_PROGRESS("in_progress")` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `COMPLETED("completed")` - - `Optional status` + - `INCOMPLETE("incomplete")` - The status of the shell call output. + - `Optional createdBy` - - `IN_PROGRESS("in_progress")` + The identifier of the actor that created the item. - - `COMPLETED("completed")` +### Beta Response Custom Tool Call Output - - `INCOMPLETE("incomplete")` +- `class BetaResponseCustomToolCallOutput:` - - `ApplyPatchCall` + The output of a custom tool call from your code, being sent back to the model. - `String callId` - The unique ID of the apply patch tool call generated by the model. + The call ID, used to map this custom tool call output to a custom tool call. - - `Operation operation` + - `Output output` - The specific create, delete, or update instruction for the apply_patch tool call. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `class CreateFile:` + - `String` - Instruction for creating a new file via the apply_patch tool. + - `List` - - `String diff` + - `class BetaResponseInputText:` - Unified diff content to apply when creating the file. + A text input to the model. - - `String path` + - `String text` - Path of the file to create relative to the workspace root. + The text input to the model. - - `JsonValue; type "create_file"constant` + - `JsonValue; type "input_text"constant` - The operation type. Always `create_file`. + The type of the input item. Always `input_text`. - - `CREATE_FILE("create_file")` + - `INPUT_TEXT("input_text")` - - `class DeleteFile:` + - `Optional promptCacheBreakpoint` - Instruction for deleting an existing file via the apply_patch tool. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String path` + - `JsonValue; mode "explicit"constant` - Path of the file to delete relative to the workspace root. + The breakpoint mode. Always `explicit`. - - `JsonValue; type "delete_file"constant` + - `EXPLICIT("explicit")` - The operation type. Always `delete_file`. + - `class BetaResponseInputImage:` - - `DELETE_FILE("delete_file")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class UpdateFile:` + - `Detail detail` - Instruction for updating an existing file via the apply_patch tool. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String diff` + - `LOW("low")` - Unified diff content to apply to the existing file. + - `HIGH("high")` - - `String path` + - `AUTO("auto")` - Path of the file to update relative to the workspace root. + - `ORIGINAL("original")` - - `JsonValue; type "update_file"constant` + - `JsonValue; type "input_image"constant` - The operation type. Always `update_file`. + The type of the input item. Always `input_image`. - - `UPDATE_FILE("update_file")` + - `INPUT_IMAGE("input_image")` - - `Status status` + - `Optional fileId` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The ID of the file to be sent to the model. - - `IN_PROGRESS("in_progress")` + - `Optional imageUrl` - - `COMPLETED("completed")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `JsonValue; type "apply_patch_call"constant` + - `Optional promptCacheBreakpoint` - The type of the item. Always `apply_patch_call`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `JsonValue; mode "explicit"constant` - - `Optional id` + The breakpoint mode. Always `explicit`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `EXPLICIT("explicit")` - - `Optional agent` + - `class BetaResponseInputFile:` - The agent that produced this item. + A file input to the model. - - `String agentName` + - `JsonValue; type "input_file"constant` - The canonical name of the agent that produced this item. + The type of the input item. Always `input_file`. - - `Optional caller` + - `INPUT_FILE("input_file")` - The execution context that produced this tool call. + - `Optional detail` - - `JsonValue;` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `JsonValue; type "direct"constant` + - `AUTO("auto")` - The caller type. Always `direct`. + - `LOW("low")` - - `DIRECT("direct")` + - `HIGH("high")` - - `class Program:` + - `Optional fileData` - - `String callerId` + The content of the file to be sent to the model. - The call ID of the program item that produced this tool call. + - `Optional fileId` - - `JsonValue; type "program"constant` + The ID of the file to be sent to the model. - The caller type. Always `program`. + - `Optional fileUrl` - - `PROGRAM("program")` + The URL of the file to be sent to the model. - - `ApplyPatchCallOutput` + - `Optional filename` - - `String callId` + The name of the file to be sent to the model. - The unique ID of the apply patch tool call generated by the model. + - `Optional promptCacheBreakpoint` - - `Status status` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `JsonValue; mode "explicit"constant` - - `COMPLETED("completed")` + The breakpoint mode. Always `explicit`. - - `FAILED("failed")` + - `EXPLICIT("explicit")` - - `JsonValue; type "apply_patch_call_output"constant` + - `JsonValue; type "custom_tool_call_output"constant` - The type of the item. Always `apply_patch_call_output`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - `Optional id` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The unique ID of the custom tool call output in the OpenAI platform. - `Optional agent` @@ -40662,486 +57161,420 @@ Compact a response - `PROGRAM("program")` - - `Optional output` +### Beta Response Custom Tool Call Output Item - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). +- `class BetaResponseCustomToolCallOutputItem:` - - `McpListTools` + The output of a custom tool call from your code, being sent back to the model. - `String id` - The unique ID of the list. - - - `String serverLabel` - - The label of the MCP server. - - - `List 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 annotations` - - Additional annotations about the tool. - - - `Optional 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 agent` - - The agent that produced this item. - - - `String agentName` + The unique ID of the custom tool call output item. - The canonical name of the agent that produced this item. + - `Status status` - - `Optional error` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Error message if the server could not list tools. + - `IN_PROGRESS("in_progress")` - - `McpApprovalRequest` + - `COMPLETED("completed")` - - `String id` + - `INCOMPLETE("incomplete")` - The unique ID of the approval request. + - `Optional createdBy` - - `String arguments` + The identifier of the actor that created the item. - A JSON string of arguments for the tool. +### Beta Response Error - - `String name` +- `class BetaResponseError:` - The name of the tool to run. + An error object returned when the model fails to generate a Response. - - `String serverLabel` + - `Code code` - The label of the MCP server making the request. + The error code for the response. - - `JsonValue; type "mcp_approval_request"constant` + - `SERVER_ERROR("server_error")` - The type of the item. Always `mcp_approval_request`. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `INVALID_PROMPT("invalid_prompt")` - - `Optional agent` + - `BIO_POLICY("bio_policy")` - The agent that produced this item. + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - `String agentName` + - `INVALID_IMAGE("invalid_image")` - The canonical name of the agent that produced this item. + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - - `McpApprovalResponse` + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - - `String approvalRequestId` + - `INVALID_IMAGE_URL("invalid_image_url")` - The ID of the approval request being answered. + - `IMAGE_TOO_LARGE("image_too_large")` - - `boolean approve` + - `IMAGE_TOO_SMALL("image_too_small")` - Whether the request was approved. + - `IMAGE_PARSE_ERROR("image_parse_error")` - - `JsonValue; type "mcp_approval_response"constant` + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - The type of the item. Always `mcp_approval_response`. + - `INVALID_IMAGE_MODE("invalid_image_mode")` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `Optional id` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - The unique ID of the approval response + - `EMPTY_IMAGE_FILE("empty_image_file")` - - `Optional agent` + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - The agent that produced this item. + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - - `String agentName` + - `String message` - The canonical name of the agent that produced this item. + A human-readable description of the error. - - `Optional reason` +### Beta Response Error Event - Optional reason for the decision. +- `class BetaResponseErrorEvent:` - - `McpCall` + Emitted when an error occurs. - - `String id` + - `Optional code` - The unique ID of the tool call. + The error code. - - `String arguments` + - `String message` - A JSON string of the arguments passed to the tool. + The error message. - - `String name` + - `Optional param` - The name of the tool that was run. + The error parameter. - - `String serverLabel` + - `long sequenceNumber` - The label of the MCP server running the tool. + The sequence number of this event. - - `JsonValue; type "mcp_call"constant` + - `JsonValue; type "error"constant` - The type of the item. Always `mcp_call`. + The type of the event. Always `error`. - - `MCP_CALL("mcp_call")` + - `ERROR("error")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional 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 error` - - The error from the tool call, if any. - - - `Optional output` - - The output from the tool call. - - - `Optional 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 BetaResponseCustomToolCallOutput:` - - 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` +### Beta Response Failed Event - - `class BetaResponseInputText:` +- `class BetaResponseFailedEvent:` - A text input to the model. + An event that is emitted when a response fails. - - `class BetaResponseInputImage:` + - `BetaResponse response` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The response that failed. - - `class BetaResponseInputFile:` + - `String id` - A file input to the model. + Unique identifier for this Response. - - `JsonValue; type "custom_tool_call_output"constant` + - `double createdAt` - The type of the custom tool call output. Always `custom_tool_call_output`. + Unix timestamp (in seconds) of when this Response was created. - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `Optional error` - - `Optional id` + An error object returned when the model fails to generate a Response. - The unique ID of the custom tool call output in the OpenAI platform. + - `Code code` - - `Optional agent` + The error code for the response. - The agent that produced this item. + - `SERVER_ERROR("server_error")` - - `String agentName` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The canonical name of the agent that produced this item. + - `INVALID_PROMPT("invalid_prompt")` - - `Optional caller` + - `BIO_POLICY("bio_policy")` - The execution context that produced this tool call. + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - `JsonValue;` + - `INVALID_IMAGE("invalid_image")` - - `JsonValue; type "direct"constant` + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - The caller type. Always `direct`. + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - - `DIRECT("direct")` + - `INVALID_IMAGE_URL("invalid_image_url")` - - `class Program:` + - `IMAGE_TOO_LARGE("image_too_large")` - - `String callerId` + - `IMAGE_TOO_SMALL("image_too_small")` - The call ID of the program item that produced this tool call. + - `IMAGE_PARSE_ERROR("image_parse_error")` - - `JsonValue; type "program"constant` + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - The caller type. Always `program`. + - `INVALID_IMAGE_MODE("invalid_image_mode")` - - `PROGRAM("program")` + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `class BetaResponseCustomToolCall:` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - A call to a custom tool created by the model. + - `EMPTY_IMAGE_FILE("empty_image_file")` - - `String callId` + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - An identifier used to map this custom tool call to a tool call output. + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - - `String input` + - `String message` - The input for the custom tool call generated by the model. + A human-readable description of the error. - - `String name` + - `Optional incompleteDetails` - The name of the custom tool being called. + Details about why the response is incomplete. - - `JsonValue; type "custom_tool_call"constant` + - `Optional reason` - The type of the custom tool call. Always `custom_tool_call`. + The reason why the response is incomplete. - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - - `Optional id` + - `CONTENT_FILTER("content_filter")` - The unique ID of the custom tool call in the OpenAI platform. + - `Optional instructions` - - `Optional agent` + A system (or developer) message inserted into the model's context. - The agent that produced this item. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `String agentName` + - `String` - The canonical name of the agent that produced this item. + - `List` - - `Optional caller` + - `class BetaEasyInputMessage:` - The execution context that produced this tool call. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `JsonValue;` + - `Content content` - - `JsonValue; type "direct"constant` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `DIRECT("direct")` + - `String` - - `class Program:` + - `List` - - `String callerId` + - `class BetaResponseInputText:` - The call ID of the program item that produced this tool call. + A text input to the model. - - `JsonValue; type "program"constant` + - `String text` - - `PROGRAM("program")` + The text input to the model. - - `Optional namespace` + - `JsonValue; type "input_text"constant` - The namespace of the custom tool being called. + The type of the input item. Always `input_text`. - - `CompactionTrigger` + - `INPUT_TEXT("input_text")` - - `JsonValue; type "compaction_trigger"constant` + - `Optional promptCacheBreakpoint` - The type of the item. Always `compaction_trigger`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `COMPACTION_TRIGGER("compaction_trigger")` + - `JsonValue; mode "explicit"constant` - - `Optional agent` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `EXPLICIT("explicit")` - - `String agentName` + - `class BetaResponseInputImage:` - The canonical name of the agent that produced this item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ItemReference` + - `Detail detail` - - `String id` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The ID of the item to reference. + - `LOW("low")` - - `Optional agent` + - `HIGH("high")` - The agent that produced this item. + - `AUTO("auto")` - - `String agentName` + - `ORIGINAL("original")` - The canonical name of the agent that produced this item. + - `JsonValue; type "input_image"constant` - - `Optional type` + The type of the input item. Always `input_image`. - The type of item to reference. Always `item_reference`. + - `INPUT_IMAGE("input_image")` - - `ITEM_REFERENCE("item_reference")` + - `Optional fileId` - - `Program` + The ID of the file to be sent to the model. - - `String id` + - `Optional imageUrl` - The unique ID of this program item. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `String callId` + - `Optional promptCacheBreakpoint` - The stable call ID of the program item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String code` + - `JsonValue; mode "explicit"constant` - The JavaScript source executed by programmatic tool calling. + The breakpoint mode. Always `explicit`. - - `String fingerprint` + - `EXPLICIT("explicit")` - Opaque program replay fingerprint that must be round-tripped. + - `class BetaResponseInputFile:` - - `JsonValue; type "program"constant` + A file input to the model. - The item type. Always `program`. + - `JsonValue; type "input_file"constant` - - `PROGRAM("program")` + The type of the input item. Always `input_file`. - - `Optional agent` + - `INPUT_FILE("input_file")` - The agent that produced this item. + - `Optional detail` - - `String agentName` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The canonical name of the agent that produced this item. + - `AUTO("auto")` - - `ProgramOutput` + - `LOW("low")` - - `String id` + - `HIGH("high")` - The unique ID of this program output item. + - `Optional fileData` - - `String callId` + The content of the file to be sent to the model. - The call ID of the program item. + - `Optional fileId` - - `String result` + The ID of the file to be sent to the model. - The result produced by the program item. + - `Optional fileUrl` - - `Status status` + The URL of the file to be sent to the model. - The terminal status of the program output. + - `Optional filename` - - `COMPLETED("completed")` + The name of the file to be sent to the model. - - `INCOMPLETE("incomplete")` + - `Optional promptCacheBreakpoint` - - `JsonValue; type "program_output"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The item type. Always `program_output`. + - `JsonValue; mode "explicit"constant` - - `PROGRAM_OUTPUT("program_output")` + The breakpoint mode. Always `explicit`. - - `Optional agent` + - `EXPLICIT("explicit")` - The agent that produced this item. + - `Role role` - - `String agentName` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The canonical name of the agent that produced this item. + - `USER("user")` - - `Optional instructions` + - `ASSISTANT("assistant")` - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - `SYSTEM("system")` - - `Optional previousResponseId` + - `DEVELOPER("developer")` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `Optional phase` - - `Optional promptCacheKey` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - A key to use when reading from or writing to the prompt cache. + - `COMMENTARY("commentary")` - - `Optional promptCacheOptions` + - `FINAL_ANSWER("final_answer")` - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + - `Optional type` - - `Optional mode` + The type of the message input. Always `message`. - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + - `MESSAGE("message")` - - `IMPLICIT("implicit")` + - `Message` - - `EXPLICIT("explicit")` + - `List content` - - `Optional ttl` + A list of one or many input items to the model, containing different content + types. - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + - `class BetaResponseInputText:` - - `_30M("30m")` + A text input to the model. - - `Optional promptCacheRetention` + - `class BetaResponseInputImage:` - How long to retain a prompt cache entry created by this request. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `IN_MEMORY("in_memory")` + - `class BetaResponseInputFile:` - - `_24H("24h")` + A file input to the model. - - `Optional serviceTier` + - `Role role` - The service tier to use for this request. + The role of the message input. One of `user`, `system`, or `developer`. - - `AUTO("auto")` + - `USER("user")` - - `DEFAULT("default")` + - `SYSTEM("system")` - - `FLEX("flex")` + - `DEVELOPER("developer")` - - `PRIORITY("priority")` + - `Optional agent` -### Returns + The agent that produced this item. -- `class BetaCompactedResponse:` + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - The unique identifier for the compacted response. + - `Optional status` - - `long createdAt` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Unix timestamp (in seconds) when the compacted conversation was created. + - `IN_PROGRESS("in_progress")` - - `JsonValue; object_ "response.compaction"constant` + - `COMPLETED("completed")` - The object type. Always `response.compaction`. + - `INCOMPLETE("incomplete")` - - `RESPONSE_COMPACTION("response.compaction")` + - `Optional type` - - `List output` + The type of the message input. Always set to `message`. - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + - `MESSAGE("message")` - `class BetaResponseOutputMessage:` @@ -41338,6 +57771,8 @@ Compact a response - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -41414,66 +57849,36 @@ Compact a response The text that was retrieved from the file. - - `class BetaResponseFunctionToolCall:` + - `class BetaResponseComputerToolCall:` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `String arguments` + - `String id` - A JSON string of the arguments to pass to the function. + The unique ID of the computer call. - `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 id` - - The unique ID of the function tool call. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` + An identifier used when responding to the tool call with output. - - `DIRECT("direct")` + - `List pendingSafetyChecks` - - `class Program:` + The pending safety checks for the computer call. - - `String callerId` + - `String id` - The call ID of the program item that produced this tool call. + The ID of the pending safety check. - - `JsonValue; type "program"constant` + - `Optional code` - - `PROGRAM("program")` + The type of the pending safety check. - - `Optional namespace` + - `Optional message` - The namespace of the function to run. + Details about the pending safety check. - - `Optional status` + - `Status status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -41484,271 +57889,236 @@ Compact a response - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionToolCallOutputItem:` - - - `String id` - - The unique ID of the function call tool output. - - - `String callId` - - The unique ID of the function tool call generated by the model. - - - `Output output` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `String` - - - `List` - - - `class BetaResponseInputText:` - - 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Type type` - - `JsonValue; mode "explicit"constant` + The type of the computer call. Always `computer_call`. - The breakpoint mode. Always `explicit`. + - `COMPUTER_CALL("computer_call")` - - `EXPLICIT("explicit")` + - `Optional action` - - `class BetaResponseInputImage:` + A click action. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Click` - - `Detail detail` + - `Button button` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `LOW("low")` + - `LEFT("left")` - - `HIGH("high")` + - `RIGHT("right")` - - `AUTO("auto")` + - `WHEEL("wheel")` - - `ORIGINAL("original")` + - `BACK("back")` - - `JsonValue; type "input_image"constant` + - `FORWARD("forward")` - The type of the input item. Always `input_image`. + - `JsonValue; type "click"constant` - - `INPUT_IMAGE("input_image")` + Specifies the event type. For a click action, this property is always `click`. - - `Optional fileId` + - `CLICK("click")` - The ID of the file to be sent to the model. + - `long x` - - `Optional imageUrl` + The x-coordinate where the click occurred. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `long y` - - `Optional promptCacheBreakpoint` + The y-coordinate where the click occurred. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional> keys` - - `JsonValue; mode "explicit"constant` + The keys being held while clicking. - The breakpoint mode. Always `explicit`. + - `DoubleClick` - - `EXPLICIT("explicit")` + - `Optional> keys` - - `class BetaResponseInputFile:` + The keys being held while double-clicking. - A file input to the model. + - `JsonValue; type "double_click"constant` - - `JsonValue; type "input_file"constant` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The type of the input item. Always `input_file`. + - `DOUBLE_CLICK("double_click")` - - `INPUT_FILE("input_file")` + - `long x` - - `Optional detail` + The x-coordinate where the double click occurred. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `long y` - - `AUTO("auto")` + The y-coordinate where the double click occurred. - - `LOW("low")` + - `Drag` - - `HIGH("high")` + - `List path` - - `Optional fileData` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The content of the file to be sent to the model. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `Optional fileId` + - `long x` - The ID of the file to be sent to the model. + The x-coordinate. - - `Optional fileUrl` + - `long y` - The URL of the file to be sent to the model. + The y-coordinate. - - `Optional filename` + - `JsonValue; type "drag"constant` - The name of the file to be sent to the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `Optional promptCacheBreakpoint` + - `DRAG("drag")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional> keys` - - `JsonValue; mode "explicit"constant` + The keys being held while dragging the mouse. - The breakpoint mode. Always `explicit`. + - `Keypress` - - `EXPLICIT("explicit")` + - `List keys` - - `Status status` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `JsonValue; type "keypress"constant` - - `IN_PROGRESS("in_progress")` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `COMPLETED("completed")` + - `KEYPRESS("keypress")` - - `INCOMPLETE("incomplete")` + - `Move` - - `JsonValue; type "function_call_output"constant` + - `JsonValue; type "move"constant` - The type of the function tool call output. Always `function_call_output`. + Specifies the event type. For a move action, this property is always set to `move`. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `MOVE("move")` - - `Optional agent` + - `long x` - The agent that produced this item. + The x-coordinate to move to. - - `String agentName` + - `long y` - The canonical name of the agent that produced this item. + The y-coordinate to move to. - - `Optional caller` + - `Optional> keys` - The execution context that produced this tool call. + The keys being held while moving the mouse. - `JsonValue;` - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` + - `JsonValue; type "screenshot"constant` - - `String callerId` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The call ID of the program item that produced this tool call. + - `SCREENSHOT("screenshot")` - - `JsonValue; type "program"constant` + - `Scroll` - The caller type. Always `program`. + - `long scrollX` - - `PROGRAM("program")` + The horizontal scroll distance. - - `Optional createdBy` + - `long scrollY` - The identifier of the actor that created the item. + The vertical scroll distance. - - `AgentMessage` + - `JsonValue; type "scroll"constant` - - `String id` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The unique ID of the agent message. + - `SCROLL("scroll")` - - `String author` + - `long x` - The sending agent identity. + The x-coordinate where the scroll occurred. - - `List content` + - `long y` - Encrypted content sent between agents. + The y-coordinate where the scroll occurred. - - `class BetaResponseInputText:` + - `Optional> keys` - A text input to the model. + The keys being held while scrolling. - - `class BetaResponseOutputText:` + - `Type` - A text output from the model. + - `String text` - - `class Text:` + The text to type. - A text content. + - `JsonValue; type "type"constant` - - `String text` + Specifies the event type. For a type action, this property is always set to `type`. - - `JsonValue; type "text"constant` + - `TYPE("type")` - - `TEXT("text")` + - `JsonValue;` - - `class SummaryText:` + - `JsonValue; type "wait"constant` - A summary text from the model. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `String text` + - `WAIT("wait")` - A summary of the reasoning output from the model so far. + - `Optional> actions` - - `JsonValue; type "summary_text"constant` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the object. Always `summary_text`. + - `Click` - - `SUMMARY_TEXT("summary_text")` + - `DoubleClick` - - `class ReasoningText:` + - `Drag` - Reasoning text from the model. + - `Keypress` - - `String text` + - `Move` - The reasoning text from the model. + - `JsonValue;` - - `JsonValue; type "reasoning_text"constant` + - `Scroll` - The type of the reasoning text. Always `reasoning_text`. + - `Type` - - `REASONING_TEXT("reasoning_text")` + - `JsonValue;` - - `class BetaResponseOutputRefusal:` + - `Optional agent` - A refusal from the model. + The agent that produced this item. - - `class BetaResponseInputImage:` + - `String agentName` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `class ComputerScreenshot:` + - `ComputerCallOutput` - A screenshot of a computer. + - `String callId` - - `Detail detail` + The ID of the computer tool call that produced the output. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `LOW("low")` + A computer screenshot image used with the computer use tool. - - `HIGH("high")` + - `JsonValue; type "computer_screenshot"constant` - - `AUTO("auto")` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `ORIGINAL("original")` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - `Optional fileId` @@ -41758,93 +58128,31 @@ Compact a response 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `class EncryptedContent:` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `String encryptedContent` - - Opaque encrypted content. - - - `JsonValue; type "encrypted_content"constant` - - The type of the input item. Always `encrypted_content`. - - - `ENCRYPTED_CONTENT("encrypted_content")` - - - `String recipient` - - The destination agent identity. - - - `JsonValue; type "agent_message"constant` - - The type of the item. Always `agent_message`. + - `JsonValue; type "computer_call_output"constant` - - `AGENT_MESSAGE("agent_message")` + The type of the computer tool call output. Always `computer_call_output`. - - `Optional agent` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - The agent that produced this item. + - `Optional id` - - `String agentName` + The ID of the computer tool call output. - The canonical name of the agent that produced this item. + - `Optional> acknowledgedSafetyChecks` - - `MultiAgentCall` + The safety checks reported by the API that have been acknowledged by the developer. - `String id` - The unique ID of the multi-agent call item. - - - `Action action` - - The multi-agent action to execute. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` - - - `SEND_MESSAGE("send_message")` - - - `FOLLOWUP_TASK("followup_task")` - - - `WAIT_AGENT("wait_agent")` - - - `String arguments` - - The JSON string of arguments generated for the action. - - - `String callId` + The ID of the pending safety check. - The unique ID linking this call to its output. + - `Optional code` - - `JsonValue; type "multi_agent_call"constant` + The type of the pending safety check. - The type of the multi-agent call. Always `multi_agent_call`. + - `Optional message` - - `MULTI_AGENT_CALL("multi_agent_call")` + Details about the pending safety check. - `Optional agent` @@ -41854,63 +58162,15 @@ Compact a response The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `String id` - - The unique ID of the multi-agent call output item. - - - `Action action` - - The multi-agent action that produced this result. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` - - - `SEND_MESSAGE("send_message")` - - - `FOLLOWUP_TASK("followup_task")` - - - `WAIT_AGENT("wait_agent")` - - - `String callId` - - The unique ID of the multi-agent call. - - - `List output` - - Text output returned by the multi-agent action. - - - `List annotations` - - The annotations of the text output. - - - `String text` - - The text output from the model. - - - `JsonValue; type "output_text"constant` - - The type of the output text. Always `output_text`. - - - `Optional> logprobs` - - - `JsonValue; type "multi_agent_call_output"constant` - - The type of the multi-agent result. Always `multi_agent_call_output`. - - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `Optional status` - - `Optional agent` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The agent that produced this item. + - `IN_PROGRESS("in_progress")` - - `String agentName` + - `COMPLETED("completed")` - The canonical name of the agent that produced this item. + - `INCOMPLETE("incomplete")` - `class BetaResponseFunctionWebSearch:` @@ -42016,324 +58276,297 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall:` + - `class BetaResponseFunctionToolCall:` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `String id` + - `String arguments` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `String callId` - An identifier used when responding to the tool call with output. - - - `List pendingSafetyChecks` - - The pending safety checks for the computer call. - - - `String id` - - The ID of the pending safety check. - - - `Optional code` - - The type of the pending safety check. - - - `Optional message` - - Details about the pending safety check. + The unique ID of the function tool call generated by the model. - - `Status status` + - `String name` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the function to run. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "function_call"constant` - - `COMPLETED("completed")` + The type of the function tool call. Always `function_call`. - - `INCOMPLETE("incomplete")` + - `FUNCTION_CALL("function_call")` - - `Type type` + - `Optional id` - The type of the computer call. Always `computer_call`. + The unique ID of the function tool call. - - `COMPUTER_CALL("computer_call")` + - `Optional agent` - - `Optional action` + The agent that produced this item. - A click action. + - `String agentName` - - `Click` + The canonical name of the agent that produced this item. - - `Button button` + - `Optional caller` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The execution context that produced this tool call. - - `LEFT("left")` + - `JsonValue;` - - `RIGHT("right")` + - `JsonValue; type "direct"constant` - - `WHEEL("wheel")` + - `DIRECT("direct")` - - `BACK("back")` + - `class Program:` - - `FORWARD("forward")` + - `String callerId` - - `JsonValue; type "click"constant` + The call ID of the program item that produced this tool call. - Specifies the event type. For a click action, this property is always `click`. + - `JsonValue; type "program"constant` - - `CLICK("click")` + - `PROGRAM("program")` - - `long x` + - `Optional namespace` - The x-coordinate where the click occurred. + The namespace of the function to run. - - `long y` + - `Optional status` - The y-coordinate where the click occurred. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional> keys` + - `IN_PROGRESS("in_progress")` - The keys being held while clicking. + - `COMPLETED("completed")` - - `DoubleClick` + - `INCOMPLETE("incomplete")` - - `Optional> keys` + - `FunctionCallOutput` - The keys being held while double-clicking. + - `String callId` - - `JsonValue; type "double_click"constant` + The unique ID of the function tool call generated by the model. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `Output output` - - `DOUBLE_CLICK("double_click")` + Text, image, or file output of the function tool call. - - `long x` + - `String` - The x-coordinate where the double click occurred. + - `List` - - `long y` + - `class BetaResponseInputTextContent:` - The y-coordinate where the double click occurred. + A text input to the model. - - `Drag` + - `String text` - - `List path` + The text input to the model. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `JsonValue; type "input_text"constant` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The type of the input item. Always `input_text`. - - `long x` + - `INPUT_TEXT("input_text")` - The x-coordinate. + - `Optional promptCacheBreakpoint` - - `long y` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The y-coordinate. + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "drag"constant` + The breakpoint mode. Always `explicit`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `EXPLICIT("explicit")` - - `DRAG("drag")` + - `class BetaResponseInputImageContent:` - - `Optional> keys` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The keys being held while dragging the mouse. + - `JsonValue; type "input_image"constant` - - `Keypress` + The type of the input item. Always `input_image`. - - `List keys` + - `INPUT_IMAGE("input_image")` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `Optional detail` - - `JsonValue; type "keypress"constant` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `LOW("low")` - - `KEYPRESS("keypress")` + - `HIGH("high")` - - `Move` + - `AUTO("auto")` - - `JsonValue; type "move"constant` + - `ORIGINAL("original")` - Specifies the event type. For a move action, this property is always set to `move`. + - `Optional fileId` - - `MOVE("move")` + The ID of the file to be sent to the model. - - `long x` + - `Optional imageUrl` - The x-coordinate to move to. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `long y` + - `Optional promptCacheBreakpoint` - The y-coordinate to move to. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional> keys` + - `JsonValue; mode "explicit"constant` - The keys being held while moving the mouse. + The breakpoint mode. Always `explicit`. - - `JsonValue;` + - `EXPLICIT("explicit")` - - `JsonValue; type "screenshot"constant` + - `class BetaResponseInputFileContent:` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + A file input to the model. - - `SCREENSHOT("screenshot")` + - `JsonValue; type "input_file"constant` - - `Scroll` + The type of the input item. Always `input_file`. - - `long scrollX` + - `INPUT_FILE("input_file")` - The horizontal scroll distance. + - `Optional detail` - - `long scrollY` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The vertical scroll distance. + - `AUTO("auto")` - - `JsonValue; type "scroll"constant` + - `LOW("low")` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `HIGH("high")` - - `SCROLL("scroll")` + - `Optional fileData` - - `long x` + The base64-encoded data of the file to be sent to the model. - The x-coordinate where the scroll occurred. + - `Optional fileId` - - `long y` + The ID of the file to be sent to the model. - The y-coordinate where the scroll occurred. + - `Optional fileUrl` - - `Optional> keys` + The URL of the file to be sent to the model. - The keys being held while scrolling. + - `Optional filename` - - `Type` + The name of the file to be sent to the model. - - `String text` + - `Optional promptCacheBreakpoint` - The text to type. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "type"constant` + - `JsonValue; mode "explicit"constant` - Specifies the event type. For a type action, this property is always set to `type`. + The breakpoint mode. Always `explicit`. - - `TYPE("type")` + - `EXPLICIT("explicit")` - - `JsonValue;` + - `JsonValue; type "function_call_output"constant` - - `JsonValue; type "wait"constant` + The type of the function tool call output. Always `function_call_output`. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `WAIT("wait")` + - `Optional id` - - `Optional> actions` + The unique ID of the function tool call output. Populated when this item is returned via API. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `Optional agent` - - `Click` + The agent that produced this item. - - `DoubleClick` + - `String agentName` - - `Drag` + The canonical name of the agent that produced this item. - - `Keypress` + - `Optional caller` - - `Move` + The execution context that produced this tool call. - `JsonValue;` - - `Scroll` - - - `Type` + - `JsonValue; type "direct"constant` - - `JsonValue;` + The caller type. Always `direct`. - - `Optional agent` + - `DIRECT("direct")` - The agent that produced this item. + - `class Program:` - - `String agentName` + - `String callerId` - The canonical name of the agent that produced this item. + The call ID of the program item that produced this tool call. - - `class BetaResponseComputerToolCallOutputItem:` + - `JsonValue; type "program"constant` - - `String id` + The caller type. Always `program`. - The unique ID of the computer call tool output. + - `PROGRAM("program")` - - `String callId` + - `Optional status` - The ID of the computer tool call that produced the output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `IN_PROGRESS("in_progress")` - A computer screenshot image used with the computer use tool. + - `COMPLETED("completed")` - - `JsonValue; type "computer_screenshot"constant` + - `INCOMPLETE("incomplete")` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `AgentMessage` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `String author` - - `Optional fileId` + The sending agent identity. - The identifier of an uploaded file that contains the screenshot. + - `List content` - - `Optional imageUrl` + Plaintext, image, or encrypted content sent between agents. - The URL of the screenshot image. + - `class BetaResponseInputTextContent:` - - `Status status` + A text input to the model. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaResponseInputImageContent:` - - `COMPLETED("completed")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `INCOMPLETE("incomplete")` + - `class EncryptedContent:` - - `FAILED("failed")` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `IN_PROGRESS("in_progress")` + - `String encryptedContent` - - `JsonValue; type "computer_call_output"constant` + Opaque encrypted content. - The type of the computer tool call output. Always `computer_call_output`. + - `JsonValue; type "encrypted_content"constant` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The type of the input item. Always `encrypted_content`. - - `Optional> acknowledgedSafetyChecks` + - `ENCRYPTED_CONTENT("encrypted_content")` - The safety checks reported by the API that have been acknowledged by the - developer. + - `String recipient` - - `String id` + The destination agent identity. - The ID of the pending safety check. + - `JsonValue; type "agent_message"constant` - - `Optional code` + The item type. Always `agent_message`. - The type of the pending safety check. + - `AGENT_MESSAGE("agent_message")` - - `Optional message` + - `Optional id` - Details about the pending safety check. + The unique ID of this agent message item. - `Optional agent` @@ -42343,40 +58576,41 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional createdBy` + - `MultiAgentCall` - The identifier of the actor that created the item. + - `Action action` - - `class BetaResponseReasoningItem:` + The multi-agent action that was executed. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `SPAWN_AGENT("spawn_agent")` - - `String id` + - `INTERRUPT_AGENT("interrupt_agent")` - The unique identifier of the reasoning content. + - `LIST_AGENTS("list_agents")` - - `List summary` + - `SEND_MESSAGE("send_message")` - Reasoning summary content. + - `FOLLOWUP_TASK("followup_task")` - - `String text` + - `WAIT_AGENT("wait_agent")` - A summary of the reasoning output from the model so far. + - `String arguments` - - `JsonValue; type "summary_text"constant` + The action arguments as a JSON string. - The type of the object. Always `summary_text`. + - `String callId` - - `SUMMARY_TEXT("summary_text")` + The unique ID linking this call to its output. - - `JsonValue; type "reasoning"constant` + - `JsonValue; type "multi_agent_call"constant` - The type of the object. Always `reasoning`. + The item type. Always `multi_agent_call`. - - `REASONING("reasoning")` + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional id` + + The unique ID of this multi-agent call. - `Optional agent` @@ -42386,142 +58620,152 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional> content` + - `MultiAgentCallOutput` - Reasoning text content. + - `Action action` - - `String text` + The multi-agent action that produced this result. - The reasoning text from the model. + - `SPAWN_AGENT("spawn_agent")` - - `JsonValue; type "reasoning_text"constant` + - `INTERRUPT_AGENT("interrupt_agent")` - The type of the reasoning text. Always `reasoning_text`. + - `LIST_AGENTS("list_agents")` - - `REASONING_TEXT("reasoning_text")` + - `SEND_MESSAGE("send_message")` - - `Optional encryptedContent` + - `FOLLOWUP_TASK("followup_task")` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `WAIT_AGENT("wait_agent")` - - `Optional status` + - `String callId` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique ID of the multi-agent call. - - `IN_PROGRESS("in_progress")` + - `List output` - - `COMPLETED("completed")` + Text output returned by the multi-agent action. - - `INCOMPLETE("incomplete")` + - `String text` - - `Program` + The text content. - - `String id` + - `JsonValue; type "output_text"constant` - The unique ID of the program item. + The content type. Always `output_text`. - - `String callId` + - `OUTPUT_TEXT("output_text")` - The stable call ID of the program item. + - `Optional annotations` - - `String code` + Citations associated with the text content. - The JavaScript source executed by programmatic tool calling. + - `List` - - `String fingerprint` + - `String fileId` - Opaque program replay fingerprint that must be round-tripped. + The ID of the file. - - `JsonValue; type "program"constant` + - `String filename` - The type of the item. Always `program`. + The filename of the file cited. - - `PROGRAM("program")` + - `long index` - - `Optional agent` + The index of the file in the list of files. - The agent that produced this item. + - `JsonValue; type "file_citation"constant` - - `String agentName` + The citation type. Always `file_citation`. - The canonical name of the agent that produced this item. + - `FILE_CITATION("file_citation")` - - `ProgramOutput` + - `List` - - `String id` + - `long endIndex` - The unique ID of the program output item. + The index of the last character of the citation in the message. - - `String callId` + - `long startIndex` - The call ID of the program item. + The index of the first character of the citation in the message. - - `String result` + - `String title` - The result produced by the program item. + The title of the cited resource. - - `Status status` + - `JsonValue; type "url_citation"constant` - The terminal status of the program output item. + The citation type. Always `url_citation`. - - `COMPLETED("completed")` + - `URL_CITATION("url_citation")` - - `INCOMPLETE("incomplete")` + - `String url` - - `JsonValue; type "program_output"constant` + The URL of the cited resource. - The type of the item. Always `program_output`. + - `List` - - `PROGRAM_OUTPUT("program_output")` + - `String containerId` - - `Optional agent` + The ID of the container. - The agent that produced this item. + - `long endIndex` - - `String agentName` + The index of the last character of the citation in the message. - The canonical name of the agent that produced this item. + - `String fileId` - - `class BetaResponseToolSearchCall:` + The ID of the container file. - - `String id` + - `String filename` - The unique ID of the tool search call item. + The filename of the container file cited. - - `JsonValue arguments` + - `long startIndex` - Arguments used for the tool search call. + The index of the first character of the citation in the message. - - `Optional callId` + - `JsonValue; type "container_file_citation"constant` - The unique ID of the tool search call generated by the model. + The citation type. Always `container_file_citation`. - - `Execution execution` + - `CONTAINER_FILE_CITATION("container_file_citation")` - Whether tool search was executed by the server or by the client. + - `JsonValue; type "multi_agent_call_output"constant` - - `SERVER("server")` + The item type. Always `multi_agent_call_output`. - - `CLIENT("client")` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `Status status` + - `Optional id` - The status of the tool search call item that was recorded. + The unique ID of this multi-agent call output. - - `IN_PROGRESS("in_progress")` + - `Optional agent` - - `COMPLETED("completed")` + The agent that produced this item. - - `INCOMPLETE("incomplete")` + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ToolSearchCall` + + - `JsonValue arguments` + + The arguments supplied to the tool search call. - `JsonValue; type "tool_search_call"constant` - The type of the item. Always `tool_search_call`. + The item type. Always `tool_search_call`. - `TOOL_SEARCH_CALL("tool_search_call")` + - `Optional id` + + The unique ID of this tool search call. + - `Optional agent` The agent that produced this item. @@ -42530,21 +58774,11 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem:` - - - `String id` - - The unique ID of the tool search output item. - - `Optional callId` The unique ID of the tool search call generated by the model. - - `Execution execution` + - `Optional execution` Whether tool search was executed by the server or by the client. @@ -42552,9 +58786,9 @@ Compact a response - `CLIENT("client")` - - `Status status` + - `Optional status` - The status of the tool search output item that was recorded. + The status of the tool search call. - `IN_PROGRESS("in_progress")` @@ -42562,9 +58796,11 @@ Compact a response - `INCOMPLETE("incomplete")` + - `class BetaResponseToolSearchOutputItemParam:` + - `List tools` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool:` @@ -42673,7 +58909,11 @@ Compact a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -42730,7 +58970,11 @@ Compact a response - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -43627,10 +59871,14 @@ Compact a response - `JsonValue; type "tool_search_output"constant` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `Optional id` + + The unique ID of this tool search output. + - `Optional agent` The agent that produced this item. @@ -43639,39 +59887,39 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional callId` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `AdditionalTools` + - `Optional execution` - - `String id` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `SERVER("server")` - - `Role role` + - `CLIENT("client")` - The role that provided the additional tools. + - `Optional status` - - `UNKNOWN("unknown")` + The status of the tool search output. - - `USER("user")` + - `IN_PROGRESS("in_progress")` - - `ASSISTANT("assistant")` + - `COMPLETED("completed")` - - `SYSTEM("system")` + - `INCOMPLETE("incomplete")` - - `CRITIC("critic")` + - `AdditionalTools` - - `DISCRIMINATOR("discriminator")` + - `JsonValue; role "developer"constant` - - `DEVELOPER("developer")` + The role that provided the additional tools. Only `developer` is supported. - - `TOOL("tool")` + - `DEVELOPER("developer")` - `List tools` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool:` @@ -43730,10 +59978,14 @@ Compact a response - `JsonValue; type "additional_tools"constant` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `ADDITIONAL_TOOLS("additional_tools")` + - `Optional id` + + The unique ID of this additional tools item. + - `Optional agent` The agent that produced this item. @@ -43742,17 +59994,82 @@ Compact a response The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` + - `class BetaResponseReasoningItem:` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `String id` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> 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 encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional 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 BetaResponseCompactionItemParam:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `String encryptedContent` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `JsonValue; type "compaction"constant` @@ -43760,6 +60077,10 @@ Compact a response - `COMPACTION("compaction")` + - `Optional id` + + The ID of the compaction item. + - `Optional agent` The agent that produced this item. @@ -43768,10 +60089,6 @@ Compact a response The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - `ImageGenerationCall` - `String id` @@ -43983,582 +60300,37 @@ Compact a response - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionShellToolCall:` - - A tool call that executes one or more shell commands in a managed environment. - - - `String id` - - The unique ID of the shell tool call. Populated when this item is returned via API. + - `ShellCall` - `Action action` The shell commands and limits that describe how to run the tool call. - - `List commands` - - - `Optional maxOutputLength` - - Optional maximum number of characters to return from each command. - - - `Optional timeoutMs` - - Optional timeout in milliseconds for the commands. - - - `String callId` - - The unique ID of the shell tool call generated by the model. - - - `Optional environment` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment:` - - Represents the use of a local environment to perform shell actions. - - - `JsonValue; type "local"constant` - - The environment type. Always `local`. - - - `LOCAL("local")` - - - `class BetaResponseContainerReference:` - - Represents a container created with /v1/containers. - - - `String containerId` - - - `JsonValue; type "container_reference"constant` - - The environment type. Always `container_reference`. - - - `CONTAINER_REFERENCE("container_reference")` - - - `Status status` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `JsonValue; type "shell_call"constant` - - The type of the item. Always `shell_call`. - - - `SHELL_CALL("shell_call")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call. - - - `class BetaResponseFunctionShellToolCallOutput:` - - The output of a shell tool call that was emitted. - - - `String id` - - The unique ID of the shell call output. Populated when this item is returned via API. - - - `String callId` - - The unique ID of the shell tool call generated by the model. - - - `Optional maxOutputLength` - - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - - `List output` - - An array of shell call output contents - - - `Outcome outcome` - - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - - `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` - - Exit code from the shell process. - - - `JsonValue; type "exit"constant` - - The outcome type. Always `exit`. - - - `EXIT("exit")` - - - `String stderr` - - The standard error output that was captured. - - - `String stdout` - - The standard output that was captured. - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `Status status` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `JsonValue; type "shell_call_output"constant` - - The type of the shell call output. Always `shell_call_output`. - - - `SHELL_CALL_OUTPUT("shell_call_output")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `class BetaResponseApplyPatchToolCall:` - - A tool call that applies file diffs by creating, deleting, or updating files. - - - `String id` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `String callId` - - The unique ID of the apply patch tool call generated by the model. - - - `Operation operation` - - One of the create_file, delete_file, or update_file operations applied via apply_patch. - - - `class CreateFile:` - - Instruction describing how to create a file via the apply_patch tool. - - - `String diff` - - Diff to apply. - - - `String path` - - Path of the file to create. - - - `JsonValue; type "create_file"constant` - - Create a new file with the provided diff. - - - `CREATE_FILE("create_file")` - - - `class DeleteFile:` - - Instruction describing how to delete a file via the apply_patch tool. - - - `String path` - - Path of the file to delete. - - - `JsonValue; type "delete_file"constant` - - Delete the specified file. - - - `DELETE_FILE("delete_file")` - - - `class UpdateFile:` - - Instruction describing how to update a file via the apply_patch tool. - - - `String diff` - - Diff to apply. - - - `String path` - - Path of the file to update. - - - `JsonValue; type "update_file"constant` - - Update an existing file with the provided diff. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput:` - - The output emitted by an apply patch tool call. - - - `String id` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call output. - - - `Optional output` - - Optional textual output returned by the apply patch tool. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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 error` - - The error from the tool call, if any. - - - `Optional output` - - The output from the tool call. - - - `Optional 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")` - - - `McpListTools` - - - `String id` - - The unique ID of the list. - - - `String serverLabel` - - The label of the MCP server. - - - `List 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 annotations` - - Additional annotations about the tool. - - - `Optional 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `McpApprovalResponse` - - - `String id` - - The unique ID of the approval response - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional reason` - - Optional reason for the decision. - - - `class BetaResponseCustomToolCall:` + - `List commands` - A call to a custom tool created by the model. + Ordered shell commands for the execution environment to run. - - `String callId` + - `Optional maxOutputLength` - An identifier used to map this custom tool call to a tool call output. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `String input` + - `Optional timeoutMs` - The input for the custom tool call generated by the model. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `String name` + - `String callId` - The name of the custom tool being called. + The unique ID of the shell tool call generated by the model. - - `JsonValue; type "custom_tool_call"constant` + - `JsonValue; type "shell_call"constant` - The type of the custom tool call. Always `custom_tool_call`. + The type of the item. Always `shell_call`. - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `SHELL_CALL("shell_call")` - `Optional id` - The unique ID of the custom tool call in the OpenAI platform. + The unique ID of the shell tool call. Populated when this item is returned via API. - `Optional agent` @@ -44576,6 +60348,8 @@ Compact a response - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -44586,24 +60360,21 @@ Compact a response - `JsonValue; type "program"constant` - - `PROGRAM("program")` - - - `Optional namespace` + The caller type. Always `program`. - The namespace of the custom tool being called. + - `PROGRAM("program")` - - `class BetaResponseCustomToolCallOutputItem:` + - `Optional environment` - The output of a custom tool call from your code, being sent back to the model. + The environment to execute the shell commands in. - - `String id` + - `class BetaLocalEnvironment:` - The unique ID of the custom tool call output item. + - `class BetaContainerReference:` - - `Status status` + - `Optional status` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` @@ -44611,409 +60382,347 @@ Compact a response - `INCOMPLETE("incomplete")` - - `Optional createdBy` - - The identifier of the actor that created the item. + - `ShellCallOutput` - - `BetaResponseUsage usage` + - `String callId` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + The unique ID of the shell tool call generated by the model. - - `long inputTokens` + - `List output` - The number of input tokens. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `InputTokensDetails inputTokensDetails` + - `Outcome outcome` - A detailed breakdown of the input tokens. + The exit or timeout outcome associated with this shell call. - - `long cacheWriteTokens` + - `JsonValue;` - The number of input tokens that were written to the cache. + - `JsonValue; type "timeout"constant` - - `long cachedTokens` + The outcome type. Always `timeout`. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `TIMEOUT("timeout")` - - `long outputTokens` + - `class Exit:` - The number of output tokens. + Indicates that the shell commands finished and returned an exit code. - - `OutputTokensDetails outputTokensDetails` + - `long exitCode` - A detailed breakdown of the output tokens. + The exit code returned by the shell process. - - `long reasoningTokens` + - `JsonValue; type "exit"constant` - The number of reasoning tokens. + The outcome type. Always `exit`. - - `long totalTokens` + - `EXIT("exit")` - The total number of tokens used. + - `String stderr` -### Example + Captured stderr output for the shell call. -```java -package com.openai.example; + - `String stdout` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.responses.BetaCompactedResponse; -import com.openai.models.beta.responses.ResponseCompactParams; + Captured stdout output for the shell call. -public final class Main { - private Main() {} + - `JsonValue; type "shell_call_output"constant` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + The type of the item. Always `shell_call_output`. - ResponseCompactParams params = ResponseCompactParams.builder() - .model(ResponseCompactParams.Model.GPT_5_6_SOL) - .build(); - BetaCompactedResponse betaCompactedResponse = client.beta().responses().compact(params); - } -} -``` + - `SHELL_CALL_OUTPUT("shell_call_output")` -#### Response + - `Optional id` -```json -{ - "id": "id", - "created_at": 0, - "object": "response.compaction", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "text": "text", - "type": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ] - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "phase": "commentary" - } - ], - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - } -} -``` + The unique ID of the shell tool call output. Populated when this item is returned via API. -## Domain Types + - `Optional agent` -### Beta Apply Patch Tool + The agent that produced this item. -- `class BetaApplyPatchTool:` + - `String agentName` - Allows the assistant to create, delete, or update files using unified diffs. + The canonical name of the agent that produced this item. - - `JsonValue; type "apply_patch"constant` + - `Optional caller` - The type of the tool. Always `apply_patch`. + The execution context that produced this tool call. - - `APPLY_PATCH("apply_patch")` + - `JsonValue;` - - `Optional> allowedCallers` + - `JsonValue; type "direct"constant` - The tool invocation context(s). + The caller type. Always `direct`. - `DIRECT("direct")` - - `PROGRAMMATIC("programmatic")` + - `class Program:` -### Beta Compacted Response + - `String callerId` -- `class BetaCompactedResponse:` + The call ID of the program item that produced this tool call. - - `String id` + - `JsonValue; type "program"constant` - The unique identifier for the compacted response. + The caller type. Always `program`. - - `long createdAt` + - `PROGRAM("program")` - Unix timestamp (in seconds) when the compacted conversation was created. + - `Optional maxOutputLength` - - `JsonValue; object_ "response.compaction"constant` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The object type. Always `response.compaction`. + - `Optional status` - - `RESPONSE_COMPACTION("response.compaction")` + The status of the shell call output. - - `List output` + - `IN_PROGRESS("in_progress")` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + - `COMPLETED("completed")` - - `class BetaResponseOutputMessage:` + - `INCOMPLETE("incomplete")` - An output message from the model. + - `ApplyPatchCall` - - `String id` + - `String callId` - The unique ID of the output message. + The unique ID of the apply patch tool call generated by the model. - - `List content` + - `Operation operation` - The content of the output message. + The specific create, delete, or update instruction for the apply_patch tool call. - - `class BetaResponseOutputText:` + - `class CreateFile:` - A text output from the model. + Instruction for creating a new file via the apply_patch tool. - - `List annotations` + - `String diff` - The annotations of the text output. + Unified diff content to apply when creating the file. - - `class FileCitation:` + - `String path` - A citation to a file. + Path of the file to create relative to the workspace root. - - `String fileId` + - `JsonValue; type "create_file"constant` - The ID of the file. + The operation type. Always `create_file`. - - `String filename` + - `CREATE_FILE("create_file")` - The filename of the file cited. + - `class DeleteFile:` - - `long index` + Instruction for deleting an existing file via the apply_patch tool. - The index of the file in the list of files. + - `String path` - - `JsonValue; type "file_citation"constant` + Path of the file to delete relative to the workspace root. - The type of the file citation. Always `file_citation`. + - `JsonValue; type "delete_file"constant` - - `FILE_CITATION("file_citation")` + The operation type. Always `delete_file`. - - `class UrlCitation:` + - `DELETE_FILE("delete_file")` - A citation for a web resource used to generate a model response. + - `class UpdateFile:` - - `long endIndex` + Instruction for updating an existing file via the apply_patch tool. - The index of the last character of the URL citation in the message. + - `String diff` - - `long startIndex` + Unified diff content to apply to the existing file. - The index of the first character of the URL citation in the message. + - `String path` - - `String title` + Path of the file to update relative to the workspace root. - The title of the web resource. + - `JsonValue; type "update_file"constant` - - `JsonValue; type "url_citation"constant` + The operation type. Always `update_file`. - The type of the URL citation. Always `url_citation`. + - `UPDATE_FILE("update_file")` - - `URL_CITATION("url_citation")` + - `Status status` - - `String url` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The URL of the web resource. + - `IN_PROGRESS("in_progress")` - - `class ContainerFileCitation:` + - `COMPLETED("completed")` - A citation for a container file used to generate a model response. + - `JsonValue; type "apply_patch_call"constant` - - `String containerId` + The type of the item. Always `apply_patch_call`. - The ID of the container file. + - `APPLY_PATCH_CALL("apply_patch_call")` - - `long endIndex` + - `Optional id` - The index of the last character of the container file citation in the message. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `String fileId` + - `Optional agent` - The ID of the file. + The agent that produced this item. - - `String filename` + - `String agentName` - The filename of the container file cited. + The canonical name of the agent that produced this item. - - `long startIndex` + - `Optional caller` - The index of the first character of the container file citation in the message. + The execution context that produced this tool call. - - `JsonValue; type "container_file_citation"constant` + - `JsonValue;` - The type of the container file citation. Always `container_file_citation`. + - `JsonValue; type "direct"constant` - - `CONTAINER_FILE_CITATION("container_file_citation")` + The caller type. Always `direct`. - - `class FilePath:` + - `DIRECT("direct")` - A path to a file. + - `class Program:` - - `String fileId` + - `String callerId` - The ID of the file. + The call ID of the program item that produced this tool call. - - `long index` + - `JsonValue; type "program"constant` - The index of the file in the list of files. + The caller type. Always `program`. - - `JsonValue; type "file_path"constant` + - `PROGRAM("program")` - The type of the file path. Always `file_path`. + - `ApplyPatchCallOutput` - - `FILE_PATH("file_path")` + - `String callId` - - `String text` + The unique ID of the apply patch tool call generated by the model. - The text output from the model. + - `Status status` - - `JsonValue; type "output_text"constant` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the output text. Always `output_text`. + - `COMPLETED("completed")` - - `OUTPUT_TEXT("output_text")` + - `FAILED("failed")` - - `Optional> logprobs` + - `JsonValue; type "apply_patch_call_output"constant` - - `String token` + The type of the item. Always `apply_patch_call_output`. - - `List bytes` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `double logprob` + - `Optional id` - - `List topLogprobs` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `String token` + - `Optional agent` - - `List bytes` + The agent that produced this item. - - `double logprob` + - `String agentName` - - `class BetaResponseOutputRefusal:` + The canonical name of the agent that produced this item. - A refusal from the model. + - `Optional caller` - - `String refusal` + The execution context that produced this tool call. - The refusal explanation from the model. + - `JsonValue;` - - `JsonValue; type "refusal"constant` + - `JsonValue; type "direct"constant` - The type of the refusal. Always `refusal`. + The caller type. Always `direct`. - - `REFUSAL("refusal")` + - `DIRECT("direct")` - - `JsonValue; role "assistant"constant` + - `class Program:` - The role of the output message. Always `assistant`. + - `String callerId` - - `ASSISTANT("assistant")` + The call ID of the program item that produced this tool call. - - `Status status` + - `JsonValue; type "program"constant` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The caller type. Always `program`. - - `IN_PROGRESS("in_progress")` + - `PROGRAM("program")` - - `COMPLETED("completed")` + - `Optional output` - - `INCOMPLETE("incomplete")` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `JsonValue; type "message"constant` + - `McpListTools` - The type of the output message. Always `message`. + - `String id` - - `MESSAGE("message")` + The unique ID of the list. - - `Optional agent` + - `String serverLabel` - The agent that produced this item. + The label of the MCP server. - - `String agentName` + - `List tools` - The canonical name of the agent that produced this item. + The tools available on the server. - - `Optional phase` + - `JsonValue inputSchema` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The JSON schema describing the tool's input. - - `COMMENTARY("commentary")` + - `String name` - - `class BetaResponseFileSearchToolCall:` + The name of the tool. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `Optional annotations` - - `String id` + Additional annotations about the tool. - The unique ID of the file search tool call. + - `Optional description` - - `List queries` + The description of the tool. - The queries used to search for files. + - `JsonValue; type "mcp_list_tools"constant` - - `Status status` + The type of the item. Always `mcp_list_tools`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `MCP_LIST_TOOLS("mcp_list_tools")` - - `IN_PROGRESS("in_progress")` + - `Optional agent` - - `SEARCHING("searching")` + The agent that produced this item. - - `COMPLETED("completed")` + - `String agentName` - - `INCOMPLETE("incomplete")` + The canonical name of the agent that produced this item. - - `FAILED("failed")` + - `Optional error` - - `JsonValue; type "file_search_call"constant` + Error message if the server could not list tools. - The type of the file search tool call. Always `file_search_call`. + - `McpApprovalRequest` - - `FILE_SEARCH_CALL("file_search_call")` + - `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")` - `Optional agent` @@ -45023,66 +60732,61 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional> results` + - `McpApprovalResponse` - The results of the file search tool call. + - `String approvalRequestId` - - `Optional attributes` + The ID of the approval request being answered. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `boolean approve` - - `String` + Whether the request was approved. - - `double` + - `JsonValue; type "mcp_approval_response"constant` - - `boolean` + The type of the item. Always `mcp_approval_response`. - - `Optional fileId` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - The unique ID of the file. + - `Optional id` - - `Optional filename` + The unique ID of the approval response - The name of the file. + - `Optional agent` - - `Optional score` + The agent that produced this item. - The relevance score of the file - a value between 0 and 1. + - `String agentName` - - `Optional text` + The canonical name of the agent that produced this item. - The text that was retrieved from the file. + - `Optional reason` - - `class BetaResponseFunctionToolCall:` + Optional reason for the decision. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `McpCall` - - `String arguments` + - `String id` - A JSON string of the arguments to pass to the function. + The unique ID of the tool call. - - `String callId` + - `String arguments` - The unique ID of the function tool call generated by the model. + A JSON string of the arguments passed to the tool. - `String name` - The name of the function to run. + The name of the tool that was run. - - `JsonValue; type "function_call"constant` + - `String serverLabel` - The type of the function tool call. Always `function_call`. + The label of the MCP server running the tool. - - `FUNCTION_CALL("function_call")` + - `JsonValue; type "mcp_call"constant` - - `Optional id` + The type of the item. Always `mcp_call`. - The unique ID of the function tool call. + - `MCP_CALL("mcp_call")` - `Optional agent` @@ -45092,34 +60796,22 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` + - `Optional approvalRequestId` - The call ID of the program item that produced this tool call. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `JsonValue; type "program"constant` + - `Optional error` - - `PROGRAM("program")` + The error from the tool call, if any. - - `Optional namespace` + - `Optional output` - The namespace of the function to run. + The output from the tool call. - `Optional status` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `IN_PROGRESS("in_progress")` @@ -45127,19 +60819,21 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionToolCallOutputItem:` + - `CALLING("calling")` - - `String id` + - `FAILED("failed")` - The unique ID of the function call tool output. + - `class BetaResponseCustomToolCallOutput:` + + The output of a custom tool call from your code, being sent back to the model. - `String callId` - The unique ID of the function tool call generated by the model. + The call ID, used to map this custom tool call output to a custom tool call. - `Output output` - The output from the function call generated by your code. + The output from the custom tool call generated by your code. Can be a string or an list of output content. - `String` @@ -45150,128 +60844,121 @@ public final class Main { 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`. + - `class BetaResponseInputImage:` - - `INPUT_TEXT("input_text")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional promptCacheBreakpoint` + - `class BetaResponseInputFile:` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A file input to the model. - - `JsonValue; mode "explicit"constant` + - `JsonValue; type "custom_tool_call_output"constant` - The breakpoint mode. Always `explicit`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `EXPLICIT("explicit")` + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - - `class BetaResponseInputImage:` + - `Optional id` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of the custom tool call output in the OpenAI platform. - - `Detail detail` + - `Optional agent` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `LOW("low")` + - `String agentName` - - `HIGH("high")` + The canonical name of the agent that produced this item. - - `AUTO("auto")` + - `Optional caller` - - `ORIGINAL("original")` + The execution context that produced this tool call. - - `JsonValue; type "input_image"constant` + - `JsonValue;` - The type of the input item. Always `input_image`. + - `JsonValue; type "direct"constant` - - `INPUT_IMAGE("input_image")` + The caller type. Always `direct`. - - `Optional fileId` + - `DIRECT("direct")` - The ID of the file to be sent to the model. + - `class Program:` - - `Optional imageUrl` + - `String callerId` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The call ID of the program item that produced this tool call. - - `Optional promptCacheBreakpoint` + - `JsonValue; type "program"constant` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The caller type. Always `program`. - - `JsonValue; mode "explicit"constant` + - `PROGRAM("program")` - The breakpoint mode. Always `explicit`. + - `class BetaResponseCustomToolCall:` - - `EXPLICIT("explicit")` + A call to a custom tool created by the model. - - `class BetaResponseInputFile:` + - `String callId` - A file input to the model. + An identifier used to map this custom tool call to a tool call output. - - `JsonValue; type "input_file"constant` + - `String input` - The type of the input item. Always `input_file`. + The input for the custom tool call generated by the model. - - `INPUT_FILE("input_file")` + - `String name` - - `Optional detail` + The name of the custom tool being called. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `JsonValue; type "custom_tool_call"constant` - - `AUTO("auto")` + The type of the custom tool call. Always `custom_tool_call`. - - `LOW("low")` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - - `HIGH("high")` + - `Optional id` - - `Optional fileData` + The unique ID of the custom tool call in the OpenAI platform. - The content of the file to be sent to the model. + - `Optional agent` - - `Optional fileId` + The agent that produced this item. - The ID of the file to be sent to the model. + - `String agentName` - - `Optional fileUrl` + The canonical name of the agent that produced this item. - The URL of the file to be sent to the model. + - `Optional caller` - - `Optional filename` + The execution context that produced this tool call. - The name of the file to be sent to the model. + - `JsonValue;` - - `Optional promptCacheBreakpoint` + - `JsonValue; type "direct"constant` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `DIRECT("direct")` - - `JsonValue; mode "explicit"constant` + - `class Program:` - The breakpoint mode. Always `explicit`. + - `String callerId` - - `EXPLICIT("explicit")` + The call ID of the program item that produced this tool call. - - `Status status` + - `JsonValue; type "program"constant` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `PROGRAM("program")` - - `IN_PROGRESS("in_progress")` + - `Optional namespace` - - `COMPLETED("completed")` + The namespace of the custom tool being called. - - `INCOMPLETE("incomplete")` + - `CompactionTrigger` - - `JsonValue; type "function_call_output"constant` + - `JsonValue; type "compaction_trigger"constant` - The type of the function tool call output. Always `function_call_output`. + The type of the item. Always `compaction_trigger`. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `COMPACTION_TRIGGER("compaction_trigger")` - `Optional agent` @@ -45281,375 +60968,378 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. + - `ItemReference` - - `DIRECT("direct")` + - `String id` - - `class Program:` + The ID of the item to reference. - - `String callerId` + - `Optional agent` - The call ID of the program item that produced this tool call. + The agent that produced this item. - - `JsonValue; type "program"constant` + - `String agentName` - The caller type. Always `program`. + The canonical name of the agent that produced this item. - - `PROGRAM("program")` + - `Optional type` - - `Optional createdBy` + The type of item to reference. Always `item_reference`. - The identifier of the actor that created the item. + - `ITEM_REFERENCE("item_reference")` - - `AgentMessage` + - `Program` - `String id` - The unique ID of the agent message. + The unique ID of this program item. - - `String author` + - `String callId` - The sending agent identity. + The stable call ID of the program item. - - `List content` + - `String code` - Encrypted content sent between agents. + The JavaScript source executed by programmatic tool calling. - - `class BetaResponseInputText:` + - `String fingerprint` - A text input to the model. + Opaque program replay fingerprint that must be round-tripped. - - `class BetaResponseOutputText:` + - `JsonValue; type "program"constant` - A text output from the model. + The item type. Always `program`. - - `class Text:` + - `PROGRAM("program")` - A text content. + - `Optional agent` - - `String text` + The agent that produced this item. - - `JsonValue; type "text"constant` + - `String agentName` - - `TEXT("text")` + The canonical name of the agent that produced this item. - - `class SummaryText:` + - `ProgramOutput` - A summary text from the model. + - `String id` - - `String text` + The unique ID of this program output item. - A summary of the reasoning output from the model so far. + - `String callId` - - `JsonValue; type "summary_text"constant` + The call ID of the program item. - The type of the object. Always `summary_text`. + - `String result` - - `SUMMARY_TEXT("summary_text")` + The result produced by the program item. - - `class ReasoningText:` + - `Status status` - Reasoning text from the model. + The terminal status of the program output. - - `String text` + - `COMPLETED("completed")` - The reasoning text from the model. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "reasoning_text"constant` + - `JsonValue; type "program_output"constant` - The type of the reasoning text. Always `reasoning_text`. + The item type. Always `program_output`. - - `REASONING_TEXT("reasoning_text")` + - `PROGRAM_OUTPUT("program_output")` - - `class BetaResponseOutputRefusal:` + - `Optional agent` - A refusal from the model. + The agent that produced this item. - - `class BetaResponseInputImage:` + - `String agentName` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `class ComputerScreenshot:` + - `Optional metadata` - A screenshot of a computer. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Detail detail` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Model model` - - `LOW("low")` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `HIGH("high")` + - `GPT_5_6_SOL("gpt-5.6-sol")` - - `AUTO("auto")` + - `GPT_5_6_TERRA("gpt-5.6-terra")` - - `ORIGINAL("original")` + - `GPT_5_6_LUNA("gpt-5.6-luna")` - - `Optional fileId` + - `GPT_5_4("gpt-5.4")` - The identifier of an uploaded file that contains the screenshot. + - `GPT_5_4_MINI("gpt-5.4-mini")` - - `Optional imageUrl` + - `GPT_5_4_NANO("gpt-5.4-nano")` - The URL of the screenshot image. + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - - `JsonValue; type "computer_screenshot"constant` + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `GPT_5_2("gpt-5.2")` - - `Optional promptCacheBreakpoint` + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - `JsonValue; mode "explicit"constant` + - `GPT_5_2_PRO("gpt-5.2-pro")` - The breakpoint mode. Always `explicit`. + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `EXPLICIT("explicit")` + - `GPT_5_1("gpt-5.1")` - - `class BetaResponseInputFile:` + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - A file input to the model. + - `GPT_5_1_CODEX("gpt-5.1-codex")` - - `class EncryptedContent:` + - `GPT_5_1_MINI("gpt-5.1-mini")` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - `String encryptedContent` + - `GPT_5("gpt-5")` - Opaque encrypted content. + - `GPT_5_MINI("gpt-5-mini")` - - `JsonValue; type "encrypted_content"constant` + - `GPT_5_NANO("gpt-5-nano")` - The type of the input item. Always `encrypted_content`. + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `String recipient` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - The destination agent identity. + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `JsonValue; type "agent_message"constant` + - `GPT_4_1("gpt-4.1")` - The type of the item. Always `agent_message`. + - `GPT_4_1_MINI("gpt-4.1-mini")` - - `AGENT_MESSAGE("agent_message")` + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `Optional agent` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - The agent that produced this item. + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `String agentName` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - The canonical name of the agent that produced this item. + - `O4_MINI("o4-mini")` - - `MultiAgentCall` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - - `String id` + - `O3("o3")` - The unique ID of the multi-agent call item. + - `O3_2025_04_16("o3-2025-04-16")` - - `Action action` + - `O3_MINI("o3-mini")` - The multi-agent action to execute. + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - `SPAWN_AGENT("spawn_agent")` + - `O1("o1")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `O1_2024_12_17("o1-2024-12-17")` - - `LIST_AGENTS("list_agents")` + - `O1_PREVIEW("o1-preview")` - - `SEND_MESSAGE("send_message")` + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - - `FOLLOWUP_TASK("followup_task")` + - `O1_MINI("o1-mini")` - - `WAIT_AGENT("wait_agent")` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - - `String arguments` + - `GPT_4O("gpt-4o")` - The JSON string of arguments generated for the action. + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - - `String callId` + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - The unique ID linking this call to its output. + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - - `JsonValue; type "multi_agent_call"constant` + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - The type of the multi-agent call. Always `multi_agent_call`. + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - - `Optional agent` + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - The agent that produced this item. + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - - `String agentName` + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - The canonical name of the agent that produced this item. + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `MultiAgentCallOutput` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `String id` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - The unique ID of the multi-agent call output item. + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - `Action action` + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - The multi-agent action that produced this result. + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `SPAWN_AGENT("spawn_agent")` + - `GPT_4O_MINI("gpt-4o-mini")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - - `LIST_AGENTS("list_agents")` + - `GPT_4_TURBO("gpt-4-turbo")` - - `SEND_MESSAGE("send_message")` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - - `FOLLOWUP_TASK("followup_task")` + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `WAIT_AGENT("wait_agent")` + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `String callId` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - The unique ID of the multi-agent call. + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - - `List output` + - `GPT_4("gpt-4")` - Text output returned by the multi-agent action. + - `GPT_4_0314("gpt-4-0314")` - - `List annotations` + - `GPT_4_0613("gpt-4-0613")` - The annotations of the text output. + - `GPT_4_32K("gpt-4-32k")` - - `String text` + - `GPT_4_32K_0314("gpt-4-32k-0314")` - The text output from the model. + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `JsonValue; type "output_text"constant` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - The type of the output text. Always `output_text`. + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `Optional> logprobs` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - - `JsonValue; type "multi_agent_call_output"constant` + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - `Optional agent` + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - The agent that produced this item. + - `O1_PRO("o1-pro")` - - `String agentName` + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - The canonical name of the agent that produced this item. + - `O3_PRO("o3-pro")` - - `class BetaResponseFunctionWebSearch:` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `String id` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - The unique ID of the web search tool call. + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - - `Action action` + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - 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). + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - `class Search:` + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - Action type "search" - Performs a web search query. + - `GPT_5_CODEX("gpt-5-codex")` - - `JsonValue; type "search"constant` + - `GPT_5_PRO("gpt-5-pro")` - The action type. + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - - `SEARCH("search")` + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - - `Optional> queries` + - `JsonValue; object_ "response"constant` - The search queries. + The object type of this resource - always set to `response`. - - `Optional query` + - `RESPONSE("response")` - The search query. + - `List output` - - `Optional> sources` + An array of content items generated by the model. - The sources used in the search. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `JsonValue; type "url"constant` + - `class BetaResponseOutputMessage:` - The type of source. Always `url`. + An output message from the model. - - `URL("url")` + - `class BetaResponseFileSearchToolCall:` - - `String url` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The URL of the source. + - `class BetaResponseFunctionToolCall:` - - `class OpenPage:` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Action type "open_page" - Opens a specific URL from search results. + - `class BetaResponseFunctionToolCallOutputItem:` - - `JsonValue; type "open_page"constant` + - `String id` - The action type. + The unique ID of the function call tool output. - - `OPEN_PAGE("open_page")` + - `String callId` - - `Optional url` + The unique ID of the function tool call generated by the model. - The URL opened by the model. + - `Output output` - - `class FindInPage:` + The output from the function call generated by your code. + Can be a string or an list of output content. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `String` - - `String pattern` + - `List` - The pattern or text to search for within the page. + - `class BetaResponseInputText:` - - `JsonValue; type "find_in_page"constant` + A text input to the model. - The action type. + - `class BetaResponseInputImage:` - - `FIND_IN_PAGE("find_in_page")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `String url` + - `class BetaResponseInputFile:` - The URL of the page searched for the pattern. + A file input to the model. - `Status status` - The status of the web search tool call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - - `SEARCHING("searching")` - - `COMPLETED("completed")` - - `FAILED("failed")` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "web_search_call"constant` + - `JsonValue; type "function_call_output"constant` - The type of the web search tool call. Always `web_search_call`. + The type of the function tool call output. Always `function_call_output`. - - `WEB_SEARCH_CALL("web_search_call")` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional agent` @@ -45659,251 +61349,271 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall:` + - `Optional caller` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The execution context that produced this tool call. - - `String id` + - `JsonValue;` - The unique ID of the computer call. + - `JsonValue; type "direct"constant` - - `String callId` + The caller type. Always `direct`. - An identifier used when responding to the tool call with output. + - `DIRECT("direct")` - - `List pendingSafetyChecks` + - `class Program:` - The pending safety checks for the computer call. + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AgentMessage` - `String id` - The ID of the pending safety check. + The unique ID of the agent message. - - `Optional code` + - `String author` - The type of the pending safety check. + The sending agent identity. - - `Optional message` + - `List content` - Details about the pending safety check. + Encrypted content sent between agents. - - `Status status` + - `class BetaResponseInputText:` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A text input to the model. - - `IN_PROGRESS("in_progress")` + - `class BetaResponseOutputText:` - - `COMPLETED("completed")` + A text output from the model. - - `INCOMPLETE("incomplete")` + - `class Text:` - - `Type type` + A text content. - The type of the computer call. Always `computer_call`. + - `String text` - - `COMPUTER_CALL("computer_call")` + - `JsonValue; type "text"constant` - - `Optional action` + - `TEXT("text")` - A click action. + - `class SummaryText:` - - `Click` + A summary text from the model. - - `Button button` + - `String text` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + A summary of the reasoning output from the model so far. - - `LEFT("left")` + - `JsonValue; type "summary_text"constant` - - `RIGHT("right")` + The type of the object. Always `summary_text`. - - `WHEEL("wheel")` + - `SUMMARY_TEXT("summary_text")` - - `BACK("back")` + - `class ReasoningText:` - - `FORWARD("forward")` + Reasoning text from the model. - - `JsonValue; type "click"constant` + - `String text` - Specifies the event type. For a click action, this property is always `click`. + The reasoning text from the model. - - `CLICK("click")` + - `JsonValue; type "reasoning_text"constant` - - `long x` + The type of the reasoning text. Always `reasoning_text`. - The x-coordinate where the click occurred. + - `REASONING_TEXT("reasoning_text")` - - `long y` + - `class BetaResponseOutputRefusal:` - The y-coordinate where the click occurred. + A refusal from the model. - - `Optional> keys` + - `class BetaResponseInputImage:` - The keys being held while clicking. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `DoubleClick` + - `class ComputerScreenshot:` - - `Optional> keys` + A screenshot of a computer. - The keys being held while double-clicking. + - `Detail detail` - - `JsonValue; type "double_click"constant` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `LOW("low")` - - `DOUBLE_CLICK("double_click")` + - `HIGH("high")` - - `long x` + - `AUTO("auto")` - The x-coordinate where the double click occurred. + - `ORIGINAL("original")` - - `long y` + - `Optional fileId` - The y-coordinate where the double click occurred. + The identifier of an uploaded file that contains the screenshot. - - `Drag` + - `Optional imageUrl` - - `List path` + The URL of the screenshot image. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `JsonValue; type "computer_screenshot"constant` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `long x` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The x-coordinate. + - `Optional promptCacheBreakpoint` - - `long y` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The y-coordinate. + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "drag"constant` + The breakpoint mode. Always `explicit`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `EXPLICIT("explicit")` - - `DRAG("drag")` + - `class BetaResponseInputFile:` - - `Optional> keys` + A file input to the model. - The keys being held while dragging the mouse. + - `class EncryptedContent:` - - `Keypress` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `List keys` + - `String encryptedContent` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Opaque encrypted content. - - `JsonValue; type "keypress"constant` + - `JsonValue; type "encrypted_content"constant` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The type of the input item. Always `encrypted_content`. - - `KEYPRESS("keypress")` + - `ENCRYPTED_CONTENT("encrypted_content")` - - `Move` + - `String recipient` - - `JsonValue; type "move"constant` + The destination agent identity. - Specifies the event type. For a move action, this property is always set to `move`. + - `JsonValue; type "agent_message"constant` - - `MOVE("move")` + The type of the item. Always `agent_message`. - - `long x` + - `AGENT_MESSAGE("agent_message")` - The x-coordinate to move to. + - `Optional agent` - - `long y` + The agent that produced this item. - The y-coordinate to move to. + - `String agentName` - - `Optional> keys` + The canonical name of the agent that produced this item. - The keys being held while moving the mouse. + - `MultiAgentCall` - - `JsonValue;` + - `String id` - - `JsonValue; type "screenshot"constant` + The unique ID of the multi-agent call item. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `Action action` - - `SCREENSHOT("screenshot")` + The multi-agent action to execute. - - `Scroll` + - `SPAWN_AGENT("spawn_agent")` - - `long scrollX` + - `INTERRUPT_AGENT("interrupt_agent")` - The horizontal scroll distance. + - `LIST_AGENTS("list_agents")` - - `long scrollY` + - `SEND_MESSAGE("send_message")` - The vertical scroll distance. + - `FOLLOWUP_TASK("followup_task")` - - `JsonValue; type "scroll"constant` + - `WAIT_AGENT("wait_agent")` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `String arguments` - - `SCROLL("scroll")` + The JSON string of arguments generated for the action. - - `long x` + - `String callId` - The x-coordinate where the scroll occurred. + The unique ID linking this call to its output. - - `long y` + - `JsonValue; type "multi_agent_call"constant` - The y-coordinate where the scroll occurred. + The type of the multi-agent call. Always `multi_agent_call`. - - `Optional> keys` + - `MULTI_AGENT_CALL("multi_agent_call")` - The keys being held while scrolling. + - `Optional agent` - - `Type` + The agent that produced this item. - - `String text` + - `String agentName` - The text to type. + The canonical name of the agent that produced this item. - - `JsonValue; type "type"constant` + - `MultiAgentCallOutput` - Specifies the event type. For a type action, this property is always set to `type`. + - `String id` - - `TYPE("type")` + The unique ID of the multi-agent call output item. - - `JsonValue;` + - `Action action` - - `JsonValue; type "wait"constant` + The multi-agent action that produced this result. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `SPAWN_AGENT("spawn_agent")` - - `WAIT("wait")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `Optional> actions` + - `LIST_AGENTS("list_agents")` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `SEND_MESSAGE("send_message")` - - `Click` + - `FOLLOWUP_TASK("followup_task")` - - `DoubleClick` + - `WAIT_AGENT("wait_agent")` - - `Drag` + - `String callId` - - `Keypress` + The unique ID of the multi-agent call. - - `Move` + - `List output` - - `JsonValue;` + Text output returned by the multi-agent action. - - `Scroll` + - `List annotations` - - `Type` + The annotations of the text output. - - `JsonValue;` + - `String text` + + The text output from the model. + + - `JsonValue; type "output_text"constant` + + The type of the output text. Always `output_text`. + + - `Optional> logprobs` + + - `JsonValue; type "multi_agent_call_output"constant` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - `Optional agent` @@ -45913,6 +61623,16 @@ public final class Main { The canonical name of the agent that produced this item. + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `class BetaResponseComputerToolCallOutputItem:` - `String id` @@ -45927,21 +61647,6 @@ public final class Main { 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 fileId` - - The identifier of an uploaded file that contains the screenshot. - - - `Optional imageUrl` - - The URL of the screenshot image. - - `Status status` The status of the message input. One of `in_progress`, `completed`, or @@ -45997,68 +61702,6 @@ public final class Main { for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `String id` - - The unique identifier of the reasoning content. - - - `List 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional> 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 encryptedContent` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `Optional 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")` - - `Program` - `String id` @@ -46213,1893 +61856,1829 @@ public final class Main { Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String name` - - The name of the function to call. - - - `Optional parameters` - - A JSON schema object describing the parameters of the function. - - - `Optional strict` - - Whether strict parameter validation is enforced for this function tool. - - - `JsonValue; type "function"constant` - - The type of the function tool. Always `function`. - - - `FUNCTION("function")` - - - `Optional> allowedCallers` - - The tool invocation context(s). - - - `DIRECT("direct")` - - - `PROGRAMMATIC("programmatic")` - - - `Optional deferLoading` - - Whether this function is deferred and loaded via tool search. - - - `Optional description` - - A description of the function. Used by the model to determine whether or not to call the function. - - - `Optional outputSchema` - - A JSON schema object describing the JSON value encoded in string outputs for this function. - - `class BetaFileSearchTool:` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `JsonValue; type "file_search"constant` - - The type of the file search tool. Always `file_search`. - - - `FILE_SEARCH("file_search")` - - - `List vectorStoreIds` - - The IDs of the vector stores to search. - - - `Optional 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. + - `class BetaComputerTool:` - - `String` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `double` + - `class BetaComputerUsePreviewTool:` - - `boolean` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `List` + - `class BetaWebSearchTool:` - - `class CompoundFilter:` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Combine multiple filters using `and` or `or`. + - `Mcp` - - `List filters` + - `CodeInterpreter` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `JsonValue;` - - `class ComparisonFilter:` + - `ImageGeneration` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `JsonValue;` - - `String key` + - `class BetaFunctionShellTool:` - The key to compare against the value. + A tool that allows the model to execute shell commands. - - `Type type` + - `class BetaCustomTool:` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class BetaNamespaceTool:` - - `EQ("eq")` + Groups function/custom tools under a shared namespace. - - `NE("ne")` + - `class BetaToolSearchTool:` - - `GT("gt")` + Hosted or BYOT tool search configuration for deferred tools. - - `GTE("gte")` + - `class BetaWebSearchPreviewTool:` - - `LT("lt")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `LTE("lte")` + - `class BetaApplyPatchTool:` - - `IN("in")` + Allows the assistant to create, delete, or update files using unified diffs. - - `NIN("nin")` + - `JsonValue; type "tool_search_output"constant` - - `Value value` + The type of the item. Always `tool_search_output`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `String` + - `Optional agent` - - `double` + The agent that produced this item. - - `boolean` + - `String agentName` - - `List` + The canonical name of the agent that produced this item. - - `JsonValue` + - `Optional createdBy` - - `Type type` + The identifier of the actor that created the item. - Type of operation: `and` or `or`. + - `AdditionalTools` - - `AND("and")` + - `String id` - - `OR("or")` + The unique ID of the additional tools item. - - `Optional maxNumResults` + - `Role role` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The role that provided the additional tools. - - `Optional rankingOptions` + - `UNKNOWN("unknown")` - Ranking options for search. + - `USER("user")` - - `Optional hybridSearch` + - `ASSISTANT("assistant")` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `SYSTEM("system")` - - `double embeddingWeight` + - `CRITIC("critic")` - The weight of the embedding in the reciprocal ranking fusion. + - `DISCRIMINATOR("discriminator")` - - `double textWeight` + - `DEVELOPER("developer")` - The weight of the text in the reciprocal ranking fusion. + - `TOOL("tool")` - - `Optional ranker` + - `List tools` - The ranker to use for the file search. + The additional tool definitions made available at this item. - - `AUTO("auto")` + - `class BetaFunctionTool:` - - `DEFAULT_2024_11_15("default-2024-11-15")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `Optional scoreThreshold` + - `class BetaFileSearchTool:` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `class BetaComputerTool:` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; type "computer"constant` - - The type of the computer tool. Always `computer`. - - - `COMPUTER("computer")` - - `class BetaComputerUsePreviewTool:` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `long displayHeight` + - `class BetaWebSearchTool:` - The height of the computer display. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `long displayWidth` + - `Mcp` - The width of the computer display. + - `CodeInterpreter` - - `Environment environment` + - `JsonValue;` - The type of computer environment to control. + - `ImageGeneration` - - `WINDOWS("windows")` + - `JsonValue;` - - `MAC("mac")` + - `class BetaFunctionShellTool:` - - `LINUX("linux")` + A tool that allows the model to execute shell commands. - - `UBUNTU("ubuntu")` + - `class BetaCustomTool:` - - `BROWSER("browser")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `JsonValue; type "computer_use_preview"constant` + - `class BetaNamespaceTool:` - The type of the computer use tool. Always `computer_use_preview`. + Groups function/custom tools under a shared namespace. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `class BetaToolSearchTool:` - - `class BetaWebSearchTool:` + Hosted or BYOT tool search configuration for deferred tools. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class BetaWebSearchPreviewTool:` - - `Type type` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `class BetaApplyPatchTool:` - - `WEB_SEARCH("web_search")` + Allows the assistant to create, delete, or update files using unified diffs. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `JsonValue; type "additional_tools"constant` - - `Optional filters` + The type of the item. Always `additional_tools`. - Filters for the search. + - `ADDITIONAL_TOOLS("additional_tools")` - - `Optional> allowedDomains` + - `Optional agent` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The agent that produced this item. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `String agentName` - - `Optional searchContextSize` + The canonical name of the agent that produced this item. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `class BetaResponseCompactionItem:` - - `LOW("low")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `MEDIUM("medium")` + - `String id` - - `HIGH("high")` + The unique ID of the compaction item. - - `Optional userLocation` + - `String encryptedContent` - The approximate location of the user. + The encrypted content that was produced by compaction. - - `Optional city` + - `JsonValue; type "compaction"constant` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the item. Always `compaction`. - - `Optional country` + - `COMPACTION("compaction")` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Optional agent` - - `Optional region` + The agent that produced this item. - Free text input for the region of the user, e.g. `California`. + - `String agentName` - - `Optional timezone` + The canonical name of the agent that produced this item. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `Optional createdBy` - - `Optional type` + The identifier of the actor that created the item. - The type of location approximation. Always `approximate`. + - `ImageGenerationCall` - - `APPROXIMATE("approximate")` + - `String id` - - `Mcp` + The unique ID of the image generation call. - - `String serverLabel` + - `Optional result` - A label for this MCP server, used to identify it in tool calls. + The generated image encoded in base64. - - `JsonValue; type "mcp"constant` + - `Status status` - The type of the MCP tool. Always `mcp`. + The status of the image generation call. - - `MCP("mcp")` + - `IN_PROGRESS("in_progress")` - - `Optional> allowedCallers` + - `COMPLETED("completed")` - The tool invocation context(s). + - `GENERATING("generating")` - - `DIRECT("direct")` + - `FAILED("failed")` - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "image_generation_call"constant` - - `Optional allowedTools` + The type of the image generation call. Always `image_generation_call`. - List of allowed tool names or a filter object. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `List` + - `Optional agent` - - `class McpToolFilter:` + The agent that produced this item. - A filter object to specify which tools are allowed. + - `String agentName` - - `Optional readOnly` + The canonical name of the agent that produced this item. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class BetaResponseCodeInterpreterToolCall:` - - `Optional> toolNames` + A tool call to run code. - List of allowed tool names. + - `LocalShellCall` - - `Optional authorization` + - `String id` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The unique ID of the local shell call. - - `Optional connectorId` + - `Action action` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + Execute a shell command on the server. - Currently supported `connector_id` values are: + - `List command` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The command to run. - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `Env env` - - `CONNECTOR_GMAIL("connector_gmail")` + Environment variables to set for the command. - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `JsonValue; type "exec"constant` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + The type of the local shell action. Always `exec`. - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `EXEC("exec")` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `Optional timeoutMs` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + Optional timeout in milliseconds for the command. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `Optional user` - - `Optional deferLoading` + Optional user to run the command as. - Whether this MCP tool is deferred and discovered via tool search. + - `Optional workingDirectory` - - `Optional headers` + Optional working directory to run the command in. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `String callId` - - `Optional requireApproval` + The unique ID of the local shell tool call generated by the model. - Specify which of the MCP server's tools require approval. + - `Status status` - - `class McpToolApprovalFilter:` + The status of the local shell call. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `IN_PROGRESS("in_progress")` - - `Optional always` + - `COMPLETED("completed")` - A filter object to specify which tools are allowed. + - `INCOMPLETE("incomplete")` - - `Optional readOnly` + - `JsonValue; type "local_shell_call"constant` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The type of the local shell call. Always `local_shell_call`. - - `Optional> toolNames` + - `LOCAL_SHELL_CALL("local_shell_call")` - List of allowed tool names. + - `Optional agent` - - `Optional never` + The agent that produced this item. - A filter object to specify which tools are allowed. + - `String agentName` - - `Optional readOnly` + The canonical name of the agent that produced this item. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `LocalShellCallOutput` - - `Optional> toolNames` + - `String id` - List of allowed tool names. + The unique ID of the local shell tool call generated by the model. - - `enum McpToolApprovalSetting:` + - `String output` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + A JSON string of the output of the local shell tool call. - - `ALWAYS("always")` + - `JsonValue; type "local_shell_call_output"constant` - - `NEVER("never")` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `Optional serverDescription` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - Optional description of the MCP server, used to provide more context. + - `Optional agent` - - `Optional serverUrl` + The agent that produced this item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `String agentName` - - `Optional tunnelId` + The canonical name of the agent that produced this item. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `Optional status` - - `CodeInterpreter` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `Container container` + - `IN_PROGRESS("in_progress")` - 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. + - `COMPLETED("completed")` - - `String` + - `INCOMPLETE("incomplete")` - - `class CodeInterpreterToolAuto:` + - `class BetaResponseFunctionShellToolCall:` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + A tool call that executes one or more shell commands in a managed environment. - - `JsonValue; type "auto"constant` + - `String id` - Always `auto`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `AUTO("auto")` + - `Action action` - - `Optional> fileIds` + The shell commands and limits that describe how to run the tool call. - An optional list of uploaded files to make available to your code. + - `List commands` - - `Optional memoryLimit` + - `Optional maxOutputLength` - The memory limit for the code interpreter container. + Optional maximum number of characters to return from each command. - - `_1G("1g")` + - `Optional timeoutMs` - - `_4G("4g")` + Optional timeout in milliseconds for the commands. - - `_16G("16g")` + - `String callId` - - `_64G("64g")` + The unique ID of the shell tool call generated by the model. - - `Optional networkPolicy` + - `Optional environment` - Network access policy for the container. + Represents the use of a local environment to perform shell actions. - - `class BetaContainerNetworkPolicyDisabled:` + - `class BetaResponseLocalEnvironment:` - - `JsonValue; type "disabled"constant` + Represents the use of a local environment to perform shell actions. - Disable outbound network access. Always `disabled`. + - `JsonValue; type "local"constant` - - `DISABLED("disabled")` + The environment type. Always `local`. - - `class BetaContainerNetworkPolicyAllowlist:` + - `LOCAL("local")` - - `List allowedDomains` + - `class BetaResponseContainerReference:` - A list of allowed domains when type is `allowlist`. + Represents a container created with /v1/containers. - - `JsonValue; type "allowlist"constant` + - `String containerId` - Allow outbound network access only to specified domains. Always `allowlist`. + - `JsonValue; type "container_reference"constant` - - `ALLOWLIST("allowlist")` + The environment type. Always `container_reference`. - - `Optional> domainSecrets` + - `CONTAINER_REFERENCE("container_reference")` - Optional domain-scoped secrets for allowlisted domains. + - `Status status` - - `String domain` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The domain associated with the secret. + - `IN_PROGRESS("in_progress")` - - `String name` + - `COMPLETED("completed")` - The name of the secret to inject for the domain. + - `INCOMPLETE("incomplete")` - - `String value` + - `JsonValue; type "shell_call"constant` - The secret value to inject for the domain. + The type of the item. Always `shell_call`. - - `JsonValue; type "code_interpreter"constant` + - `SHELL_CALL("shell_call")` - The type of the code interpreter tool. Always `code_interpreter`. + - `Optional agent` - - `CODE_INTERPRETER("code_interpreter")` + The agent that produced this item. - - `Optional> allowedCallers` + - `String agentName` - The tool invocation context(s). + The canonical name of the agent that produced this item. - - `DIRECT("direct")` + - `Optional caller` - - `PROGRAMMATIC("programmatic")` + The execution context that produced this tool call. - `JsonValue;` - - `JsonValue; type "programmatic_tool_calling"constant` - - The type of the tool. Always `programmatic_tool_calling`. - - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - - `ImageGeneration` - - - `JsonValue; type "image_generation"constant` - - The type of the image generation tool. Always `image_generation`. - - - `IMAGE_GENERATION("image_generation")` - - - `Optional action` - - Whether to generate a new image or edit an existing image. Default: `auto`. - - - `GENERATE("generate")` - - - `EDIT("edit")` + - `JsonValue; type "direct"constant` - - `AUTO("auto")` + - `DIRECT("direct")` - - `Optional background` + - `class Program:` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `String callerId` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The call ID of the program item that produced this tool call. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `JsonValue; type "program"constant` - - `TRANSPARENT("transparent")` + - `PROGRAM("program")` - - `OPAQUE("opaque")` + - `Optional createdBy` - - `AUTO("auto")` + The ID of the entity that created this tool call. - - `Optional inputFidelity` + - `class BetaResponseFunctionShellToolCallOutput:` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The output of a shell tool call that was emitted. - - `HIGH("high")` + - `String id` - - `LOW("low")` + The unique ID of the shell call output. Populated when this item is returned via API. - - `Optional inputImageMask` + - `String callId` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The unique ID of the shell tool call generated by the model. - - `Optional fileId` + - `Optional maxOutputLength` - File ID for the mask image. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `Optional imageUrl` + - `List output` - Base64-encoded mask image. + An array of shell call output contents - - `Optional model` + - `Outcome outcome` - The image generation model to use. Default: `gpt-image-1`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `GPT_IMAGE_1("gpt-image-1")` + - `JsonValue;` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `JsonValue; type "timeout"constant` - - `GPT_IMAGE_2("gpt-image-2")` + The outcome type. Always `timeout`. - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + - `TIMEOUT("timeout")` - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `class Exit:` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + Indicates that the shell commands finished and returned an exit code. - - `Optional moderation` + - `long exitCode` - Moderation level for the generated image. Default: `auto`. + Exit code from the shell process. - - `AUTO("auto")` + - `JsonValue; type "exit"constant` - - `LOW("low")` + The outcome type. Always `exit`. - - `Optional outputCompression` + - `EXIT("exit")` - Compression level for the output image. Default: 100. + - `String stderr` - - `Optional outputFormat` + The standard error output that was captured. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `String stdout` - - `PNG("png")` + The standard output that was captured. - - `WEBP("webp")` + - `Optional createdBy` - - `JPEG("jpeg")` + The identifier of the actor that created the item. - - `Optional partialImages` + - `Status status` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `Optional quality` + - `IN_PROGRESS("in_progress")` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `COMPLETED("completed")` - - `LOW("low")` + - `INCOMPLETE("incomplete")` - - `MEDIUM("medium")` + - `JsonValue; type "shell_call_output"constant` - - `HIGH("high")` + The type of the shell call output. Always `shell_call_output`. - - `AUTO("auto")` + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `Optional size` + - `Optional agent` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The agent that produced this item. - - `_1024X1024("1024x1024")` + - `String agentName` - - `_1024X1536("1024x1536")` + The canonical name of the agent that produced this item. - - `_1536X1024("1536x1024")` + - `Optional caller` - - `AUTO("auto")` + The execution context that produced this tool call. - `JsonValue;` - - `JsonValue; type "local_shell"constant` + - `JsonValue; type "direct"constant` - The type of the local shell tool. Always `local_shell`. + - `DIRECT("direct")` - - `LOCAL_SHELL("local_shell")` + - `class Program:` - - `class BetaFunctionShellTool:` + - `String callerId` - A tool that allows the model to execute shell commands. + The call ID of the program item that produced this tool call. - - `JsonValue; type "shell"constant` + - `JsonValue; type "program"constant` - The type of the shell tool. Always `shell`. + - `PROGRAM("program")` - - `SHELL("shell")` + - `Optional createdBy` - - `Optional> allowedCallers` + The identifier of the actor that created the item. - The tool invocation context(s). + - `class BetaResponseApplyPatchToolCall:` - - `DIRECT("direct")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `PROGRAMMATIC("programmatic")` + - `String id` - - `Optional environment` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `class BetaContainerAuto:` + - `String callId` - - `JsonValue; type "container_auto"constant` + The unique ID of the apply patch tool call generated by the model. - Automatically creates a container for this request + - `Operation operation` - - `CONTAINER_AUTO("container_auto")` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `Optional> fileIds` + - `class CreateFile:` - An optional list of uploaded files to make available to your code. + Instruction describing how to create a file via the apply_patch tool. - - `Optional memoryLimit` + - `String diff` - The memory limit for the container. + Diff to apply. - - `_1G("1g")` + - `String path` - - `_4G("4g")` + Path of the file to create. - - `_16G("16g")` + - `JsonValue; type "create_file"constant` - - `_64G("64g")` + Create a new file with the provided diff. - - `Optional networkPolicy` + - `CREATE_FILE("create_file")` - Network access policy for the container. + - `class DeleteFile:` - - `class BetaContainerNetworkPolicyDisabled:` + Instruction describing how to delete a file via the apply_patch tool. - - `class BetaContainerNetworkPolicyAllowlist:` + - `String path` - - `Optional> skills` + Path of the file to delete. - An optional list of skills referenced by id or inline data. + - `JsonValue; type "delete_file"constant` - - `class BetaSkillReference:` + Delete the specified file. - - `String skillId` + - `DELETE_FILE("delete_file")` - The ID of the referenced skill. + - `class UpdateFile:` - - `JsonValue; type "skill_reference"constant` + Instruction describing how to update a file via the apply_patch tool. - References a skill created with the /v1/skills endpoint. + - `String diff` - - `SKILL_REFERENCE("skill_reference")` + Diff to apply. - - `Optional version` + - `String path` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Path of the file to update. - - `class BetaInlineSkill:` + - `JsonValue; type "update_file"constant` - - `String description` + Update an existing file with the provided diff. - The description of the skill. + - `UPDATE_FILE("update_file")` - - `String name` + - `Status status` - The name of the skill. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `BetaInlineSkillSource source` + - `IN_PROGRESS("in_progress")` - Inline skill payload + - `COMPLETED("completed")` - - `String data` + - `JsonValue; type "apply_patch_call"constant` - Base64-encoded skill zip bundle. + The type of the item. Always `apply_patch_call`. - - `JsonValue; mediaType "application/zip"constant` + - `APPLY_PATCH_CALL("apply_patch_call")` - The media type of the inline skill payload. Must be `application/zip`. + - `Optional agent` - - `APPLICATION_ZIP("application/zip")` + The agent that produced this item. - - `JsonValue; type "base64"constant` + - `String agentName` - The type of the inline skill source. Must be `base64`. + The canonical name of the agent that produced this item. - - `BASE64("base64")` + - `Optional caller` - - `JsonValue; type "inline"constant` + The execution context that produced this tool call. - Defines an inline skill for this request. + - `JsonValue;` - - `INLINE("inline")` + - `JsonValue; type "direct"constant` - - `class BetaLocalEnvironment:` + - `DIRECT("direct")` - - `JsonValue; type "local"constant` + - `class Program:` - Use a local computer environment. + - `String callerId` - - `LOCAL("local")` + The call ID of the program item that produced this tool call. - - `Optional> skills` + - `JsonValue; type "program"constant` - An optional list of skills. + - `PROGRAM("program")` - - `String description` + - `Optional createdBy` - The description of the skill. + The ID of the entity that created this tool call. - - `String name` + - `class BetaResponseApplyPatchToolCallOutput:` - The name of the skill. + The output emitted by an apply patch tool call. - - `String path` + - `String id` - The path to the directory containing the skill. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class BetaContainerReference:` + - `String callId` - - `String containerId` + The unique ID of the apply patch tool call generated by the model. - The ID of the referenced container. + - `Status status` - - `JsonValue; type "container_reference"constant` + The status of the apply patch tool call output. One of `completed` or `failed`. - References a container created with the /v1/containers endpoint + - `COMPLETED("completed")` - - `CONTAINER_REFERENCE("container_reference")` + - `FAILED("failed")` - - `class BetaCustomTool:` + - `JsonValue; type "apply_patch_call_output"constant` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The type of the item. Always `apply_patch_call_output`. - - `String name` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - The name of the custom tool, used to identify it in tool calls. + - `Optional agent` - - `JsonValue; type "custom"constant` + The agent that produced this item. - The type of the custom tool. Always `custom`. + - `String agentName` - - `CUSTOM("custom")` + The canonical name of the agent that produced this item. - - `Optional> allowedCallers` + - `Optional caller` - The tool invocation context(s). + The execution context that produced this tool call. - - `DIRECT("direct")` + - `JsonValue;` - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "direct"constant` - - `Optional deferLoading` + - `DIRECT("direct")` - Whether this tool should be deferred and discovered via tool search. + - `class Program:` - - `Optional description` + - `String callerId` - Optional description of the custom tool, used to provide more context. + The call ID of the program item that produced this tool call. - - `Optional format` + - `JsonValue; type "program"constant` - The input format for the custom tool. Default is unconstrained text. + - `PROGRAM("program")` - - `JsonValue;` + - `Optional createdBy` - - `JsonValue; type "text"constant` + The ID of the entity that created this tool call output. - Unconstrained text format. Always `text`. + - `Optional output` - - `TEXT("text")` + Optional textual output returned by the apply patch tool. - - `class Grammar:` + - `McpCall` - A grammar defined by the user. + - `String id` - - `String definition` + The unique ID of the tool call. - The grammar definition. + - `String arguments` - - `Syntax syntax` + A JSON string of the arguments passed to the tool. - The syntax of the grammar definition. One of `lark` or `regex`. + - `String name` - - `LARK("lark")` + The name of the tool that was run. - - `REGEX("regex")` + - `String serverLabel` - - `JsonValue; type "grammar"constant` + The label of the MCP server running the tool. - Grammar format. Always `grammar`. + - `JsonValue; type "mcp_call"constant` - - `GRAMMAR("grammar")` + The type of the item. Always `mcp_call`. - - `class BetaNamespaceTool:` + - `MCP_CALL("mcp_call")` - Groups function/custom tools under a shared namespace. + - `Optional agent` - - `String description` + The agent that produced this item. - A description of the namespace shown to the model. + - `String agentName` - - `String name` + The canonical name of the agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `Optional approvalRequestId` - - `List tools` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The function/custom tools available inside this namespace. + - `Optional error` - - `class Function:` + The error from the tool call, if any. - - `String name` + - `Optional output` - - `JsonValue; type "function"constant` + The output from the tool call. - - `FUNCTION("function")` + - `Optional status` - - `Optional> allowedCallers` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The tool invocation context(s). + - `IN_PROGRESS("in_progress")` - - `DIRECT("direct")` + - `COMPLETED("completed")` - - `PROGRAMMATIC("programmatic")` + - `INCOMPLETE("incomplete")` - - `Optional deferLoading` + - `CALLING("calling")` - Whether this function should be deferred and discovered via tool search. + - `FAILED("failed")` - - `Optional description` + - `McpListTools` - - `Optional outputSchema` + - `String id` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The unique ID of the list. - - `Optional parameters` + - `String serverLabel` - - `Optional strict` + The label of the MCP server. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `List tools` - - `class BetaCustomTool:` + The tools available on the server. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `JsonValue inputSchema` - - `JsonValue; type "namespace"constant` + The JSON schema describing the tool's input. - The type of the tool. Always `namespace`. + - `String name` - - `NAMESPACE("namespace")` + The name of the tool. - - `class BetaToolSearchTool:` + - `Optional annotations` - Hosted or BYOT tool search configuration for deferred tools. + Additional annotations about the tool. - - `JsonValue; type "tool_search"constant` + - `Optional description` - The type of the tool. Always `tool_search`. + The description of the tool. - - `TOOL_SEARCH("tool_search")` + - `JsonValue; type "mcp_list_tools"constant` - - `Optional description` + The type of the item. Always `mcp_list_tools`. - Description shown to the model for a client-executed tool search tool. + - `MCP_LIST_TOOLS("mcp_list_tools")` - - `Optional execution` + - `Optional agent` - Whether tool search is executed by the server or by the client. + The agent that produced this item. - - `SERVER("server")` + - `String agentName` - - `CLIENT("client")` + The canonical name of the agent that produced this item. - - `Optional parameters` + - `Optional error` - Parameter schema for a client-executed tool search tool. + Error message if the server could not list tools. - - `class BetaWebSearchPreviewTool:` + - `McpApprovalRequest` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String id` - - `Type type` + The unique ID of the approval request. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `String arguments` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + A JSON string of arguments for the tool. - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `String name` - - `Optional> searchContentTypes` + The name of the tool to run. - - `TEXT("text")` + - `String serverLabel` - - `IMAGE("image")` + The label of the MCP server making the request. - - `Optional searchContextSize` + - `JsonValue; type "mcp_approval_request"constant` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the item. Always `mcp_approval_request`. - - `LOW("low")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `MEDIUM("medium")` + - `Optional agent` - - `HIGH("high")` + The agent that produced this item. - - `Optional userLocation` + - `String agentName` - The user's location. + The canonical name of the agent that produced this item. - - `JsonValue; type "approximate"constant` + - `McpApprovalResponse` - The type of location approximation. Always `approximate`. + - `String id` - - `APPROXIMATE("approximate")` + The unique ID of the approval response - - `Optional city` + - `String approvalRequestId` - Free text input for the city of the user, e.g. `San Francisco`. + The ID of the approval request being answered. - - `Optional country` + - `boolean approve` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Whether the request was approved. - - `Optional region` + - `JsonValue; type "mcp_approval_response"constant` - Free text input for the region of the user, e.g. `California`. + The type of the item. Always `mcp_approval_response`. - - `Optional timezone` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `Optional agent` - - `class BetaApplyPatchTool:` + The agent that produced this item. - Allows the assistant to create, delete, or update files using unified diffs. + - `String agentName` - - `JsonValue; type "apply_patch"constant` + The canonical name of the agent that produced this item. - The type of the tool. Always `apply_patch`. + - `Optional reason` - - `APPLY_PATCH("apply_patch")` + Optional reason for the decision. - - `Optional> allowedCallers` + - `class BetaResponseCustomToolCall:` - The tool invocation context(s). + A call to a custom tool created by the model. - - `DIRECT("direct")` + - `class BetaResponseCustomToolCallOutputItem:` - - `PROGRAMMATIC("programmatic")` + The output of a custom tool call from your code, being sent back to the model. - - `JsonValue; type "tool_search_output"constant` + - `String id` - The type of the item. Always `tool_search_output`. + The unique ID of the custom tool call output item. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `Status status` - - `Optional agent` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The agent that produced this item. + - `IN_PROGRESS("in_progress")` - - `String agentName` + - `COMPLETED("completed")` - The canonical name of the agent that produced this item. + - `INCOMPLETE("incomplete")` - `Optional createdBy` The identifier of the actor that created the item. - - `AdditionalTools` - - - `String id` + - `boolean parallelToolCalls` - The unique ID of the additional tools item. + Whether to allow the model to run tool calls in parallel. - - `Role role` + - `Optional temperature` - The role that provided the additional tools. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `UNKNOWN("unknown")` + - `ToolChoice toolChoice` - - `USER("user")` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `ASSISTANT("assistant")` + - `enum BetaToolChoiceOptions:` - - `SYSTEM("system")` + Controls which (if any) tool is called by the model. - - `CRITIC("critic")` + `none` means the model will not call any tool and instead generates a message. - - `DISCRIMINATOR("discriminator")` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `DEVELOPER("developer")` + `required` means the model must call one or more tools. - - `TOOL("tool")` + - `NONE("none")` - - `List tools` + - `AUTO("auto")` - The additional tool definitions made available at this item. + - `REQUIRED("required")` - - `class BetaFunctionTool:` + - `class BetaToolChoiceAllowed:` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + Constrains the tools available to the model to a pre-defined set. - - `class BetaFileSearchTool:` + - `Mode mode` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Constrains the tools available to the model to a pre-defined set. - - `class BetaComputerTool:` + `auto` allows the model to pick from among the allowed tools and generate a + message. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + `required` requires the model to call one or more of the allowed tools. - - `class BetaComputerUsePreviewTool:` + - `AUTO("auto")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `REQUIRED("required")` - - `class BetaWebSearchTool:` + - `List tools` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A list of tool definitions that the model should be allowed to call. - - `Mcp` + For the Responses API, the list of tool definitions might look like: - - `CodeInterpreter` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `JsonValue;` + - `JsonValue; type "allowed_tools"constant` - - `ImageGeneration` + Allowed tool configuration type. Always `allowed_tools`. - - `JsonValue;` + - `ALLOWED_TOOLS("allowed_tools")` - - `class BetaFunctionShellTool:` + - `class BetaToolChoiceTypes:` - A tool that allows the model to execute shell commands. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `class BetaCustomTool:` + - `Type type` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `class BetaNamespaceTool:` + Allowed values are: - Groups function/custom tools under a shared namespace. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `class BetaToolSearchTool:` + - `FILE_SEARCH("file_search")` - Hosted or BYOT tool search configuration for deferred tools. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `class BetaWebSearchPreviewTool:` + - `COMPUTER("computer")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `class BetaApplyPatchTool:` + - `COMPUTER_USE("computer_use")` - Allows the assistant to create, delete, or update files using unified diffs. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `JsonValue; type "additional_tools"constant` + - `IMAGE_GENERATION("image_generation")` - The type of the item. Always `additional_tools`. + - `CODE_INTERPRETER("code_interpreter")` - - `ADDITIONAL_TOOLS("additional_tools")` + - `class BetaToolChoiceFunction:` - - `Optional agent` + Use this option to force the model to call a specific function. - The agent that produced this item. + - `String name` - - `String agentName` + The name of the function to call. - The canonical name of the agent that produced this item. + - `JsonValue; type "function"constant` - - `class BetaResponseCompactionItem:` + For function calling, the type is always `function`. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `FUNCTION("function")` - - `String id` + - `class BetaToolChoiceMcp:` - The unique ID of the compaction item. + Use this option to force the model to call a specific tool on a remote MCP server. - - `String encryptedContent` + - `String serverLabel` - The encrypted content that was produced by compaction. + The label of the MCP server to use. - - `JsonValue; type "compaction"constant` + - `JsonValue; type "mcp"constant` - The type of the item. Always `compaction`. + For MCP tools, the type is always `mcp`. - - `COMPACTION("compaction")` + - `MCP("mcp")` - - `Optional agent` + - `Optional name` - The agent that produced this item. + The name of the tool to call on the server. - - `String agentName` + - `class BetaToolChoiceCustom:` - The canonical name of the agent that produced this item. + Use this option to force the model to call a specific custom tool. - - `Optional createdBy` + - `String name` - The identifier of the actor that created the item. + The name of the custom tool to call. - - `ImageGenerationCall` + - `JsonValue; type "custom"constant` - - `String id` + For custom tool calling, the type is always `custom`. - The unique ID of the image generation call. + - `CUSTOM("custom")` - - `Optional result` + - `JsonValue;` - The generated image encoded in base64. + - `JsonValue; type "programmatic_tool_calling"constant` - - `Status status` + The tool to call. Always `programmatic_tool_calling`. - The status of the image generation call. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `IN_PROGRESS("in_progress")` + - `class BetaToolChoiceApplyPatch:` - - `COMPLETED("completed")` + Forces the model to call the apply_patch tool when executing a tool call. - - `GENERATING("generating")` + - `JsonValue; type "apply_patch"constant` - - `FAILED("failed")` + The tool to call. Always `apply_patch`. - - `JsonValue; type "image_generation_call"constant` + - `APPLY_PATCH("apply_patch")` - The type of the image generation call. Always `image_generation_call`. + - `class BetaToolChoiceShell:` - - `IMAGE_GENERATION_CALL("image_generation_call")` + Forces the model to call the shell tool when a tool call is required. - - `Optional agent` + - `JsonValue; type "shell"constant` - The agent that produced this item. + The tool to call. Always `shell`. - - `String agentName` + - `SHELL("shell")` - The canonical name of the agent that produced this item. + - `List tools` - - `class BetaResponseCodeInterpreterToolCall:` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - A tool call to run code. + We support the following categories of tools: - - `String id` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - The unique ID of the code interpreter tool call. + - `class BetaFunctionTool:` - - `Optional code` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The code to run, or null if not available. + - `class BetaFileSearchTool:` - - `String containerId` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The ID of the container used to run the code. + - `class BetaComputerTool:` - - `Optional> outputs` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `class BetaComputerUsePreviewTool:` - - `class Logs:` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The logs output from the code interpreter. + - `class BetaWebSearchTool:` - - `String logs` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The logs output from the code interpreter. + - `Mcp` - - `JsonValue; type "logs"constant` + - `CodeInterpreter` - The type of the output. Always `logs`. + - `JsonValue;` - - `LOGS("logs")` + - `ImageGeneration` - - `class Image:` + - `JsonValue;` - The image output from the code interpreter. + - `class BetaFunctionShellTool:` - - `JsonValue; type "image"constant` + A tool that allows the model to execute shell commands. - The type of the output. Always `image`. + - `class BetaCustomTool:` - - `IMAGE("image")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `String url` + - `class BetaNamespaceTool:` - The URL of the image output from the code interpreter. + Groups function/custom tools under a shared namespace. - - `Status status` + - `class BetaToolSearchTool:` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Hosted or BYOT tool search configuration for deferred tools. - - `IN_PROGRESS("in_progress")` + - `class BetaWebSearchPreviewTool:` - - `COMPLETED("completed")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `INCOMPLETE("incomplete")` + - `class BetaApplyPatchTool:` - - `INTERPRETING("interpreting")` + Allows the assistant to create, delete, or update files using unified diffs. - - `FAILED("failed")` + - `Optional topP` - - `JsonValue; type "code_interpreter_call"constant` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - The type of the code interpreter tool call. Always `code_interpreter_call`. + We generally recommend altering this or `temperature` but not both. - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `Optional background` - - `Optional agent` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The agent that produced this item. + - `Optional completedAt` - - `String agentName` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The canonical name of the agent that produced this item. + - `Optional conversation` - - `LocalShellCall` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - `String id` - The unique ID of the local shell call. - - - `Action action` + The unique ID of the conversation that this response was associated with. - Execute a shell command on the server. + - `Optional maxOutputTokens` - - `List command` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The command to run. + - `Optional maxToolCalls` - - `Env env` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - Environment variables to set for the command. + - `Optional moderation` - - `JsonValue; type "exec"constant` + Moderation results for the response input and output, if moderated completions were requested. - The type of the local shell action. Always `exec`. + - `Input input` - - `EXEC("exec")` + Moderation for the response input. - - `Optional timeoutMs` + - `class ModerationResult:` - Optional timeout in milliseconds for the command. + A moderation result produced for the response input or output. - - `Optional user` + - `Categories categories` - Optional user to run the command as. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `Optional workingDirectory` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - Optional working directory to run the command in. + Which modalities of input are reflected by the score for each category. - - `String callId` + - `TEXT("text")` - The unique ID of the local shell tool call generated by the model. + - `IMAGE("image")` - - `Status status` + - `CategoryScores categoryScores` - The status of the local shell call. + A dictionary of moderation categories to scores. - - `IN_PROGRESS("in_progress")` + - `boolean flagged` - - `COMPLETED("completed")` + A boolean indicating whether the content was flagged by any category. - - `INCOMPLETE("incomplete")` + - `String model` - - `JsonValue; type "local_shell_call"constant` + The moderation model that produced this result. - The type of the local shell call. Always `local_shell_call`. + - `JsonValue; type "moderation_result"constant` - - `LOCAL_SHELL_CALL("local_shell_call")` + The object type, which was always `moderation_result` for successful moderation results. - - `Optional agent` + - `MODERATION_RESULT("moderation_result")` - The agent that produced this item. + - `class Error:` - - `String agentName` + An error produced while attempting moderation for the response input or output. - The canonical name of the agent that produced this item. + - `String code` - - `LocalShellCallOutput` + The error code. - - `String id` + - `String message` - The unique ID of the local shell tool call generated by the model. + The error message. - - `String output` + - `JsonValue; type "error"constant` - A JSON string of the output of the local shell tool call. + The object type, which was always `error` for moderation failures. - - `JsonValue; type "local_shell_call_output"constant` + - `ERROR("error")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `Output output` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + Moderation for the response output. - - `Optional agent` + - `class ModerationResult:` - The agent that produced this item. + A moderation result produced for the response input or output. - - `String agentName` + - `Categories categories` - The canonical name of the agent that produced this item. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `Optional status` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Which modalities of input are reflected by the score for each category. - - `IN_PROGRESS("in_progress")` + - `TEXT("text")` - - `COMPLETED("completed")` + - `IMAGE("image")` - - `INCOMPLETE("incomplete")` + - `CategoryScores categoryScores` - - `class BetaResponseFunctionShellToolCall:` + A dictionary of moderation categories to scores. - A tool call that executes one or more shell commands in a managed environment. + - `boolean flagged` - - `String id` + A boolean indicating whether the content was flagged by any category. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `String model` - - `Action action` + The moderation model that produced this result. - The shell commands and limits that describe how to run the tool call. + - `JsonValue; type "moderation_result"constant` - - `List commands` + The object type, which was always `moderation_result` for successful moderation results. - - `Optional maxOutputLength` + - `MODERATION_RESULT("moderation_result")` - Optional maximum number of characters to return from each command. + - `class Error:` - - `Optional timeoutMs` + An error produced while attempting moderation for the response input or output. - Optional timeout in milliseconds for the commands. + - `String code` - - `String callId` + The error code. - The unique ID of the shell tool call generated by the model. + - `String message` - - `Optional environment` + The error message. - Represents the use of a local environment to perform shell actions. + - `JsonValue; type "error"constant` - - `class BetaResponseLocalEnvironment:` + The object type, which was always `error` for moderation failures. - Represents the use of a local environment to perform shell actions. + - `ERROR("error")` - - `JsonValue; type "local"constant` + - `Optional previousResponseId` - The environment type. Always `local`. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `LOCAL("local")` + - `Optional prompt` - - `class BetaResponseContainerReference:` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - Represents a container created with /v1/containers. + - `String id` - - `String containerId` + The unique identifier of the prompt template to use. - - `JsonValue; type "container_reference"constant` + - `Optional variables` - The environment type. Always `container_reference`. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `CONTAINER_REFERENCE("container_reference")` + - `String` - - `Status status` + - `class BetaResponseInputText:` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + A text input to the model. - - `IN_PROGRESS("in_progress")` + - `class BetaResponseInputImage:` - - `COMPLETED("completed")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `INCOMPLETE("incomplete")` + - `class BetaResponseInputFile:` - - `JsonValue; type "shell_call"constant` + A file input to the model. - The type of the item. Always `shell_call`. + - `Optional version` - - `SHELL_CALL("shell_call")` + Optional version of the prompt template. - - `Optional agent` + - `Optional promptCacheKey` - The agent that produced this item. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `String agentName` + - `Optional promptCacheOptions` - The canonical name of the agent that produced this item. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `Optional caller` + - `Mode mode` - The execution context that produced this tool call. + Whether implicit prompt-cache breakpoints were enabled. - - `JsonValue;` + - `IMPLICIT("implicit")` - - `JsonValue; type "direct"constant` + - `EXPLICIT("explicit")` - - `DIRECT("direct")` + - `Ttl ttl` - - `class Program:` + The minimum lifetime applied to each cache breakpoint. - - `String callerId` + - `_30M("30m")` - The call ID of the program item that produced this tool call. + - `Optional promptCacheRetention` - - `JsonValue; type "program"constant` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `PROGRAM("program")` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `Optional createdBy` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The ID of the entity that created this tool call. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `class BetaResponseFunctionShellToolCallOutput:` + - `IN_MEMORY("in_memory")` - The output of a shell tool call that was emitted. + - `_24H("24h")` - - `String id` + - `Optional reasoning` - The unique ID of the shell call output. Populated when this item is returned via API. + **gpt-5 and o-series models only** - - `String callId` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The unique ID of the shell tool call generated by the model. + - `Optional context` - - `Optional maxOutputLength` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `AUTO("auto")` - - `List output` + - `CURRENT_TURN("current_turn")` - An array of shell call output contents + - `ALL_TURNS("all_turns")` - - `Outcome outcome` + - `Optional effort` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `JsonValue;` + - `NONE("none")` - - `JsonValue; type "timeout"constant` + - `MINIMAL("minimal")` - The outcome type. Always `timeout`. + - `LOW("low")` - - `TIMEOUT("timeout")` + - `MEDIUM("medium")` - - `class Exit:` + - `HIGH("high")` - Indicates that the shell commands finished and returned an exit code. + - `XHIGH("xhigh")` - - `long exitCode` + - `MAX("max")` - Exit code from the shell process. + - `Optional generateSummary` - - `JsonValue; type "exit"constant` + **Deprecated:** use `summary` instead. - The outcome type. Always `exit`. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `EXIT("exit")` + - `AUTO("auto")` - - `String stderr` + - `CONCISE("concise")` - The standard error output that was captured. + - `DETAILED("detailed")` - - `String stdout` + - `Optional mode` - The standard output that was captured. + Controls the reasoning execution mode for the request. - - `Optional createdBy` + When returned on a response, this is the effective execution mode. - The identifier of the actor that created the item. + - `STANDARD("standard")` - - `Status status` + - `PRO("pro")` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `Optional summary` - - `IN_PROGRESS("in_progress")` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `COMPLETED("completed")` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `INCOMPLETE("incomplete")` + - `AUTO("auto")` - - `JsonValue; type "shell_call_output"constant` + - `CONCISE("concise")` - The type of the shell call output. Always `shell_call_output`. + - `DETAILED("detailed")` - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional safetyIdentifier` - - `Optional agent` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The agent that produced this item. + - `Optional serviceTier` - - `String agentName` + Specifies the processing type used for serving the request. - The canonical name of the agent that produced this item. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `Optional caller` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The execution context that produced this tool call. + - `AUTO("auto")` - - `JsonValue;` + - `DEFAULT("default")` - - `JsonValue; type "direct"constant` + - `FLEX("flex")` - - `DIRECT("direct")` + - `SCALE("scale")` - - `class Program:` + - `PRIORITY("priority")` - - `String callerId` + - `Optional status` - The call ID of the program item that produced this tool call. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `JsonValue; type "program"constant` + - `COMPLETED("completed")` - - `PROGRAM("program")` + - `FAILED("failed")` - - `Optional createdBy` + - `IN_PROGRESS("in_progress")` - The identifier of the actor that created the item. + - `CANCELLED("cancelled")` - - `class BetaResponseApplyPatchToolCall:` + - `QUEUED("queued")` - A tool call that applies file diffs by creating, deleting, or updating files. + - `INCOMPLETE("incomplete")` - - `String id` + - `Optional text` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `String callId` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The unique ID of the apply patch tool call generated by the model. + - `Optional format` - - `Operation operation` + An object specifying the format that the model must output. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `class CreateFile:` + The default format is `{ "type": "text" }` with no additional options. - Instruction describing how to create a file via the apply_patch tool. + **Not recommended for gpt-4o and newer models:** - - `String diff` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - Diff to apply. + - `JsonValue;` - - `String path` + - `JsonValue; type "text"constant` - Path of the file to create. + The type of response format being defined. Always `text`. - - `JsonValue; type "create_file"constant` + - `TEXT("text")` - Create a new file with the provided diff. + - `class BetaResponseFormatTextJsonSchemaConfig:` - - `CREATE_FILE("create_file")` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `class DeleteFile:` + - `String name` - Instruction describing how to delete a file via the apply_patch tool. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `String path` + - `Schema schema` - Path of the file to delete. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `JsonValue; type "delete_file"constant` + - `JsonValue; type "json_schema"constant` - Delete the specified file. + The type of response format being defined. Always `json_schema`. - - `DELETE_FILE("delete_file")` + - `JSON_SCHEMA("json_schema")` - - `class UpdateFile:` + - `Optional description` - Instruction describing how to update a file via the apply_patch tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `String diff` + - `Optional strict` - Diff to apply. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `String path` + - `JsonValue;` - Path of the file to update. + - `JsonValue; type "json_object"constant` - - `JsonValue; type "update_file"constant` + The type of response format being defined. Always `json_object`. - Update an existing file with the provided diff. + - `JSON_OBJECT("json_object")` - - `UPDATE_FILE("update_file")` + - `Optional verbosity` - - `Status status` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `LOW("low")` - - `IN_PROGRESS("in_progress")` + - `MEDIUM("medium")` - - `COMPLETED("completed")` + - `HIGH("high")` - - `JsonValue; type "apply_patch_call"constant` + - `Optional topLogprobs` - The type of the item. Always `apply_patch_call`. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `Optional truncation` - - `Optional agent` + The truncation strategy to use for the model response. - The agent that produced this item. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `String agentName` + - `AUTO("auto")` - The canonical name of the agent that produced this item. + - `DISABLED("disabled")` - - `Optional caller` + - `Optional usage` - The execution context that produced this tool call. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `JsonValue;` + - `long inputTokens` - - `JsonValue; type "direct"constant` + The number of input tokens. - - `DIRECT("direct")` + - `InputTokensDetails inputTokensDetails` - - `class Program:` + A detailed breakdown of the input tokens. - - `String callerId` + - `long cacheWriteTokens` - The call ID of the program item that produced this tool call. + The number of input tokens that were written to the cache. - - `JsonValue; type "program"constant` + - `long cachedTokens` - - `PROGRAM("program")` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `Optional createdBy` + - `long outputTokens` - The ID of the entity that created this tool call. + The number of output tokens. - - `class BetaResponseApplyPatchToolCallOutput:` + - `OutputTokensDetails outputTokensDetails` - The output emitted by an apply patch tool call. + A detailed breakdown of the output tokens. - - `String id` + - `long reasoningTokens` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The number of reasoning tokens. - - `String callId` + - `long totalTokens` - The unique ID of the apply patch tool call generated by the model. + The total number of tokens used. - - `Status status` + - `Optional user` - The status of the apply patch tool call output. One of `completed` or `failed`. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `COMPLETED("completed")` + - `long sequenceNumber` - - `FAILED("failed")` + The sequence number of this event. - - `JsonValue; type "apply_patch_call_output"constant` + - `JsonValue; type "response.failed"constant` - The type of the item. Always `apply_patch_call_output`. + The type of the event. Always `response.failed`. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `RESPONSE_FAILED("response.failed")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` +### Beta Response File Search Call Completed Event - The execution context that produced this tool call. +- `class BetaResponseFileSearchCallCompletedEvent:` - - `JsonValue;` + Emitted when a file search call is completed (results found). - - `JsonValue; type "direct"constant` + - `String itemId` - - `DIRECT("direct")` + The ID of the output item that the file search call is initiated. - - `class Program:` + - `long outputIndex` - - `String callerId` + The index of the output item that the file search call is initiated. - The call ID of the program item that produced this tool call. + - `long sequenceNumber` - - `JsonValue; type "program"constant` + The sequence number of this event. - - `PROGRAM("program")` + - `JsonValue; type "response.file_search_call.completed"constant` - - `Optional createdBy` + The type of the event. Always `response.file_search_call.completed`. - The ID of the entity that created this tool call output. + - `RESPONSE_FILE_SEARCH_CALL_COMPLETED("response.file_search_call.completed")` - - `Optional output` + - `Optional agent` - Optional textual output returned by the apply patch tool. + The agent that owns this multi-agent streaming event. - - `McpCall` + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - The unique ID of the tool call. +### Beta Response File Search Call In Progress Event - - `String arguments` +- `class BetaResponseFileSearchCallInProgressEvent:` - A JSON string of the arguments passed to the tool. + Emitted when a file search call is initiated. - - `String name` + - `String itemId` - The name of the tool that was run. + The ID of the output item that the file search call is initiated. - - `String serverLabel` + - `long outputIndex` - The label of the MCP server running the tool. + The index of the output item that the file search call is initiated. - - `JsonValue; type "mcp_call"constant` + - `long sequenceNumber` - The type of the item. Always `mcp_call`. + The sequence number of this event. - - `MCP_CALL("mcp_call")` + - `JsonValue; type "response.file_search_call.in_progress"constant` + + The type of the event. Always `response.file_search_call.in_progress`. + + - `RESPONSE_FILE_SEARCH_CALL_IN_PROGRESS("response.file_search_call.in_progress")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional approvalRequestId` +### Beta Response File Search Call Searching Event - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. +- `class BetaResponseFileSearchCallSearchingEvent:` - - `Optional error` + Emitted when a file search is currently searching. - The error from the tool call, if any. + - `String itemId` - - `Optional output` + The ID of the output item that the file search call is initiated. - The output from the tool call. + - `long outputIndex` - - `Optional status` + The index of the output item that the file search call is searching. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `long sequenceNumber` - - `IN_PROGRESS("in_progress")` + The sequence number of this event. - - `COMPLETED("completed")` + - `JsonValue; type "response.file_search_call.searching"constant` - - `INCOMPLETE("incomplete")` + The type of the event. Always `response.file_search_call.searching`. - - `CALLING("calling")` + - `RESPONSE_FILE_SEARCH_CALL_SEARCHING("response.file_search_call.searching")` - - `FAILED("failed")` + - `Optional agent` - - `McpListTools` + The agent that owns this multi-agent streaming event. - - `String id` + - `String agentName` - The unique ID of the list. + The canonical name of the agent that produced this item. - - `String serverLabel` +### Beta Response File Search Tool Call - The label of the MCP server. +- `class BetaResponseFileSearchToolCall:` - - `List tools` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The tools available on the server. + - `String id` - - `JsonValue inputSchema` + The unique ID of the file search tool call. - The JSON schema describing the tool's input. + - `List queries` - - `String name` + The queries used to search for files. - The name of the tool. + - `Status status` - - `Optional annotations` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Additional annotations about the tool. + - `IN_PROGRESS("in_progress")` - - `Optional description` + - `SEARCHING("searching")` - The description of the tool. + - `COMPLETED("completed")` - - `JsonValue; type "mcp_list_tools"constant` + - `INCOMPLETE("incomplete")` - The type of the item. Always `mcp_list_tools`. + - `FAILED("failed")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `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 agent` @@ -48109,693 +63688,702 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional error` - - Error message if the server could not list tools. - - - `McpApprovalRequest` - - - `String id` + - `Optional> results` - The unique ID of the approval request. + The results of the file search tool call. - - `String arguments` + - `Optional attributes` - A JSON string of arguments for the tool. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `String name` + - `String` - The name of the tool to run. + - `double` - - `String serverLabel` + - `boolean` - The label of the MCP server making the request. + - `Optional fileId` - - `JsonValue; type "mcp_approval_request"constant` + The unique ID of the file. - The type of the item. Always `mcp_approval_request`. + - `Optional filename` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + The name of the file. - - `Optional agent` + - `Optional score` - The agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `String agentName` + - `Optional text` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - - `McpApprovalResponse` +### Beta Response Format Text Config - - `String id` +- `class BetaResponseFormatTextConfig: A class that can be one of several variants.union` - The unique ID of the approval response + An object specifying the format that the model must output. - - `String approvalRequestId` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The ID of the approval request being answered. + The default format is `{ "type": "text" }` with no additional options. - - `boolean approve` + **Not recommended for gpt-4o and newer models:** - Whether the request was approved. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `JsonValue; type "mcp_approval_response"constant` + - `JsonValue;` - The type of the item. Always `mcp_approval_response`. + - `JsonValue; type "text"constant` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + The type of response format being defined. Always `text`. - - `Optional agent` + - `TEXT("text")` - The agent that produced this item. + - `class BetaResponseFormatTextJsonSchemaConfig:` - - `String agentName` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The canonical name of the agent that produced this item. + - `String name` - - `Optional reason` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - Optional reason for the decision. + - `Schema schema` - - `class BetaResponseCustomToolCall:` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - A call to a custom tool created by the model. + - `JsonValue; type "json_schema"constant` - - `String callId` + The type of response format being defined. Always `json_schema`. - An identifier used to map this custom tool call to a tool call output. + - `JSON_SCHEMA("json_schema")` - - `String input` + - `Optional description` - The input for the custom tool call generated by the model. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `String name` + - `Optional strict` - The name of the custom tool being called. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `JsonValue; type "custom_tool_call"constant` + - `JsonValue;` - The type of the custom tool call. Always `custom_tool_call`. + - `JsonValue; type "json_object"constant` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + The type of response format being defined. Always `json_object`. - - `Optional id` + - `JSON_OBJECT("json_object")` - The unique ID of the custom tool call in the OpenAI platform. +### Beta Response Format Text JSON Schema Config - - `Optional agent` +- `class BetaResponseFormatTextJsonSchemaConfig:` - The agent that produced this item. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `String agentName` + - `String name` - The canonical name of the agent that produced this item. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `Optional caller` + - `Schema schema` - The execution context that produced this tool call. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `JsonValue;` + - `JsonValue; type "json_schema"constant` - - `JsonValue; type "direct"constant` + The type of response format being defined. Always `json_schema`. - - `DIRECT("direct")` + - `JSON_SCHEMA("json_schema")` - - `class Program:` + - `Optional description` - - `String callerId` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The call ID of the program item that produced this tool call. + - `Optional strict` - - `JsonValue; type "program"constant` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `PROGRAM("program")` +### Beta Response Function Call Arguments Delta Event - - `Optional namespace` +- `class BetaResponseFunctionCallArgumentsDeltaEvent:` - The namespace of the custom tool being called. + Emitted when there is a partial function-call arguments delta. - - `class BetaResponseCustomToolCallOutputItem:` + - `String delta` - The output of a custom tool call from your code, being sent back to the model. + The function-call arguments delta that is added. - - `String id` + - `String itemId` - The unique ID of the custom tool call output item. + The ID of the output item that the function-call arguments delta is added to. - - `Status status` + - `long outputIndex` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The index of the output item that the function-call arguments delta is added to. - - `IN_PROGRESS("in_progress")` + - `long sequenceNumber` - - `COMPLETED("completed")` + The sequence number of this event. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "response.function_call_arguments.delta"constant` - - `Optional createdBy` + The type of the event. Always `response.function_call_arguments.delta`. - The identifier of the actor that created the item. + - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DELTA("response.function_call_arguments.delta")` - - `BetaResponseUsage usage` + - `Optional agent` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + The agent that owns this multi-agent streaming event. - - `long inputTokens` + - `String agentName` - The number of input tokens. + The canonical name of the agent that produced this item. - - `InputTokensDetails inputTokensDetails` +### Beta Response Function Call Arguments Done Event - A detailed breakdown of the input tokens. +- `class BetaResponseFunctionCallArgumentsDoneEvent:` - - `long cacheWriteTokens` + Emitted when function-call arguments are finalized. - The number of input tokens that were written to the cache. + - `String arguments` - - `long cachedTokens` + The function-call arguments. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `String itemId` - - `long outputTokens` + The ID of the item. - The number of output tokens. + - `String name` - - `OutputTokensDetails outputTokensDetails` + The name of the function that was called. - A detailed breakdown of the output tokens. + - `long outputIndex` - - `long reasoningTokens` + The index of the output item. - The number of reasoning tokens. + - `long sequenceNumber` - - `long totalTokens` + The sequence number of this event. - The total number of tokens used. + - `JsonValue; type "response.function_call_arguments.done"constant` -### Beta Computer Action + - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DONE("response.function_call_arguments.done")` -- `class BetaComputerAction: A class that can be one of several variants.union` + - `Optional agent` - A click action. + The agent that owns this multi-agent streaming event. - - `Click` + - `String agentName` - - `Button button` + The canonical name of the agent that produced this item. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. +### Beta Response Function Call Output Item - - `LEFT("left")` +- `class BetaResponseFunctionCallOutputItem: A class that can be one of several variants.union` - - `RIGHT("right")` + A piece of message content, such as text, an image, or a file. - - `WHEEL("wheel")` + - `class BetaResponseInputTextContent:` - - `BACK("back")` + A text input to the model. - - `FORWARD("forward")` + - `String text` - - `JsonValue; type "click"constant` + The text input to the model. - Specifies the event type. For a click action, this property is always `click`. + - `JsonValue; type "input_text"constant` - - `CLICK("click")` + The type of the input item. Always `input_text`. - - `long x` + - `INPUT_TEXT("input_text")` - The x-coordinate where the click occurred. + - `Optional promptCacheBreakpoint` - - `long y` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The y-coordinate where the click occurred. + - `JsonValue; mode "explicit"constant` - - `Optional> keys` + The breakpoint mode. Always `explicit`. - The keys being held while clicking. + - `EXPLICIT("explicit")` - - `DoubleClick` + - `class BetaResponseInputImageContent:` - - `Optional> keys` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The keys being held while double-clicking. + - `JsonValue; type "input_image"constant` - - `JsonValue; type "double_click"constant` + The type of the input item. Always `input_image`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `INPUT_IMAGE("input_image")` - - `DOUBLE_CLICK("double_click")` + - `Optional detail` - - `long x` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The x-coordinate where the double click occurred. + - `LOW("low")` - - `long y` + - `HIGH("high")` - The y-coordinate where the double click occurred. + - `AUTO("auto")` - - `Drag` + - `ORIGINAL("original")` - - `List path` + - `Optional fileId` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The ID of the file to be sent to the model. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `Optional imageUrl` - - `long x` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The x-coordinate. + - `Optional promptCacheBreakpoint` - - `long y` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The y-coordinate. + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "drag"constant` + The breakpoint mode. Always `explicit`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `EXPLICIT("explicit")` - - `DRAG("drag")` + - `class BetaResponseInputFileContent:` - - `Optional> keys` + A file input to the model. - The keys being held while dragging the mouse. + - `JsonValue; type "input_file"constant` - - `Keypress` + The type of the input item. Always `input_file`. - - `List keys` + - `INPUT_FILE("input_file")` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `Optional detail` - - `JsonValue; type "keypress"constant` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `AUTO("auto")` - - `KEYPRESS("keypress")` + - `LOW("low")` - - `Move` + - `HIGH("high")` - - `JsonValue; type "move"constant` + - `Optional fileData` - Specifies the event type. For a move action, this property is always set to `move`. + The base64-encoded data of the file to be sent to the model. - - `MOVE("move")` + - `Optional fileId` - - `long x` + The ID of the file to be sent to the model. - The x-coordinate to move to. + - `Optional fileUrl` - - `long y` + The URL of the file to be sent to the model. - The y-coordinate to move to. + - `Optional filename` - - `Optional> keys` + The name of the file to be sent to the model. - The keys being held while moving the mouse. + - `Optional promptCacheBreakpoint` - - `JsonValue;` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "screenshot"constant` + - `JsonValue; mode "explicit"constant` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The breakpoint mode. Always `explicit`. - - `SCREENSHOT("screenshot")` + - `EXPLICIT("explicit")` - - `Scroll` +### Beta Response Function Shell Call Output Content - - `long scrollX` +- `class BetaResponseFunctionShellCallOutputContent:` - The horizontal scroll distance. + Captured stdout and stderr for a portion of a shell tool call output. - - `long scrollY` + - `Outcome outcome` - The vertical scroll distance. + The exit or timeout outcome associated with this shell call. - - `JsonValue; type "scroll"constant` + - `JsonValue;` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `JsonValue; type "timeout"constant` - - `SCROLL("scroll")` + The outcome type. Always `timeout`. - - `long x` + - `TIMEOUT("timeout")` - The x-coordinate where the scroll occurred. + - `class Exit:` - - `long y` + Indicates that the shell commands finished and returned an exit code. - The y-coordinate where the scroll occurred. + - `long exitCode` - - `Optional> keys` + The exit code returned by the shell process. - The keys being held while scrolling. + - `JsonValue; type "exit"constant` - - `Type` + The outcome type. Always `exit`. - - `String text` + - `EXIT("exit")` - The text to type. + - `String stderr` - - `JsonValue; type "type"constant` + Captured stderr output for the shell call. - Specifies the event type. For a type action, this property is always set to `type`. + - `String stdout` - - `TYPE("type")` + Captured stdout output for the shell call. - - `JsonValue;` +### Beta Response Function Shell Tool Call - - `JsonValue; type "wait"constant` +- `class BetaResponseFunctionShellToolCall:` - Specifies the event type. For a wait action, this property is always set to `wait`. + A tool call that executes one or more shell commands in a managed environment. - - `WAIT("wait")` + - `String id` -### Beta Computer Tool + The unique ID of the shell tool call. Populated when this item is returned via API. -- `class BetaComputerTool:` + - `Action action` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The shell commands and limits that describe how to run the tool call. - - `JsonValue; type "computer"constant` + - `List commands` - The type of the computer tool. Always `computer`. + - `Optional maxOutputLength` - - `COMPUTER("computer")` + Optional maximum number of characters to return from each command. -### Beta Computer Use Preview Tool + - `Optional timeoutMs` -- `class BetaComputerUsePreviewTool:` + Optional timeout in milliseconds for the commands. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String callId` - - `long displayHeight` + The unique ID of the shell tool call generated by the model. - The height of the computer display. + - `Optional environment` - - `long displayWidth` + Represents the use of a local environment to perform shell actions. - The width of the computer display. + - `class BetaResponseLocalEnvironment:` - - `Environment environment` + Represents the use of a local environment to perform shell actions. - The type of computer environment to control. + - `JsonValue; type "local"constant` - - `WINDOWS("windows")` + The environment type. Always `local`. - - `MAC("mac")` + - `LOCAL("local")` - - `LINUX("linux")` + - `class BetaResponseContainerReference:` - - `UBUNTU("ubuntu")` + Represents a container created with /v1/containers. - - `BROWSER("browser")` + - `String containerId` - - `JsonValue; type "computer_use_preview"constant` + - `JsonValue; type "container_reference"constant` - The type of the computer use tool. Always `computer_use_preview`. + The environment type. Always `container_reference`. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `CONTAINER_REFERENCE("container_reference")` -### Beta Container Auto + - `Status status` -- `class BetaContainerAuto:` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `JsonValue; type "container_auto"constant` + - `IN_PROGRESS("in_progress")` - Automatically creates a container for this request + - `COMPLETED("completed")` - - `CONTAINER_AUTO("container_auto")` + - `INCOMPLETE("incomplete")` - - `Optional> fileIds` + - `JsonValue; type "shell_call"constant` - An optional list of uploaded files to make available to your code. + The type of the item. Always `shell_call`. - - `Optional memoryLimit` + - `SHELL_CALL("shell_call")` - The memory limit for the container. + - `Optional agent` - - `_1G("1g")` + The agent that produced this item. - - `_4G("4g")` + - `String agentName` - - `_16G("16g")` + The canonical name of the agent that produced this item. - - `_64G("64g")` + - `Optional caller` - - `Optional networkPolicy` + The execution context that produced this tool call. - Network access policy for the container. + - `JsonValue;` - - `class BetaContainerNetworkPolicyDisabled:` + - `JsonValue; type "direct"constant` - - `JsonValue; type "disabled"constant` + - `DIRECT("direct")` - Disable outbound network access. Always `disabled`. + - `class Program:` - - `DISABLED("disabled")` + - `String callerId` - - `class BetaContainerNetworkPolicyAllowlist:` + The call ID of the program item that produced this tool call. - - `List allowedDomains` + - `JsonValue; type "program"constant` - A list of allowed domains when type is `allowlist`. + - `PROGRAM("program")` - - `JsonValue; type "allowlist"constant` + - `Optional createdBy` - Allow outbound network access only to specified domains. Always `allowlist`. + The ID of the entity that created this tool call. - - `ALLOWLIST("allowlist")` +### Beta Response Function Shell Tool Call Output - - `Optional> domainSecrets` +- `class BetaResponseFunctionShellToolCallOutput:` - Optional domain-scoped secrets for allowlisted domains. + The output of a shell tool call that was emitted. - - `String domain` + - `String id` - The domain associated with the secret. + The unique ID of the shell call output. Populated when this item is returned via API. - - `String name` + - `String callId` - The name of the secret to inject for the domain. + The unique ID of the shell tool call generated by the model. - - `String value` + - `Optional maxOutputLength` - The secret value to inject for the domain. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `Optional> skills` + - `List output` - An optional list of skills referenced by id or inline data. + An array of shell call output contents - - `class BetaSkillReference:` + - `Outcome outcome` - - `String skillId` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The ID of the referenced skill. + - `JsonValue;` - - `JsonValue; type "skill_reference"constant` + - `JsonValue; type "timeout"constant` - References a skill created with the /v1/skills endpoint. + The outcome type. Always `timeout`. - - `SKILL_REFERENCE("skill_reference")` + - `TIMEOUT("timeout")` - - `Optional version` + - `class Exit:` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Indicates that the shell commands finished and returned an exit code. - - `class BetaInlineSkill:` + - `long exitCode` - - `String description` + Exit code from the shell process. - The description of the skill. + - `JsonValue; type "exit"constant` - - `String name` + The outcome type. Always `exit`. - The name of the skill. + - `EXIT("exit")` - - `BetaInlineSkillSource source` + - `String stderr` - Inline skill payload + The standard error output that was captured. - - `String data` + - `String stdout` - Base64-encoded skill zip bundle. + The standard output that was captured. - - `JsonValue; mediaType "application/zip"constant` + - `Optional createdBy` - The media type of the inline skill payload. Must be `application/zip`. + The identifier of the actor that created the item. - - `APPLICATION_ZIP("application/zip")` + - `Status status` - - `JsonValue; type "base64"constant` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The type of the inline skill source. Must be `base64`. + - `IN_PROGRESS("in_progress")` - - `BASE64("base64")` + - `COMPLETED("completed")` - - `JsonValue; type "inline"constant` + - `INCOMPLETE("incomplete")` - Defines an inline skill for this request. + - `JsonValue; type "shell_call_output"constant` - - `INLINE("inline")` + The type of the shell call output. Always `shell_call_output`. -### Beta Container Network Policy Allowlist + - `SHELL_CALL_OUTPUT("shell_call_output")` -- `class BetaContainerNetworkPolicyAllowlist:` + - `Optional agent` - - `List allowedDomains` + The agent that produced this item. - A list of allowed domains when type is `allowlist`. + - `String agentName` - - `JsonValue; type "allowlist"constant` + The canonical name of the agent that produced this item. - Allow outbound network access only to specified domains. Always `allowlist`. + - `Optional caller` - - `ALLOWLIST("allowlist")` + The execution context that produced this tool call. - - `Optional> domainSecrets` + - `JsonValue;` - Optional domain-scoped secrets for allowlisted domains. + - `JsonValue; type "direct"constant` - - `String domain` + - `DIRECT("direct")` - The domain associated with the secret. + - `class Program:` - - `String name` + - `String callerId` - The name of the secret to inject for the domain. + The call ID of the program item that produced this tool call. - - `String value` + - `JsonValue; type "program"constant` - The secret value to inject for the domain. + - `PROGRAM("program")` -### Beta Container Network Policy Disabled + - `Optional createdBy` -- `class BetaContainerNetworkPolicyDisabled:` + The identifier of the actor that created the item. - - `JsonValue; type "disabled"constant` +### Beta Response Function Tool Call - Disable outbound network access. Always `disabled`. +- `class BetaResponseFunctionToolCall:` - - `DISABLED("disabled")` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. -### Beta Container Network Policy Domain Secret + - `String arguments` -- `class BetaContainerNetworkPolicyDomainSecret:` + A JSON string of the arguments to pass to the function. - - `String domain` + - `String callId` - The domain associated with the secret. + The unique ID of the function tool call generated by the model. - `String name` - The name of the secret to inject for the domain. - - - `String value` + The name of the function to run. - The secret value to inject for the domain. + - `JsonValue; type "function_call"constant` -### Beta Container Reference + The type of the function tool call. Always `function_call`. -- `class BetaContainerReference:` + - `FUNCTION_CALL("function_call")` - - `String containerId` + - `Optional id` - The ID of the referenced container. + The unique ID of the function tool call. - - `JsonValue; type "container_reference"constant` + - `Optional agent` - References a container created with the /v1/containers endpoint + The agent that produced this item. - - `CONTAINER_REFERENCE("container_reference")` + - `String agentName` -### Beta Custom Tool + The canonical name of the agent that produced this item. -- `class BetaCustomTool:` + - `Optional caller` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The execution context that produced this tool call. - - `String name` + - `JsonValue;` - The name of the custom tool, used to identify it in tool calls. + - `JsonValue; type "direct"constant` - - `JsonValue; type "custom"constant` + - `DIRECT("direct")` - The type of the custom tool. Always `custom`. + - `class Program:` - - `CUSTOM("custom")` + - `String callerId` - - `Optional> allowedCallers` + The call ID of the program item that produced this tool call. - The tool invocation context(s). + - `JsonValue; type "program"constant` - - `DIRECT("direct")` + - `PROGRAM("program")` - - `PROGRAMMATIC("programmatic")` + - `Optional namespace` - - `Optional deferLoading` + The namespace of the function to run. - Whether this tool should be deferred and discovered via tool search. + - `Optional status` - - `Optional description` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Optional description of the custom tool, used to provide more context. + - `IN_PROGRESS("in_progress")` - - `Optional format` + - `COMPLETED("completed")` - The input format for the custom tool. Default is unconstrained text. + - `INCOMPLETE("incomplete")` - - `JsonValue;` +### Beta Response Function Tool Call Item - - `JsonValue; type "text"constant` +- `class BetaResponseFunctionToolCallItem:` - Unconstrained text format. Always `text`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `TEXT("text")` + - `String id` - - `class Grammar:` + The unique ID of the function tool call. - A grammar defined by the user. + - `Status status` - - `String definition` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The grammar definition. + - `IN_PROGRESS("in_progress")` - - `Syntax syntax` + - `COMPLETED("completed")` - The syntax of the grammar definition. One of `lark` or `regex`. + - `INCOMPLETE("incomplete")` - - `LARK("lark")` + - `Optional createdBy` - - `REGEX("regex")` + The identifier of the actor that created the item. - - `JsonValue; type "grammar"constant` +### Beta Response Function Tool Call Output Item - Grammar format. Always `grammar`. +- `class BetaResponseFunctionToolCallOutputItem:` - - `GRAMMAR("grammar")` + - `String id` -### Beta Easy Input Message + The unique ID of the function call tool output. -- `class BetaEasyInputMessage:` + - `String callId` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The unique ID of the function tool call generated by the model. - - `Content content` + - `Output output` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The output from the function call generated by your code. + Can be a string or an list of output content. - `String` - - `List` + - `List` - `class BetaResponseInputText:` @@ -48907,648 +64495,310 @@ public final class Main { - `EXPLICIT("explicit")` - - `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` - - 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")` - - - `Optional type` - - The type of the message input. Always `message`. - - - `MESSAGE("message")` - -### Beta File Search Tool - -- `class BetaFileSearchTool:` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `JsonValue; type "file_search"constant` - - The type of the file search tool. Always `file_search`. - - - `FILE_SEARCH("file_search")` - - - `List vectorStoreIds` - - The IDs of the vector stores to search. - - - `Optional 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` - - - `class CompoundFilter:` - - Combine multiple filters using `and` or `or`. - - - `List 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. - - - `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` - - - `JsonValue` - - - `Type type` - - Type of operation: `and` or `or`. - - - `AND("and")` - - - `OR("or")` - - - `Optional maxNumResults` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `Optional rankingOptions` - - Ranking options for search. - - - `Optional 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. + - `Status status` - - `double textWeight` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The weight of the text in the reciprocal ranking fusion. + - `IN_PROGRESS("in_progress")` - - `Optional ranker` + - `COMPLETED("completed")` - The ranker to use for the file search. + - `INCOMPLETE("incomplete")` - - `AUTO("auto")` + - `JsonValue; type "function_call_output"constant` - - `DEFAULT_2024_11_15("default-2024-11-15")` + The type of the function tool call output. Always `function_call_output`. - - `Optional scoreThreshold` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `Optional agent` -### Beta Function Shell Tool + The agent that produced this item. -- `class BetaFunctionShellTool:` + - `String agentName` - A tool that allows the model to execute shell commands. + The canonical name of the agent that produced this item. - - `JsonValue; type "shell"constant` + - `Optional caller` - The type of the shell tool. Always `shell`. + The execution context that produced this tool call. - - `SHELL("shell")` + - `JsonValue;` - - `Optional> allowedCallers` + - `JsonValue; type "direct"constant` - The tool invocation context(s). + The caller type. Always `direct`. - `DIRECT("direct")` - - `PROGRAMMATIC("programmatic")` - - - `Optional environment` - - - `class BetaContainerAuto:` - - - `JsonValue; type "container_auto"constant` - - Automatically creates a container for this request - - - `CONTAINER_AUTO("container_auto")` - - - `Optional> fileIds` - - An optional list of uploaded files to make available to your code. - - - `Optional memoryLimit` - - The memory limit for the container. - - - `_1G("1g")` - - - `_4G("4g")` - - - `_16G("16g")` - - - `_64G("64g")` - - - `Optional networkPolicy` - - Network access policy for the container. - - - `class BetaContainerNetworkPolicyDisabled:` - - - `JsonValue; type "disabled"constant` - - Disable outbound network access. Always `disabled`. - - - `DISABLED("disabled")` - - - `class BetaContainerNetworkPolicyAllowlist:` - - - `List 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> 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. - - - `Optional> skills` - - An optional list of skills referenced by id or inline data. - - - `class BetaSkillReference:` - - - `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 version` - - Optional skill version. Use a positive integer or 'latest'. Omit for default. - - - `class BetaInlineSkill:` - - - `String description` - - The description of the skill. - - - `String name` - - The name of the skill. - - - `BetaInlineSkillSource 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 BetaLocalEnvironment:` - - - `JsonValue; type "local"constant` - - Use a local computer environment. - - - `LOCAL("local")` - - - `Optional> 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 BetaContainerReference:` - - - `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")` - -### Beta Function Tool - -- `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class Program:` - - `String name` + - `String callerId` - The name of the function to call. + The call ID of the program item that produced this tool call. - - `Optional parameters` + - `JsonValue; type "program"constant` - A JSON schema object describing the parameters of the function. + The caller type. Always `program`. - - `Optional strict` + - `PROGRAM("program")` - Whether strict parameter validation is enforced for this function tool. + - `Optional createdBy` - - `JsonValue; type "function"constant` + The identifier of the actor that created the item. - The type of the function tool. Always `function`. +### Beta Response Function Web Search - - `FUNCTION("function")` +- `class BetaResponseFunctionWebSearch:` - - `Optional> allowedCallers` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The tool invocation context(s). + - `String id` - - `DIRECT("direct")` + The unique ID of the web search tool call. - - `PROGRAMMATIC("programmatic")` + - `Action action` - - `Optional deferLoading` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - Whether this function is deferred and loaded via tool search. + - `class Search:` - - `Optional description` + Action type "search" - Performs a web search query. - A description of the function. Used by the model to determine whether or not to call the function. + - `JsonValue; type "search"constant` - - `Optional outputSchema` + The action type. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `SEARCH("search")` -### Beta Inline Skill + - `Optional> queries` -- `class BetaInlineSkill:` + The search queries. - - `String description` + - `Optional query` - The description of the skill. + The search query. - - `String name` + - `Optional> sources` - The name of the skill. + The sources used in the search. - - `BetaInlineSkillSource source` + - `JsonValue; type "url"constant` - Inline skill payload + The type of source. Always `url`. - - `String data` + - `URL("url")` - Base64-encoded skill zip bundle. + - `String url` - - `JsonValue; mediaType "application/zip"constant` + The URL of the source. - The media type of the inline skill payload. Must be `application/zip`. + - `class OpenPage:` - - `APPLICATION_ZIP("application/zip")` + Action type "open_page" - Opens a specific URL from search results. - - `JsonValue; type "base64"constant` + - `JsonValue; type "open_page"constant` - The type of the inline skill source. Must be `base64`. + The action type. - - `BASE64("base64")` + - `OPEN_PAGE("open_page")` - - `JsonValue; type "inline"constant` + - `Optional url` - Defines an inline skill for this request. + The URL opened by the model. - - `INLINE("inline")` + - `class FindInPage:` -### Beta Inline Skill Source + Action type "find_in_page": Searches for a pattern within a loaded page. -- `class BetaInlineSkillSource:` + - `String pattern` - Inline skill payload + The pattern or text to search for within the page. - - `String data` + - `JsonValue; type "find_in_page"constant` - Base64-encoded skill zip bundle. + The action type. - - `JsonValue; mediaType "application/zip"constant` + - `FIND_IN_PAGE("find_in_page")` - The media type of the inline skill payload. Must be `application/zip`. + - `String url` - - `APPLICATION_ZIP("application/zip")` + The URL of the page searched for the pattern. - - `JsonValue; type "base64"constant` + - `Status status` - The type of the inline skill source. Must be `base64`. + The status of the web search tool call. - - `BASE64("base64")` + - `IN_PROGRESS("in_progress")` -### Beta Local Environment + - `SEARCHING("searching")` -- `class BetaLocalEnvironment:` + - `COMPLETED("completed")` - - `JsonValue; type "local"constant` + - `FAILED("failed")` - Use a local computer environment. + - `JsonValue; type "web_search_call"constant` - - `LOCAL("local")` + The type of the web search tool call. Always `web_search_call`. - - `Optional> skills` + - `WEB_SEARCH_CALL("web_search_call")` - An optional list of skills. + - `Optional agent` - - `String description` + The agent that produced this item. - The description of the skill. + - `String agentName` - - `String name` + The canonical name of the agent that produced this item. - The name of the skill. +### Beta Response Image Gen Call Completed Event - - `String path` +- `class BetaResponseImageGenCallCompletedEvent:` - The path to the directory containing the skill. + Emitted when an image generation tool call has completed and the final image is available. -### Beta Local Skill + - `String itemId` -- `class BetaLocalSkill:` + The unique identifier of the image generation item being processed. - - `String description` + - `long outputIndex` - The description of the skill. + The index of the output item in the response's output array. - - `String name` + - `long sequenceNumber` - The name of the skill. + The sequence number of this event. - - `String path` + - `JsonValue; type "response.image_generation_call.completed"constant` - The path to the directory containing the skill. + The type of the event. Always 'response.image_generation_call.completed'. -### Beta Namespace Tool + - `RESPONSE_IMAGE_GENERATION_CALL_COMPLETED("response.image_generation_call.completed")` -- `class BetaNamespaceTool:` + - `Optional agent` - Groups function/custom tools under a shared namespace. + The agent that owns this multi-agent streaming event. - - `String description` + - `String agentName` - A description of the namespace shown to the model. + The canonical name of the agent that produced this item. - - `String name` +### Beta Response Image Gen Call Generating Event - The namespace name used in tool calls (for example, `crm`). +- `class BetaResponseImageGenCallGeneratingEvent:` - - `List tools` + Emitted when an image generation tool call is actively generating an image (intermediate state). - The function/custom tools available inside this namespace. + - `String itemId` - - `class Function:` + The unique identifier of the image generation item being processed. - - `String name` + - `long outputIndex` - - `JsonValue; type "function"constant` + The index of the output item in the response's output array. - - `FUNCTION("function")` + - `long sequenceNumber` - - `Optional> allowedCallers` + The sequence number of the image generation item being processed. - The tool invocation context(s). + - `JsonValue; type "response.image_generation_call.generating"constant` - - `DIRECT("direct")` + The type of the event. Always 'response.image_generation_call.generating'. - - `PROGRAMMATIC("programmatic")` + - `RESPONSE_IMAGE_GENERATION_CALL_GENERATING("response.image_generation_call.generating")` - - `Optional deferLoading` + - `Optional agent` - Whether this function should be deferred and discovered via tool search. + The agent that owns this multi-agent streaming event. - - `Optional description` + - `String agentName` - - `Optional outputSchema` + The canonical name of the agent that produced this item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +### Beta Response Image Gen Call In Progress Event - - `Optional parameters` +- `class BetaResponseImageGenCallInProgressEvent:` - - `Optional strict` + Emitted when an image generation tool call is in progress. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `String itemId` - - `class BetaCustomTool:` + The unique identifier of the image generation item being processed. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `long outputIndex` - - `String name` + The index of the output item in the response's output array. - The name of the custom tool, used to identify it in tool calls. + - `long sequenceNumber` - - `JsonValue; type "custom"constant` + The sequence number of the image generation item being processed. - The type of the custom tool. Always `custom`. + - `JsonValue; type "response.image_generation_call.in_progress"constant` - - `CUSTOM("custom")` + The type of the event. Always 'response.image_generation_call.in_progress'. - - `Optional> allowedCallers` + - `RESPONSE_IMAGE_GENERATION_CALL_IN_PROGRESS("response.image_generation_call.in_progress")` - The tool invocation context(s). + - `Optional agent` - - `DIRECT("direct")` + The agent that owns this multi-agent streaming event. - - `PROGRAMMATIC("programmatic")` + - `String agentName` - - `Optional deferLoading` + The canonical name of the agent that produced this item. - Whether this tool should be deferred and discovered via tool search. +### Beta Response Image Gen Call Partial Image Event - - `Optional description` +- `class BetaResponseImageGenCallPartialImageEvent:` - Optional description of the custom tool, used to provide more context. + Emitted when a partial image is available during image generation streaming. - - `Optional format` + - `String itemId` - The input format for the custom tool. Default is unconstrained text. + The unique identifier of the image generation item being processed. - - `JsonValue;` + - `long outputIndex` - - `JsonValue; type "text"constant` + The index of the output item in the response's output array. - Unconstrained text format. Always `text`. + - `String partialImageB64` - - `TEXT("text")` + Base64-encoded partial image data, suitable for rendering as an image. - - `class Grammar:` + - `long partialImageIndex` - A grammar defined by the user. + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `String definition` + - `long sequenceNumber` - The grammar definition. + The sequence number of the image generation item being processed. - - `Syntax syntax` + - `JsonValue; type "response.image_generation_call.partial_image"constant` - The syntax of the grammar definition. One of `lark` or `regex`. + The type of the event. Always 'response.image_generation_call.partial_image'. - - `LARK("lark")` + - `RESPONSE_IMAGE_GENERATION_CALL_PARTIAL_IMAGE("response.image_generation_call.partial_image")` - - `REGEX("regex")` + - `Optional agent` - - `JsonValue; type "grammar"constant` + The agent that owns this multi-agent streaming event. - Grammar format. Always `grammar`. + - `String agentName` - - `GRAMMAR("grammar")` + The canonical name of the agent that produced this item. - - `JsonValue; type "namespace"constant` +### Beta Response In Progress Event - The type of the tool. Always `namespace`. +- `class BetaResponseInProgressEvent:` - - `NAMESPACE("namespace")` + Emitted when the response is in progress. -### Beta Response + - `BetaResponse response` -- `class BetaResponse:` + The response that is in progress. - `String id` @@ -49780,6 +65030,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -50035,6 +65287,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -51171,7 +66425,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -51228,7 +66486,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -55784,447 +71046,15 @@ public final class Main { A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). -### Beta Response Apply Patch Tool Call - -- `class BetaResponseApplyPatchToolCall:` - - A tool call that applies file diffs by creating, deleting, or updating files. - - - `String id` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `String callId` - - The unique ID of the apply patch tool call generated by the model. - - - `Operation operation` - - One of the create_file, delete_file, or update_file operations applied via apply_patch. - - - `class CreateFile:` - - Instruction describing how to create a file via the apply_patch tool. - - - `String diff` - - Diff to apply. - - - `String path` - - Path of the file to create. - - - `JsonValue; type "create_file"constant` - - Create a new file with the provided diff. - - - `CREATE_FILE("create_file")` - - - `class DeleteFile:` - - Instruction describing how to delete a file via the apply_patch tool. - - - `String path` - - Path of the file to delete. - - - `JsonValue; type "delete_file"constant` - - Delete the specified file. - - - `DELETE_FILE("delete_file")` - - - `class UpdateFile:` - - Instruction describing how to update a file via the apply_patch tool. - - - `String diff` - - Diff to apply. - - - `String path` - - Path of the file to update. - - - `JsonValue; type "update_file"constant` - - Update an existing file with the provided diff. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call. - -### Beta Response Apply Patch Tool Call Output - -- `class BetaResponseApplyPatchToolCallOutput:` - - The output emitted by an apply patch tool call. - - - `String id` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call output. - - - `Optional output` - - Optional textual output returned by the apply patch tool. - -### Beta Response Audio Delta Event - -- `class BetaResponseAudioDeltaEvent:` - - Emitted when there is a partial audio response. - - - `String delta` - - A chunk of Base64 encoded response audio bytes. - - - `long sequenceNumber` - - A sequence number for this chunk of the stream response. - - - `JsonValue; type "response.audio.delta"constant` - - The type of the event. Always `response.audio.delta`. - - - `RESPONSE_AUDIO_DELTA("response.audio.delta")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Audio Done Event - -- `class BetaResponseAudioDoneEvent:` - - Emitted when the audio response is complete. - - - `long sequenceNumber` - - The sequence number of the delta. - - - `JsonValue; type "response.audio.done"constant` - - The type of the event. Always `response.audio.done`. - - - `RESPONSE_AUDIO_DONE("response.audio.done")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Audio Transcript Delta Event - -- `class BetaResponseAudioTranscriptDeltaEvent:` - - Emitted when there is a partial transcript of audio. - - - `String delta` - - The partial transcript of the audio response. - - - `long sequenceNumber` - - The sequence number of this event. - - - `JsonValue; type "response.audio.transcript.delta"constant` - - The type of the event. Always `response.audio.transcript.delta`. - - - `RESPONSE_AUDIO_TRANSCRIPT_DELTA("response.audio.transcript.delta")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Audio Transcript Done Event - -- `class BetaResponseAudioTranscriptDoneEvent:` - - Emitted when the full audio transcript is completed. - - `long sequenceNumber` The sequence number of this event. - - `JsonValue; type "response.audio.transcript.done"constant` - - The type of the event. Always `response.audio.transcript.done`. - - - `RESPONSE_AUDIO_TRANSCRIPT_DONE("response.audio.transcript.done")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Code Interpreter Call Code Delta Event - -- `class BetaResponseCodeInterpreterCallCodeDeltaEvent:` - - Emitted when a partial code snippet is streamed by the code interpreter. - - - `String delta` - - The partial code snippet being streamed by the code interpreter. - - - `String itemId` - - The unique identifier of the code interpreter tool call item. - - - `long outputIndex` - - The index of the output item in the response for which the code is being streamed. - - - `long sequenceNumber` - - The sequence number of this event, used to order streaming events. - - - `JsonValue; type "response.code_interpreter_call_code.delta"constant` - - The type of the event. Always `response.code_interpreter_call_code.delta`. - - - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DELTA("response.code_interpreter_call_code.delta")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Code Interpreter Call Code Done Event - -- `class BetaResponseCodeInterpreterCallCodeDoneEvent:` - - Emitted when the code snippet is finalized by the code interpreter. - - - `String code` - - The final code snippet output by the code interpreter. - - - `String itemId` - - The unique identifier of the code interpreter tool call item. - - - `long outputIndex` - - The index of the output item in the response for which the code is finalized. - - - `long sequenceNumber` - - The sequence number of this event, used to order streaming events. - - - `JsonValue; type "response.code_interpreter_call_code.done"constant` - - The type of the event. Always `response.code_interpreter_call_code.done`. - - - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DONE("response.code_interpreter_call_code.done")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Code Interpreter Call Completed Event - -- `class BetaResponseCodeInterpreterCallCompletedEvent:` - - Emitted when the code interpreter call is completed. - - - `String itemId` - - The unique identifier of the code interpreter tool call item. - - - `long outputIndex` - - The index of the output item in the response for which the code interpreter call is completed. - - - `long sequenceNumber` - - The sequence number of this event, used to order streaming events. - - - `JsonValue; type "response.code_interpreter_call.completed"constant` - - The type of the event. Always `response.code_interpreter_call.completed`. - - - `RESPONSE_CODE_INTERPRETER_CALL_COMPLETED("response.code_interpreter_call.completed")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Code Interpreter Call In Progress Event - -- `class BetaResponseCodeInterpreterCallInProgressEvent:` - - Emitted when a code interpreter call is in progress. - - - `String itemId` - - The unique identifier of the code interpreter tool call item. - - - `long outputIndex` - - The index of the output item in the response for which the code interpreter call is in progress. - - - `long sequenceNumber` - - The sequence number of this event, used to order streaming events. - - - `JsonValue; type "response.code_interpreter_call.in_progress"constant` - - The type of the event. Always `response.code_interpreter_call.in_progress`. - - - `RESPONSE_CODE_INTERPRETER_CALL_IN_PROGRESS("response.code_interpreter_call.in_progress")` - - - `Optional agent` - - The agent that owns this multi-agent streaming event. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Code Interpreter Call Interpreting Event - -- `class BetaResponseCodeInterpreterCallInterpretingEvent:` - - Emitted when the code interpreter is actively interpreting the code snippet. - - - `String itemId` - - The unique identifier of the code interpreter tool call item. - - - `long outputIndex` - - The index of the output item in the response for which the code interpreter is interpreting code. - - - `long sequenceNumber` - - The sequence number of this event, used to order streaming events. - - - `JsonValue; type "response.code_interpreter_call.interpreting"constant` + - `JsonValue; type "response.in_progress"constant` - The type of the event. Always `response.code_interpreter_call.interpreting`. + The type of the event. Always `response.in_progress`. - - `RESPONSE_CODE_INTERPRETER_CALL_INTERPRETING("response.code_interpreter_call.interpreting")` + - `RESPONSE_IN_PROGRESS("response.in_progress")` - `Optional agent` @@ -56234,154 +71064,46 @@ public final class Main { The canonical name of the agent that produced this item. -### Beta Response Code Interpreter Tool Call - -- `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. - - - `String id` - - The unique ID of the code interpreter tool call. - - - `Optional code` - - The code to run, or null if not available. - - - `String containerId` - - The ID of the container used to run the code. - - - `Optional> 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - -### Beta Response Compaction Item - -- `class BetaResponseCompactionItem:` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `String id` - - The unique ID of the compaction item. - - - `String encryptedContent` - - The encrypted content that was produced by compaction. - - - `JsonValue; type "compaction"constant` - - The type of the item. Always `compaction`. - - - `COMPACTION("compaction")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional createdBy` - - The identifier of the actor that created the item. - -### Beta Response Compaction Item Param - -- `class BetaResponseCompactionItemParam:` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). +### Beta Response Includable - - `String encryptedContent` +- `enum BetaResponseIncludable:` - The encrypted content of the compaction summary. + Specify additional output data to include in the model response. Currently supported values are: - - `JsonValue; type "compaction"constant` + - `web_search_call.results`: Include the search results of the web search tool call. + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - The type of the item. Always `compaction`. + - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` - - `COMPACTION("compaction")` + - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` - - `Optional id` + - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` - The ID of the compaction item. + - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` - - `Optional agent` + - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` - The agent that produced this item. + - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` - - `String agentName` + - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` - The canonical name of the agent that produced this item. + - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` -### Beta Response Completed Event +### Beta Response Incomplete Event -- `class BetaResponseCompletedEvent:` +- `class BetaResponseIncompleteEvent:` - Emitted when the model response is complete. + An event that is emitted when a response finishes as incomplete. - `BetaResponse response` - Properties of the completed response. + The response that was incomplete. - `String id` @@ -56613,6 +71335,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -56868,6 +71592,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -58004,7 +72730,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -58061,7 +72791,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -59625,1024 +74359,27 @@ public final class Main { - `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 id` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - The caller type. Always `program`. - - - `PROGRAM("program")` - - - `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 id` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - The caller type. Always `program`. - - - `PROGRAM("program")` - - - `Optional 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 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 annotations` - - Additional annotations about the tool. - - - `Optional 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `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 id` - - The unique ID of the approval response - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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 error` - - The error from the tool call, if any. - - - `Optional output` - - The output from the tool call. - - - `Optional 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 BetaResponseCustomToolCallOutput:` - - 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` - - - `class BetaResponseInputText:` - - A text input to the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `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 id` - - The unique ID of the custom tool call output in the OpenAI platform. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - The caller type. Always `program`. - - - `PROGRAM("program")` - - - `class BetaResponseCustomToolCall:` - - 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 id` - - The unique ID of the custom tool call in the OpenAI platform. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional namespace` - - The namespace of the custom tool being called. - - - `CompactionTrigger` - - - `JsonValue; type "compaction_trigger"constant` - - The type of the item. Always `compaction_trigger`. - - - `COMPACTION_TRIGGER("compaction_trigger")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ItemReference` - - - `String id` - - The ID of the item to reference. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional type` - - The type of item to reference. Always `item_reference`. - - - `ITEM_REFERENCE("item_reference")` - - - `Program` - - - `String id` - - The unique ID of this program item. - - - `String callId` - - The stable call ID of the program item. - - - `String code` - - The JavaScript source executed by programmatic tool calling. - - - `String fingerprint` - - Opaque program replay fingerprint that must be round-tripped. - - - `JsonValue; type "program"constant` - - The item type. Always `program`. - - - `PROGRAM("program")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ProgramOutput` - - - `String id` - - The unique ID of this program output item. - - - `String callId` - - The call ID of the program item. - - - `String result` - - The result produced by the program item. - - - `Status status` - - The terminal status of the program output. - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `JsonValue; type "program_output"constant` - - The item type. Always `program_output`. - - - `PROGRAM_OUTPUT("program_output")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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. - - - `Model model` - - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. - - - `GPT_5_6_SOL("gpt-5.6-sol")` - - - `GPT_5_6_TERRA("gpt-5.6-terra")` - - - `GPT_5_6_LUNA("gpt-5.6-luna")` - - - `GPT_5_4("gpt-5.4")` - - - `GPT_5_4_MINI("gpt-5.4-mini")` - - - `GPT_5_4_NANO("gpt-5.4-nano")` - - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - - `GPT_5_2("gpt-5.2")` - - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - - `GPT_5_2_PRO("gpt-5.2-pro")` - - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - - `GPT_5_1("gpt-5.1")` - - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - - `GPT_5_1_CODEX("gpt-5.1-codex")` - - - `GPT_5_1_MINI("gpt-5.1-mini")` - - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - - `GPT_5("gpt-5")` - - - `GPT_5_MINI("gpt-5-mini")` - - - `GPT_5_NANO("gpt-5-nano")` - - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - - `GPT_4_1("gpt-4.1")` - - - `GPT_4_1_MINI("gpt-4.1-mini")` - - - `GPT_4_1_NANO("gpt-4.1-nano")` - - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - - - `O4_MINI("o4-mini")` - - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - - - `O3("o3")` - - - `O3_2025_04_16("o3-2025-04-16")` - - - `O3_MINI("o3-mini")` - - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - - `O1("o1")` - - - `O1_2024_12_17("o1-2024-12-17")` - - - `O1_PREVIEW("o1-preview")` - - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - - - `O1_MINI("o1-mini")` - - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - - - `GPT_4O("gpt-4o")` - - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - - `CODEX_MINI_LATEST("codex-mini-latest")` - - - `GPT_4O_MINI("gpt-4o-mini")` - - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - - - `GPT_4_TURBO("gpt-4-turbo")` - - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - - - `GPT_4("gpt-4")` - - - `GPT_4_0314("gpt-4-0314")` - - - `GPT_4_0613("gpt-4-0613")` - - - `GPT_4_32K("gpt-4-32k")` - - - `GPT_4_32K_0314("gpt-4-32k-0314")` - - - `GPT_4_32K_0613("gpt-4-32k-0613")` - - - `GPT_3_5_TURBO("gpt-3.5-turbo")` - - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - - - `O1_PRO("o1-pro")` - - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - - - `O3_PRO("o3-pro")` - - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - - - `O3_DEEP_RESEARCH("o3-deep-research")` - - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - - - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - - - `GPT_5_CODEX("gpt-5-codex")` - - - `GPT_5_PRO("gpt-5-pro")` - - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - - - `JsonValue; object_ "response"constant` - - The object type of this resource - always set to `response`. - - - `RESPONSE("response")` - - - `List output` - - An array of content items generated by the model. - - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. - - - `class BetaResponseOutputMessage:` - - An output message from the model. - - - `class BetaResponseFileSearchToolCall:` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - - `class BetaResponseFunctionToolCall:` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - - `class BetaResponseFunctionToolCallOutputItem:` - - - `String id` - - The unique ID of the function call tool output. - - - `String callId` - - The unique ID of the function tool call generated by the model. - - - `Output output` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `String` - - - `List` - - - `class BetaResponseInputText:` - - A text input to the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `Status 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")` - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - The caller type. Always `program`. - - - `PROGRAM("program")` - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `AgentMessage` - - - `String id` - - The unique ID of the agent message. - - - `String author` - - The sending agent identity. - - - `List content` - - Encrypted content sent between agents. - - - `class BetaResponseInputText:` - - A text input to the model. - - - `class BetaResponseOutputText:` - - A text output from the model. - - - `class Text:` - - A text content. - - - `String text` - - - `JsonValue; type "text"constant` - - - `TEXT("text")` - - - `class SummaryText:` - - 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 BetaResponseOutputRefusal:` - - A refusal from the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class ComputerScreenshot:` - - A screenshot of a computer. - - - `Detail 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 fileId` - - The identifier of an uploaded file that contains the screenshot. - - - `Optional 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `class EncryptedContent:` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `String encryptedContent` - - Opaque encrypted content. - - - `JsonValue; type "encrypted_content"constant` - - The type of the input item. Always `encrypted_content`. - - - `ENCRYPTED_CONTENT("encrypted_content")` - - - `String recipient` - - The destination agent identity. - - - `JsonValue; type "agent_message"constant` - - The type of the item. Always `agent_message`. - - - `AGENT_MESSAGE("agent_message")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `MultiAgentCall` - - - `String id` - - The unique ID of the multi-agent call item. - - - `Action action` - - The multi-agent action to execute. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` + The operation type. Always `update_file`. - - `SEND_MESSAGE("send_message")` + - `UPDATE_FILE("update_file")` - - `FOLLOWUP_TASK("followup_task")` + - `Status status` - - `WAIT_AGENT("wait_agent")` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `String arguments` + - `IN_PROGRESS("in_progress")` - The JSON string of arguments generated for the action. + - `COMPLETED("completed")` - - `String callId` + - `JsonValue; type "apply_patch_call"constant` - The unique ID linking this call to its output. + The type of the item. Always `apply_patch_call`. - - `JsonValue; type "multi_agent_call"constant` + - `APPLY_PATCH_CALL("apply_patch_call")` - The type of the multi-agent call. Always `multi_agent_call`. + - `Optional id` - - `MULTI_AGENT_CALL("multi_agent_call")` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `Optional agent` @@ -60652,55 +74389,53 @@ public final class Main { The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `String id` + - `Optional caller` - The unique ID of the multi-agent call output item. + The execution context that produced this tool call. - - `Action action` + - `JsonValue;` - The multi-agent action that produced this result. + - `JsonValue; type "direct"constant` - - `SPAWN_AGENT("spawn_agent")` + The caller type. Always `direct`. - - `INTERRUPT_AGENT("interrupt_agent")` + - `DIRECT("direct")` - - `LIST_AGENTS("list_agents")` + - `class Program:` - - `SEND_MESSAGE("send_message")` + - `String callerId` - - `FOLLOWUP_TASK("followup_task")` + The call ID of the program item that produced this tool call. - - `WAIT_AGENT("wait_agent")` + - `JsonValue; type "program"constant` - - `String callId` + The caller type. Always `program`. - The unique ID of the multi-agent call. + - `PROGRAM("program")` - - `List output` + - `ApplyPatchCallOutput` - Text output returned by the multi-agent action. + - `String callId` - - `List annotations` + The unique ID of the apply patch tool call generated by the model. - The annotations of the text output. + - `Status status` - - `String text` + The status of the apply patch tool call output. One of `completed` or `failed`. - The text output from the model. + - `COMPLETED("completed")` - - `JsonValue; type "output_text"constant` + - `FAILED("failed")` - The type of the output text. Always `output_text`. + - `JsonValue; type "apply_patch_call_output"constant` - - `Optional> logprobs` + The type of the item. Always `apply_patch_call_output`. - - `JsonValue; type "multi_agent_call_output"constant` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `Optional id` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `Optional agent` @@ -60710,65 +74445,69 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch:` + - `Optional caller` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The execution context that produced this tool call. - - `class BetaResponseComputerToolCall:` + - `JsonValue;` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `JsonValue; type "direct"constant` - - `class BetaResponseComputerToolCallOutputItem:` + The caller type. Always `direct`. - - `String id` + - `DIRECT("direct")` - The unique ID of the computer call tool output. + - `class Program:` - - `String callId` + - `String callerId` - The ID of the computer tool call that produced the output. + The call ID of the program item that produced this tool call. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `JsonValue; type "program"constant` - A computer screenshot image used with the computer use tool. + The caller type. Always `program`. - - `Status status` + - `PROGRAM("program")` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `Optional output` - - `COMPLETED("completed")` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `INCOMPLETE("incomplete")` + - `McpListTools` - - `FAILED("failed")` + - `String id` - - `IN_PROGRESS("in_progress")` + The unique ID of the list. - - `JsonValue; type "computer_call_output"constant` + - `String serverLabel` - The type of the computer tool call output. Always `computer_call_output`. + The label of the MCP server. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `List tools` - - `Optional> acknowledgedSafetyChecks` + The tools available on the server. - The safety checks reported by the API that have been acknowledged by the - developer. + - `JsonValue inputSchema` - - `String id` + The JSON schema describing the tool's input. - The ID of the pending safety check. + - `String name` - - `Optional code` + The name of the tool. - The type of the pending safety check. + - `Optional annotations` - - `Optional message` + Additional annotations about the tool. - Details about the pending safety check. + - `Optional 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 agent` @@ -60778,40 +74517,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `class BetaResponseReasoningItem:` + - `Optional error` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Error message if the server could not list tools. - - `Program` + - `McpApprovalRequest` - `String id` - The unique ID of the program item. + The unique ID of the approval request. - - `String callId` + - `String arguments` - The stable call ID of the program item. + A JSON string of arguments for the tool. - - `String code` + - `String name` - The JavaScript source executed by programmatic tool calling. + The name of the tool to run. - - `String fingerprint` + - `String serverLabel` - Opaque program replay fingerprint that must be round-tripped. + The label of the MCP server making the request. - - `JsonValue; type "program"constant` + - `JsonValue; type "mcp_approval_request"constant` - The type of the item. Always `program`. + The type of the item. Always `mcp_approval_request`. - - `PROGRAM("program")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - `Optional agent` @@ -60821,33 +74553,25 @@ public final class Main { The canonical name of the agent that produced this item. - - `ProgramOutput` - - - `String id` - - The unique ID of the program output item. - - - `String callId` - - The call ID of the program item. + - `McpApprovalResponse` - - `String result` + - `String approvalRequestId` - The result produced by the program item. + The ID of the approval request being answered. - - `Status status` + - `boolean approve` - The terminal status of the program output item. + Whether the request was approved. - - `COMPLETED("completed")` + - `JsonValue; type "mcp_approval_response"constant` - - `INCOMPLETE("incomplete")` + The type of the item. Always `mcp_approval_response`. - - `JsonValue; type "program_output"constant` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - The type of the item. Always `program_output`. + - `Optional id` - - `PROGRAM_OUTPUT("program_output")` + The unique ID of the approval response - `Optional agent` @@ -60857,43 +74581,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall:` - - - `String id` - - The unique ID of the tool search call item. - - - `JsonValue arguments` - - Arguments used for the tool search call. - - - `Optional callId` + - `Optional reason` - The unique ID of the tool search call generated by the model. + Optional reason for the decision. - - `Execution execution` + - `McpCall` - Whether tool search was executed by the server or by the client. + - `String id` - - `SERVER("server")` + The unique ID of the tool call. - - `CLIENT("client")` + - `String arguments` - - `Status status` + A JSON string of the arguments passed to the tool. - The status of the tool search call item that was recorded. + - `String name` - - `IN_PROGRESS("in_progress")` + The name of the tool that was run. - - `COMPLETED("completed")` + - `String serverLabel` - - `INCOMPLETE("incomplete")` + The label of the MCP server running the tool. - - `JsonValue; type "tool_search_call"constant` + - `JsonValue; type "mcp_call"constant` - The type of the item. Always `tool_search_call`. + The type of the item. Always `mcp_call`. - - `TOOL_SEARCH_CALL("tool_search_call")` + - `MCP_CALL("mcp_call")` - `Optional agent` @@ -60903,31 +74617,22 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem:` - - - `String id` - - The unique ID of the tool search output item. - - - `Optional callId` + - `Optional approvalRequestId` - The unique ID of the tool search call generated by the model. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `Execution execution` + - `Optional error` - Whether tool search was executed by the server or by the client. + The error from the tool call, if any. - - `SERVER("server")` + - `Optional output` - - `CLIENT("client")` + The output from the tool call. - - `Status status` + - `Optional status` - The status of the tool search output item that was recorded. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `IN_PROGRESS("in_progress")` @@ -60935,199 +74640,198 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `List tools` + - `CALLING("calling")` - The loaded tool definitions returned by tool search. + - `FAILED("failed")` - - `class BetaFunctionTool:` + - `class BetaResponseCustomToolCallOutput:` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The output of a custom tool call from your code, being sent back to the model. - - `class BetaFileSearchTool:` + - `String callId` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The call ID, used to map this custom tool call output to a custom tool call. - - `class BetaComputerTool:` + - `Output output` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `class BetaComputerUsePreviewTool:` + - `String` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `List` - - `class BetaWebSearchTool:` + - `class BetaResponseInputText:` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A text input to the model. - - `Mcp` + - `class BetaResponseInputImage:` - - `CodeInterpreter` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `JsonValue;` + - `class BetaResponseInputFile:` - - `ImageGeneration` + A file input to the model. - - `JsonValue;` + - `JsonValue; type "custom_tool_call_output"constant` - - `class BetaFunctionShellTool:` + The type of the custom tool call output. Always `custom_tool_call_output`. - A tool that allows the model to execute shell commands. + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - - `class BetaCustomTool:` + - `Optional id` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The unique ID of the custom tool call output in the OpenAI platform. - - `class BetaNamespaceTool:` + - `Optional agent` - Groups function/custom tools under a shared namespace. + The agent that produced this item. - - `class BetaToolSearchTool:` + - `String agentName` - Hosted or BYOT tool search configuration for deferred tools. + The canonical name of the agent that produced this item. - - `class BetaWebSearchPreviewTool:` + - `Optional caller` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The execution context that produced this tool call. - - `class BetaApplyPatchTool:` + - `JsonValue;` - Allows the assistant to create, delete, or update files using unified diffs. + - `JsonValue; type "direct"constant` - - `JsonValue; type "tool_search_output"constant` + The caller type. Always `direct`. - The type of the item. Always `tool_search_output`. + - `DIRECT("direct")` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `class Program:` - - `Optional agent` + - `String callerId` - The agent that produced this item. + The call ID of the program item that produced this tool call. - - `String agentName` + - `JsonValue; type "program"constant` - The canonical name of the agent that produced this item. + The caller type. Always `program`. - - `Optional createdBy` + - `PROGRAM("program")` - The identifier of the actor that created the item. + - `class BetaResponseCustomToolCall:` - - `AdditionalTools` + A call to a custom tool created by the model. - - `String id` + - `String callId` - The unique ID of the additional tools item. + An identifier used to map this custom tool call to a tool call output. - - `Role role` + - `String input` - The role that provided the additional tools. + The input for the custom tool call generated by the model. - - `UNKNOWN("unknown")` + - `String name` - - `USER("user")` + The name of the custom tool being called. - - `ASSISTANT("assistant")` + - `JsonValue; type "custom_tool_call"constant` - - `SYSTEM("system")` + The type of the custom tool call. Always `custom_tool_call`. - - `CRITIC("critic")` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - - `DISCRIMINATOR("discriminator")` + - `Optional id` - - `DEVELOPER("developer")` + The unique ID of the custom tool call in the OpenAI platform. - - `TOOL("tool")` + - `Optional agent` - - `List tools` + The agent that produced this item. - The additional tool definitions made available at this item. + - `String agentName` - - `class BetaFunctionTool:` + The canonical name of the agent that produced this item. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Optional caller` - - `class BetaFileSearchTool:` + The execution context that produced this tool call. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `JsonValue;` - - `class BetaComputerTool:` + - `JsonValue; type "direct"constant` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `DIRECT("direct")` - - `class BetaComputerUsePreviewTool:` + - `class Program:` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String callerId` - - `class BetaWebSearchTool:` + The call ID of the program item that produced this tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "program"constant` - - `Mcp` + - `PROGRAM("program")` - - `CodeInterpreter` + - `Optional namespace` - - `JsonValue;` + The namespace of the custom tool being called. - - `ImageGeneration` + - `CompactionTrigger` - - `JsonValue;` + - `JsonValue; type "compaction_trigger"constant` - - `class BetaFunctionShellTool:` + The type of the item. Always `compaction_trigger`. - A tool that allows the model to execute shell commands. + - `COMPACTION_TRIGGER("compaction_trigger")` - - `class BetaCustomTool:` + - `Optional agent` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The agent that produced this item. - - `class BetaNamespaceTool:` + - `String agentName` - Groups function/custom tools under a shared namespace. + The canonical name of the agent that produced this item. - - `class BetaToolSearchTool:` + - `ItemReference` - Hosted or BYOT tool search configuration for deferred tools. + - `String id` - - `class BetaWebSearchPreviewTool:` + The ID of the item to reference. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional agent` - - `class BetaApplyPatchTool:` + The agent that produced this item. - Allows the assistant to create, delete, or update files using unified diffs. + - `String agentName` - - `JsonValue; type "additional_tools"constant` + The canonical name of the agent that produced this item. - The type of the item. Always `additional_tools`. + - `Optional type` - - `ADDITIONAL_TOOLS("additional_tools")` + The type of item to reference. Always `item_reference`. - - `Optional agent` + - `ITEM_REFERENCE("item_reference")` - The agent that produced this item. + - `Program` - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The unique ID of this program item. - - `class BetaResponseCompactionItem:` + - `String callId` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The stable call ID of the program item. - - `String id` + - `String code` - The unique ID of the compaction item. + The JavaScript source executed by programmatic tool calling. - - `String encryptedContent` + - `String fingerprint` - The encrypted content that was produced by compaction. + Opaque program replay fingerprint that must be round-tripped. - - `JsonValue; type "compaction"constant` + - `JsonValue; type "program"constant` - The type of the item. Always `compaction`. + The item type. Always `program`. - - `COMPACTION("compaction")` + - `PROGRAM("program")` - `Optional agent` @@ -61137,37 +74841,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `ProgramOutput` - The identifier of the actor that created the item. + - `String id` - - `ImageGenerationCall` + The unique ID of this program output item. - - `String id` + - `String callId` - The unique ID of the image generation call. + The call ID of the program item. - - `Optional result` + - `String result` - The generated image encoded in base64. + The result produced by the program item. - `Status status` - The status of the image generation call. - - - `IN_PROGRESS("in_progress")` + The terminal status of the program output. - `COMPLETED("completed")` - - `GENERATING("generating")` - - - `FAILED("failed")` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "program_output"constant` - The type of the image generation call. Always `image_generation_call`. + The item type. Always `program_output`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -61177,269 +74877,278 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. - - - `LocalShellCall` - - - `String id` + - `Optional metadata` - The unique ID of the local shell call. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Action action` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Execute a shell command on the server. + - `Model model` - - `List command` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - The command to run. + - `GPT_5_6_SOL("gpt-5.6-sol")` - - `Env env` + - `GPT_5_6_TERRA("gpt-5.6-terra")` - Environment variables to set for the command. + - `GPT_5_6_LUNA("gpt-5.6-luna")` - - `JsonValue; type "exec"constant` + - `GPT_5_4("gpt-5.4")` - The type of the local shell action. Always `exec`. + - `GPT_5_4_MINI("gpt-5.4-mini")` - - `EXEC("exec")` + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `Optional timeoutMs` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - Optional timeout in milliseconds for the command. + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - `Optional user` + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - Optional user to run the command as. + - `GPT_5_2("gpt-5.2")` - - `Optional workingDirectory` + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - Optional working directory to run the command in. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - `String callId` + - `GPT_5_2_PRO("gpt-5.2-pro")` - The unique ID of the local shell tool call generated by the model. + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `Status status` + - `GPT_5_1("gpt-5.1")` - The status of the local shell call. + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - `IN_PROGRESS("in_progress")` + - `GPT_5_1_CODEX("gpt-5.1-codex")` - - `COMPLETED("completed")` + - `GPT_5_1_MINI("gpt-5.1-mini")` - - `INCOMPLETE("incomplete")` + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - `JsonValue; type "local_shell_call"constant` + - `GPT_5("gpt-5")` - The type of the local shell call. Always `local_shell_call`. + - `GPT_5_MINI("gpt-5-mini")` - - `LOCAL_SHELL_CALL("local_shell_call")` + - `GPT_5_NANO("gpt-5-nano")` - - `Optional agent` + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - The agent that produced this item. + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `String agentName` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - The canonical name of the agent that produced this item. + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `LocalShellCallOutput` + - `GPT_4_1("gpt-4.1")` - - `String id` + - `GPT_4_1_MINI("gpt-4.1-mini")` - The unique ID of the local shell tool call generated by the model. + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `String output` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - A JSON string of the output of the local shell tool call. + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `JsonValue; type "local_shell_call_output"constant` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `O4_MINI("o4-mini")` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - - `Optional agent` + - `O3("o3")` - The agent that produced this item. + - `O3_2025_04_16("o3-2025-04-16")` - - `String agentName` + - `O3_MINI("o3-mini")` - The canonical name of the agent that produced this item. + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - `Optional status` + - `O1("o1")` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `O1_2024_12_17("o1-2024-12-17")` - - `IN_PROGRESS("in_progress")` + - `O1_PREVIEW("o1-preview")` - - `COMPLETED("completed")` + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - - `INCOMPLETE("incomplete")` + - `O1_MINI("o1-mini")` - - `class BetaResponseFunctionShellToolCall:` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - A tool call that executes one or more shell commands in a managed environment. + - `GPT_4O("gpt-4o")` - - `String id` + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - `Action action` + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - The shell commands and limits that describe how to run the tool call. + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - `List commands` + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - `Optional maxOutputLength` + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - Optional maximum number of characters to return from each command. + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - - `Optional timeoutMs` + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - Optional timeout in milliseconds for the commands. + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - `String callId` + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - The unique ID of the shell tool call generated by the model. + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `Optional environment` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - Represents the use of a local environment to perform shell actions. + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - `class BetaResponseLocalEnvironment:` + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - Represents the use of a local environment to perform shell actions. + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `JsonValue; type "local"constant` + - `GPT_4O_MINI("gpt-4o-mini")` - The environment type. Always `local`. + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - - `LOCAL("local")` + - `GPT_4_TURBO("gpt-4-turbo")` - - `class BetaResponseContainerReference:` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - Represents a container created with /v1/containers. + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `String containerId` + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `JsonValue; type "container_reference"constant` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - The environment type. Always `container_reference`. + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - - `CONTAINER_REFERENCE("container_reference")` + - `GPT_4("gpt-4")` - - `Status status` + - `GPT_4_0314("gpt-4-0314")` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `GPT_4_0613("gpt-4-0613")` - - `IN_PROGRESS("in_progress")` + - `GPT_4_32K("gpt-4-32k")` - - `COMPLETED("completed")` + - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `INCOMPLETE("incomplete")` + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `JsonValue; type "shell_call"constant` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - The type of the item. Always `shell_call`. + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `SHELL_CALL("shell_call")` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - - `Optional agent` + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - The agent that produced this item. + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - - `String agentName` + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - The canonical name of the agent that produced this item. + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - - `Optional caller` + - `O1_PRO("o1-pro")` - The execution context that produced this tool call. + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - - `JsonValue;` + - `O3_PRO("o3-pro")` - - `JsonValue; type "direct"constant` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - - `DIRECT("direct")` + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `class Program:` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - - `String callerId` + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - The call ID of the program item that produced this tool call. + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - - `JsonValue; type "program"constant` + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - `PROGRAM("program")` + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - - `Optional createdBy` + - `GPT_5_CODEX("gpt-5-codex")` - The ID of the entity that created this tool call. + - `GPT_5_PRO("gpt-5-pro")` - - `class BetaResponseFunctionShellToolCallOutput:` + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - The output of a shell tool call that was emitted. + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - - `String id` + - `JsonValue; object_ "response"constant` - The unique ID of the shell call output. Populated when this item is returned via API. + The object type of this resource - always set to `response`. - - `String callId` + - `RESPONSE("response")` - The unique ID of the shell tool call generated by the model. + - `List output` - - `Optional maxOutputLength` + An array of content items generated by the model. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `List output` + - `class BetaResponseOutputMessage:` - An array of shell call output contents + An output message from the model. - - `Outcome outcome` + - `class BetaResponseFileSearchToolCall:` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `JsonValue;` + - `class BetaResponseFunctionToolCall:` - - `JsonValue; type "timeout"constant` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The outcome type. Always `timeout`. + - `class BetaResponseFunctionToolCallOutputItem:` - - `TIMEOUT("timeout")` + - `String id` - - `class Exit:` + The unique ID of the function call tool output. - Indicates that the shell commands finished and returned an exit code. + - `String callId` - - `long exitCode` + The unique ID of the function tool call generated by the model. - Exit code from the shell process. + - `Output output` - - `JsonValue; type "exit"constant` + The output from the function call generated by your code. + Can be a string or an list of output content. - The outcome type. Always `exit`. + - `String` - - `EXIT("exit")` + - `List` - - `String stderr` + - `class BetaResponseInputText:` - The standard error output that was captured. + A text input to the model. - - `String stdout` + - `class BetaResponseInputImage:` - The standard output that was captured. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional createdBy` + - `class BetaResponseInputFile:` - The identifier of the actor that created the item. + A file input to the model. - `Status status` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -61447,11 +75156,11 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `JsonValue; type "shell_call_output"constant` + - `JsonValue; type "function_call_output"constant` - The type of the shell call output. Always `shell_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional agent` @@ -61469,6 +75178,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -61479,149 +75190,149 @@ public final class Main { - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - `Optional createdBy` The identifier of the actor that created the item. - - `class BetaResponseApplyPatchToolCall:` - - A tool call that applies file diffs by creating, deleting, or updating files. + - `AgentMessage` - `String id` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of the agent message. - - `String callId` + - `String author` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `Operation operation` + - `List content` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Encrypted content sent between agents. - - `class CreateFile:` + - `class BetaResponseInputText:` - Instruction describing how to create a file via the apply_patch tool. + A text input to the model. - - `String diff` + - `class BetaResponseOutputText:` - Diff to apply. + A text output from the model. - - `String path` + - `class Text:` - Path of the file to create. + A text content. - - `JsonValue; type "create_file"constant` + - `String text` - Create a new file with the provided diff. + - `JsonValue; type "text"constant` - - `CREATE_FILE("create_file")` + - `TEXT("text")` - - `class DeleteFile:` + - `class SummaryText:` - Instruction describing how to delete a file via the apply_patch tool. + A summary text from the model. - - `String path` + - `String text` - Path of the file to delete. + A summary of the reasoning output from the model so far. - - `JsonValue; type "delete_file"constant` + - `JsonValue; type "summary_text"constant` - Delete the specified file. + The type of the object. Always `summary_text`. - - `DELETE_FILE("delete_file")` + - `SUMMARY_TEXT("summary_text")` - - `class UpdateFile:` + - `class ReasoningText:` - Instruction describing how to update a file via the apply_patch tool. + Reasoning text from the model. - - `String diff` + - `String text` - Diff to apply. + The reasoning text from the model. - - `String path` + - `JsonValue; type "reasoning_text"constant` - Path of the file to update. + The type of the reasoning text. Always `reasoning_text`. - - `JsonValue; type "update_file"constant` + - `REASONING_TEXT("reasoning_text")` - Update an existing file with the provided diff. + - `class BetaResponseOutputRefusal:` - - `UPDATE_FILE("update_file")` + A refusal from the model. - - `Status status` + - `class BetaResponseInputImage:` - The status of the apply patch tool call. One of `in_progress` or `completed`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `IN_PROGRESS("in_progress")` + - `class ComputerScreenshot:` - - `COMPLETED("completed")` + A screenshot of a computer. - - `JsonValue; type "apply_patch_call"constant` + - `Detail detail` - The type of the item. Always `apply_patch_call`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `LOW("low")` - - `Optional agent` + - `HIGH("high")` - The agent that produced this item. + - `AUTO("auto")` - - `String agentName` + - `ORIGINAL("original")` - The canonical name of the agent that produced this item. + - `Optional fileId` - - `Optional caller` + The identifier of an uploaded file that contains the screenshot. - The execution context that produced this tool call. + - `Optional imageUrl` - - `JsonValue;` + The URL of the screenshot image. - - `JsonValue; type "direct"constant` + - `JsonValue; type "computer_screenshot"constant` - - `DIRECT("direct")` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `class Program:` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `String callerId` + - `Optional promptCacheBreakpoint` - The call ID of the program item that produced this tool call. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "program"constant` + - `JsonValue; mode "explicit"constant` - - `PROGRAM("program")` + The breakpoint mode. Always `explicit`. - - `Optional createdBy` + - `EXPLICIT("explicit")` - The ID of the entity that created this tool call. + - `class BetaResponseInputFile:` - - `class BetaResponseApplyPatchToolCallOutput:` + A file input to the model. - The output emitted by an apply patch tool call. + - `class EncryptedContent:` - - `String id` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `String encryptedContent` - - `String callId` + Opaque encrypted content. - The unique ID of the apply patch tool call generated by the model. + - `JsonValue; type "encrypted_content"constant` - - `Status status` + The type of the input item. Always `encrypted_content`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `COMPLETED("completed")` + - `String recipient` - - `FAILED("failed")` + The destination agent identity. - - `JsonValue; type "apply_patch_call_output"constant` + - `JsonValue; type "agent_message"constant` - The type of the item. Always `apply_patch_call_output`. + The type of the item. Always `agent_message`. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `AGENT_MESSAGE("agent_message")` - `Optional agent` @@ -61631,57 +75342,41 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` + - `MultiAgentCall` - The call ID of the program item that produced this tool call. + - `String id` - - `JsonValue; type "program"constant` + The unique ID of the multi-agent call item. - - `PROGRAM("program")` + - `Action action` - - `Optional createdBy` + The multi-agent action to execute. - The ID of the entity that created this tool call output. + - `SPAWN_AGENT("spawn_agent")` - - `Optional output` + - `INTERRUPT_AGENT("interrupt_agent")` - Optional textual output returned by the apply patch tool. + - `LIST_AGENTS("list_agents")` - - `McpCall` + - `SEND_MESSAGE("send_message")` - - `String id` + - `FOLLOWUP_TASK("followup_task")` - The unique ID of the tool call. + - `WAIT_AGENT("wait_agent")` - `String arguments` - A JSON string of the arguments passed to the tool. - - - `String name` - - The name of the tool that was run. + The JSON string of arguments generated for the action. - - `String serverLabel` + - `String callId` - The label of the MCP server running the tool. + The unique ID linking this call to its output. - - `JsonValue; type "mcp_call"constant` + - `JsonValue; type "multi_agent_call"constant` - The type of the item. Always `mcp_call`. + The type of the multi-agent call. Always `multi_agent_call`. - - `MCP_CALL("mcp_call")` + - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional agent` @@ -61691,104 +75386,55 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional 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 error` - - The error from the tool call, if any. - - - `Optional output` - - The output from the tool call. - - - `Optional 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")` - - - `McpListTools` + - `MultiAgentCallOutput` - `String id` - The unique ID of the list. - - - `String serverLabel` - - The label of the MCP server. - - - `List 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 annotations` - - Additional annotations about the tool. - - - `Optional description` + The unique ID of the multi-agent call output item. - The description of the tool. + - `Action action` - - `JsonValue; type "mcp_list_tools"constant` + The multi-agent action that produced this result. - The type of the item. Always `mcp_list_tools`. + - `SPAWN_AGENT("spawn_agent")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `Optional agent` + - `LIST_AGENTS("list_agents")` - The agent that produced this item. + - `SEND_MESSAGE("send_message")` - - `String agentName` + - `FOLLOWUP_TASK("followup_task")` - The canonical name of the agent that produced this item. + - `WAIT_AGENT("wait_agent")` - - `Optional error` + - `String callId` - Error message if the server could not list tools. + The unique ID of the multi-agent call. - - `McpApprovalRequest` + - `List output` - - `String id` + Text output returned by the multi-agent action. - The unique ID of the approval request. + - `List annotations` - - `String arguments` + The annotations of the text output. - A JSON string of arguments for the tool. + - `String text` - - `String name` + The text output from the model. - The name of the tool to run. + - `JsonValue; type "output_text"constant` - - `String serverLabel` + The type of the output text. Always `output_text`. - The label of the MCP server making the request. + - `Optional> logprobs` - - `JsonValue; type "mcp_approval_request"constant` + - `JsonValue; type "multi_agent_call_output"constant` - The type of the item. Always `mcp_approval_request`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - `Optional agent` @@ -61798,263 +75444,234 @@ public final class Main { The canonical name of the agent that produced this item. - - `McpApprovalResponse` + - `class BetaResponseFunctionWebSearch:` - - `String id` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The unique ID of the approval response + - `class BetaResponseComputerToolCall:` - - `String approvalRequestId` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The ID of the approval request being answered. + - `class BetaResponseComputerToolCallOutputItem:` - - `boolean approve` + - `String id` - Whether the request was approved. + The unique ID of the computer call tool output. - - `JsonValue; type "mcp_approval_response"constant` + - `String callId` - The type of the item. Always `mcp_approval_response`. + The ID of the computer tool call that produced the output. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `BetaResponseComputerToolCallOutputScreenshot output` - - `Optional agent` + A computer screenshot image used with the computer use tool. - The agent that produced this item. + - `Status status` - - `String agentName` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The canonical name of the agent that produced this item. + - `COMPLETED("completed")` - - `Optional reason` + - `INCOMPLETE("incomplete")` - Optional reason for the decision. + - `FAILED("failed")` - - `class BetaResponseCustomToolCall:` + - `IN_PROGRESS("in_progress")` - A call to a custom tool created by the model. + - `JsonValue; type "computer_call_output"constant` - - `class BetaResponseCustomToolCallOutputItem:` + The type of the computer tool call output. Always `computer_call_output`. - The output of a custom tool call from your code, being sent back to the model. + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `String id` + - `Optional> acknowledgedSafetyChecks` - The unique ID of the custom tool call output item. + The safety checks reported by the API that have been acknowledged by the + developer. - - `Status status` + - `String id` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The ID of the pending safety check. - - `IN_PROGRESS("in_progress")` + - `Optional code` - - `COMPLETED("completed")` + The type of the pending safety check. - - `INCOMPLETE("incomplete")` + - `Optional message` - - `Optional createdBy` + Details about the pending safety check. - The identifier of the actor that created the item. + - `Optional agent` - - `boolean parallelToolCalls` + The agent that produced this item. - Whether to allow the model to run tool calls in parallel. + - `String agentName` - - `Optional temperature` + The canonical name of the agent that produced this item. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `Optional createdBy` - - `ToolChoice toolChoice` + The identifier of the actor that created the item. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `class BetaResponseReasoningItem:` - - `enum BetaToolChoiceOptions:` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - Controls which (if any) tool is called by the model. + - `Program` - `none` means the model will not call any tool and instead generates a message. + - `String id` - `auto` means the model can pick between generating a message or calling one or - more tools. + The unique ID of the program item. - `required` means the model must call one or more tools. + - `String callId` - - `NONE("none")` + The stable call ID of the program item. - - `AUTO("auto")` + - `String code` - - `REQUIRED("required")` + The JavaScript source executed by programmatic tool calling. - - `class BetaToolChoiceAllowed:` + - `String fingerprint` - Constrains the tools available to the model to a pre-defined set. + Opaque program replay fingerprint that must be round-tripped. - - `Mode mode` + - `JsonValue; type "program"constant` - Constrains the tools available to the model to a pre-defined set. + The type of the item. Always `program`. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `PROGRAM("program")` - `required` requires the model to call one or more of the allowed tools. + - `Optional agent` - - `AUTO("auto")` + The agent that produced this item. - - `REQUIRED("required")` + - `String agentName` - - `List tools` + The canonical name of the agent that produced this item. - A list of tool definitions that the model should be allowed to call. + - `ProgramOutput` - For the Responses API, the list of tool definitions might look like: + - `String id` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The unique ID of the program output item. - - `JsonValue; type "allowed_tools"constant` + - `String callId` - Allowed tool configuration type. Always `allowed_tools`. + The call ID of the program item. - - `ALLOWED_TOOLS("allowed_tools")` + - `String result` - - `class BetaToolChoiceTypes:` + The result produced by the program item. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `Status status` - - `Type type` + The terminal status of the program output item. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `COMPLETED("completed")` - Allowed values are: + - `INCOMPLETE("incomplete")` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `JsonValue; type "program_output"constant` - - `FILE_SEARCH("file_search")` + The type of the item. Always `program_output`. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `PROGRAM_OUTPUT("program_output")` - - `COMPUTER("computer")` + - `Optional agent` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The agent that produced this item. - - `COMPUTER_USE("computer_use")` + - `String agentName` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The canonical name of the agent that produced this item. - - `IMAGE_GENERATION("image_generation")` + - `class BetaResponseToolSearchCall:` - - `CODE_INTERPRETER("code_interpreter")` + - `String id` - - `class BetaToolChoiceFunction:` + The unique ID of the tool search call item. - Use this option to force the model to call a specific function. + - `JsonValue arguments` - - `String name` + Arguments used for the tool search call. - The name of the function to call. + - `Optional callId` - - `JsonValue; type "function"constant` + The unique ID of the tool search call generated by the model. - For function calling, the type is always `function`. + - `Execution execution` - - `FUNCTION("function")` + Whether tool search was executed by the server or by the client. - - `class BetaToolChoiceMcp:` + - `SERVER("server")` - Use this option to force the model to call a specific tool on a remote MCP server. + - `CLIENT("client")` - - `String serverLabel` + - `Status status` - The label of the MCP server to use. + The status of the tool search call item that was recorded. - - `JsonValue; type "mcp"constant` + - `IN_PROGRESS("in_progress")` - For MCP tools, the type is always `mcp`. + - `COMPLETED("completed")` - - `MCP("mcp")` + - `INCOMPLETE("incomplete")` - - `Optional name` + - `JsonValue; type "tool_search_call"constant` - The name of the tool to call on the server. + The type of the item. Always `tool_search_call`. - - `class BetaToolChoiceCustom:` + - `TOOL_SEARCH_CALL("tool_search_call")` - Use this option to force the model to call a specific custom tool. + - `Optional agent` - - `String name` + The agent that produced this item. - The name of the custom tool to call. + - `String agentName` - - `JsonValue; type "custom"constant` + The canonical name of the agent that produced this item. - For custom tool calling, the type is always `custom`. + - `Optional createdBy` - - `CUSTOM("custom")` + The identifier of the actor that created the item. - - `JsonValue;` + - `class BetaResponseToolSearchOutputItem:` - - `JsonValue; type "programmatic_tool_calling"constant` + - `String id` - The tool to call. Always `programmatic_tool_calling`. + The unique ID of the tool search output item. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional callId` - - `class BetaToolChoiceApplyPatch:` + The unique ID of the tool search call generated by the model. - Forces the model to call the apply_patch tool when executing a tool call. + - `Execution execution` - - `JsonValue; type "apply_patch"constant` + Whether tool search was executed by the server or by the client. - The tool to call. Always `apply_patch`. + - `SERVER("server")` - - `APPLY_PATCH("apply_patch")` + - `CLIENT("client")` - - `class BetaToolChoiceShell:` + - `Status status` - Forces the model to call the shell tool when a tool call is required. + The status of the tool search output item that was recorded. - - `JsonValue; type "shell"constant` + - `IN_PROGRESS("in_progress")` - The tool to call. Always `shell`. + - `COMPLETED("completed")` - - `SHELL("shell")` + - `INCOMPLETE("incomplete")` - `List tools` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. - - We support the following categories of tools: - - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool:` @@ -62111,777 +75728,694 @@ public final class Main { Allows the assistant to create, delete, or update files using unified diffs. - - `Optional topP` + - `JsonValue; type "tool_search_output"constant` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The type of the item. Always `tool_search_output`. - We generally recommend altering this or `temperature` but not both. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `Optional background` + - `Optional agent` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The agent that produced this item. - - `Optional completedAt` + - `String agentName` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The canonical name of the agent that produced this item. - - `Optional conversation` + - `Optional createdBy` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The identifier of the actor that created the item. + + - `AdditionalTools` - `String id` - The unique ID of the conversation that this response was associated with. + The unique ID of the additional tools item. - - `Optional maxOutputTokens` + - `Role role` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The role that provided the additional tools. - - `Optional maxToolCalls` + - `UNKNOWN("unknown")` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `USER("user")` - - `Optional moderation` + - `ASSISTANT("assistant")` - Moderation results for the response input and output, if moderated completions were requested. + - `SYSTEM("system")` - - `Input input` + - `CRITIC("critic")` - Moderation for the response input. + - `DISCRIMINATOR("discriminator")` - - `class ModerationResult:` + - `DEVELOPER("developer")` - A moderation result produced for the response input or output. + - `TOOL("tool")` - - `Categories categories` + - `List tools` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The additional tool definitions made available at this item. - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `class BetaFunctionTool:` - Which modalities of input are reflected by the score for each category. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `TEXT("text")` + - `class BetaFileSearchTool:` - - `IMAGE("image")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `CategoryScores categoryScores` + - `class BetaComputerTool:` - A dictionary of moderation categories to scores. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `boolean flagged` + - `class BetaComputerUsePreviewTool:` - A boolean indicating whether the content was flagged by any category. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String model` + - `class BetaWebSearchTool:` - The moderation model that produced this result. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue; type "moderation_result"constant` + - `Mcp` - The object type, which was always `moderation_result` for successful moderation results. + - `CodeInterpreter` - - `MODERATION_RESULT("moderation_result")` + - `JsonValue;` - - `class Error:` + - `ImageGeneration` - An error produced while attempting moderation for the response input or output. + - `JsonValue;` - - `String code` + - `class BetaFunctionShellTool:` - The error code. + A tool that allows the model to execute shell commands. - - `String message` + - `class BetaCustomTool:` - The error message. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `JsonValue; type "error"constant` + - `class BetaNamespaceTool:` - The object type, which was always `error` for moderation failures. + Groups function/custom tools under a shared namespace. - - `ERROR("error")` + - `class BetaToolSearchTool:` - - `Output output` + Hosted or BYOT tool search configuration for deferred tools. - Moderation for the response output. + - `class BetaWebSearchPreviewTool:` - - `class ModerationResult:` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A moderation result produced for the response input or output. + - `class BetaApplyPatchTool:` - - `Categories categories` + Allows the assistant to create, delete, or update files using unified diffs. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `JsonValue; type "additional_tools"constant` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + The type of the item. Always `additional_tools`. - Which modalities of input are reflected by the score for each category. + - `ADDITIONAL_TOOLS("additional_tools")` - - `TEXT("text")` + - `Optional agent` - - `IMAGE("image")` + The agent that produced this item. - - `CategoryScores categoryScores` + - `String agentName` - A dictionary of moderation categories to scores. + The canonical name of the agent that produced this item. - - `boolean flagged` + - `class BetaResponseCompactionItem:` - A boolean indicating whether the content was flagged by any category. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `String model` + - `String id` - The moderation model that produced this result. + The unique ID of the compaction item. - - `JsonValue; type "moderation_result"constant` + - `String encryptedContent` - The object type, which was always `moderation_result` for successful moderation results. + The encrypted content that was produced by compaction. - - `MODERATION_RESULT("moderation_result")` + - `JsonValue; type "compaction"constant` - - `class Error:` + The type of the item. Always `compaction`. - An error produced while attempting moderation for the response input or output. + - `COMPACTION("compaction")` - - `String code` + - `Optional agent` - The error code. + The agent that produced this item. - - `String message` + - `String agentName` - The error message. + The canonical name of the agent that produced this item. - - `JsonValue; type "error"constant` + - `Optional createdBy` - The object type, which was always `error` for moderation failures. + The identifier of the actor that created the item. - - `ERROR("error")` + - `ImageGenerationCall` - - `Optional previousResponseId` + - `String id` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The unique ID of the image generation call. - - `Optional prompt` + - `Optional result` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The generated image encoded in base64. - - `String id` + - `Status status` - The unique identifier of the prompt template to use. + The status of the image generation call. - - `Optional variables` + - `IN_PROGRESS("in_progress")` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `COMPLETED("completed")` - - `String` + - `GENERATING("generating")` - - `class BetaResponseInputText:` + - `FAILED("failed")` - A text input to the model. + - `JsonValue; type "image_generation_call"constant` - - `class BetaResponseInputImage:` + The type of the image generation call. Always `image_generation_call`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `class BetaResponseInputFile:` + - `Optional agent` - A file input to the model. + The agent that produced this item. - - `Optional version` + - `String agentName` - Optional version of the prompt template. + The canonical name of the agent that produced this item. - - `Optional promptCacheKey` + - `class BetaResponseCodeInterpreterToolCall:` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + A tool call to run code. - - `Optional promptCacheOptions` + - `LocalShellCall` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `String id` - - `Mode mode` + The unique ID of the local shell call. - Whether implicit prompt-cache breakpoints were enabled. + - `Action action` - - `IMPLICIT("implicit")` + Execute a shell command on the server. - - `EXPLICIT("explicit")` + - `List command` - - `Ttl ttl` + The command to run. - The minimum lifetime applied to each cache breakpoint. + - `Env env` - - `_30M("30m")` + Environment variables to set for the command. - - `Optional promptCacheRetention` + - `JsonValue; type "exec"constant` - Deprecated. Use `prompt_cache_options.ttl` instead. + The type of the local shell action. Always `exec`. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `EXEC("exec")` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `Optional timeoutMs` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Optional timeout in milliseconds for the command. - - `IN_MEMORY("in_memory")` + - `Optional user` - - `_24H("24h")` + Optional user to run the command as. - - `Optional reasoning` + - `Optional workingDirectory` - **gpt-5 and o-series models only** + Optional working directory to run the command in. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `String callId` - - `Optional context` + The unique ID of the local shell tool call generated by the model. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `Status status` - - `AUTO("auto")` + The status of the local shell call. - - `CURRENT_TURN("current_turn")` + - `IN_PROGRESS("in_progress")` - - `ALL_TURNS("all_turns")` + - `COMPLETED("completed")` - - `Optional effort` + - `INCOMPLETE("incomplete")` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `JsonValue; type "local_shell_call"constant` - - `NONE("none")` + The type of the local shell call. Always `local_shell_call`. - - `MINIMAL("minimal")` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `LOW("low")` + - `Optional agent` - - `MEDIUM("medium")` + The agent that produced this item. - - `HIGH("high")` + - `String agentName` - - `XHIGH("xhigh")` + The canonical name of the agent that produced this item. - - `MAX("max")` + - `LocalShellCallOutput` - - `Optional generateSummary` + - `String id` - **Deprecated:** use `summary` instead. + The unique ID of the local shell tool call generated by the model. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `String output` - - `AUTO("auto")` + A JSON string of the output of the local shell tool call. - - `CONCISE("concise")` + - `JsonValue; type "local_shell_call_output"constant` - - `DETAILED("detailed")` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `Optional mode` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - Controls the reasoning execution mode for the request. + - `Optional agent` - When returned on a response, this is the effective execution mode. + The agent that produced this item. - - `STANDARD("standard")` + - `String agentName` - - `PRO("pro")` + The canonical name of the agent that produced this item. - - `Optional summary` + - `Optional status` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `IN_PROGRESS("in_progress")` - - `AUTO("auto")` + - `COMPLETED("completed")` - - `CONCISE("concise")` + - `INCOMPLETE("incomplete")` - - `DETAILED("detailed")` + - `class BetaResponseFunctionShellToolCall:` - - `Optional safetyIdentifier` + A tool call that executes one or more shell commands in a managed environment. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `String id` - - `Optional serviceTier` + The unique ID of the shell tool call. Populated when this item is returned via API. - Specifies the processing type used for serving the request. + - `Action action` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The shell commands and limits that describe how to run the tool call. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `List commands` - - `AUTO("auto")` + - `Optional maxOutputLength` - - `DEFAULT("default")` + Optional maximum number of characters to return from each command. - - `FLEX("flex")` + - `Optional timeoutMs` - - `SCALE("scale")` + Optional timeout in milliseconds for the commands. - - `PRIORITY("priority")` + - `String callId` - - `Optional status` + The unique ID of the shell tool call generated by the model. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `Optional environment` - - `COMPLETED("completed")` + Represents the use of a local environment to perform shell actions. - - `FAILED("failed")` + - `class BetaResponseLocalEnvironment:` - - `IN_PROGRESS("in_progress")` + Represents the use of a local environment to perform shell actions. - - `CANCELLED("cancelled")` + - `JsonValue; type "local"constant` - - `QUEUED("queued")` + The environment type. Always `local`. - - `INCOMPLETE("incomplete")` + - `LOCAL("local")` - - `Optional text` + - `class BetaResponseContainerReference:` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Represents a container created with /v1/containers. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `String containerId` - - `Optional format` + - `JsonValue; type "container_reference"constant` - An object specifying the format that the model must output. + The environment type. Always `container_reference`. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `CONTAINER_REFERENCE("container_reference")` - The default format is `{ "type": "text" }` with no additional options. + - `Status status` - **Not recommended for gpt-4o and newer models:** + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `IN_PROGRESS("in_progress")` - - `JsonValue;` + - `COMPLETED("completed")` - - `JsonValue; type "text"constant` + - `INCOMPLETE("incomplete")` - The type of response format being defined. Always `text`. + - `JsonValue; type "shell_call"constant` - - `TEXT("text")` + The type of the item. Always `shell_call`. - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `SHELL_CALL("shell_call")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional agent` - - `String name` + The agent that produced this item. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `String agentName` - - `Schema schema` + The canonical name of the agent that produced this item. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `Optional caller` - - `JsonValue; type "json_schema"constant` + The execution context that produced this tool call. - The type of response format being defined. Always `json_schema`. + - `JsonValue;` - - `JSON_SCHEMA("json_schema")` + - `JsonValue; type "direct"constant` - - `Optional description` + - `DIRECT("direct")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `class Program:` - - `Optional strict` + - `String callerId` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The call ID of the program item that produced this tool call. - - `JsonValue;` + - `JsonValue; type "program"constant` - - `JsonValue; type "json_object"constant` + - `PROGRAM("program")` - The type of response format being defined. Always `json_object`. + - `Optional createdBy` - - `JSON_OBJECT("json_object")` + The ID of the entity that created this tool call. - - `Optional verbosity` + - `class BetaResponseFunctionShellToolCallOutput:` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The output of a shell tool call that was emitted. - - `LOW("low")` + - `String id` - - `MEDIUM("medium")` + The unique ID of the shell call output. Populated when this item is returned via API. - - `HIGH("high")` + - `String callId` - - `Optional topLogprobs` + The unique ID of the shell tool call generated by the model. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `Optional maxOutputLength` - - `Optional truncation` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The truncation strategy to use for the model response. + - `List output` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + An array of shell call output contents - - `AUTO("auto")` + - `Outcome outcome` - - `DISABLED("disabled")` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `Optional usage` + - `JsonValue;` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `JsonValue; type "timeout"constant` - - `long inputTokens` + The outcome type. Always `timeout`. - The number of input tokens. + - `TIMEOUT("timeout")` - - `InputTokensDetails inputTokensDetails` + - `class Exit:` - A detailed breakdown of the input tokens. + Indicates that the shell commands finished and returned an exit code. - - `long cacheWriteTokens` + - `long exitCode` - The number of input tokens that were written to the cache. + Exit code from the shell process. - - `long cachedTokens` + - `JsonValue; type "exit"constant` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The outcome type. Always `exit`. - - `long outputTokens` + - `EXIT("exit")` - The number of output tokens. + - `String stderr` - - `OutputTokensDetails outputTokensDetails` + The standard error output that was captured. - A detailed breakdown of the output tokens. + - `String stdout` - - `long reasoningTokens` + The standard output that was captured. - The number of reasoning tokens. + - `Optional createdBy` - - `long totalTokens` + The identifier of the actor that created the item. - The total number of tokens used. + - `Status status` - - `Optional user` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `IN_PROGRESS("in_progress")` - - `long sequenceNumber` + - `COMPLETED("completed")` - The sequence number for this event. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "response.completed"constant` + - `JsonValue; type "shell_call_output"constant` - The type of the event. Always `response.completed`. + The type of the shell call output. Always `shell_call_output`. - - `RESPONSE_COMPLETED("response.completed")` + - `SHELL_CALL_OUTPUT("shell_call_output")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. -### Beta Response Computer Tool Call - -- `class BetaResponseComputerToolCall:` - - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - - `String id` - - The unique ID of the computer call. - - - `String callId` - - An identifier used when responding to the tool call with output. - - - `List pendingSafetyChecks` - - The pending safety checks for the computer call. - - - `String id` + - `Optional caller` - The ID of the pending safety check. + The execution context that produced this tool call. - - `Optional code` + - `JsonValue;` - The type of the pending safety check. + - `JsonValue; type "direct"constant` - - `Optional message` + - `DIRECT("direct")` - Details about the pending safety check. + - `class Program:` - - `Status status` + - `String callerId` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The call ID of the program item that produced this tool call. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "program"constant` - - `COMPLETED("completed")` + - `PROGRAM("program")` - - `INCOMPLETE("incomplete")` + - `Optional createdBy` - - `Type type` + The identifier of the actor that created the item. - The type of the computer call. Always `computer_call`. + - `class BetaResponseApplyPatchToolCall:` - - `COMPUTER_CALL("computer_call")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `Optional action` + - `String id` - A click action. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `Click` + - `String callId` - - `Button button` + The unique ID of the apply patch tool call generated by the model. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `Operation operation` - - `LEFT("left")` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `RIGHT("right")` + - `class CreateFile:` - - `WHEEL("wheel")` + Instruction describing how to create a file via the apply_patch tool. - - `BACK("back")` + - `String diff` - - `FORWARD("forward")` + Diff to apply. - - `JsonValue; type "click"constant` + - `String path` - Specifies the event type. For a click action, this property is always `click`. + Path of the file to create. - - `CLICK("click")` + - `JsonValue; type "create_file"constant` - - `long x` + Create a new file with the provided diff. - The x-coordinate where the click occurred. + - `CREATE_FILE("create_file")` - - `long y` + - `class DeleteFile:` - The y-coordinate where the click occurred. + Instruction describing how to delete a file via the apply_patch tool. - - `Optional> keys` + - `String path` - The keys being held while clicking. + Path of the file to delete. - - `DoubleClick` + - `JsonValue; type "delete_file"constant` - - `Optional> keys` + Delete the specified file. - The keys being held while double-clicking. + - `DELETE_FILE("delete_file")` - - `JsonValue; type "double_click"constant` + - `class UpdateFile:` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Instruction describing how to update a file via the apply_patch tool. - - `DOUBLE_CLICK("double_click")` + - `String diff` - - `long x` + Diff to apply. - The x-coordinate where the double click occurred. + - `String path` - - `long y` + Path of the file to update. - The y-coordinate where the double click occurred. + - `JsonValue; type "update_file"constant` - - `Drag` + Update an existing file with the provided diff. - - `List path` + - `UPDATE_FILE("update_file")` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `Status status` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `long x` + - `IN_PROGRESS("in_progress")` - The x-coordinate. + - `COMPLETED("completed")` - - `long y` + - `JsonValue; type "apply_patch_call"constant` - The y-coordinate. + The type of the item. Always `apply_patch_call`. - - `JsonValue; type "drag"constant` + - `APPLY_PATCH_CALL("apply_patch_call")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `Optional agent` - - `DRAG("drag")` + The agent that produced this item. - - `Optional> keys` + - `String agentName` - The keys being held while dragging the mouse. + The canonical name of the agent that produced this item. - - `Keypress` + - `Optional caller` - - `List keys` + The execution context that produced this tool call. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `JsonValue;` - - `JsonValue; type "keypress"constant` + - `JsonValue; type "direct"constant` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `DIRECT("direct")` - - `KEYPRESS("keypress")` + - `class Program:` - - `Move` + - `String callerId` - - `JsonValue; type "move"constant` + The call ID of the program item that produced this tool call. - Specifies the event type. For a move action, this property is always set to `move`. + - `JsonValue; type "program"constant` - - `MOVE("move")` + - `PROGRAM("program")` - - `long x` + - `Optional createdBy` - The x-coordinate to move to. + The ID of the entity that created this tool call. - - `long y` + - `class BetaResponseApplyPatchToolCallOutput:` - The y-coordinate to move to. + The output emitted by an apply patch tool call. - - `Optional> keys` + - `String id` - The keys being held while moving the mouse. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `JsonValue;` + - `String callId` - - `JsonValue; type "screenshot"constant` + The unique ID of the apply patch tool call generated by the model. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `Status status` - - `SCREENSHOT("screenshot")` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `Scroll` + - `COMPLETED("completed")` - - `long scrollX` + - `FAILED("failed")` - The horizontal scroll distance. + - `JsonValue; type "apply_patch_call_output"constant` - - `long scrollY` + The type of the item. Always `apply_patch_call_output`. - The vertical scroll distance. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `JsonValue; type "scroll"constant` + - `Optional agent` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The agent that produced this item. - - `SCROLL("scroll")` + - `String agentName` - - `long x` + The canonical name of the agent that produced this item. - The x-coordinate where the scroll occurred. + - `Optional caller` - - `long y` + The execution context that produced this tool call. - The y-coordinate where the scroll occurred. + - `JsonValue;` - - `Optional> keys` + - `JsonValue; type "direct"constant` - The keys being held while scrolling. + - `DIRECT("direct")` - - `Type` + - `class Program:` - - `String text` + - `String callerId` - The text to type. + The call ID of the program item that produced this tool call. - - `JsonValue; type "type"constant` + - `JsonValue; type "program"constant` - Specifies the event type. For a type action, this property is always set to `type`. + - `PROGRAM("program")` - - `TYPE("type")` + - `Optional createdBy` - - `JsonValue;` + The ID of the entity that created this tool call output. - - `JsonValue; type "wait"constant` + - `Optional output` - Specifies the event type. For a wait action, this property is always set to `wait`. + Optional textual output returned by the apply patch tool. - - `WAIT("wait")` + - `McpCall` - - `Optional> actions` + - `String id` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The unique ID of the tool call. - - `Click` + - `String arguments` - - `DoubleClick` + A JSON string of the arguments passed to the tool. - - `Drag` + - `String name` - - `Keypress` + The name of the tool that was run. - - `Move` + - `String serverLabel` - - `JsonValue;` + The label of the MCP server running the tool. - - `Scroll` + - `JsonValue; type "mcp_call"constant` - - `Type` + The type of the item. Always `mcp_call`. - - `JsonValue;` + - `MCP_CALL("mcp_call")` - `Optional agent` @@ -62891,72 +76425,68 @@ public final class Main { The canonical name of the agent that produced this item. -### Beta Response Computer Tool Call Output Item - -- `class BetaResponseComputerToolCallOutputItem:` + - `Optional approvalRequestId` - - `String id` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The unique ID of the computer call tool output. + - `Optional error` - - `String callId` + The error from the tool call, if any. - The ID of the computer tool call that produced the output. + - `Optional output` - - `BetaResponseComputerToolCallOutputScreenshot output` + The output from the tool call. - A computer screenshot image used with the computer use tool. + - `Optional status` - - `JsonValue; type "computer_screenshot"constant` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `IN_PROGRESS("in_progress")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `COMPLETED("completed")` - - `Optional fileId` + - `INCOMPLETE("incomplete")` - The identifier of an uploaded file that contains the screenshot. + - `CALLING("calling")` - - `Optional imageUrl` + - `FAILED("failed")` - The URL of the screenshot image. + - `McpListTools` - - `Status status` + - `String id` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The unique ID of the list. - - `COMPLETED("completed")` + - `String serverLabel` - - `INCOMPLETE("incomplete")` + The label of the MCP server. - - `FAILED("failed")` + - `List tools` - - `IN_PROGRESS("in_progress")` + The tools available on the server. - - `JsonValue; type "computer_call_output"constant` + - `JsonValue inputSchema` - The type of the computer tool call output. Always `computer_call_output`. + The JSON schema describing the tool's input. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `String name` - - `Optional> acknowledgedSafetyChecks` + The name of the tool. - The safety checks reported by the API that have been acknowledged by the - developer. + - `Optional annotations` - - `String id` + Additional annotations about the tool. - The ID of the pending safety check. + - `Optional description` - - `Optional code` + The description of the tool. - The type of the pending safety check. + - `JsonValue; type "mcp_list_tools"constant` - - `Optional message` + The type of the item. Always `mcp_list_tools`. - Details about the pending safety check. + - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` @@ -62966,814 +76496,916 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional error` - The identifier of the actor that created the item. + Error message if the server could not list tools. -### Beta Response Computer Tool Call Output Screenshot + - `McpApprovalRequest` -- `class BetaResponseComputerToolCallOutputScreenshot:` + - `String id` - A computer screenshot image used with the computer use tool. + The unique ID of the approval request. - - `JsonValue; type "computer_screenshot"constant` + - `String arguments` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + A JSON string of arguments for the tool. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `String name` - - `Optional fileId` + The name of the tool to run. - The identifier of an uploaded file that contains the screenshot. + - `String serverLabel` - - `Optional imageUrl` + The label of the MCP server making the request. - The URL of the screenshot image. + - `JsonValue; type "mcp_approval_request"constant` -### Beta Response Container Reference + The type of the item. Always `mcp_approval_request`. -- `class BetaResponseContainerReference:` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - Represents a container created with /v1/containers. + - `Optional agent` - - `String containerId` + The agent that produced this item. - - `JsonValue; type "container_reference"constant` + - `String agentName` - The environment type. Always `container_reference`. + The canonical name of the agent that produced this item. - - `CONTAINER_REFERENCE("container_reference")` + - `McpApprovalResponse` -### Beta Response Content + - `String id` -- `class BetaResponseContent: A class that can be one of several variants.union` + The unique ID of the approval response - Multi-modal input and output contents. + - `String approvalRequestId` - - `class BetaResponseInputText:` + The ID of the approval request being answered. - A text input to the model. + - `boolean approve` - - `String text` + Whether the request was approved. - The text input to the model. + - `JsonValue; type "mcp_approval_response"constant` - - `JsonValue; type "input_text"constant` + The type of the item. Always `mcp_approval_response`. - The type of the input item. Always `input_text`. + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `INPUT_TEXT("input_text")` + - `Optional agent` - - `Optional promptCacheBreakpoint` + The agent that produced this item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String agentName` - - `JsonValue; mode "explicit"constant` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. + - `Optional reason` - - `EXPLICIT("explicit")` + Optional reason for the decision. - - `class BetaResponseInputImage:` + - `class BetaResponseCustomToolCall:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A call to a custom tool created by the model. - - `Detail detail` + - `class BetaResponseCustomToolCallOutputItem:` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The output of a custom tool call from your code, being sent back to the model. - - `LOW("low")` + - `String id` - - `HIGH("high")` + The unique ID of the custom tool call output item. - - `AUTO("auto")` + - `Status status` - - `ORIGINAL("original")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue; type "input_image"constant` + - `IN_PROGRESS("in_progress")` - The type of the input item. Always `input_image`. + - `COMPLETED("completed")` - - `INPUT_IMAGE("input_image")` + - `INCOMPLETE("incomplete")` - - `Optional fileId` + - `Optional createdBy` - The ID of the file to be sent to the model. + The identifier of the actor that created the item. - - `Optional imageUrl` + - `boolean parallelToolCalls` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Whether to allow the model to run tool calls in parallel. - - `Optional promptCacheBreakpoint` + - `Optional temperature` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `JsonValue; mode "explicit"constant` + - `ToolChoice toolChoice` - The breakpoint mode. Always `explicit`. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `EXPLICIT("explicit")` + - `enum BetaToolChoiceOptions:` - - `class BetaResponseInputFile:` + Controls which (if any) tool is called by the model. - A file input to the model. + `none` means the model will not call any tool and instead generates a message. - - `JsonValue; type "input_file"constant` + `auto` means the model can pick between generating a message or calling one or + more tools. - The type of the input item. Always `input_file`. + `required` means the model must call one or more tools. - - `INPUT_FILE("input_file")` + - `NONE("none")` - - `Optional detail` + - `AUTO("auto")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `REQUIRED("required")` - - `AUTO("auto")` + - `class BetaToolChoiceAllowed:` - - `LOW("low")` + Constrains the tools available to the model to a pre-defined set. - - `HIGH("high")` + - `Mode mode` - - `Optional fileData` + Constrains the tools available to the model to a pre-defined set. - The content of the file to be sent to the model. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `Optional fileId` + `required` requires the model to call one or more of the allowed tools. - The ID of the file to be sent to the model. + - `AUTO("auto")` - - `Optional fileUrl` + - `REQUIRED("required")` - The URL of the file to be sent to the model. + - `List tools` - - `Optional filename` + A list of tool definitions that the model should be allowed to call. - The name of the file to be sent to the model. + For the Responses API, the list of tool definitions might look like: - - `Optional promptCacheBreakpoint` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; type "allowed_tools"constant` - - `JsonValue; mode "explicit"constant` + Allowed tool configuration type. Always `allowed_tools`. - The breakpoint mode. Always `explicit`. + - `ALLOWED_TOOLS("allowed_tools")` - - `EXPLICIT("explicit")` + - `class BetaToolChoiceTypes:` - - `class BetaResponseOutputText:` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - A text output from the model. + - `Type type` - - `List annotations` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The annotations of the text output. + Allowed values are: - - `class FileCitation:` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - A citation to a file. + - `FILE_SEARCH("file_search")` - - `String fileId` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - The ID of the file. + - `COMPUTER("computer")` - - `String filename` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - The filename of the file cited. + - `COMPUTER_USE("computer_use")` - - `long index` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - The index of the file in the list of files. + - `IMAGE_GENERATION("image_generation")` - - `JsonValue; type "file_citation"constant` + - `CODE_INTERPRETER("code_interpreter")` - The type of the file citation. Always `file_citation`. + - `class BetaToolChoiceFunction:` - - `FILE_CITATION("file_citation")` + Use this option to force the model to call a specific function. - - `class UrlCitation:` + - `String name` - A citation for a web resource used to generate a model response. + The name of the function to call. - - `long endIndex` + - `JsonValue; type "function"constant` - The index of the last character of the URL citation in the message. + For function calling, the type is always `function`. - - `long startIndex` + - `FUNCTION("function")` - The index of the first character of the URL citation in the message. + - `class BetaToolChoiceMcp:` - - `String title` + Use this option to force the model to call a specific tool on a remote MCP server. - The title of the web resource. + - `String serverLabel` - - `JsonValue; type "url_citation"constant` + The label of the MCP server to use. - The type of the URL citation. Always `url_citation`. + - `JsonValue; type "mcp"constant` - - `URL_CITATION("url_citation")` + For MCP tools, the type is always `mcp`. - - `String url` + - `MCP("mcp")` - The URL of the web resource. + - `Optional name` - - `class ContainerFileCitation:` + The name of the tool to call on the server. - A citation for a container file used to generate a model response. + - `class BetaToolChoiceCustom:` - - `String containerId` + Use this option to force the model to call a specific custom tool. - The ID of the container file. + - `String name` - - `long endIndex` + The name of the custom tool to call. - The index of the last character of the container file citation in the message. + - `JsonValue; type "custom"constant` - - `String fileId` + For custom tool calling, the type is always `custom`. - The ID of the file. + - `CUSTOM("custom")` - - `String filename` + - `JsonValue;` - The filename of the container file cited. + - `JsonValue; type "programmatic_tool_calling"constant` - - `long startIndex` + The tool to call. Always `programmatic_tool_calling`. - The index of the first character of the container file citation in the message. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `JsonValue; type "container_file_citation"constant` + - `class BetaToolChoiceApplyPatch:` - The type of the container file citation. Always `container_file_citation`. + Forces the model to call the apply_patch tool when executing a tool call. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `JsonValue; type "apply_patch"constant` - - `class FilePath:` + The tool to call. Always `apply_patch`. - A path to a file. + - `APPLY_PATCH("apply_patch")` - - `String fileId` + - `class BetaToolChoiceShell:` - The ID of the file. + Forces the model to call the shell tool when a tool call is required. - - `long index` + - `JsonValue; type "shell"constant` - The index of the file in the list of files. + The tool to call. Always `shell`. - - `JsonValue; type "file_path"constant` + - `SHELL("shell")` - The type of the file path. Always `file_path`. + - `List tools` - - `FILE_PATH("file_path")` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `String text` + We support the following categories of tools: - The text output from the model. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `JsonValue; type "output_text"constant` + - `class BetaFunctionTool:` - The type of the output text. Always `output_text`. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `OUTPUT_TEXT("output_text")` + - `class BetaFileSearchTool:` - - `Optional> logprobs` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `String token` + - `class BetaComputerTool:` - - `List bytes` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `double logprob` + - `class BetaComputerUsePreviewTool:` - - `List topLogprobs` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String token` + - `class BetaWebSearchTool:` - - `List bytes` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `double logprob` + - `Mcp` - - `class BetaResponseOutputRefusal:` + - `CodeInterpreter` - A refusal from the model. + - `JsonValue;` - - `String refusal` + - `ImageGeneration` - The refusal explanation from the model. + - `JsonValue;` - - `JsonValue; type "refusal"constant` + - `class BetaFunctionShellTool:` - The type of the refusal. Always `refusal`. + A tool that allows the model to execute shell commands. - - `REFUSAL("refusal")` + - `class BetaCustomTool:` - - `ReasoningText` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `String text` + - `class BetaNamespaceTool:` - The reasoning text from the model. + Groups function/custom tools under a shared namespace. - - `JsonValue; type "reasoning_text"constant` + - `class BetaToolSearchTool:` - The type of the reasoning text. Always `reasoning_text`. + Hosted or BYOT tool search configuration for deferred tools. - - `REASONING_TEXT("reasoning_text")` + - `class BetaWebSearchPreviewTool:` -### Beta Response Content Part Added Event + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). -- `class BetaResponseContentPartAddedEvent:` + - `class BetaApplyPatchTool:` - Emitted when a new content part is added. + Allows the assistant to create, delete, or update files using unified diffs. - - `long contentIndex` + - `Optional topP` - The index of the content part that was added. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `String itemId` + We generally recommend altering this or `temperature` but not both. - The ID of the output item that the content part was added to. + - `Optional background` - - `long outputIndex` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The index of the output item that the content part was added to. + - `Optional completedAt` - - `Part part` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The content part that was added. + - `Optional conversation` - - `class BetaResponseOutputText:` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - A text output from the model. + - `String id` - - `List annotations` + The unique ID of the conversation that this response was associated with. - The annotations of the text output. + - `Optional maxOutputTokens` - - `class FileCitation:` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - A citation to a file. + - `Optional maxToolCalls` - - `String fileId` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The ID of the file. + - `Optional moderation` - - `String filename` + Moderation results for the response input and output, if moderated completions were requested. - The filename of the file cited. + - `Input input` - - `long index` + Moderation for the response input. - The index of the file in the list of files. + - `class ModerationResult:` - - `JsonValue; type "file_citation"constant` + A moderation result produced for the response input or output. - The type of the file citation. Always `file_citation`. + - `Categories categories` - - `FILE_CITATION("file_citation")` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `class UrlCitation:` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - A citation for a web resource used to generate a model response. + Which modalities of input are reflected by the score for each category. - - `long endIndex` + - `TEXT("text")` - The index of the last character of the URL citation in the message. + - `IMAGE("image")` - - `long startIndex` + - `CategoryScores categoryScores` - The index of the first character of the URL citation in the message. + A dictionary of moderation categories to scores. - - `String title` + - `boolean flagged` - The title of the web resource. + A boolean indicating whether the content was flagged by any category. - - `JsonValue; type "url_citation"constant` + - `String model` - The type of the URL citation. Always `url_citation`. + The moderation model that produced this result. - - `URL_CITATION("url_citation")` + - `JsonValue; type "moderation_result"constant` - - `String url` + The object type, which was always `moderation_result` for successful moderation results. - The URL of the web resource. + - `MODERATION_RESULT("moderation_result")` - - `class ContainerFileCitation:` + - `class Error:` - A citation for a container file used to generate a model response. + An error produced while attempting moderation for the response input or output. - - `String containerId` + - `String code` - The ID of the container file. + The error code. - - `long endIndex` + - `String message` - The index of the last character of the container file citation in the message. + The error message. - - `String fileId` + - `JsonValue; type "error"constant` - The ID of the file. + The object type, which was always `error` for moderation failures. - - `String filename` + - `ERROR("error")` - The filename of the container file cited. + - `Output output` - - `long startIndex` + Moderation for the response output. - The index of the first character of the container file citation in the message. + - `class ModerationResult:` - - `JsonValue; type "container_file_citation"constant` + A moderation result produced for the response input or output. - The type of the container file citation. Always `container_file_citation`. + - `Categories categories` - - `CONTAINER_FILE_CITATION("container_file_citation")` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `class FilePath:` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - A path to a file. + Which modalities of input are reflected by the score for each category. - - `String fileId` + - `TEXT("text")` - The ID of the file. + - `IMAGE("image")` - - `long index` + - `CategoryScores categoryScores` - The index of the file in the list of files. + A dictionary of moderation categories to scores. - - `JsonValue; type "file_path"constant` + - `boolean flagged` - The type of the file path. Always `file_path`. + A boolean indicating whether the content was flagged by any category. - - `FILE_PATH("file_path")` + - `String model` - - `String text` + The moderation model that produced this result. - The text output from the model. + - `JsonValue; type "moderation_result"constant` - - `JsonValue; type "output_text"constant` + The object type, which was always `moderation_result` for successful moderation results. - The type of the output text. Always `output_text`. + - `MODERATION_RESULT("moderation_result")` - - `OUTPUT_TEXT("output_text")` + - `class Error:` - - `Optional> logprobs` + An error produced while attempting moderation for the response input or output. - - `String token` + - `String code` - - `List bytes` + The error code. - - `double logprob` + - `String message` - - `List topLogprobs` + The error message. - - `String token` + - `JsonValue; type "error"constant` - - `List bytes` + The object type, which was always `error` for moderation failures. - - `double logprob` + - `ERROR("error")` - - `class BetaResponseOutputRefusal:` + - `Optional previousResponseId` - A refusal from the model. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `String refusal` + - `Optional prompt` - The refusal explanation from the model. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `JsonValue; type "refusal"constant` + - `String id` - The type of the refusal. Always `refusal`. + The unique identifier of the prompt template to use. - - `REFUSAL("refusal")` + - `Optional variables` - - `class ReasoningText:` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - Reasoning text from the model. + - `String` - - `String text` + - `class BetaResponseInputText:` - The reasoning text from the model. + A text input to the model. - - `JsonValue; type "reasoning_text"constant` + - `class BetaResponseInputImage:` - The type of the reasoning text. Always `reasoning_text`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `REASONING_TEXT("reasoning_text")` + - `class BetaResponseInputFile:` - - `long sequenceNumber` + A file input to the model. - The sequence number of this event. + - `Optional version` - - `JsonValue; type "response.content_part.added"constant` + Optional version of the prompt template. - The type of the event. Always `response.content_part.added`. + - `Optional promptCacheKey` - - `RESPONSE_CONTENT_PART_ADDED("response.content_part.added")` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `Optional agent` + - `Optional promptCacheOptions` - The agent that owns this multi-agent streaming event. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `String agentName` + - `Mode mode` - The canonical name of the agent that produced this item. + Whether implicit prompt-cache breakpoints were enabled. -### Beta Response Content Part Done Event + - `IMPLICIT("implicit")` -- `class BetaResponseContentPartDoneEvent:` + - `EXPLICIT("explicit")` - Emitted when a content part is done. + - `Ttl ttl` - - `long contentIndex` + The minimum lifetime applied to each cache breakpoint. - The index of the content part that is done. + - `_30M("30m")` - - `String itemId` + - `Optional promptCacheRetention` - The ID of the output item that the content part was added to. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `long outputIndex` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - The index of the output item that the content part was added to. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `Part part` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The content part that is done. + - `IN_MEMORY("in_memory")` - - `class BetaResponseOutputText:` + - `_24H("24h")` - A text output from the model. + - `Optional reasoning` - - `List annotations` + **gpt-5 and o-series models only** - The annotations of the text output. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `class FileCitation:` + - `Optional context` - A citation to a file. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `String fileId` + - `AUTO("auto")` - The ID of the file. + - `CURRENT_TURN("current_turn")` - - `String filename` + - `ALL_TURNS("all_turns")` - The filename of the file cited. + - `Optional effort` - - `long index` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The index of the file in the list of files. + - `NONE("none")` - - `JsonValue; type "file_citation"constant` + - `MINIMAL("minimal")` - The type of the file citation. Always `file_citation`. + - `LOW("low")` - - `FILE_CITATION("file_citation")` + - `MEDIUM("medium")` - - `class UrlCitation:` + - `HIGH("high")` - A citation for a web resource used to generate a model response. + - `XHIGH("xhigh")` - - `long endIndex` + - `MAX("max")` - The index of the last character of the URL citation in the message. + - `Optional generateSummary` - - `long startIndex` + **Deprecated:** use `summary` instead. - The index of the first character of the URL citation in the message. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `String title` + - `AUTO("auto")` - The title of the web resource. + - `CONCISE("concise")` - - `JsonValue; type "url_citation"constant` + - `DETAILED("detailed")` - The type of the URL citation. Always `url_citation`. + - `Optional mode` - - `URL_CITATION("url_citation")` + Controls the reasoning execution mode for the request. - - `String url` + When returned on a response, this is the effective execution mode. - The URL of the web resource. + - `STANDARD("standard")` - - `class ContainerFileCitation:` + - `PRO("pro")` - A citation for a container file used to generate a model response. + - `Optional summary` - - `String containerId` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The ID of the container file. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `long endIndex` + - `AUTO("auto")` - The index of the last character of the container file citation in the message. + - `CONCISE("concise")` - - `String fileId` + - `DETAILED("detailed")` - The ID of the file. + - `Optional safetyIdentifier` - - `String filename` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The filename of the container file cited. + - `Optional serviceTier` - - `long startIndex` + Specifies the processing type used for serving the request. - The index of the first character of the container file citation in the message. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `JsonValue; type "container_file_citation"constant` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The type of the container file citation. Always `container_file_citation`. + - `AUTO("auto")` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `DEFAULT("default")` - - `class FilePath:` + - `FLEX("flex")` - A path to a file. + - `SCALE("scale")` - - `String fileId` + - `PRIORITY("priority")` - The ID of the file. + - `Optional status` - - `long index` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The index of the file in the list of files. + - `COMPLETED("completed")` - - `JsonValue; type "file_path"constant` + - `FAILED("failed")` - The type of the file path. Always `file_path`. + - `IN_PROGRESS("in_progress")` - - `FILE_PATH("file_path")` + - `CANCELLED("cancelled")` - - `String text` + - `QUEUED("queued")` - The text output from the model. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "output_text"constant` + - `Optional text` - The type of the output text. Always `output_text`. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `OUTPUT_TEXT("output_text")` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `Optional> logprobs` + - `Optional format` - - `String token` + An object specifying the format that the model must output. - - `List bytes` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `double logprob` + The default format is `{ "type": "text" }` with no additional options. - - `List topLogprobs` + **Not recommended for gpt-4o and newer models:** - - `String token` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `List bytes` + - `JsonValue;` - - `double logprob` + - `JsonValue; type "text"constant` - - `class BetaResponseOutputRefusal:` + The type of response format being defined. Always `text`. - A refusal from the model. + - `TEXT("text")` - - `String refusal` + - `class BetaResponseFormatTextJsonSchemaConfig:` - The refusal explanation from the model. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `JsonValue; type "refusal"constant` + - `String name` - The type of the refusal. Always `refusal`. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `REFUSAL("refusal")` + - `Schema schema` - - `class ReasoningText:` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Reasoning text from the model. + - `JsonValue; type "json_schema"constant` - - `String text` + The type of response format being defined. Always `json_schema`. - The reasoning text from the model. + - `JSON_SCHEMA("json_schema")` - - `JsonValue; type "reasoning_text"constant` + - `Optional description` - The type of the reasoning text. Always `reasoning_text`. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `REASONING_TEXT("reasoning_text")` + - `Optional strict` - - `long sequenceNumber` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The sequence number of this event. + - `JsonValue;` - - `JsonValue; type "response.content_part.done"constant` + - `JsonValue; type "json_object"constant` - The type of the event. Always `response.content_part.done`. + The type of response format being defined. Always `json_object`. - - `RESPONSE_CONTENT_PART_DONE("response.content_part.done")` + - `JSON_OBJECT("json_object")` - - `Optional agent` + - `Optional verbosity` - The agent that owns this multi-agent streaming event. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `String agentName` + - `LOW("low")` - The canonical name of the agent that produced this item. + - `MEDIUM("medium")` -### Beta Response Conversation Param + - `HIGH("high")` -- `class BetaResponseConversationParam:` + - `Optional topLogprobs` - The conversation that this response belongs to. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `String id` + - `Optional truncation` - The unique ID of the conversation. + The truncation strategy to use for the model response. -### Beta Response Created Event + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. -- `class BetaResponseCreatedEvent:` + - `AUTO("auto")` - An event that is emitted when a response is created. + - `DISABLED("disabled")` - - `BetaResponse response` + - `Optional usage` - The response that was created. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `String id` + - `long inputTokens` - Unique identifier for this Response. + The number of input tokens. - - `double createdAt` + - `InputTokensDetails inputTokensDetails` - Unix timestamp (in seconds) of when this Response was created. + A detailed breakdown of the input tokens. - - `Optional error` + - `long cacheWriteTokens` - An error object returned when the model fails to generate a Response. + The number of input tokens that were written to the cache. - - `Code code` + - `long cachedTokens` - The error code for the response. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `SERVER_ERROR("server_error")` + - `long outputTokens` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + The number of output tokens. - - `INVALID_PROMPT("invalid_prompt")` + - `OutputTokensDetails outputTokensDetails` - - `BIO_POLICY("bio_policy")` + A detailed breakdown of the output tokens. - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + - `long reasoningTokens` - - `INVALID_IMAGE("invalid_image")` + The number of reasoning tokens. - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + - `long totalTokens` - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + The total number of tokens used. - - `INVALID_IMAGE_URL("invalid_image_url")` + - `Optional user` - - `IMAGE_TOO_LARGE("image_too_large")` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `IMAGE_TOO_SMALL("image_too_small")` + - `long sequenceNumber` - - `IMAGE_PARSE_ERROR("image_parse_error")` + The sequence number of this event. - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + - `JsonValue; type "response.incomplete"constant` - - `INVALID_IMAGE_MODE("invalid_image_mode")` + The type of the event. Always `response.incomplete`. - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + - `RESPONSE_INCOMPLETE("response.incomplete")` - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + - `Optional agent` - - `EMPTY_IMAGE_FILE("empty_image_file")` + The agent that owns this multi-agent streaming event. - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + - `String agentName` - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + The canonical name of the agent that produced this item. - - `String message` +### Beta Response Inject Created Event - A human-readable description of the error. +- `class BetaResponseInjectCreatedEvent:` - - `Optional incompleteDetails` + Emitted when all injected input items were validated and committed to the + active response. - Details about why the response is incomplete. + - `String responseId` - - `Optional reason` + The ID of the response that accepted the input. - The reason why the response is incomplete. + - `long sequenceNumber` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + The sequence number for this event. - - `CONTENT_FILTER("content_filter")` + - `JsonValue; type "response.inject.created"constant` - - `Optional instructions` + The event discriminator. Always `response.inject.created`. - A system (or developer) message inserted into the model's context. + - `RESPONSE_INJECT_CREATED("response.inject.created")` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `Optional streamId` - - `String` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `List` +### Beta Response Inject Event + +- `class BetaResponseInjectEvent:` + + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. + + - `List input` + + Input items to inject into the active response. - `class BetaEasyInputMessage:` @@ -63923,6 +77555,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -64178,6 +77812,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -65314,7 +78950,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -65371,7 +79011,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -67261,482 +80905,189 @@ public final class Main { - `Optional agent` - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - The caller type. Always `program`. - - - `PROGRAM("program")` - - - `class BetaResponseCustomToolCall:` - - 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 id` - - The unique ID of the custom tool call in the OpenAI platform. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional namespace` - - The namespace of the custom tool being called. - - - `CompactionTrigger` - - - `JsonValue; type "compaction_trigger"constant` - - The type of the item. Always `compaction_trigger`. - - - `COMPACTION_TRIGGER("compaction_trigger")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ItemReference` - - - `String id` - - The ID of the item to reference. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional type` - - The type of item to reference. Always `item_reference`. - - - `ITEM_REFERENCE("item_reference")` - - - `Program` - - - `String id` - - The unique ID of this program item. - - - `String callId` - - The stable call ID of the program item. - - - `String code` - - The JavaScript source executed by programmatic tool calling. - - - `String fingerprint` - - Opaque program replay fingerprint that must be round-tripped. - - - `JsonValue; type "program"constant` - - The item type. Always `program`. - - - `PROGRAM("program")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ProgramOutput` - - - `String id` - - The unique ID of this program output item. - - - `String callId` - - The call ID of the program item. - - - `String result` - - The result produced by the program item. - - - `Status status` - - The terminal status of the program output. - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `JsonValue; type "program_output"constant` - - The item type. Always `program_output`. - - - `PROGRAM_OUTPUT("program_output")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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. - - - `Model model` - - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. - - - `GPT_5_6_SOL("gpt-5.6-sol")` - - - `GPT_5_6_TERRA("gpt-5.6-terra")` - - - `GPT_5_6_LUNA("gpt-5.6-luna")` - - - `GPT_5_4("gpt-5.4")` - - - `GPT_5_4_MINI("gpt-5.4-mini")` - - - `GPT_5_4_NANO("gpt-5.4-nano")` - - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - - `GPT_5_2("gpt-5.2")` - - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - - `GPT_5_2_PRO("gpt-5.2-pro")` - - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - - `GPT_5_1("gpt-5.1")` - - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - - `GPT_5_1_CODEX("gpt-5.1-codex")` - - - `GPT_5_1_MINI("gpt-5.1-mini")` - - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - - `GPT_5("gpt-5")` - - - `GPT_5_MINI("gpt-5-mini")` - - - `GPT_5_NANO("gpt-5-nano")` - - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - - `GPT_4_1("gpt-4.1")` - - - `GPT_4_1_MINI("gpt-4.1-mini")` - - - `GPT_4_1_NANO("gpt-4.1-nano")` - - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - - - `O4_MINI("o4-mini")` - - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - - - `O3("o3")` - - - `O3_2025_04_16("o3-2025-04-16")` - - - `O3_MINI("o3-mini")` - - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + The agent that produced this item. - - `O1("o1")` + - `String agentName` - - `O1_2024_12_17("o1-2024-12-17")` + The canonical name of the agent that produced this item. - - `O1_PREVIEW("o1-preview")` + - `Optional caller` - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + The execution context that produced this tool call. - - `O1_MINI("o1-mini")` + - `JsonValue;` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + - `JsonValue; type "direct"constant` - - `GPT_4O("gpt-4o")` + The caller type. Always `direct`. - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + - `DIRECT("direct")` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + - `class Program:` - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + - `String callerId` - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + The call ID of the program item that produced this tool call. - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + - `JsonValue; type "program"constant` - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + The caller type. Always `program`. - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + - `PROGRAM("program")` - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + - `class BetaResponseCustomToolCall:` - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + A call to a custom tool created by the model. - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + - `String callId` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + An identifier used to map this custom tool call to a tool call output. - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `String input` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + The input for the custom tool call generated by the model. - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `String name` - - `CODEX_MINI_LATEST("codex-mini-latest")` + The name of the custom tool being called. - - `GPT_4O_MINI("gpt-4o-mini")` + - `JsonValue; type "custom_tool_call"constant` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + The type of the custom tool call. Always `custom_tool_call`. - - `GPT_4_TURBO("gpt-4-turbo")` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `Optional id` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + The unique ID of the custom tool call in the OpenAI platform. - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + - `Optional agent` - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + The agent that produced this item. - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + - `String agentName` - - `GPT_4("gpt-4")` + The canonical name of the agent that produced this item. - - `GPT_4_0314("gpt-4-0314")` + - `Optional caller` - - `GPT_4_0613("gpt-4-0613")` + The execution context that produced this tool call. - - `GPT_4_32K("gpt-4-32k")` + - `JsonValue;` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + - `JsonValue; type "direct"constant` - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `DIRECT("direct")` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `class Program:` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `String callerId` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + The call ID of the program item that produced this tool call. - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `JsonValue; type "program"constant` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `PROGRAM("program")` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `Optional namespace` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + The namespace of the custom tool being called. - - `O1_PRO("o1-pro")` + - `CompactionTrigger` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - `JsonValue; type "compaction_trigger"constant` - - `O3_PRO("o3-pro")` + The type of the item. Always `compaction_trigger`. - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `COMPACTION_TRIGGER("compaction_trigger")` - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `Optional agent` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + The agent that produced this item. - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + - `String agentName` - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + The canonical name of the agent that produced this item. - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `ItemReference` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `String id` - - `GPT_5_CODEX("gpt-5-codex")` + The ID of the item to reference. - - `GPT_5_PRO("gpt-5-pro")` + - `Optional agent` - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + The agent that produced this item. - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + - `String agentName` - - `JsonValue; object_ "response"constant` + The canonical name of the agent that produced this item. - The object type of this resource - always set to `response`. + - `Optional type` - - `RESPONSE("response")` + The type of item to reference. Always `item_reference`. - - `List output` + - `ITEM_REFERENCE("item_reference")` - An array of content items generated by the model. + - `Program` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `String id` - - `class BetaResponseOutputMessage:` + The unique ID of this program item. - An output message from the model. + - `String callId` - - `class BetaResponseFileSearchToolCall:` + The stable call ID of the program item. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `String code` - - `class BetaResponseFunctionToolCall:` + The JavaScript source executed by programmatic tool calling. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `String fingerprint` - - `class BetaResponseFunctionToolCallOutputItem:` + Opaque program replay fingerprint that must be round-tripped. - - `String id` + - `JsonValue; type "program"constant` - The unique ID of the function call tool output. + The item type. Always `program`. - - `String callId` + - `PROGRAM("program")` - The unique ID of the function tool call generated by the model. + - `Optional agent` - - `Output output` + The agent that produced this item. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `String agentName` - - `String` + The canonical name of the agent that produced this item. - - `List` + - `ProgramOutput` - - `class BetaResponseInputText:` + - `String id` - A text input to the model. + The unique ID of this program output item. - - `class BetaResponseInputImage:` + - `String callId` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The call ID of the program item. - - `class BetaResponseInputFile:` + - `String result` - A file input to the model. + The result produced by the program item. - `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")` + The terminal status of the program output. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `JsonValue; type "function_call_output"constant` + - `JsonValue; type "program_output"constant` - The type of the function tool call output. Always `function_call_output`. + The item type. Always `program_output`. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -67746,109 +81097,92 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` + - `String responseId` - - `String callerId` + The ID of the active response that should receive the input. - The call ID of the program item that produced this tool call. + - `JsonValue; type "response.inject"constant` - - `JsonValue; type "program"constant` + The event discriminator. Always `response.inject`. - The caller type. Always `program`. + - `RESPONSE_INJECT("response.inject")` - - `PROGRAM("program")` +### Beta Response Inject Failed Event - - `Optional createdBy` +- `class BetaResponseInjectFailedEvent:` - The identifier of the actor that created the item. + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - - `AgentMessage` + - `Error error` - - `String id` + Information about why the input was not committed. - The unique ID of the agent message. + - `Code code` - - `String author` + A machine-readable error code. - The sending agent identity. + - `RESPONSE_ALREADY_COMPLETED("response_already_completed")` - - `List content` + - `RESPONSE_NOT_FOUND("response_not_found")` - Encrypted content sent between agents. + - `String message` - - `class BetaResponseInputText:` + A human-readable description of the error. - A text input to the model. + - `List input` - - `class BetaResponseOutputText:` + The raw input items that were not committed. - A text output from the model. + - `class BetaEasyInputMessage:` - - `class Text:` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - A text content. + - `Content content` - - `String text` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `JsonValue; type "text"constant` + - `String` - - `TEXT("text")` + - `List` - - `class SummaryText:` + - `class BetaResponseInputText:` - A summary text from the model. + A text input to 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:` + The text input to the model. - Reasoning text from the model. + - `JsonValue; type "input_text"constant` - - `String text` + The type of the input item. Always `input_text`. - The reasoning text from the model. + - `INPUT_TEXT("input_text")` - - `JsonValue; type "reasoning_text"constant` + - `Optional promptCacheBreakpoint` - The type of the reasoning text. Always `reasoning_text`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `REASONING_TEXT("reasoning_text")` + - `JsonValue; mode "explicit"constant` - - `class BetaResponseOutputRefusal:` + The breakpoint mode. Always `explicit`. - A refusal from the model. + - `EXPLICIT("explicit")` - `class BetaResponseInputImage:` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class ComputerScreenshot:` - - A screenshot of a computer. - - `Detail detail` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `LOW("low")` @@ -67858,19 +81192,19 @@ public final class Main { - `ORIGINAL("original")` - - `Optional fileId` + - `JsonValue; type "input_image"constant` - The identifier of an uploaded file that contains the screenshot. + The type of the input item. Always `input_image`. - - `Optional imageUrl` + - `INPUT_IMAGE("input_image")` - The URL of the screenshot image. + - `Optional fileId` - - `JsonValue; type "computer_screenshot"constant` + The ID of the file to be sent to the model. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `Optional imageUrl` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `Optional promptCacheBreakpoint` @@ -67886,73 +81220,105 @@ public final class Main { A file input to the model. - - `class EncryptedContent:` + - `JsonValue; type "input_file"constant` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The type of the input item. Always `input_file`. - - `String encryptedContent` + - `INPUT_FILE("input_file")` - Opaque encrypted content. + - `Optional detail` - - `JsonValue; type "encrypted_content"constant` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The type of the input item. Always `encrypted_content`. + - `AUTO("auto")` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `LOW("low")` - - `String recipient` + - `HIGH("high")` - The destination agent identity. + - `Optional fileData` - - `JsonValue; type "agent_message"constant` + The content of the file to be sent to the model. - The type of the item. Always `agent_message`. + - `Optional fileId` - - `AGENT_MESSAGE("agent_message")` + The ID of the file to be sent to the model. - - `Optional agent` + - `Optional fileUrl` - The agent that produced this item. + The URL of the file to be sent to the model. - - `String agentName` + - `Optional filename` - The canonical name of the agent that produced this item. + The name of the file to be sent to the model. - - `MultiAgentCall` + - `Optional promptCacheBreakpoint` - - `String id` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The unique ID of the multi-agent call item. + - `JsonValue; mode "explicit"constant` - - `Action action` + The breakpoint mode. Always `explicit`. - The multi-agent action to execute. + - `EXPLICIT("explicit")` - - `SPAWN_AGENT("spawn_agent")` + - `Role role` - - `INTERRUPT_AGENT("interrupt_agent")` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `LIST_AGENTS("list_agents")` + - `USER("user")` - - `SEND_MESSAGE("send_message")` + - `ASSISTANT("assistant")` - - `FOLLOWUP_TASK("followup_task")` + - `SYSTEM("system")` - - `WAIT_AGENT("wait_agent")` + - `DEVELOPER("developer")` - - `String arguments` + - `Optional phase` - The JSON string of arguments generated for the action. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `String callId` + - `COMMENTARY("commentary")` - The unique ID linking this call to its output. + - `FINAL_ANSWER("final_answer")` - - `JsonValue; type "multi_agent_call"constant` + - `Optional type` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the message input. Always `message`. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `MESSAGE("message")` + + - `Message` + + - `List content` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Role role` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `USER("user")` + + - `SYSTEM("system")` + + - `DEVELOPER("developer")` - `Optional agent` @@ -67962,202 +81328,201 @@ public final class Main { The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` + - `Optional status` - - `String id` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The unique ID of the multi-agent call output item. + - `IN_PROGRESS("in_progress")` - - `Action action` + - `COMPLETED("completed")` - The multi-agent action that produced this result. + - `INCOMPLETE("incomplete")` - - `SPAWN_AGENT("spawn_agent")` + - `Optional type` - - `INTERRUPT_AGENT("interrupt_agent")` + The type of the message input. Always set to `message`. - - `LIST_AGENTS("list_agents")` + - `MESSAGE("message")` - - `SEND_MESSAGE("send_message")` + - `class BetaResponseOutputMessage:` - - `FOLLOWUP_TASK("followup_task")` + An output message from the model. - - `WAIT_AGENT("wait_agent")` + - `String id` - - `String callId` + The unique ID of the output message. - The unique ID of the multi-agent call. + - `List content` - - `List output` + The content of the output message. - Text output returned by the multi-agent action. + - `class BetaResponseOutputText:` + + A text output from the model. - `List annotations` The annotations of the text output. - - `String text` + - `class FileCitation:` - The text output from the model. + A citation to a file. - - `JsonValue; type "output_text"constant` + - `String fileId` - The type of the output text. Always `output_text`. + The ID of the file. - - `Optional> logprobs` + - `String filename` - - `JsonValue; type "multi_agent_call_output"constant` + The filename of the file cited. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `long index` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + The index of the file in the list of files. - - `Optional agent` + - `JsonValue; type "file_citation"constant` - The agent that produced this item. + The type of the file citation. Always `file_citation`. - - `String agentName` + - `FILE_CITATION("file_citation")` - The canonical name of the agent that produced this item. + - `class UrlCitation:` - - `class BetaResponseFunctionWebSearch:` + A citation for a web resource used to generate a model response. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `long endIndex` - - `class BetaResponseComputerToolCall:` + The index of the last character of the URL citation in the message. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `long startIndex` - - `class BetaResponseComputerToolCallOutputItem:` + The index of the first character of the URL citation in the message. - - `String id` + - `String title` - The unique ID of the computer call tool output. + The title of the web resource. - - `String callId` + - `JsonValue; type "url_citation"constant` - The ID of the computer tool call that produced the output. + The type of the URL citation. Always `url_citation`. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `URL_CITATION("url_citation")` - A computer screenshot image used with the computer use tool. + - `String url` - - `Status status` + The URL of the web resource. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class ContainerFileCitation:` - - `COMPLETED("completed")` + A citation for a container file used to generate a model response. - - `INCOMPLETE("incomplete")` + - `String containerId` - - `FAILED("failed")` + The ID of the container file. - - `IN_PROGRESS("in_progress")` + - `long endIndex` - - `JsonValue; type "computer_call_output"constant` + The index of the last character of the container file citation in the message. - The type of the computer tool call output. Always `computer_call_output`. + - `String fileId` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The ID of the file. - - `Optional> acknowledgedSafetyChecks` + - `String filename` - The safety checks reported by the API that have been acknowledged by the - developer. + The filename of the container file cited. - - `String id` + - `long startIndex` - The ID of the pending safety check. + The index of the first character of the container file citation in the message. - - `Optional code` + - `JsonValue; type "container_file_citation"constant` - The type of the pending safety check. + The type of the container file citation. Always `container_file_citation`. - - `Optional message` + - `CONTAINER_FILE_CITATION("container_file_citation")` - Details about the pending safety check. + - `class FilePath:` - - `Optional agent` + A path to a file. - The agent that produced this item. + - `String fileId` - - `String agentName` + The ID of the file. - The canonical name of the agent that produced this item. + - `long index` - - `Optional createdBy` + The index of the file in the list of files. - The identifier of the actor that created the item. + - `JsonValue; type "file_path"constant` - - `class BetaResponseReasoningItem:` + The type of the file path. Always `file_path`. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `FILE_PATH("file_path")` - - `Program` + - `String text` - - `String id` + The text output from the model. - The unique ID of the program item. + - `JsonValue; type "output_text"constant` - - `String callId` + The type of the output text. Always `output_text`. - The stable call ID of the program item. + - `OUTPUT_TEXT("output_text")` - - `String code` + - `Optional> logprobs` - The JavaScript source executed by programmatic tool calling. + - `String token` - - `String fingerprint` + - `List bytes` - Opaque program replay fingerprint that must be round-tripped. + - `double logprob` - - `JsonValue; type "program"constant` + - `List topLogprobs` - The type of the item. Always `program`. + - `String token` - - `PROGRAM("program")` + - `List bytes` - - `Optional agent` + - `double logprob` - The agent that produced this item. + - `class BetaResponseOutputRefusal:` - - `String agentName` + A refusal from the model. - The canonical name of the agent that produced this item. + - `String refusal` - - `ProgramOutput` + The refusal explanation from the model. - - `String id` + - `JsonValue; type "refusal"constant` - The unique ID of the program output item. + The type of the refusal. Always `refusal`. - - `String callId` + - `REFUSAL("refusal")` - The call ID of the program item. + - `JsonValue; role "assistant"constant` - - `String result` + The role of the output message. Always `assistant`. - The result produced by the program item. + - `ASSISTANT("assistant")` - `Status status` - The terminal status of the program output item. + 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 "program_output"constant` + - `JsonValue; type "message"constant` - The type of the item. Always `program_output`. + The type of the output message. Always `message`. - - `PROGRAM_OUTPUT("program_output")` + - `MESSAGE("message")` - `Optional agent` @@ -68167,43 +81532,49 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall:` - - - `String id` + - `Optional phase` - The unique ID of the tool search call item. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `JsonValue arguments` + - `COMMENTARY("commentary")` - Arguments used for the tool search call. + - `FINAL_ANSWER("final_answer")` - - `Optional callId` + - `class BetaResponseFileSearchToolCall:` - The unique ID of the tool search call generated by the model. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `Execution execution` + - `String id` - Whether tool search was executed by the server or by the client. + The unique ID of the file search tool call. - - `SERVER("server")` + - `List queries` - - `CLIENT("client")` + The queries used to search for files. - `Status status` - The status of the tool search call item that was recorded. + 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")` - - `JsonValue; type "tool_search_call"constant` + - `FAILED("failed")` - The type of the item. Always `tool_search_call`. + - `JsonValue; type "file_search_call"constant` - - `TOOL_SEARCH_CALL("tool_search_call")` + The type of the file search tool call. Always `file_search_call`. + + - `FILE_SEARCH_CALL("file_search_call")` - `Optional agent` @@ -68213,271 +81584,285 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional> results` - The identifier of the actor that created the item. + The results of the file search tool call. - - `class BetaResponseToolSearchOutputItem:` + - `Optional attributes` - - `String id` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - The unique ID of the tool search output item. + - `String` - - `Optional callId` + - `double` - The unique ID of the tool search call generated by the model. + - `boolean` - - `Execution execution` + - `Optional fileId` - Whether tool search was executed by the server or by the client. + The unique ID of the file. - - `SERVER("server")` + - `Optional filename` - - `CLIENT("client")` + The name of the file. - - `Status status` + - `Optional score` - The status of the tool search output item that was recorded. + The relevance score of the file - a value between 0 and 1. - - `IN_PROGRESS("in_progress")` + - `Optional text` - - `COMPLETED("completed")` + The text that was retrieved from the file. - - `INCOMPLETE("incomplete")` + - `class BetaResponseComputerToolCall:` - - `List tools` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The loaded tool definitions returned by tool search. + - `String id` - - `class BetaFunctionTool:` + The unique ID of the computer call. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `String callId` - - `class BetaFileSearchTool:` + An identifier used when responding to the tool call with output. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `List pendingSafetyChecks` - - `class BetaComputerTool:` + The pending safety checks for the computer call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String id` - - `class BetaComputerUsePreviewTool:` + The ID of the pending safety check. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional code` - - `class BetaWebSearchTool:` + The type of the pending safety check. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional message` - - `Mcp` + Details about the pending safety check. - - `CodeInterpreter` + - `Status status` - - `JsonValue;` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `ImageGeneration` + - `IN_PROGRESS("in_progress")` - - `JsonValue;` + - `COMPLETED("completed")` - - `class BetaFunctionShellTool:` + - `INCOMPLETE("incomplete")` - A tool that allows the model to execute shell commands. + - `Type type` - - `class BetaCustomTool:` + The type of the computer call. Always `computer_call`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `COMPUTER_CALL("computer_call")` - - `class BetaNamespaceTool:` + - `Optional action` - Groups function/custom tools under a shared namespace. + A click action. - - `class BetaToolSearchTool:` + - `Click` - Hosted or BYOT tool search configuration for deferred tools. + - `Button button` - - `class BetaWebSearchPreviewTool:` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `LEFT("left")` - - `class BetaApplyPatchTool:` + - `RIGHT("right")` - Allows the assistant to create, delete, or update files using unified diffs. + - `WHEEL("wheel")` - - `JsonValue; type "tool_search_output"constant` + - `BACK("back")` - The type of the item. Always `tool_search_output`. + - `FORWARD("forward")` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `JsonValue; type "click"constant` - - `Optional agent` + Specifies the event type. For a click action, this property is always `click`. - The agent that produced this item. + - `CLICK("click")` - - `String agentName` + - `long x` - The canonical name of the agent that produced this item. + The x-coordinate where the click occurred. - - `Optional createdBy` + - `long y` - The identifier of the actor that created the item. + The y-coordinate where the click occurred. - - `AdditionalTools` + - `Optional> keys` - - `String id` + The keys being held while clicking. - The unique ID of the additional tools item. + - `DoubleClick` - - `Role role` + - `Optional> keys` - The role that provided the additional tools. + The keys being held while double-clicking. - - `UNKNOWN("unknown")` + - `JsonValue; type "double_click"constant` - - `USER("user")` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `ASSISTANT("assistant")` + - `DOUBLE_CLICK("double_click")` - - `SYSTEM("system")` + - `long x` - - `CRITIC("critic")` + The x-coordinate where the double click occurred. - - `DISCRIMINATOR("discriminator")` + - `long y` - - `DEVELOPER("developer")` + The y-coordinate where the double click occurred. - - `TOOL("tool")` + - `Drag` - - `List tools` + - `List path` - The additional tool definitions made available at this item. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `class BetaFunctionTool:` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `long x` - - `class BetaFileSearchTool:` + The x-coordinate. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `long y` - - `class BetaComputerTool:` + The y-coordinate. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JsonValue; type "drag"constant` - - `class BetaComputerUsePreviewTool:` + Specifies the event type. For a drag action, this property is always set to `drag`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `DRAG("drag")` - - `class BetaWebSearchTool:` + - `Optional> keys` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The keys being held while dragging the mouse. - - `Mcp` + - `Keypress` - - `CodeInterpreter` + - `List keys` - - `JsonValue;` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `ImageGeneration` + - `JsonValue; type "keypress"constant` - - `JsonValue;` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `class BetaFunctionShellTool:` + - `KEYPRESS("keypress")` - A tool that allows the model to execute shell commands. + - `Move` - - `class BetaCustomTool:` + - `JsonValue; type "move"constant` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Specifies the event type. For a move action, this property is always set to `move`. - - `class BetaNamespaceTool:` + - `MOVE("move")` - Groups function/custom tools under a shared namespace. + - `long x` - - `class BetaToolSearchTool:` + The x-coordinate to move to. - Hosted or BYOT tool search configuration for deferred tools. + - `long y` - - `class BetaWebSearchPreviewTool:` + The y-coordinate to move to. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional> keys` - - `class BetaApplyPatchTool:` + The keys being held while moving the mouse. - Allows the assistant to create, delete, or update files using unified diffs. + - `JsonValue;` - - `JsonValue; type "additional_tools"constant` + - `JsonValue; type "screenshot"constant` - The type of the item. Always `additional_tools`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `ADDITIONAL_TOOLS("additional_tools")` + - `SCREENSHOT("screenshot")` - - `Optional agent` + - `Scroll` - The agent that produced this item. + - `long scrollX` - - `String agentName` + The horizontal scroll distance. - The canonical name of the agent that produced this item. + - `long scrollY` - - `class BetaResponseCompactionItem:` + The vertical scroll distance. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `JsonValue; type "scroll"constant` - - `String id` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The unique ID of the compaction item. + - `SCROLL("scroll")` - - `String encryptedContent` + - `long x` - The encrypted content that was produced by compaction. + The x-coordinate where the scroll occurred. - - `JsonValue; type "compaction"constant` + - `long y` - The type of the item. Always `compaction`. + The y-coordinate where the scroll occurred. - - `COMPACTION("compaction")` + - `Optional> keys` - - `Optional agent` + The keys being held while scrolling. - The agent that produced this item. + - `Type` - - `String agentName` + - `String text` - The canonical name of the agent that produced this item. + The text to type. - - `Optional createdBy` + - `JsonValue; type "type"constant` - The identifier of the actor that created the item. + Specifies the event type. For a type action, this property is always set to `type`. - - `ImageGenerationCall` + - `TYPE("type")` - - `String id` + - `JsonValue;` - The unique ID of the image generation call. + - `JsonValue; type "wait"constant` - - `Optional result` + Specifies the event type. For a wait action, this property is always set to `wait`. - The generated image encoded in base64. + - `WAIT("wait")` - - `Status status` + - `Optional> actions` - The status of the image generation call. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `IN_PROGRESS("in_progress")` + - `Click` - - `COMPLETED("completed")` + - `DoubleClick` - - `GENERATING("generating")` + - `Drag` - - `FAILED("failed")` + - `Keypress` - - `JsonValue; type "image_generation_call"constant` + - `Move` - The type of the image generation call. Always `image_generation_call`. + - `JsonValue;` - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `Scroll` + + - `Type` + + - `JsonValue;` - `Optional agent` @@ -68487,65 +81872,56 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. - - - `LocalShellCall` - - - `String id` - - The unique ID of the local shell call. - - - `Action action` + - `ComputerCallOutput` - Execute a shell command on the server. + - `String callId` - - `List command` + The ID of the computer tool call that produced the output. - The command to run. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `Env env` + A computer screenshot image used with the computer use tool. - Environment variables to set for the command. + - `JsonValue; type "computer_screenshot"constant` - - `JsonValue; type "exec"constant` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The type of the local shell action. Always `exec`. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `EXEC("exec")` + - `Optional fileId` - - `Optional timeoutMs` + The identifier of an uploaded file that contains the screenshot. - Optional timeout in milliseconds for the command. + - `Optional imageUrl` - - `Optional user` + The URL of the screenshot image. - Optional user to run the command as. + - `JsonValue; type "computer_call_output"constant` - - `Optional workingDirectory` + The type of the computer tool call output. Always `computer_call_output`. - Optional working directory to run the command in. + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `String callId` + - `Optional id` - The unique ID of the local shell tool call generated by the model. + The ID of the computer tool call output. - - `Status status` + - `Optional> acknowledgedSafetyChecks` - The status of the local shell call. + The safety checks reported by the API that have been acknowledged by the developer. - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The ID of the pending safety check. - - `INCOMPLETE("incomplete")` + - `Optional code` - - `JsonValue; type "local_shell_call"constant` + The type of the pending safety check. - The type of the local shell call. Always `local_shell_call`. + - `Optional message` - - `LOCAL_SHELL_CALL("local_shell_call")` + Details about the pending safety check. - `Optional agent` @@ -68555,107 +81931,111 @@ public final class Main { The canonical name of the agent that produced this item. - - `LocalShellCallOutput` + - `Optional status` - - `String id` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The unique ID of the local shell tool call generated by the model. + - `IN_PROGRESS("in_progress")` - - `String output` + - `COMPLETED("completed")` - A JSON string of the output of the local shell tool call. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "local_shell_call_output"constant` + - `class BetaResponseFunctionWebSearch:` - The type of the local shell tool call output. Always `local_shell_call_output`. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `String id` - - `Optional agent` + The unique ID of the web search tool call. - The agent that produced this item. + - `Action action` - - `String agentName` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - The canonical name of the agent that produced this item. + - `class Search:` - - `Optional status` + Action type "search" - Performs a web search query. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `JsonValue; type "search"constant` - - `IN_PROGRESS("in_progress")` + The action type. - - `COMPLETED("completed")` + - `SEARCH("search")` - - `INCOMPLETE("incomplete")` + - `Optional> queries` - - `class BetaResponseFunctionShellToolCall:` + The search queries. - A tool call that executes one or more shell commands in a managed environment. + - `Optional query` - - `String id` + The search query. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `Optional> sources` - - `Action action` + The sources used in the search. - The shell commands and limits that describe how to run the tool call. + - `JsonValue; type "url"constant` - - `List commands` + The type of source. Always `url`. - - `Optional maxOutputLength` + - `URL("url")` - Optional maximum number of characters to return from each command. + - `String url` - - `Optional timeoutMs` + The URL of the source. - Optional timeout in milliseconds for the commands. + - `class OpenPage:` - - `String callId` + Action type "open_page" - Opens a specific URL from search results. - The unique ID of the shell tool call generated by the model. + - `JsonValue; type "open_page"constant` - - `Optional environment` + The action type. - Represents the use of a local environment to perform shell actions. + - `OPEN_PAGE("open_page")` - - `class BetaResponseLocalEnvironment:` + - `Optional url` - Represents the use of a local environment to perform shell actions. + The URL opened by the model. - - `JsonValue; type "local"constant` + - `class FindInPage:` - The environment type. Always `local`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `LOCAL("local")` + - `String pattern` - - `class BetaResponseContainerReference:` + The pattern or text to search for within the page. - Represents a container created with /v1/containers. + - `JsonValue; type "find_in_page"constant` - - `String containerId` + The action type. - - `JsonValue; type "container_reference"constant` + - `FIND_IN_PAGE("find_in_page")` - The environment type. Always `container_reference`. + - `String url` - - `CONTAINER_REFERENCE("container_reference")` + The URL of the page searched for the pattern. - `Status status` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the web search tool call. - `IN_PROGRESS("in_progress")` + - `SEARCHING("searching")` + - `COMPLETED("completed")` - - `INCOMPLETE("incomplete")` + - `FAILED("failed")` - - `JsonValue; type "shell_call"constant` + - `JsonValue; type "web_search_call"constant` - The type of the item. Always `shell_call`. + The type of the web search tool call. Always `web_search_call`. - - `SHELL_CALL("shell_call")` + - `WEB_SEARCH_CALL("web_search_call")` - `Optional agent` @@ -68665,215 +82045,209 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` + - `class BetaResponseFunctionToolCall:` - - `String callerId` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The call ID of the program item that produced this tool call. + - `String arguments` - - `JsonValue; type "program"constant` + A JSON string of the arguments to pass to the function. - - `PROGRAM("program")` + - `String callId` - - `Optional createdBy` + The unique ID of the function tool call generated by the model. - The ID of the entity that created this tool call. + - `String name` - - `class BetaResponseFunctionShellToolCallOutput:` + The name of the function to run. - The output of a shell tool call that was emitted. + - `JsonValue; type "function_call"constant` - - `String id` + The type of the function tool call. Always `function_call`. - The unique ID of the shell call output. Populated when this item is returned via API. + - `FUNCTION_CALL("function_call")` - - `String callId` + - `Optional id` - The unique ID of the shell tool call generated by the model. + The unique ID of the function tool call. - - `Optional maxOutputLength` + - `Optional agent` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The agent that produced this item. - - `List output` + - `String agentName` - An array of shell call output contents + The canonical name of the agent that produced this item. - - `Outcome outcome` + - `Optional caller` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The execution context that produced this tool call. - `JsonValue;` - - `JsonValue; type "timeout"constant` + - `JsonValue; type "direct"constant` - The outcome type. Always `timeout`. + - `DIRECT("direct")` - - `TIMEOUT("timeout")` + - `class Program:` - - `class Exit:` + - `String callerId` - Indicates that the shell commands finished and returned an exit code. + The call ID of the program item that produced this tool call. - - `long exitCode` + - `JsonValue; type "program"constant` - Exit code from the shell process. + - `PROGRAM("program")` - - `JsonValue; type "exit"constant` + - `Optional namespace` - The outcome type. Always `exit`. + The namespace of the function to run. - - `EXIT("exit")` + - `Optional status` - - `String stderr` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The standard error output that was captured. + - `IN_PROGRESS("in_progress")` - - `String stdout` + - `COMPLETED("completed")` - The standard output that was captured. + - `INCOMPLETE("incomplete")` - - `Optional createdBy` + - `FunctionCallOutput` - The identifier of the actor that created the item. + - `String callId` - - `Status status` + The unique ID of the function tool call generated by the model. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `Output output` - - `IN_PROGRESS("in_progress")` + Text, image, or file output of the function tool call. - - `COMPLETED("completed")` + - `String` - - `INCOMPLETE("incomplete")` + - `List` - - `JsonValue; type "shell_call_output"constant` + - `class BetaResponseInputTextContent:` - The type of the shell call output. Always `shell_call_output`. + A text input to the model. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `String text` - - `Optional agent` + The text input to the model. - The agent that produced this item. + - `JsonValue; type "input_text"constant` - - `String agentName` + The type of the input item. Always `input_text`. - The canonical name of the agent that produced this item. + - `INPUT_TEXT("input_text")` - - `Optional caller` + - `Optional promptCacheBreakpoint` - The execution context that produced this tool call. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue;` + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "direct"constant` + The breakpoint mode. Always `explicit`. - - `DIRECT("direct")` + - `EXPLICIT("explicit")` - - `class Program:` + - `class BetaResponseInputImageContent:` - - `String callerId` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The call ID of the program item that produced this tool call. + - `JsonValue; type "input_image"constant` - - `JsonValue; type "program"constant` + The type of the input item. Always `input_image`. - - `PROGRAM("program")` + - `INPUT_IMAGE("input_image")` - - `Optional createdBy` + - `Optional detail` - The identifier of the actor that created the item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class BetaResponseApplyPatchToolCall:` + - `LOW("low")` - A tool call that applies file diffs by creating, deleting, or updating files. + - `HIGH("high")` - - `String id` + - `AUTO("auto")` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `ORIGINAL("original")` - - `String callId` + - `Optional fileId` - The unique ID of the apply patch tool call generated by the model. + The ID of the file to be sent to the model. - - `Operation operation` + - `Optional imageUrl` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `class CreateFile:` + - `Optional promptCacheBreakpoint` - Instruction describing how to create a file via the apply_patch tool. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String diff` + - `JsonValue; mode "explicit"constant` - Diff to apply. + The breakpoint mode. Always `explicit`. - - `String path` + - `EXPLICIT("explicit")` - Path of the file to create. + - `class BetaResponseInputFileContent:` - - `JsonValue; type "create_file"constant` + A file input to the model. - Create a new file with the provided diff. + - `JsonValue; type "input_file"constant` - - `CREATE_FILE("create_file")` + The type of the input item. Always `input_file`. - - `class DeleteFile:` + - `INPUT_FILE("input_file")` - Instruction describing how to delete a file via the apply_patch tool. + - `Optional detail` - - `String path` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Path of the file to delete. + - `AUTO("auto")` - - `JsonValue; type "delete_file"constant` + - `LOW("low")` - Delete the specified file. + - `HIGH("high")` - - `DELETE_FILE("delete_file")` + - `Optional fileData` - - `class UpdateFile:` + The base64-encoded data of the file to be sent to the model. - Instruction describing how to update a file via the apply_patch tool. + - `Optional fileId` - - `String diff` + The ID of the file to be sent to the model. - Diff to apply. + - `Optional fileUrl` - - `String path` + The URL of the file to be sent to the model. - Path of the file to update. + - `Optional filename` - - `JsonValue; type "update_file"constant` + The name of the file to be sent to the model. - Update an existing file with the provided diff. + - `Optional promptCacheBreakpoint` - - `UPDATE_FILE("update_file")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Status status` + - `JsonValue; mode "explicit"constant` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The breakpoint mode. Always `explicit`. - - `IN_PROGRESS("in_progress")` + - `EXPLICIT("explicit")` - - `COMPLETED("completed")` + - `JsonValue; type "function_call_output"constant` - - `JsonValue; type "apply_patch_call"constant` + The type of the function tool call output. Always `function_call_output`. - The type of the item. Always `apply_patch_call`. + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `APPLY_PATCH_CALL("apply_patch_call")` + - `Optional id` + + The unique ID of the function tool call output. Populated when this item is returned via API. - `Optional agent` @@ -68891,6 +82265,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -68901,97 +82277,109 @@ public final class Main { - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - - `Optional createdBy` + - `Optional status` - The ID of the entity that created this tool call. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `class BetaResponseApplyPatchToolCallOutput:` + - `IN_PROGRESS("in_progress")` - The output emitted by an apply patch tool call. + - `COMPLETED("completed")` - - `String id` + - `INCOMPLETE("incomplete")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `AgentMessage` - - `String callId` + - `String author` - The unique ID of the apply patch tool call generated by the model. + The sending agent identity. - - `Status status` + - `List content` - The status of the apply patch tool call output. One of `completed` or `failed`. + Plaintext, image, or encrypted content sent between agents. - - `COMPLETED("completed")` + - `class BetaResponseInputTextContent:` - - `FAILED("failed")` + A text input to the model. - - `JsonValue; type "apply_patch_call_output"constant` + - `class BetaResponseInputImageContent:` - The type of the item. Always `apply_patch_call_output`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `class EncryptedContent:` - - `Optional agent` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The agent that produced this item. + - `String encryptedContent` - - `String agentName` + Opaque encrypted content. - The canonical name of the agent that produced this item. + - `JsonValue; type "encrypted_content"constant` - - `Optional caller` + The type of the input item. Always `encrypted_content`. - The execution context that produced this tool call. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `JsonValue;` + - `String recipient` - - `JsonValue; type "direct"constant` + The destination agent identity. - - `DIRECT("direct")` + - `JsonValue; type "agent_message"constant` - - `class Program:` + The item type. Always `agent_message`. - - `String callerId` + - `AGENT_MESSAGE("agent_message")` - The call ID of the program item that produced this tool call. + - `Optional id` - - `JsonValue; type "program"constant` + The unique ID of this agent message item. - - `PROGRAM("program")` + - `Optional agent` - - `Optional createdBy` + The agent that produced this item. - The ID of the entity that created this tool call output. + - `String agentName` - - `Optional output` + The canonical name of the agent that produced this item. - Optional textual output returned by the apply patch tool. + - `MultiAgentCall` - - `McpCall` + - `Action action` - - `String id` + The multi-agent action that was executed. - The unique ID of the tool call. + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` - `String arguments` - A JSON string of the arguments passed to the tool. + The action arguments as a JSON string. - - `String name` + - `String callId` - The name of the tool that was run. + The unique ID linking this call to its output. - - `String serverLabel` + - `JsonValue; type "multi_agent_call"constant` - The label of the MCP server running the tool. + The item type. Always `multi_agent_call`. - - `JsonValue; type "mcp_call"constant` + - `MULTI_AGENT_CALL("multi_agent_call")` - The type of the item. Always `mcp_call`. + - `Optional id` - - `MCP_CALL("mcp_call")` + The unique ID of this multi-agent call. - `Optional agent` @@ -69001,104 +82389,127 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional approvalRequestId` + - `MultiAgentCallOutput` - 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. + - `Action action` - - `Optional error` + The multi-agent action that produced this result. - The error from the tool call, if any. + - `SPAWN_AGENT("spawn_agent")` - - `Optional output` + - `INTERRUPT_AGENT("interrupt_agent")` - The output from the tool call. + - `LIST_AGENTS("list_agents")` - - `Optional status` + - `SEND_MESSAGE("send_message")` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `FOLLOWUP_TASK("followup_task")` - - `IN_PROGRESS("in_progress")` + - `WAIT_AGENT("wait_agent")` - - `COMPLETED("completed")` + - `String callId` - - `INCOMPLETE("incomplete")` + The unique ID of the multi-agent call. - - `CALLING("calling")` + - `List output` - - `FAILED("failed")` + Text output returned by the multi-agent action. - - `McpListTools` + - `String text` - - `String id` + The text content. - The unique ID of the list. + - `JsonValue; type "output_text"constant` - - `String serverLabel` + The content type. Always `output_text`. - The label of the MCP server. + - `OUTPUT_TEXT("output_text")` - - `List tools` + - `Optional annotations` - The tools available on the server. + Citations associated with the text content. - - `JsonValue inputSchema` + - `List` - The JSON schema describing the tool's input. + - `String fileId` - - `String name` + The ID of the file. - The name of the tool. + - `String filename` - - `Optional annotations` + The filename of the file cited. - Additional annotations about the tool. + - `long index` - - `Optional description` + The index of the file in the list of files. - The description of the tool. + - `JsonValue; type "file_citation"constant` - - `JsonValue; type "mcp_list_tools"constant` + The citation type. Always `file_citation`. - The type of the item. Always `mcp_list_tools`. + - `FILE_CITATION("file_citation")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `List` - - `Optional agent` + - `long endIndex` - The agent that produced this item. + The index of the last character of the citation in the message. - - `String agentName` + - `long startIndex` - The canonical name of the agent that produced this item. + The index of the first character of the citation in the message. - - `Optional error` + - `String title` - Error message if the server could not list tools. + The title of the cited resource. - - `McpApprovalRequest` + - `JsonValue; type "url_citation"constant` - - `String id` + The citation type. Always `url_citation`. - The unique ID of the approval request. + - `URL_CITATION("url_citation")` - - `String arguments` + - `String url` - A JSON string of arguments for the tool. + The URL of the cited resource. - - `String name` + - `List` - The name of the tool to run. + - `String containerId` - - `String serverLabel` + The ID of the container. - The label of the MCP server making the request. + - `long endIndex` - - `JsonValue; type "mcp_approval_request"constant` + The index of the last character of the citation in the message. - The type of the item. Always `mcp_approval_request`. + - `String fileId` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + The ID of the container file. + + - `String filename` + + The filename of the container file cited. + + - `long startIndex` + + The index of the first character of the citation in the message. + + - `JsonValue; type "container_file_citation"constant` + + The citation type. Always `container_file_citation`. + + - `CONTAINER_FILE_CITATION("container_file_citation")` + + - `JsonValue; type "multi_agent_call_output"constant` + + The item type. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + + - `Optional id` + + The unique ID of this multi-agent call output. - `Optional agent` @@ -69108,25 +82519,21 @@ public final class Main { The canonical name of the agent that produced this item. - - `McpApprovalResponse` - - - `String id` - - The unique ID of the approval response + - `ToolSearchCall` - - `String approvalRequestId` + - `JsonValue arguments` - The ID of the approval request being answered. + The arguments supplied to the tool search call. - - `boolean approve` + - `JsonValue; type "tool_search_call"constant` - Whether the request was approved. + The item type. Always `tool_search_call`. - - `JsonValue; type "mcp_approval_response"constant` + - `TOOL_SEARCH_CALL("tool_search_call")` - The type of the item. Always `mcp_approval_response`. + - `Optional id` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + The unique ID of this tool search call. - `Optional agent` @@ -69136,26 +82543,21 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional reason` - - Optional reason for the decision. - - - `class BetaResponseCustomToolCall:` + - `Optional callId` - A call to a custom tool created by the model. + The unique ID of the tool search call generated by the model. - - `class BetaResponseCustomToolCallOutputItem:` + - `Optional execution` - The output of a custom tool call from your code, being sent back to the model. + Whether tool search was executed by the server or by the client. - - `String id` + - `SERVER("server")` - The unique ID of the custom tool call output item. + - `CLIENT("client")` - - `Status status` + - `Optional status` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool search call. - `IN_PROGRESS("in_progress")` @@ -69163,698 +82565,686 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `Optional createdBy` + - `class BetaResponseToolSearchOutputItemParam:` - The identifier of the actor that created the item. + - `List tools` - - `boolean parallelToolCalls` + The loaded tool definitions returned by the tool search output. - Whether to allow the model to run tool calls in parallel. + - `class BetaFunctionTool:` - - `Optional temperature` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `String name` - - `ToolChoice toolChoice` + The name of the function to call. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `Optional parameters` - - `enum BetaToolChoiceOptions:` + A JSON schema object describing the parameters of the function. - Controls which (if any) tool is called by the model. + - `Optional strict` - `none` means the model will not call any tool and instead generates a message. + Whether strict parameter validation is enforced for this function tool. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `JsonValue; type "function"constant` - `required` means the model must call one or more tools. + The type of the function tool. Always `function`. - - `NONE("none")` + - `FUNCTION("function")` - - `AUTO("auto")` + - `Optional> allowedCallers` - - `REQUIRED("required")` + The tool invocation context(s). - - `class BetaToolChoiceAllowed:` + - `DIRECT("direct")` - Constrains the tools available to the model to a pre-defined set. + - `PROGRAMMATIC("programmatic")` - - `Mode mode` + - `Optional deferLoading` - Constrains the tools available to the model to a pre-defined set. + Whether this function is deferred and loaded via tool search. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `Optional description` - `required` requires the model to call one or more of the allowed tools. + A description of the function. Used by the model to determine whether or not to call the function. - - `AUTO("auto")` + - `Optional outputSchema` - - `REQUIRED("required")` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `List tools` + - `class BetaFileSearchTool:` - A list of tool definitions that the model should be allowed to call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - For the Responses API, the list of tool definitions might look like: + - `JsonValue; type "file_search"constant` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The type of the file search tool. Always `file_search`. - - `JsonValue; type "allowed_tools"constant` + - `FILE_SEARCH("file_search")` - Allowed tool configuration type. Always `allowed_tools`. + - `List vectorStoreIds` - - `ALLOWED_TOOLS("allowed_tools")` + The IDs of the vector stores to search. - - `class BetaToolChoiceTypes:` + - `Optional filters` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + 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` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Allowed values are: + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `EQ("eq")` - - `FILE_SEARCH("file_search")` + - `NE("ne")` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `GT("gt")` - - `COMPUTER("computer")` + - `GTE("gte")` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `LT("lt")` - - `COMPUTER_USE("computer_use")` + - `LTE("lte")` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `IN("in")` - - `IMAGE_GENERATION("image_generation")` + - `NIN("nin")` - - `CODE_INTERPRETER("code_interpreter")` + - `Value value` - - `class BetaToolChoiceFunction:` + The value to compare against the attribute key; supports string, number, or boolean types. - Use this option to force the model to call a specific function. + - `String` - - `String name` + - `double` - The name of the function to call. + - `boolean` - - `JsonValue; type "function"constant` + - `List` - For function calling, the type is always `function`. + - `String` - - `FUNCTION("function")` + - `double` - - `class BetaToolChoiceMcp:` + - `class CompoundFilter:` - Use this option to force the model to call a specific tool on a remote MCP server. + Combine multiple filters using `and` or `or`. - - `String serverLabel` + - `List filters` - The label of the MCP server to use. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `JsonValue; type "mcp"constant` + - `class ComparisonFilter:` - For MCP tools, the type is always `mcp`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `MCP("mcp")` + - `String key` - - `Optional name` + The key to compare against the value. - The name of the tool to call on the server. + - `Type type` - - `class BetaToolChoiceCustom:` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Use this option to force the model to call a specific custom tool. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `String name` + - `EQ("eq")` - The name of the custom tool to call. + - `NE("ne")` - - `JsonValue; type "custom"constant` + - `GT("gt")` - For custom tool calling, the type is always `custom`. + - `GTE("gte")` - - `CUSTOM("custom")` + - `LT("lt")` - - `JsonValue;` + - `LTE("lte")` - - `JsonValue; type "programmatic_tool_calling"constant` + - `IN("in")` - The tool to call. Always `programmatic_tool_calling`. + - `NIN("nin")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Value value` - - `class BetaToolChoiceApplyPatch:` + The value to compare against the attribute key; supports string, number, or boolean types. - Forces the model to call the apply_patch tool when executing a tool call. + - `String` - - `JsonValue; type "apply_patch"constant` + - `double` - The tool to call. Always `apply_patch`. + - `boolean` - - `APPLY_PATCH("apply_patch")` + - `List` - - `class BetaToolChoiceShell:` + - `String` - Forces the model to call the shell tool when a tool call is required. + - `double` - - `JsonValue; type "shell"constant` + - `JsonValue` - The tool to call. Always `shell`. + - `Type type` - - `SHELL("shell")` + Type of operation: `and` or `or`. - - `List tools` + - `AND("and")` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `OR("or")` - We support the following categories of tools: + - `Optional maxNumResults` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `class BetaFunctionTool:` + - `Optional rankingOptions` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + Ranking options for search. - - `class BetaFileSearchTool:` + - `Optional hybridSearch` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `class BetaComputerTool:` + - `double embeddingWeight` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The weight of the embedding in the reciprocal ranking fusion. - - `class BetaComputerUsePreviewTool:` + - `double textWeight` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The weight of the text in the reciprocal ranking fusion. - - `class BetaWebSearchTool:` + - `Optional ranker` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The ranker to use for the file search. - - `Mcp` + - `AUTO("auto")` - - `CodeInterpreter` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `JsonValue;` + - `Optional scoreThreshold` - - `ImageGeneration` + 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. - - `JsonValue;` + - `class BetaComputerTool:` - - `class BetaFunctionShellTool:` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A tool that allows the model to execute shell commands. + - `JsonValue; type "computer"constant` - - `class BetaCustomTool:` + The type of the computer tool. Always `computer`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `COMPUTER("computer")` - - `class BetaNamespaceTool:` + - `class BetaComputerUsePreviewTool:` - Groups function/custom tools under a shared namespace. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaToolSearchTool:` + - `long displayHeight` - Hosted or BYOT tool search configuration for deferred tools. + The height of the computer display. - - `class BetaWebSearchPreviewTool:` + - `long displayWidth` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The width of the computer display. - - `class BetaApplyPatchTool:` + - `Environment environment` - Allows the assistant to create, delete, or update files using unified diffs. + The type of computer environment to control. - - `Optional topP` + - `WINDOWS("windows")` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `MAC("mac")` - We generally recommend altering this or `temperature` but not both. + - `LINUX("linux")` - - `Optional background` + - `UBUNTU("ubuntu")` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `BROWSER("browser")` - - `Optional completedAt` + - `JsonValue; type "computer_use_preview"constant` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The type of the computer use tool. Always `computer_use_preview`. - - `Optional conversation` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `class BetaWebSearchTool:` - - `String id` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The unique ID of the conversation that this response was associated with. + - `Type type` - - `Optional maxOutputTokens` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `WEB_SEARCH("web_search")` - - `Optional maxToolCalls` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `Optional filters` - - `Optional moderation` + Filters for the search. - Moderation results for the response input and output, if moderated completions were requested. + - `Optional> allowedDomains` - - `Input input` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Moderation for the response input. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `class ModerationResult:` + - `Optional searchContextSize` - A moderation result produced for the response input or output. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Categories categories` + - `LOW("low")` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `MEDIUM("medium")` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `HIGH("high")` - Which modalities of input are reflected by the score for each category. + - `Optional userLocation` - - `TEXT("text")` + The approximate location of the user. - - `IMAGE("image")` + - `Optional city` - - `CategoryScores categoryScores` + Free text input for the city of the user, e.g. `San Francisco`. - A dictionary of moderation categories to scores. + - `Optional country` - - `boolean flagged` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A boolean indicating whether the content was flagged by any category. + - `Optional region` - - `String model` + Free text input for the region of the user, e.g. `California`. - The moderation model that produced this result. + - `Optional timezone` - - `JsonValue; type "moderation_result"constant` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The object type, which was always `moderation_result` for successful moderation results. + - `Optional type` - - `MODERATION_RESULT("moderation_result")` + The type of location approximation. Always `approximate`. - - `class Error:` + - `APPROXIMATE("approximate")` - An error produced while attempting moderation for the response input or output. + - `Mcp` - - `String code` + - `String serverLabel` - The error code. + A label for this MCP server, used to identify it in tool calls. - - `String message` + - `JsonValue; type "mcp"constant` - The error message. + The type of the MCP tool. Always `mcp`. - - `JsonValue; type "error"constant` + - `MCP("mcp")` - The object type, which was always `error` for moderation failures. + - `Optional> allowedCallers` - - `ERROR("error")` + The tool invocation context(s). - - `Output output` + - `DIRECT("direct")` - Moderation for the response output. + - `PROGRAMMATIC("programmatic")` - - `class ModerationResult:` + - `Optional allowedTools` - A moderation result produced for the response input or output. + List of allowed tool names or a filter object. - - `Categories categories` + - `List` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `class McpToolFilter:` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + A filter object to specify which tools are allowed. - Which modalities of input are reflected by the score for each category. + - `Optional readOnly` - - `TEXT("text")` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `IMAGE("image")` + - `Optional> toolNames` - - `CategoryScores categoryScores` + List of allowed tool names. - A dictionary of moderation categories to scores. + - `Optional authorization` - - `boolean flagged` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A boolean indicating whether the content was flagged by any category. + - `Optional connectorId` - - `String model` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The moderation model that produced this result. + Currently supported `connector_id` values are: - - `JsonValue; type "moderation_result"constant` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The object type, which was always `moderation_result` for successful moderation results. + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `MODERATION_RESULT("moderation_result")` + - `CONNECTOR_GMAIL("connector_gmail")` - - `class Error:` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - An error produced while attempting moderation for the response input or output. + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `String code` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - The error code. + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `String message` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - The error message. + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `JsonValue; type "error"constant` + - `Optional deferLoading` - The object type, which was always `error` for moderation failures. + Whether this MCP tool is deferred and discovered via tool search. - - `ERROR("error")` + - `Optional headers` - - `Optional previousResponseId` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `Optional requireApproval` - - `Optional prompt` + Specify which of the MCP server's tools require approval. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `class McpToolApprovalFilter:` - - `String id` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The unique identifier of the prompt template to use. + - `Optional always` - - `Optional variables` + A filter object to specify which tools are allowed. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `Optional readOnly` - - `String` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `class BetaResponseInputText:` + - `Optional> toolNames` - A text input to the model. + List of allowed tool names. - - `class BetaResponseInputImage:` + - `Optional never` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A filter object to specify which tools are allowed. - - `class BetaResponseInputFile:` + - `Optional readOnly` - A file input to the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `Optional version` + - `Optional> toolNames` - Optional version of the prompt template. + 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 promptCacheKey` + - `Optional serverDescription` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Optional description of the MCP server, used to provide more context. - - `Optional promptCacheOptions` + - `Optional serverUrl` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `Mode mode` + - `Optional tunnelId` - Whether implicit prompt-cache breakpoints were enabled. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `IMPLICIT("implicit")` + - `CodeInterpreter` - - `EXPLICIT("explicit")` + - `Container container` - - `Ttl ttl` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The minimum lifetime applied to each cache breakpoint. + - `String` - - `_30M("30m")` + - `class CodeInterpreterToolAuto:` - - `Optional promptCacheRetention` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `JsonValue; type "auto"constant` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + Always `auto`. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `AUTO("auto")` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `Optional> fileIds` - - `IN_MEMORY("in_memory")` + An optional list of uploaded files to make available to your code. - - `_24H("24h")` + - `Optional memoryLimit` - - `Optional reasoning` + The memory limit for the code interpreter container. - **gpt-5 and o-series models only** + - `_1G("1g")` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `_4G("4g")` - - `Optional context` + - `_16G("16g")` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `_64G("64g")` - - `AUTO("auto")` + - `Optional networkPolicy` - - `CURRENT_TURN("current_turn")` + Network access policy for the container. - - `ALL_TURNS("all_turns")` + - `class BetaContainerNetworkPolicyDisabled:` - - `Optional effort` + - `JsonValue; type "disabled"constant` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + Disable outbound network access. Always `disabled`. - - `NONE("none")` + - `DISABLED("disabled")` - - `MINIMAL("minimal")` + - `class BetaContainerNetworkPolicyAllowlist:` - - `LOW("low")` + - `List allowedDomains` - - `MEDIUM("medium")` + A list of allowed domains when type is `allowlist`. - - `HIGH("high")` + - `JsonValue; type "allowlist"constant` - - `XHIGH("xhigh")` + Allow outbound network access only to specified domains. Always `allowlist`. - - `MAX("max")` + - `ALLOWLIST("allowlist")` - - `Optional generateSummary` + - `Optional> domainSecrets` - **Deprecated:** use `summary` instead. + Optional domain-scoped secrets for allowlisted domains. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `String domain` - - `AUTO("auto")` + The domain associated with the secret. - - `CONCISE("concise")` + - `String name` - - `DETAILED("detailed")` + The name of the secret to inject for the domain. - - `Optional mode` + - `String value` - Controls the reasoning execution mode for the request. + The secret value to inject for the domain. - When returned on a response, this is the effective execution mode. + - `JsonValue; type "code_interpreter"constant` - - `STANDARD("standard")` + The type of the code interpreter tool. Always `code_interpreter`. - - `PRO("pro")` + - `CODE_INTERPRETER("code_interpreter")` - - `Optional summary` + - `Optional> allowedCallers` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The tool invocation context(s). - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `DIRECT("direct")` - - `AUTO("auto")` + - `PROGRAMMATIC("programmatic")` - - `CONCISE("concise")` + - `JsonValue;` - - `DETAILED("detailed")` + - `JsonValue; type "programmatic_tool_calling"constant` - - `Optional safetyIdentifier` + The type of the tool. Always `programmatic_tool_calling`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `Optional serviceTier` + - `ImageGeneration` - Specifies the processing type used for serving the request. + - `JsonValue; type "image_generation"constant` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The type of the image generation tool. Always `image_generation`. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `IMAGE_GENERATION("image_generation")` - - `AUTO("auto")` + - `Optional action` - - `DEFAULT("default")` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `FLEX("flex")` + - `GENERATE("generate")` - - `SCALE("scale")` + - `EDIT("edit")` - - `PRIORITY("priority")` + - `AUTO("auto")` - - `Optional status` + - `Optional background` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `COMPLETED("completed")` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `FAILED("failed")` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `IN_PROGRESS("in_progress")` + - `TRANSPARENT("transparent")` - - `CANCELLED("cancelled")` + - `OPAQUE("opaque")` - - `QUEUED("queued")` + - `AUTO("auto")` - - `INCOMPLETE("incomplete")` + - `Optional inputFidelity` - - `Optional text` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `HIGH("high")` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `LOW("low")` - - `Optional format` + - `Optional inputImageMask` - An object specifying the format that the model must output. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional fileId` - The default format is `{ "type": "text" }` with no additional options. + File ID for the mask image. - **Not recommended for gpt-4o and newer models:** + - `Optional imageUrl` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + Base64-encoded mask image. - - `JsonValue;` + - `Optional model` - - `JsonValue; type "text"constant` + The image generation model to use. Default: `gpt-image-1`. - The type of response format being defined. Always `text`. + - `GPT_IMAGE_1("gpt-image-1")` - - `TEXT("text")` + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `GPT_IMAGE_2("gpt-image-2")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `String name` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `Schema schema` + - `Optional moderation` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Moderation level for the generated image. Default: `auto`. - - `JsonValue; type "json_schema"constant` + - `AUTO("auto")` - The type of response format being defined. Always `json_schema`. + - `LOW("low")` - - `JSON_SCHEMA("json_schema")` + - `Optional outputCompression` - - `Optional description` + Compression level for the output image. Default: 100. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Optional outputFormat` - - `Optional strict` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `PNG("png")` - - `JsonValue;` + - `WEBP("webp")` - - `JsonValue; type "json_object"constant` + - `JPEG("jpeg")` - The type of response format being defined. Always `json_object`. + - `Optional partialImages` - - `JSON_OBJECT("json_object")` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `Optional verbosity` + - `Optional quality` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - `LOW("low")` @@ -69862,431 +83252,425 @@ public final class Main { - `HIGH("high")` - - `Optional topLogprobs` + - `AUTO("auto")` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `Optional size` - - `Optional truncation` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The truncation strategy to use for the model response. + - `_1024X1024("1024x1024")` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `_1024X1536("1024x1536")` + + - `_1536X1024("1536x1024")` - `AUTO("auto")` - - `DISABLED("disabled")` + - `JsonValue;` - - `Optional usage` + - `JsonValue; type "local_shell"constant` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The type of the local shell tool. Always `local_shell`. - - `long inputTokens` + - `LOCAL_SHELL("local_shell")` - The number of input tokens. + - `class BetaFunctionShellTool:` - - `InputTokensDetails inputTokensDetails` + A tool that allows the model to execute shell commands. - A detailed breakdown of the input tokens. + - `JsonValue; type "shell"constant` - - `long cacheWriteTokens` + The type of the shell tool. Always `shell`. - The number of input tokens that were written to the cache. + - `SHELL("shell")` - - `long cachedTokens` + - `Optional> allowedCallers` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The tool invocation context(s). - - `long outputTokens` + - `DIRECT("direct")` - The number of output tokens. + - `PROGRAMMATIC("programmatic")` - - `OutputTokensDetails outputTokensDetails` + - `Optional environment` - A detailed breakdown of the output tokens. + - `class BetaContainerAuto:` - - `long reasoningTokens` + - `JsonValue; type "container_auto"constant` - The number of reasoning tokens. + Automatically creates a container for this request - - `long totalTokens` + - `CONTAINER_AUTO("container_auto")` - The total number of tokens used. + - `Optional> fileIds` - - `Optional user` + An optional list of uploaded files to make available to your code. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `Optional memoryLimit` - - `long sequenceNumber` + The memory limit for the container. - The sequence number for this event. + - `_1G("1g")` - - `JsonValue; type "response.created"constant` + - `_4G("4g")` - The type of the event. Always `response.created`. + - `_16G("16g")` - - `RESPONSE_CREATED("response.created")` + - `_64G("64g")` - - `Optional agent` + - `Optional networkPolicy` - The agent that owns this multi-agent streaming event. + Network access policy for the container. - - `String agentName` + - `class BetaContainerNetworkPolicyDisabled:` - The canonical name of the agent that produced this item. + - `class BetaContainerNetworkPolicyAllowlist:` -### Beta Response Custom Tool Call + - `Optional> skills` -- `class BetaResponseCustomToolCall:` + An optional list of skills referenced by id or inline data. - A call to a custom tool created by the model. + - `class BetaSkillReference:` - - `String callId` + - `String skillId` - An identifier used to map this custom tool call to a tool call output. + The ID of the referenced skill. - - `String input` + - `JsonValue; type "skill_reference"constant` - The input for the custom tool call generated by the model. + References a skill created with the /v1/skills endpoint. - - `String name` + - `SKILL_REFERENCE("skill_reference")` - The name of the custom tool being called. + - `Optional version` - - `JsonValue; type "custom_tool_call"constant` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The type of the custom tool call. Always `custom_tool_call`. + - `class BetaInlineSkill:` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `String description` - - `Optional id` + The description of the skill. - The unique ID of the custom tool call in the OpenAI platform. + - `String name` - - `Optional agent` + The name of the skill. - The agent that produced this item. + - `BetaInlineSkillSource source` - - `String agentName` + Inline skill payload - The canonical name of the agent that produced this item. + - `String data` - - `Optional caller` + Base64-encoded skill zip bundle. - The execution context that produced this tool call. + - `JsonValue; mediaType "application/zip"constant` - - `JsonValue;` + The media type of the inline skill payload. Must be `application/zip`. - - `JsonValue; type "direct"constant` + - `APPLICATION_ZIP("application/zip")` - - `DIRECT("direct")` + - `JsonValue; type "base64"constant` - - `class Program:` + The type of the inline skill source. Must be `base64`. - - `String callerId` + - `BASE64("base64")` - The call ID of the program item that produced this tool call. + - `JsonValue; type "inline"constant` - - `JsonValue; type "program"constant` + Defines an inline skill for this request. - - `PROGRAM("program")` + - `INLINE("inline")` - - `Optional namespace` + - `class BetaLocalEnvironment:` - The namespace of the custom tool being called. + - `JsonValue; type "local"constant` -### Beta Response Custom Tool Call Input Delta Event + Use a local computer environment. -- `class BetaResponseCustomToolCallInputDeltaEvent:` + - `LOCAL("local")` - Event representing a delta (partial update) to the input of a custom tool call. + - `Optional> skills` - - `String delta` + An optional list of skills. - The incremental input data (delta) for the custom tool call. + - `String description` - - `String itemId` + The description of the skill. - Unique identifier for the API item associated with this event. + - `String name` - - `long outputIndex` + The name of the skill. - The index of the output this delta applies to. + - `String path` - - `long sequenceNumber` + The path to the directory containing the skill. - The sequence number of this event. + - `class BetaContainerReference:` - - `JsonValue; type "response.custom_tool_call_input.delta"constant` + - `String containerId` - The event type identifier. + The ID of the referenced container. - - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DELTA("response.custom_tool_call_input.delta")` + - `JsonValue; type "container_reference"constant` - - `Optional agent` + References a container created with the /v1/containers endpoint - The agent that owns this multi-agent streaming event. + - `CONTAINER_REFERENCE("container_reference")` - - `String agentName` + - `class BetaCustomTool:` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) -### Beta Response Custom Tool Call Input Done Event + - `String name` -- `class BetaResponseCustomToolCallInputDoneEvent:` + The name of the custom tool, used to identify it in tool calls. - Event indicating that input for a custom tool call is complete. + - `JsonValue; type "custom"constant` - - `String input` + The type of the custom tool. Always `custom`. - The complete input data for the custom tool call. + - `CUSTOM("custom")` - - `String itemId` + - `Optional> allowedCallers` - Unique identifier for the API item associated with this event. + The tool invocation context(s). - - `long outputIndex` + - `DIRECT("direct")` - The index of the output this event applies to. + - `PROGRAMMATIC("programmatic")` - - `long sequenceNumber` + - `Optional deferLoading` - The sequence number of this event. + Whether this tool should be deferred and discovered via tool search. - - `JsonValue; type "response.custom_tool_call_input.done"constant` + - `Optional description` - The event type identifier. + Optional description of the custom tool, used to provide more context. - - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DONE("response.custom_tool_call_input.done")` + - `Optional format` - - `Optional agent` + The input format for the custom tool. Default is unconstrained text. - The agent that owns this multi-agent streaming event. + - `JsonValue;` - - `String agentName` + - `JsonValue; type "text"constant` - The canonical name of the agent that produced this item. + Unconstrained text format. Always `text`. -### Beta Response Custom Tool Call Item + - `TEXT("text")` -- `class BetaResponseCustomToolCallItem:` + - `class Grammar:` - A call to a custom tool created by the model. + A grammar defined by the user. - - `String id` + - `String definition` - The unique ID of the custom tool call item. + The grammar definition. - - `Status status` + - `Syntax syntax` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The syntax of the grammar definition. One of `lark` or `regex`. - - `IN_PROGRESS("in_progress")` + - `LARK("lark")` - - `COMPLETED("completed")` + - `REGEX("regex")` - - `INCOMPLETE("incomplete")` + - `JsonValue; type "grammar"constant` - - `Optional createdBy` + Grammar format. Always `grammar`. - The identifier of the actor that created the item. + - `GRAMMAR("grammar")` -### Beta Response Custom Tool Call Output + - `class BetaNamespaceTool:` -- `class BetaResponseCustomToolCallOutput:` + Groups function/custom tools under a shared namespace. - The output of a custom tool call from your code, being sent back to the model. + - `String description` - - `String callId` + A description of the namespace shown to the model. - The call ID, used to map this custom tool call output to a custom tool call. + - `String name` - - `Output output` + The namespace name used in tool calls (for example, `crm`). - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `List tools` - - `String` + The function/custom tools available inside this namespace. - - `List` + - `class Function:` - - `class BetaResponseInputText:` + - `String name` - A text input to the model. + - `JsonValue; type "function"constant` - - `String text` + - `FUNCTION("function")` - The text input to the model. + - `Optional> allowedCallers` - - `JsonValue; type "input_text"constant` + The tool invocation context(s). - The type of the input item. Always `input_text`. + - `DIRECT("direct")` - - `INPUT_TEXT("input_text")` + - `PROGRAMMATIC("programmatic")` - - `Optional promptCacheBreakpoint` + - `Optional deferLoading` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Whether this function should be deferred and discovered via tool search. - - `JsonValue; mode "explicit"constant` + - `Optional description` - The breakpoint mode. Always `explicit`. + - `Optional outputSchema` - - `EXPLICIT("explicit")` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class BetaResponseInputImage:` + - `Optional parameters` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Optional strict` - - `Detail detail` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `class BetaCustomTool:` - - `LOW("low")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `HIGH("high")` + - `JsonValue; type "namespace"constant` - - `AUTO("auto")` + The type of the tool. Always `namespace`. - - `ORIGINAL("original")` + - `NAMESPACE("namespace")` - - `JsonValue; type "input_image"constant` + - `class BetaToolSearchTool:` - The type of the input item. Always `input_image`. + Hosted or BYOT tool search configuration for deferred tools. - - `INPUT_IMAGE("input_image")` + - `JsonValue; type "tool_search"constant` - - `Optional fileId` + The type of the tool. Always `tool_search`. - The ID of the file to be sent to the model. + - `TOOL_SEARCH("tool_search")` - - `Optional imageUrl` + - `Optional description` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Description shown to the model for a client-executed tool search tool. - - `Optional promptCacheBreakpoint` + - `Optional execution` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Whether tool search is executed by the server or by the client. - - `JsonValue; mode "explicit"constant` + - `SERVER("server")` - The breakpoint mode. Always `explicit`. + - `CLIENT("client")` - - `EXPLICIT("explicit")` + - `Optional parameters` - - `class BetaResponseInputFile:` + Parameter schema for a client-executed tool search tool. - A file input to the model. + - `class BetaWebSearchPreviewTool:` - - `JsonValue; type "input_file"constant` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The type of the input item. Always `input_file`. + - `Type type` - - `INPUT_FILE("input_file")` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `Optional detail` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `AUTO("auto")` + - `Optional> searchContentTypes` - - `LOW("low")` + - `TEXT("text")` - - `HIGH("high")` + - `IMAGE("image")` - - `Optional fileData` + - `Optional searchContextSize` - The content of the file to be sent to the model. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Optional fileId` + - `LOW("low")` - The ID of the file to be sent to the model. + - `MEDIUM("medium")` - - `Optional fileUrl` + - `HIGH("high")` - The URL of the file to be sent to the model. + - `Optional userLocation` - - `Optional filename` + The user's location. - The name of the file to be sent to the model. + - `JsonValue; type "approximate"constant` - - `Optional promptCacheBreakpoint` + The type of location approximation. Always `approximate`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `APPROXIMATE("approximate")` - - `JsonValue; mode "explicit"constant` + - `Optional city` - The breakpoint mode. Always `explicit`. + Free text input for the city of the user, e.g. `San Francisco`. - - `EXPLICIT("explicit")` + - `Optional country` - - `JsonValue; type "custom_tool_call_output"constant` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `Optional region` - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + Free text input for the region of the user, e.g. `California`. - - `Optional id` + - `Optional timezone` - The unique ID of the custom tool call output in the OpenAI platform. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Optional agent` + - `class BetaApplyPatchTool:` - The agent that produced this item. + Allows the assistant to create, delete, or update files using unified diffs. - - `String agentName` + - `JsonValue; type "apply_patch"constant` - The canonical name of the agent that produced this item. + The type of the tool. Always `apply_patch`. - - `Optional caller` + - `APPLY_PATCH("apply_patch")` - The execution context that produced this tool call. + - `Optional> allowedCallers` - - `JsonValue;` + The tool invocation context(s). - - `JsonValue; type "direct"constant` + - `DIRECT("direct")` - The caller type. Always `direct`. + - `PROGRAMMATIC("programmatic")` - - `DIRECT("direct")` + - `JsonValue; type "tool_search_output"constant` - - `class Program:` + The item type. Always `tool_search_output`. - - `String callerId` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - The call ID of the program item that produced this tool call. + - `Optional id` - - `JsonValue; type "program"constant` + The unique ID of this tool search output. - The caller type. Always `program`. + - `Optional agent` - - `PROGRAM("program")` + The agent that produced this item. -### Beta Response Custom Tool Call Output Item + - `String agentName` -- `class BetaResponseCustomToolCallOutputItem:` + The canonical name of the agent that produced this item. - The output of a custom tool call from your code, being sent back to the model. + - `Optional callId` - - `String id` + The unique ID of the tool search call generated by the model. - The unique ID of the custom tool call output item. + - `Optional execution` - - `Status status` + Whether tool search was executed by the server or by the client. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `SERVER("server")` + + - `CLIENT("client")` + + - `Optional status` + + The status of the tool search output. - `IN_PROGRESS("in_progress")` @@ -70294,372 +83678,378 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `Optional createdBy` + - `AdditionalTools` - The identifier of the actor that created the item. + - `JsonValue; role "developer"constant` -### Beta Response Error + The role that provided the additional tools. Only `developer` is supported. -- `class BetaResponseError:` + - `DEVELOPER("developer")` - An error object returned when the model fails to generate a Response. + - `List tools` - - `Code code` + A list of additional tools made available at this item. - The error code for the response. + - `class BetaFunctionTool:` - - `SERVER_ERROR("server_error")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `class BetaFileSearchTool:` - - `INVALID_PROMPT("invalid_prompt")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `BIO_POLICY("bio_policy")` + - `class BetaComputerTool:` - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `INVALID_IMAGE("invalid_image")` + - `class BetaComputerUsePreviewTool:` - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `class BetaWebSearchTool:` - - `INVALID_IMAGE_URL("invalid_image_url")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `IMAGE_TOO_LARGE("image_too_large")` + - `Mcp` - - `IMAGE_TOO_SMALL("image_too_small")` + - `CodeInterpreter` - - `IMAGE_PARSE_ERROR("image_parse_error")` + - `JsonValue;` - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + - `ImageGeneration` - - `INVALID_IMAGE_MODE("invalid_image_mode")` + - `JsonValue;` - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + - `class BetaFunctionShellTool:` - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + A tool that allows the model to execute shell commands. - - `EMPTY_IMAGE_FILE("empty_image_file")` + - `class BetaCustomTool:` - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + - `class BetaNamespaceTool:` - - `String message` + Groups function/custom tools under a shared namespace. - A human-readable description of the error. + - `class BetaToolSearchTool:` -### Beta Response Error Event + Hosted or BYOT tool search configuration for deferred tools. -- `class BetaResponseErrorEvent:` + - `class BetaWebSearchPreviewTool:` - Emitted when an error occurs. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional code` + - `class BetaApplyPatchTool:` - The error code. + Allows the assistant to create, delete, or update files using unified diffs. - - `String message` + - `JsonValue; type "additional_tools"constant` - The error message. + The item type. Always `additional_tools`. - - `Optional param` + - `ADDITIONAL_TOOLS("additional_tools")` - The error parameter. + - `Optional id` - - `long sequenceNumber` + The unique ID of this additional tools item. - The sequence number of this event. + - `Optional agent` - - `JsonValue; type "error"constant` + The agent that produced this item. - The type of the event. Always `error`. + - `String agentName` - - `ERROR("error")` + The canonical name of the agent that produced this item. - - `Optional agent` + - `class BetaResponseReasoningItem:` - The agent that owns this multi-agent streaming event. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The unique identifier of the reasoning content. -### Beta Response Failed Event + - `List summary` -- `class BetaResponseFailedEvent:` + Reasoning summary content. - An event that is emitted when a response fails. + - `String text` - - `BetaResponse response` + A summary of the reasoning output from the model so far. - The response that failed. + - `JsonValue; type "summary_text"constant` - - `String id` + The type of the object. Always `summary_text`. - Unique identifier for this Response. + - `SUMMARY_TEXT("summary_text")` - - `double createdAt` + - `JsonValue; type "reasoning"constant` - Unix timestamp (in seconds) of when this Response was created. + The type of the object. Always `reasoning`. - - `Optional error` + - `REASONING("reasoning")` - An error object returned when the model fails to generate a Response. + - `Optional agent` - - `Code code` + The agent that produced this item. - The error code for the response. + - `String agentName` - - `SERVER_ERROR("server_error")` + The canonical name of the agent that produced this item. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `Optional> content` - - `INVALID_PROMPT("invalid_prompt")` + Reasoning text content. - - `BIO_POLICY("bio_policy")` + - `String text` - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + The reasoning text from the model. - - `INVALID_IMAGE("invalid_image")` + - `JsonValue; type "reasoning_text"constant` - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + The type of the reasoning text. Always `reasoning_text`. - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `REASONING_TEXT("reasoning_text")` - - `INVALID_IMAGE_URL("invalid_image_url")` + - `Optional encryptedContent` - - `IMAGE_TOO_LARGE("image_too_large")` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `IMAGE_TOO_SMALL("image_too_small")` + - `Optional status` - - `IMAGE_PARSE_ERROR("image_parse_error")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + - `IN_PROGRESS("in_progress")` - - `INVALID_IMAGE_MODE("invalid_image_mode")` + - `COMPLETED("completed")` - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + - `INCOMPLETE("incomplete")` - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + - `class BetaResponseCompactionItemParam:` - - `EMPTY_IMAGE_FILE("empty_image_file")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + - `String encryptedContent` - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + The encrypted content of the compaction summary. - - `String message` + - `JsonValue; type "compaction"constant` - A human-readable description of the error. + The type of the item. Always `compaction`. - - `Optional incompleteDetails` + - `COMPACTION("compaction")` - Details about why the response is incomplete. + - `Optional id` - - `Optional reason` + The ID of the compaction item. - The reason why the response is incomplete. + - `Optional agent` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + The agent that produced this item. - - `CONTENT_FILTER("content_filter")` + - `String agentName` - - `Optional instructions` + The canonical name of the agent that produced this item. - A system (or developer) message inserted into the model's context. + - `ImageGenerationCall` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `String id` - - `String` + The unique ID of the image generation call. - - `List` + - `Optional result` - - `class BetaEasyInputMessage:` + The generated image encoded in base64. - 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. + - `Status status` - - `Content content` + The status of the image generation call. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `IN_PROGRESS("in_progress")` - - `String` + - `COMPLETED("completed")` - - `List` + - `GENERATING("generating")` - - `class BetaResponseInputText:` + - `FAILED("failed")` - A text input to the model. + - `JsonValue; type "image_generation_call"constant` - - `String text` + The type of the image generation call. Always `image_generation_call`. - The text input to the model. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `JsonValue; type "input_text"constant` + - `Optional agent` - The type of the input item. Always `input_text`. + The agent that produced this item. - - `INPUT_TEXT("input_text")` + - `String agentName` - - `Optional promptCacheBreakpoint` + The canonical name of the agent that produced this item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaResponseCodeInterpreterToolCall:` - - `JsonValue; mode "explicit"constant` + A tool call to run code. - The breakpoint mode. Always `explicit`. + - `String id` - - `EXPLICIT("explicit")` + The unique ID of the code interpreter tool call. - - `class BetaResponseInputImage:` + - `Optional code` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The code to run, or null if not available. - - `Detail detail` + - `String containerId` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The ID of the container used to run the code. - - `LOW("low")` + - `Optional> outputs` - - `HIGH("high")` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `AUTO("auto")` + - `class Logs:` - - `ORIGINAL("original")` + The logs output from the code interpreter. - - `JsonValue; type "input_image"constant` + - `String logs` - The type of the input item. Always `input_image`. + The logs output from the code interpreter. - - `INPUT_IMAGE("input_image")` + - `JsonValue; type "logs"constant` - - `Optional fileId` + The type of the output. Always `logs`. - The ID of the file to be sent to the model. + - `LOGS("logs")` - - `Optional imageUrl` + - `class Image:` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The image output from the code interpreter. - - `Optional promptCacheBreakpoint` + - `JsonValue; type "image"constant` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the output. Always `image`. - - `JsonValue; mode "explicit"constant` + - `IMAGE("image")` - The breakpoint mode. Always `explicit`. + - `String url` - - `EXPLICIT("explicit")` + The URL of the image output from the code interpreter. - - `class BetaResponseInputFile:` + - `Status status` - A file input to the model. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `JsonValue; type "input_file"constant` + - `IN_PROGRESS("in_progress")` - The type of the input item. Always `input_file`. + - `COMPLETED("completed")` - - `INPUT_FILE("input_file")` + - `INCOMPLETE("incomplete")` - - `Optional detail` + - `INTERPRETING("interpreting")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `FAILED("failed")` - - `AUTO("auto")` + - `JsonValue; type "code_interpreter_call"constant` - - `LOW("low")` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `HIGH("high")` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `Optional fileData` + - `Optional agent` - The content of the file to be sent to the model. + The agent that produced this item. - - `Optional fileId` + - `String agentName` - The ID of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `Optional fileUrl` + - `LocalShellCall` - The URL of the file to be sent to the model. + - `String id` - - `Optional filename` + The unique ID of the local shell call. - The name of the file to be sent to the model. + - `Action action` - - `Optional promptCacheBreakpoint` + Execute a shell command on the server. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `List command` - - `JsonValue; mode "explicit"constant` + The command to run. - The breakpoint mode. Always `explicit`. + - `Env env` - - `EXPLICIT("explicit")` + Environment variables to set for the command. - - `Role role` + - `JsonValue; type "exec"constant` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The type of the local shell action. Always `exec`. + + - `EXEC("exec")` + + - `Optional timeoutMs` + + Optional timeout in milliseconds for the command. + + - `Optional user` - - `USER("user")` + Optional user to run the command as. - - `ASSISTANT("assistant")` + - `Optional workingDirectory` - - `SYSTEM("system")` + Optional working directory to run the command in. - - `DEVELOPER("developer")` + - `String callId` - - `Optional phase` + The unique ID of the local shell tool call generated by the model. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `Status status` - - `COMMENTARY("commentary")` + The status of the local shell call. - - `Optional type` + - `IN_PROGRESS("in_progress")` - The type of the message input. Always `message`. + - `COMPLETED("completed")` - - `MESSAGE("message")` + - `INCOMPLETE("incomplete")` - - `Message` + - `JsonValue; type "local_shell_call"constant` - - `List content` + The type of the local shell call. Always `local_shell_call`. - A list of one or many input items to the model, containing different content - types. + - `LOCAL_SHELL_CALL("local_shell_call")` - - `class BetaResponseInputText:` + - `Optional agent` - A text input to the model. + The agent that produced this item. - - `class BetaResponseInputImage:` + - `String agentName` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `class BetaResponseInputFile:` + - `LocalShellCallOutput` - A file input to the model. + - `String id` - - `Role role` + The unique ID of the local shell tool call generated by the model. - The role of the message input. One of `user`, `system`, or `developer`. + - `String output` - - `USER("user")` + A JSON string of the output of the local shell tool call. - - `SYSTEM("system")` + - `JsonValue; type "local_shell_call_output"constant` - - `DEVELOPER("developer")` + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - `Optional agent` @@ -70671,8 +84061,7 @@ public final class Main { - `Optional status` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` @@ -70680,178 +84069,181 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `Optional type` + - `ShellCall` - The type of the message input. Always set to `message`. + - `Action action` - - `MESSAGE("message")` + The shell commands and limits that describe how to run the tool call. - - `class BetaResponseOutputMessage:` + - `List commands` - An output message from the model. + Ordered shell commands for the execution environment to run. - - `String id` + - `Optional maxOutputLength` - The unique ID of the output message. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `List content` + - `Optional timeoutMs` - The content of the output message. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `class BetaResponseOutputText:` + - `String callId` - A text output from the model. + The unique ID of the shell tool call generated by the model. - - `List annotations` + - `JsonValue; type "shell_call"constant` - The annotations of the text output. + The type of the item. Always `shell_call`. - - `class FileCitation:` + - `SHELL_CALL("shell_call")` - A citation to a file. + - `Optional id` - - `String fileId` + The unique ID of the shell tool call. Populated when this item is returned via API. - The ID of the file. + - `Optional agent` - - `String filename` + The agent that produced this item. - The filename of the file cited. + - `String agentName` - - `long index` + The canonical name of the agent that produced this item. - The index of the file in the list of files. + - `Optional caller` - - `JsonValue; type "file_citation"constant` + The execution context that produced this tool call. - The type of the file citation. Always `file_citation`. + - `JsonValue;` - - `FILE_CITATION("file_citation")` + - `JsonValue; type "direct"constant` - - `class UrlCitation:` + The caller type. Always `direct`. - A citation for a web resource used to generate a model response. + - `DIRECT("direct")` - - `long endIndex` + - `class Program:` - The index of the last character of the URL citation in the message. + - `String callerId` - - `long startIndex` + The call ID of the program item that produced this tool call. - The index of the first character of the URL citation in the message. + - `JsonValue; type "program"constant` - - `String title` + The caller type. Always `program`. - The title of the web resource. + - `PROGRAM("program")` - - `JsonValue; type "url_citation"constant` + - `Optional environment` - The type of the URL citation. Always `url_citation`. + The environment to execute the shell commands in. - - `URL_CITATION("url_citation")` + - `class BetaLocalEnvironment:` - - `String url` + - `class BetaContainerReference:` - The URL of the web resource. + - `Optional status` - - `class ContainerFileCitation:` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - A citation for a container file used to generate a model response. + - `IN_PROGRESS("in_progress")` - - `String containerId` + - `COMPLETED("completed")` - The ID of the container file. + - `INCOMPLETE("incomplete")` - - `long endIndex` + - `ShellCallOutput` - The index of the last character of the container file citation in the message. + - `String callId` - - `String fileId` + The unique ID of the shell tool call generated by the model. - The ID of the file. + - `List output` - - `String filename` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The filename of the container file cited. + - `Outcome outcome` - - `long startIndex` + The exit or timeout outcome associated with this shell call. - The index of the first character of the container file citation in the message. + - `JsonValue;` - - `JsonValue; type "container_file_citation"constant` + - `JsonValue; type "timeout"constant` - The type of the container file citation. Always `container_file_citation`. + The outcome type. Always `timeout`. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `TIMEOUT("timeout")` - - `class FilePath:` + - `class Exit:` - A path to a file. + Indicates that the shell commands finished and returned an exit code. - - `String fileId` + - `long exitCode` - The ID of the file. + The exit code returned by the shell process. - - `long index` + - `JsonValue; type "exit"constant` - The index of the file in the list of files. + The outcome type. Always `exit`. - - `JsonValue; type "file_path"constant` + - `EXIT("exit")` - The type of the file path. Always `file_path`. + - `String stderr` - - `FILE_PATH("file_path")` + Captured stderr output for the shell call. - - `String text` + - `String stdout` - The text output from the model. + Captured stdout output for the shell call. - - `JsonValue; type "output_text"constant` + - `JsonValue; type "shell_call_output"constant` - The type of the output text. Always `output_text`. + The type of the item. Always `shell_call_output`. - - `OUTPUT_TEXT("output_text")` + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `Optional> logprobs` + - `Optional id` - - `String token` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `List bytes` + - `Optional agent` - - `double logprob` + The agent that produced this item. - - `List topLogprobs` + - `String agentName` - - `String token` + The canonical name of the agent that produced this item. - - `List bytes` + - `Optional caller` - - `double logprob` + The execution context that produced this tool call. - - `class BetaResponseOutputRefusal:` + - `JsonValue;` - A refusal from the model. + - `JsonValue; type "direct"constant` - - `String refusal` + The caller type. Always `direct`. - The refusal explanation from the model. + - `DIRECT("direct")` - - `JsonValue; type "refusal"constant` + - `class Program:` - The type of the refusal. Always `refusal`. + - `String callerId` - - `REFUSAL("refusal")` + The call ID of the program item that produced this tool call. - - `JsonValue; role "assistant"constant` + - `JsonValue; type "program"constant` - The role of the output message. Always `assistant`. + The caller type. Always `program`. - - `ASSISTANT("assistant")` + - `PROGRAM("program")` - - `Status status` + - `Optional maxOutputLength` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `Optional status` + + The status of the shell call output. - `IN_PROGRESS("in_progress")` @@ -70859,61 +84251,83 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `JsonValue; type "message"constant` + - `ApplyPatchCall` - The type of the output message. Always `message`. + - `String callId` - - `MESSAGE("message")` + The unique ID of the apply patch tool call generated by the model. - - `Optional agent` + - `Operation operation` - The agent that produced this item. + The specific create, delete, or update instruction for the apply_patch tool call. - - `String agentName` + - `class CreateFile:` - The canonical name of the agent that produced this item. + Instruction for creating a new file via the apply_patch tool. - - `Optional phase` + - `String diff` - 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. + Unified diff content to apply when creating the file. - - `COMMENTARY("commentary")` + - `String path` - - `class BetaResponseFileSearchToolCall:` + Path of the file to create relative to the workspace root. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `JsonValue; type "create_file"constant` - - `String id` + The operation type. Always `create_file`. - The unique ID of the file search tool call. + - `CREATE_FILE("create_file")` - - `List queries` + - `class DeleteFile:` - The queries used to search for files. + 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 file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The status of the apply patch tool call. One of `in_progress` or `completed`. - `IN_PROGRESS("in_progress")` - - `SEARCHING("searching")` - - `COMPLETED("completed")` - - `INCOMPLETE("incomplete")` + - `JsonValue; type "apply_patch_call"constant` - - `FAILED("failed")` + The type of the item. Always `apply_patch_call`. - - `JsonValue; type "file_search_call"constant` + - `APPLY_PATCH_CALL("apply_patch_call")` - The type of the file search tool call. Always `file_search_call`. + - `Optional id` - - `FILE_SEARCH_CALL("file_search_call")` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `Optional agent` @@ -70923,458 +84337,449 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional> results` + - `Optional caller` - The results of the file search tool call. + The execution context that produced this tool call. - - `Optional attributes` + - `JsonValue;` - Set of 16 key-value pairs that can be attached to an object. 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. + - `JsonValue; type "direct"constant` - - `String` + The caller type. Always `direct`. - - `double` + - `DIRECT("direct")` - - `boolean` + - `class Program:` - - `Optional fileId` + - `String callerId` - The unique ID of the file. + The call ID of the program item that produced this tool call. - - `Optional filename` + - `JsonValue; type "program"constant` - The name of the file. + The caller type. Always `program`. - - `Optional score` + - `PROGRAM("program")` - The relevance score of the file - a value between 0 and 1. + - `ApplyPatchCallOutput` - - `Optional text` + - `String callId` - The text that was retrieved from the file. + The unique ID of the apply patch tool call generated by the model. - - `class BetaResponseComputerToolCall:` + - `Status status` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `String id` + - `COMPLETED("completed")` - The unique ID of the computer call. + - `FAILED("failed")` - - `String callId` + - `JsonValue; type "apply_patch_call_output"constant` - An identifier used when responding to the tool call with output. + The type of the item. Always `apply_patch_call_output`. - - `List pendingSafetyChecks` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - The pending safety checks for the computer call. + - `Optional id` - - `String id` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The ID of the pending safety check. + - `Optional agent` - - `Optional code` + The agent that produced this item. - The type of the pending safety check. + - `String agentName` - - `Optional message` + The canonical name of the agent that produced this item. - Details about the pending safety check. + - `Optional caller` - - `Status status` + The execution context that produced this tool call. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `JsonValue;` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "direct"constant` - - `COMPLETED("completed")` + The caller type. Always `direct`. - - `INCOMPLETE("incomplete")` + - `DIRECT("direct")` - - `Type type` + - `class Program:` - The type of the computer call. Always `computer_call`. + - `String callerId` - - `COMPUTER_CALL("computer_call")` + The call ID of the program item that produced this tool call. - - `Optional action` + - `JsonValue; type "program"constant` - A click action. + The caller type. Always `program`. - - `Click` + - `PROGRAM("program")` - - `Button button` + - `Optional output` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `LEFT("left")` + - `McpListTools` - - `RIGHT("right")` + - `String id` - - `WHEEL("wheel")` + The unique ID of the list. - - `BACK("back")` + - `String serverLabel` - - `FORWARD("forward")` + The label of the MCP server. - - `JsonValue; type "click"constant` + - `List tools` - Specifies the event type. For a click action, this property is always `click`. + The tools available on the server. - - `CLICK("click")` + - `JsonValue inputSchema` - - `long x` + The JSON schema describing the tool's input. - The x-coordinate where the click occurred. + - `String name` - - `long y` + The name of the tool. - The y-coordinate where the click occurred. + - `Optional annotations` - - `Optional> keys` + Additional annotations about the tool. - The keys being held while clicking. + - `Optional description` - - `DoubleClick` + The description of the tool. - - `Optional> keys` + - `JsonValue; type "mcp_list_tools"constant` - The keys being held while double-clicking. + The type of the item. Always `mcp_list_tools`. - - `JsonValue; type "double_click"constant` + - `MCP_LIST_TOOLS("mcp_list_tools")` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `Optional agent` - - `DOUBLE_CLICK("double_click")` + The agent that produced this item. - - `long x` + - `String agentName` - The x-coordinate where the double click occurred. + The canonical name of the agent that produced this item. - - `long y` + - `Optional error` - The y-coordinate where the double click occurred. + Error message if the server could not list tools. - - `Drag` + - `McpApprovalRequest` - - `List path` + - `String id` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The unique ID of the approval request. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `String arguments` - - `long x` + A JSON string of arguments for the tool. - The x-coordinate. + - `String name` - - `long y` + The name of the tool to run. - The y-coordinate. + - `String serverLabel` - - `JsonValue; type "drag"constant` + The label of the MCP server making the request. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `JsonValue; type "mcp_approval_request"constant` - - `DRAG("drag")` + The type of the item. Always `mcp_approval_request`. - - `Optional> keys` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - The keys being held while dragging the mouse. + - `Optional agent` - - `Keypress` + The agent that produced this item. - - `List keys` + - `String agentName` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The canonical name of the agent that produced this item. - - `JsonValue; type "keypress"constant` + - `McpApprovalResponse` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `String approvalRequestId` - - `KEYPRESS("keypress")` + The ID of the approval request being answered. - - `Move` + - `boolean approve` - - `JsonValue; type "move"constant` + Whether the request was approved. - Specifies the event type. For a move action, this property is always set to `move`. + - `JsonValue; type "mcp_approval_response"constant` - - `MOVE("move")` + The type of the item. Always `mcp_approval_response`. - - `long x` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - The x-coordinate to move to. + - `Optional id` - - `long y` + The unique ID of the approval response - The y-coordinate to move to. + - `Optional agent` - - `Optional> keys` + The agent that produced this item. - The keys being held while moving the mouse. + - `String agentName` - - `JsonValue;` + The canonical name of the agent that produced this item. - - `JsonValue; type "screenshot"constant` + - `Optional reason` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Optional reason for the decision. - - `SCREENSHOT("screenshot")` + - `McpCall` - - `Scroll` + - `String id` - - `long scrollX` + The unique ID of the tool call. - The horizontal scroll distance. + - `String arguments` - - `long scrollY` + A JSON string of the arguments passed to the tool. - The vertical scroll distance. + - `String name` - - `JsonValue; type "scroll"constant` + The name of the tool that was run. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `String serverLabel` - - `SCROLL("scroll")` + The label of the MCP server running the tool. - - `long x` + - `JsonValue; type "mcp_call"constant` - The x-coordinate where the scroll occurred. + The type of the item. Always `mcp_call`. - - `long y` + - `MCP_CALL("mcp_call")` - The y-coordinate where the scroll occurred. + - `Optional agent` - - `Optional> keys` + The agent that produced this item. - The keys being held while scrolling. + - `String agentName` - - `Type` + The canonical name of the agent that produced this item. - - `String text` + - `Optional approvalRequestId` - The text to type. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `JsonValue; type "type"constant` + - `Optional error` - Specifies the event type. For a type action, this property is always set to `type`. + The error from the tool call, if any. - - `TYPE("type")` + - `Optional output` - - `JsonValue;` + The output from the tool call. - - `JsonValue; type "wait"constant` + - `Optional status` - Specifies the event type. For a wait action, this property is always set to `wait`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `WAIT("wait")` + - `IN_PROGRESS("in_progress")` - - `Optional> actions` + - `COMPLETED("completed")` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `INCOMPLETE("incomplete")` - - `Click` + - `CALLING("calling")` - - `DoubleClick` + - `FAILED("failed")` - - `Drag` + - `class BetaResponseCustomToolCallOutput:` - - `Keypress` + The output of a custom tool call from your code, being sent back to the model. - - `Move` + - `String callId` - - `JsonValue;` + The call ID, used to map this custom tool call output to a custom tool call. - - `Scroll` + - `Output output` - - `Type` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `JsonValue;` + - `String` - - `Optional agent` + - `List` - The agent that produced this item. + - `class BetaResponseInputText:` - - `String agentName` + A text input to the model. - The canonical name of the agent that produced this item. + - `class BetaResponseInputImage:` - - `ComputerCallOutput` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `String callId` + - `class BetaResponseInputFile:` - The ID of the computer tool call that produced the output. + A file input to the model. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `JsonValue; type "custom_tool_call_output"constant` - A computer screenshot image used with the computer use tool. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `JsonValue; type "computer_screenshot"constant` + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `Optional id` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + The unique ID of the custom tool call output in the OpenAI platform. - - `Optional fileId` + - `Optional agent` - The identifier of an uploaded file that contains the screenshot. + The agent that produced this item. - - `Optional imageUrl` + - `String agentName` - The URL of the screenshot image. + The canonical name of the agent that produced this item. - - `JsonValue; type "computer_call_output"constant` + - `Optional caller` - The type of the computer tool call output. Always `computer_call_output`. + The execution context that produced this tool call. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `JsonValue;` - - `Optional id` + - `JsonValue; type "direct"constant` - The ID of the computer tool call output. + The caller type. Always `direct`. - - `Optional> acknowledgedSafetyChecks` + - `DIRECT("direct")` - The safety checks reported by the API that have been acknowledged by the developer. + - `class Program:` - - `String id` + - `String callerId` - The ID of the pending safety check. + The call ID of the program item that produced this tool call. - - `Optional code` + - `JsonValue; type "program"constant` - The type of the pending safety check. + The caller type. Always `program`. - - `Optional message` + - `PROGRAM("program")` - Details about the pending safety check. + - `class BetaResponseCustomToolCall:` - - `Optional agent` + A call to a custom tool created by the model. - The agent that produced this item. + - `String callId` - - `String agentName` + An identifier used to map this custom tool call to a tool call output. - The canonical name of the agent that produced this item. + - `String input` - - `Optional status` + The input for the custom tool call generated by the model. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `String name` - - `IN_PROGRESS("in_progress")` + The name of the custom tool being called. - - `COMPLETED("completed")` + - `JsonValue; type "custom_tool_call"constant` - - `INCOMPLETE("incomplete")` + The type of the custom tool call. Always `custom_tool_call`. - - `class BetaResponseFunctionWebSearch:` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Optional id` - - `String id` + The unique ID of the custom tool call in the OpenAI platform. - The unique ID of the web search tool call. + - `Optional agent` - - `Action action` + The agent that produced this item. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `String agentName` - - `class Search:` + The canonical name of the agent that produced this item. - Action type "search" - Performs a web search query. + - `Optional caller` - - `JsonValue; type "search"constant` + The execution context that produced this tool call. - The action type. + - `JsonValue;` - - `SEARCH("search")` + - `JsonValue; type "direct"constant` - - `Optional> queries` + - `DIRECT("direct")` - The search queries. + - `class Program:` - - `Optional query` + - `String callerId` - The search query. + The call ID of the program item that produced this tool call. - - `Optional> sources` + - `JsonValue; type "program"constant` - The sources used in the search. + - `PROGRAM("program")` - - `JsonValue; type "url"constant` + - `Optional namespace` - The type of source. Always `url`. + The namespace of the custom tool being called. - - `URL("url")` + - `CompactionTrigger` - - `String url` + - `JsonValue; type "compaction_trigger"constant` - The URL of the source. + The type of the item. Always `compaction_trigger`. - - `class OpenPage:` + - `COMPACTION_TRIGGER("compaction_trigger")` - Action type "open_page" - Opens a specific URL from search results. + - `Optional agent` - - `JsonValue; type "open_page"constant` + The agent that produced this item. - The action type. + - `String agentName` - - `OPEN_PAGE("open_page")` + The canonical name of the agent that produced this item. - - `Optional url` + - `ItemReference` - The URL opened by the model. + - `String id` - - `class FindInPage:` + The ID of the item to reference. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `Optional agent` - - `String pattern` + The agent that produced this item. - The pattern or text to search for within the page. + - `String agentName` - - `JsonValue; type "find_in_page"constant` + The canonical name of the agent that produced this item. - The action type. + - `Optional type` - - `FIND_IN_PAGE("find_in_page")` + The type of item to reference. Always `item_reference`. - - `String url` + - `ITEM_REFERENCE("item_reference")` - The URL of the page searched for the pattern. + - `Program` - - `Status status` + - `String id` - The status of the web search tool call. + The unique ID of this program item. - - `IN_PROGRESS("in_progress")` + - `String callId` - - `SEARCHING("searching")` + The stable call ID of the program item. - - `COMPLETED("completed")` + - `String code` - - `FAILED("failed")` + The JavaScript source executed by programmatic tool calling. - - `JsonValue; type "web_search_call"constant` + - `String fingerprint` - The type of the web search tool call. Always `web_search_call`. + Opaque program replay fingerprint that must be round-tripped. - - `WEB_SEARCH_CALL("web_search_call")` + - `JsonValue; type "program"constant` + + The item type. Always `program`. + + - `PROGRAM("program")` - `Optional agent` @@ -71384,32 +84789,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall:` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `ProgramOutput` - - `String arguments` + - `String id` - A JSON string of the arguments to pass to the function. + The unique ID of this program output item. - `String callId` - The unique ID of the function tool call generated by the model. + The call ID of the program item. - - `String name` + - `String result` - The name of the function to run. + The result produced by the program item. - - `JsonValue; type "function_call"constant` + - `Status status` - The type of the function tool call. Always `function_call`. + The terminal status of the program output. - - `FUNCTION_CALL("function_call")` + - `COMPLETED("completed")` - - `Optional id` + - `INCOMPLETE("incomplete")` - The unique ID of the function tool call. + - `JsonValue; type "program_output"constant` + + The item type. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -71419,56 +84825,59 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` + - `String responseId` - The execution context that produced this tool call. + The ID of the response that rejected the input. - - `JsonValue;` + - `long sequenceNumber` - - `JsonValue; type "direct"constant` + The sequence number for this event. - - `DIRECT("direct")` + - `JsonValue; type "response.inject.failed"constant` - - `class Program:` + The event discriminator. Always `response.inject.failed`. - - `String callerId` + - `RESPONSE_INJECT_FAILED("response.inject.failed")` - The call ID of the program item that produced this tool call. + - `Optional streamId` - - `JsonValue; type "program"constant` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `PROGRAM("program")` +### Beta Response Input Audio - - `Optional namespace` +- `class BetaResponseInputAudio:` - The namespace of the function to run. + An audio input to the model. - - `Optional status` + - `InputAudio inputAudio` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `String data` - - `IN_PROGRESS("in_progress")` + Base64-encoded audio data. - - `COMPLETED("completed")` + - `Format format` - - `INCOMPLETE("incomplete")` + The format of the audio data. Currently supported formats are `mp3` and + `wav`. - - `FunctionCallOutput` + - `MP3("mp3")` - - `String callId` + - `WAV("wav")` - The unique ID of the function tool call generated by the model. + - `JsonValue; type "input_audio"constant` - - `Output output` + The type of the input item. Always `input_audio`. - Text, image, or file output of the function tool call. + - `INPUT_AUDIO("input_audio")` - - `String` +### Beta Response Input Content - - `List` +- `class BetaResponseInputContent: A class that can be one of several variants.union` - - `class BetaResponseInputTextContent:` + A text input to the model. + + - `class BetaResponseInputText:` A text input to the model. @@ -71492,17 +84901,11 @@ public final class Main { - `EXPLICIT("explicit")` - - `class BetaResponseInputImageContent:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. + - `class BetaResponseInputImage:` - - `INPUT_IMAGE("input_image")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional detail` + - `Detail detail` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. @@ -71514,6 +84917,12 @@ public final class Main { - `ORIGINAL("original")` + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + - `Optional fileId` The ID of the file to be sent to the model. @@ -71532,7 +84941,7 @@ public final class Main { - `EXPLICIT("explicit")` - - `class BetaResponseInputFileContent:` + - `class BetaResponseInputFile:` A file input to the model. @@ -71554,7 +84963,7 @@ public final class Main { - `Optional fileData` - The base64-encoded data of the file to be sent to the model. + The content of the file to be sent to the model. - `Optional fileId` @@ -71578,1406 +84987,1397 @@ public final class Main { - `EXPLICIT("explicit")` - - `JsonValue; type "function_call_output"constant` +### Beta Response Input File - The type of the function tool call output. Always `function_call_output`. +- `class BetaResponseInputFile:` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + A file input to the model. - - `Optional id` + - `JsonValue; type "input_file"constant` - The unique ID of the function tool call output. Populated when this item is returned via API. + The type of the input item. Always `input_file`. - - `Optional agent` + - `INPUT_FILE("input_file")` - The agent that produced this item. + - `Optional detail` - - `String agentName` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The canonical name of the agent that produced this item. + - `AUTO("auto")` - - `Optional caller` + - `LOW("low")` - The execution context that produced this tool call. + - `HIGH("high")` - - `JsonValue;` + - `Optional fileData` - - `JsonValue; type "direct"constant` + The content of the file to be sent to the model. - The caller type. Always `direct`. + - `Optional fileId` - - `DIRECT("direct")` + The ID of the file to be sent to the model. - - `class Program:` + - `Optional fileUrl` - - `String callerId` + The URL of the file to be sent to the model. - The call ID of the program item that produced this tool call. + - `Optional filename` - - `JsonValue; type "program"constant` + The name of the file to be sent to the model. - The caller type. Always `program`. + - `Optional promptCacheBreakpoint` - - `PROGRAM("program")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional status` + - `JsonValue; mode "explicit"constant` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The breakpoint mode. Always `explicit`. - - `IN_PROGRESS("in_progress")` + - `EXPLICIT("explicit")` - - `COMPLETED("completed")` +### Beta Response Input File Content - - `INCOMPLETE("incomplete")` +- `class BetaResponseInputFileContent:` - - `AgentMessage` + A file input to the model. - - `String author` + - `JsonValue; type "input_file"constant` - The sending agent identity. + The type of the input item. Always `input_file`. - - `List content` + - `INPUT_FILE("input_file")` - Plaintext, image, or encrypted content sent between agents. + - `Optional detail` - - `class BetaResponseInputTextContent:` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - A text input to the model. + - `AUTO("auto")` - - `class BetaResponseInputImageContent:` + - `LOW("low")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `HIGH("high")` - - `class EncryptedContent:` + - `Optional fileData` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The base64-encoded data of the file to be sent to the model. - - `String encryptedContent` + - `Optional fileId` - Opaque encrypted content. + The ID of the file to be sent to the model. - - `JsonValue; type "encrypted_content"constant` + - `Optional fileUrl` - The type of the input item. Always `encrypted_content`. + The URL of the file to be sent to the model. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `Optional filename` - - `String recipient` + The name of the file to be sent to the model. - The destination agent identity. + - `Optional promptCacheBreakpoint` - - `JsonValue; type "agent_message"constant` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The item type. Always `agent_message`. + - `JsonValue; mode "explicit"constant` - - `AGENT_MESSAGE("agent_message")` + The breakpoint mode. Always `explicit`. - - `Optional id` + - `EXPLICIT("explicit")` - The unique ID of this agent message item. +### Beta Response Input Image - - `Optional agent` +- `class BetaResponseInputImage:` - The agent that produced this item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `String agentName` + - `Detail detail` - The canonical name of the agent that produced this item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `MultiAgentCall` + - `LOW("low")` - - `Action action` + - `HIGH("high")` - The multi-agent action that was executed. + - `AUTO("auto")` - - `SPAWN_AGENT("spawn_agent")` + - `ORIGINAL("original")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `JsonValue; type "input_image"constant` - - `LIST_AGENTS("list_agents")` + The type of the input item. Always `input_image`. - - `SEND_MESSAGE("send_message")` + - `INPUT_IMAGE("input_image")` - - `FOLLOWUP_TASK("followup_task")` + - `Optional fileId` - - `WAIT_AGENT("wait_agent")` + The ID of the file to be sent to the model. - - `String arguments` + - `Optional imageUrl` - The action arguments as a JSON string. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `String callId` + - `Optional promptCacheBreakpoint` - The unique ID linking this call to its output. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "multi_agent_call"constant` + - `JsonValue; mode "explicit"constant` - The item type. Always `multi_agent_call`. + The breakpoint mode. Always `explicit`. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `EXPLICIT("explicit")` - - `Optional id` +### Beta Response Input Image Content + +- `class BetaResponseInputImageContent:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. - The unique ID of this multi-agent call. + - `INPUT_IMAGE("input_image")` - - `Optional agent` + - `Optional detail` - The agent that produced this item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String agentName` + - `LOW("low")` - The canonical name of the agent that produced this item. + - `HIGH("high")` - - `MultiAgentCallOutput` + - `AUTO("auto")` - - `Action action` + - `ORIGINAL("original")` - The multi-agent action that produced this result. + - `Optional fileId` - - `SPAWN_AGENT("spawn_agent")` + The ID of the file to be sent to the model. - - `INTERRUPT_AGENT("interrupt_agent")` + - `Optional imageUrl` - - `LIST_AGENTS("list_agents")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `SEND_MESSAGE("send_message")` + - `Optional promptCacheBreakpoint` - - `FOLLOWUP_TASK("followup_task")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `WAIT_AGENT("wait_agent")` + - `JsonValue; mode "explicit"constant` - - `String callId` + The breakpoint mode. Always `explicit`. - The unique ID of the multi-agent call. + - `EXPLICIT("explicit")` - - `List output` +### Beta Response Input Item - Text output returned by the multi-agent action. +- `class BetaResponseInputItem: A class that can be one of several variants.union` - - `String text` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - The text content. + - `class BetaEasyInputMessage:` - - `JsonValue; type "output_text"constant` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - The content type. Always `output_text`. + - `Content content` - - `OUTPUT_TEXT("output_text")` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `Optional annotations` + - `String` - Citations associated with the text content. + - `List` - - `List` + - `class BetaResponseInputText:` - - `String fileId` + A text input to the model. - The ID of the file. + - `String text` - - `String filename` + The text input to the model. - The filename of the file cited. + - `JsonValue; type "input_text"constant` - - `long index` + The type of the input item. Always `input_text`. - The index of the file in the list of files. + - `INPUT_TEXT("input_text")` - - `JsonValue; type "file_citation"constant` + - `Optional promptCacheBreakpoint` - The citation type. Always `file_citation`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `FILE_CITATION("file_citation")` + - `JsonValue; mode "explicit"constant` - - `List` + The breakpoint mode. Always `explicit`. - - `long endIndex` + - `EXPLICIT("explicit")` - The index of the last character of the citation in the message. + - `class BetaResponseInputImage:` - - `long startIndex` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The index of the first character of the citation in the message. + - `Detail detail` - - `String title` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The title of the cited resource. + - `LOW("low")` - - `JsonValue; type "url_citation"constant` + - `HIGH("high")` - The citation type. Always `url_citation`. + - `AUTO("auto")` - - `URL_CITATION("url_citation")` + - `ORIGINAL("original")` - - `String url` + - `JsonValue; type "input_image"constant` - The URL of the cited resource. + The type of the input item. Always `input_image`. - - `List` + - `INPUT_IMAGE("input_image")` - - `String containerId` + - `Optional fileId` - The ID of the container. + The ID of the file to be sent to the model. - - `long endIndex` + - `Optional imageUrl` - The index of the last character of the citation in the message. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `String fileId` + - `Optional promptCacheBreakpoint` - The ID of the container file. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String filename` + - `JsonValue; mode "explicit"constant` - The filename of the container file cited. + The breakpoint mode. Always `explicit`. - - `long startIndex` + - `EXPLICIT("explicit")` - The index of the first character of the citation in the message. + - `class BetaResponseInputFile:` - - `JsonValue; type "container_file_citation"constant` + A file input to the model. - The citation type. Always `container_file_citation`. + - `JsonValue; type "input_file"constant` - - `CONTAINER_FILE_CITATION("container_file_citation")` + The type of the input item. Always `input_file`. - - `JsonValue; type "multi_agent_call_output"constant` + - `INPUT_FILE("input_file")` - The item type. Always `multi_agent_call_output`. + - `Optional detail` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `Optional id` + - `AUTO("auto")` - The unique ID of this multi-agent call output. + - `LOW("low")` - - `Optional agent` + - `HIGH("high")` - The agent that produced this item. + - `Optional fileData` - - `String agentName` + The content of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `Optional fileId` - - `ToolSearchCall` + The ID of the file to be sent to the model. - - `JsonValue arguments` + - `Optional fileUrl` - The arguments supplied to the tool search call. + The URL of the file to be sent to the model. - - `JsonValue; type "tool_search_call"constant` + - `Optional filename` - The item type. Always `tool_search_call`. + The name of the file to be sent to the model. - - `TOOL_SEARCH_CALL("tool_search_call")` + - `Optional promptCacheBreakpoint` - - `Optional id` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The unique ID of this tool search call. + - `JsonValue; mode "explicit"constant` - - `Optional agent` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `EXPLICIT("explicit")` - - `String agentName` + - `Role role` - The canonical name of the agent that produced this item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `Optional callId` + - `USER("user")` - The unique ID of the tool search call generated by the model. + - `ASSISTANT("assistant")` - - `Optional execution` + - `SYSTEM("system")` - Whether tool search was executed by the server or by the client. + - `DEVELOPER("developer")` - - `SERVER("server")` + - `Optional phase` - - `CLIENT("client")` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `Optional status` + - `COMMENTARY("commentary")` - The status of the tool search call. + - `FINAL_ANSWER("final_answer")` - - `IN_PROGRESS("in_progress")` + - `Optional type` - - `COMPLETED("completed")` + The type of the message input. Always `message`. - - `INCOMPLETE("incomplete")` + - `MESSAGE("message")` - - `class BetaResponseToolSearchOutputItemParam:` + - `Message` - - `List tools` + - `List content` - The loaded tool definitions returned by the tool search output. + A list of one or many input items to the model, containing different content + types. - - `class BetaFunctionTool:` + - `class BetaResponseInputText:` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + A text input to the model. - - `String name` + - `class BetaResponseInputImage:` - The name of the function to call. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional parameters` + - `class BetaResponseInputFile:` - A JSON schema object describing the parameters of the function. + A file input to the model. - - `Optional strict` + - `Role role` - Whether strict parameter validation is enforced for this function tool. + The role of the message input. One of `user`, `system`, or `developer`. - - `JsonValue; type "function"constant` + - `USER("user")` - The type of the function tool. Always `function`. + - `SYSTEM("system")` - - `FUNCTION("function")` + - `DEVELOPER("developer")` - - `Optional> allowedCallers` + - `Optional agent` - The tool invocation context(s). + The agent that produced this item. - - `DIRECT("direct")` + - `String agentName` - - `PROGRAMMATIC("programmatic")` + The canonical name of the agent that produced this item. - - `Optional deferLoading` + - `Optional status` - Whether this function is deferred and loaded via tool search. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional description` + - `IN_PROGRESS("in_progress")` - A description of the function. Used by the model to determine whether or not to call the function. + - `COMPLETED("completed")` - - `Optional outputSchema` + - `INCOMPLETE("incomplete")` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `Optional type` - - `class BetaFileSearchTool:` + The type of the message input. Always set to `message`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `MESSAGE("message")` - - `JsonValue; type "file_search"constant` + - `class BetaResponseOutputMessage:` - The type of the file search tool. Always `file_search`. + An output message from the model. - - `FILE_SEARCH("file_search")` + - `String id` - - `List vectorStoreIds` + The unique ID of the output message. - The IDs of the vector stores to search. + - `List content` - - `Optional filters` + The content of the output message. - A filter to apply. + - `class BetaResponseOutputText:` - - `class ComparisonFilter:` + A text output from the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `List annotations` - - `String key` + The annotations of the text output. - The key to compare against the value. + - `class FileCitation:` - - `Type type` + A citation to a file. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `String fileId` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The ID of the file. - - `EQ("eq")` + - `String filename` - - `NE("ne")` + The filename of the file cited. - - `GT("gt")` + - `long index` - - `GTE("gte")` + The index of the file in the list of files. - - `LT("lt")` + - `JsonValue; type "file_citation"constant` - - `LTE("lte")` + The type of the file citation. Always `file_citation`. - - `IN("in")` + - `FILE_CITATION("file_citation")` - - `NIN("nin")` + - `class UrlCitation:` - - `Value value` + A citation for a web resource used to generate a model response. - The value to compare against the attribute key; supports string, number, or boolean types. + - `long endIndex` - - `String` + The index of the last character of the URL citation in the message. - - `double` + - `long startIndex` - - `boolean` + The index of the first character of the URL citation in the message. - - `List` + - `String title` - - `class CompoundFilter:` + The title of the web resource. - Combine multiple filters using `and` or `or`. + - `JsonValue; type "url_citation"constant` - - `List filters` + The type of the URL citation. Always `url_citation`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `URL_CITATION("url_citation")` - - `class ComparisonFilter:` + - `String url` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The URL of the web resource. - - `String key` + - `class ContainerFileCitation:` - The key to compare against the value. + A citation for a container file used to generate a model response. - - `Type type` + - `String containerId` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The ID of the container file. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `long endIndex` - - `EQ("eq")` + The index of the last character of the container file citation in the message. - - `NE("ne")` + - `String fileId` - - `GT("gt")` + The ID of the file. - - `GTE("gte")` + - `String filename` - - `LT("lt")` + The filename of the container file cited. - - `LTE("lte")` + - `long startIndex` - - `IN("in")` + The index of the first character of the container file citation in the message. - - `NIN("nin")` + - `JsonValue; type "container_file_citation"constant` - - `Value value` + The type of the container file citation. Always `container_file_citation`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `String` + - `class FilePath:` - - `double` + A path to a file. - - `boolean` + - `String fileId` - - `List` + The ID of the file. - - `JsonValue` + - `long index` - - `Type type` + The index of the file in the list of files. - Type of operation: `and` or `or`. + - `JsonValue; type "file_path"constant` - - `AND("and")` + The type of the file path. Always `file_path`. - - `OR("or")` + - `FILE_PATH("file_path")` - - `Optional maxNumResults` + - `String text` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The text output from the model. - - `Optional rankingOptions` + - `JsonValue; type "output_text"constant` - Ranking options for search. + The type of the output text. Always `output_text`. - - `Optional hybridSearch` + - `OUTPUT_TEXT("output_text")` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `Optional> logprobs` - - `double embeddingWeight` + - `String token` - The weight of the embedding in the reciprocal ranking fusion. + - `List bytes` - - `double textWeight` + - `double logprob` - The weight of the text in the reciprocal ranking fusion. + - `List topLogprobs` - - `Optional ranker` + - `String token` - The ranker to use for the file search. + - `List bytes` - - `AUTO("auto")` + - `double logprob` - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `class BetaResponseOutputRefusal:` - - `Optional scoreThreshold` + A refusal from the model. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `String refusal` - - `class BetaComputerTool:` + The refusal explanation from the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JsonValue; type "refusal"constant` - - `JsonValue; type "computer"constant` + The type of the refusal. Always `refusal`. - The type of the computer tool. Always `computer`. + - `REFUSAL("refusal")` - - `COMPUTER("computer")` + - `JsonValue; role "assistant"constant` - - `class BetaComputerUsePreviewTool:` + The role of the output message. Always `assistant`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `ASSISTANT("assistant")` - - `long displayHeight` + - `Status status` - The height of the computer display. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `long displayWidth` + - `IN_PROGRESS("in_progress")` - The width of the computer display. + - `COMPLETED("completed")` - - `Environment environment` + - `INCOMPLETE("incomplete")` - The type of computer environment to control. + - `JsonValue; type "message"constant` - - `WINDOWS("windows")` + The type of the output message. Always `message`. - - `MAC("mac")` + - `MESSAGE("message")` - - `LINUX("linux")` + - `Optional agent` - - `UBUNTU("ubuntu")` + The agent that produced this item. - - `BROWSER("browser")` + - `String agentName` - - `JsonValue; type "computer_use_preview"constant` + The canonical name of the agent that produced this item. - The type of the computer use tool. Always `computer_use_preview`. + - `Optional phase` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `class BetaWebSearchTool:` + - `COMMENTARY("commentary")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `FINAL_ANSWER("final_answer")` - - `Type type` + - `class BetaResponseFileSearchToolCall:` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `WEB_SEARCH("web_search")` + - `String id` - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + The unique ID of the file search tool call. - - `Optional filters` + - `List queries` - Filters for the search. + The queries used to search for files. - - `Optional> allowedDomains` + - `Status status` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `IN_PROGRESS("in_progress")` - - `Optional searchContextSize` + - `SEARCHING("searching")` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `COMPLETED("completed")` - - `LOW("low")` + - `INCOMPLETE("incomplete")` - - `MEDIUM("medium")` + - `FAILED("failed")` - - `HIGH("high")` + - `JsonValue; type "file_search_call"constant` - - `Optional userLocation` + The type of the file search tool call. Always `file_search_call`. - The approximate location of the user. + - `FILE_SEARCH_CALL("file_search_call")` - - `Optional city` + - `Optional agent` - Free text input for the city of the user, e.g. `San Francisco`. + The agent that produced this item. - - `Optional country` + - `String agentName` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The canonical name of the agent that produced this item. - - `Optional region` + - `Optional> results` - Free text input for the region of the user, e.g. `California`. + The results of the file search tool call. - - `Optional timezone` + - `Optional attributes` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `Optional type` + - `String` - The type of location approximation. Always `approximate`. + - `double` - - `APPROXIMATE("approximate")` + - `boolean` - - `Mcp` + - `Optional fileId` - - `String serverLabel` + The unique ID of the file. - A label for this MCP server, used to identify it in tool calls. + - `Optional filename` - - `JsonValue; type "mcp"constant` + The name of the file. - The type of the MCP tool. Always `mcp`. + - `Optional score` - - `MCP("mcp")` + The relevance score of the file - a value between 0 and 1. - - `Optional> allowedCallers` + - `Optional text` - The tool invocation context(s). + The text that was retrieved from the file. - - `DIRECT("direct")` + - `class BetaResponseComputerToolCall:` - - `PROGRAMMATIC("programmatic")` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `Optional allowedTools` + - `String id` - List of allowed tool names or a filter object. + The unique ID of the computer call. - - `List` + - `String callId` - - `class McpToolFilter:` + An identifier used when responding to the tool call with output. - A filter object to specify which tools are allowed. + - `List pendingSafetyChecks` - - `Optional readOnly` + The pending safety checks for the computer call. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `String id` - - `Optional> toolNames` + The ID of the pending safety check. - List of allowed tool names. + - `Optional code` - - `Optional authorization` + The type of the pending safety check. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `Optional message` - - `Optional connectorId` + Details about the pending safety check. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `Status status` - Currently supported `connector_id` values are: + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `IN_PROGRESS("in_progress")` - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `COMPLETED("completed")` - - `CONNECTOR_GMAIL("connector_gmail")` + - `INCOMPLETE("incomplete")` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `Type type` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + The type of the computer call. Always `computer_call`. - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `COMPUTER_CALL("computer_call")` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `Optional action` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + A click action. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `Click` - - `Optional deferLoading` + - `Button button` - Whether this MCP tool is deferred and discovered via tool search. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Optional headers` + - `LEFT("left")` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `RIGHT("right")` - - `Optional requireApproval` + - `WHEEL("wheel")` - Specify which of the MCP server's tools require approval. + - `BACK("back")` - - `class McpToolApprovalFilter:` + - `FORWARD("forward")` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `JsonValue; type "click"constant` - - `Optional always` + Specifies the event type. For a click action, this property is always `click`. - A filter object to specify which tools are allowed. + - `CLICK("click")` - - `Optional readOnly` + - `long x` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The x-coordinate where the click occurred. - - `Optional> toolNames` + - `long y` - List of allowed tool names. + The y-coordinate where the click occurred. - - `Optional never` + - `Optional> keys` - A filter object to specify which tools are allowed. + The keys being held while clicking. - - `Optional readOnly` + - `DoubleClick` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Optional> keys` - - `Optional> toolNames` + The keys being held while double-clicking. - List of allowed tool names. + - `JsonValue; type "double_click"constant` - - `enum McpToolApprovalSetting:` + Specifies the event type. For a double click action, this property is always set to `double_click`. - 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. + - `DOUBLE_CLICK("double_click")` - - `ALWAYS("always")` + - `long x` - - `NEVER("never")` + The x-coordinate where the double click occurred. - - `Optional serverDescription` + - `long y` - Optional description of the MCP server, used to provide more context. + The y-coordinate where the double click occurred. - - `Optional serverUrl` + - `Drag` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `List path` - - `Optional tunnelId` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `CodeInterpreter` + - `long x` - - `Container container` + The x-coordinate. - 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. + - `long y` - - `String` + The y-coordinate. - - `class CodeInterpreterToolAuto:` + - `JsonValue; type "drag"constant` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `JsonValue; type "auto"constant` + - `DRAG("drag")` - Always `auto`. + - `Optional> keys` - - `AUTO("auto")` + The keys being held while dragging the mouse. - - `Optional> fileIds` + - `Keypress` - An optional list of uploaded files to make available to your code. + - `List keys` - - `Optional memoryLimit` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The memory limit for the code interpreter container. + - `JsonValue; type "keypress"constant` - - `_1G("1g")` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `_4G("4g")` + - `KEYPRESS("keypress")` - - `_16G("16g")` + - `Move` - - `_64G("64g")` + - `JsonValue; type "move"constant` - - `Optional networkPolicy` + Specifies the event type. For a move action, this property is always set to `move`. - Network access policy for the container. + - `MOVE("move")` - - `class BetaContainerNetworkPolicyDisabled:` + - `long x` - - `JsonValue; type "disabled"constant` + The x-coordinate to move to. - Disable outbound network access. Always `disabled`. + - `long y` - - `DISABLED("disabled")` + The y-coordinate to move to. - - `class BetaContainerNetworkPolicyAllowlist:` + - `Optional> keys` - - `List allowedDomains` + The keys being held while moving the mouse. - A list of allowed domains when type is `allowlist`. + - `JsonValue;` - - `JsonValue; type "allowlist"constant` + - `JsonValue; type "screenshot"constant` - Allow outbound network access only to specified domains. Always `allowlist`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `ALLOWLIST("allowlist")` + - `SCREENSHOT("screenshot")` - - `Optional> domainSecrets` + - `Scroll` - Optional domain-scoped secrets for allowlisted domains. + - `long scrollX` - - `String domain` + The horizontal scroll distance. - The domain associated with the secret. + - `long scrollY` - - `String name` + The vertical scroll distance. - The name of the secret to inject for the domain. + - `JsonValue; type "scroll"constant` - - `String value` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The secret value to inject for the domain. + - `SCROLL("scroll")` - - `JsonValue; type "code_interpreter"constant` + - `long x` - The type of the code interpreter tool. Always `code_interpreter`. + The x-coordinate where the scroll occurred. - - `CODE_INTERPRETER("code_interpreter")` + - `long y` - - `Optional> allowedCallers` + The y-coordinate where the scroll occurred. - The tool invocation context(s). + - `Optional> keys` - - `DIRECT("direct")` + The keys being held while scrolling. - - `PROGRAMMATIC("programmatic")` + - `Type` - - `JsonValue;` + - `String text` - - `JsonValue; type "programmatic_tool_calling"constant` + The text to type. - The type of the tool. Always `programmatic_tool_calling`. + - `JsonValue; type "type"constant` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + Specifies the event type. For a type action, this property is always set to `type`. - - `ImageGeneration` + - `TYPE("type")` - - `JsonValue; type "image_generation"constant` + - `JsonValue;` - The type of the image generation tool. Always `image_generation`. + - `JsonValue; type "wait"constant` - - `IMAGE_GENERATION("image_generation")` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `Optional action` + - `WAIT("wait")` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `Optional> actions` - - `GENERATE("generate")` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `EDIT("edit")` + - `Click` - - `AUTO("auto")` + - `DoubleClick` - - `Optional background` + - `Drag` - 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. + - `Keypress` - `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. + - `Move` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `JsonValue;` - - `TRANSPARENT("transparent")` + - `Scroll` - - `OPAQUE("opaque")` + - `Type` - - `AUTO("auto")` + - `JsonValue;` - - `Optional inputFidelity` + - `Optional agent` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The agent that produced this item. - - `HIGH("high")` + - `String agentName` - - `LOW("low")` + The canonical name of the agent that produced this item. - - `Optional inputImageMask` + - `ComputerCallOutput` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `String callId` - - `Optional fileId` + The ID of the computer tool call that produced the output. - File ID for the mask image. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `Optional imageUrl` + A computer screenshot image used with the computer use tool. - Base64-encoded mask image. + - `JsonValue; type "computer_screenshot"constant` - - `Optional model` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The image generation model to use. Default: `gpt-image-1`. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `GPT_IMAGE_1("gpt-image-1")` + - `Optional fileId` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + The identifier of an uploaded file that contains the screenshot. - - `GPT_IMAGE_2("gpt-image-2")` + - `Optional imageUrl` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The URL of the screenshot image. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `JsonValue; type "computer_call_output"constant` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + The type of the computer tool call output. Always `computer_call_output`. - - `Optional moderation` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - Moderation level for the generated image. Default: `auto`. + - `Optional id` - - `AUTO("auto")` + The ID of the computer tool call output. - - `LOW("low")` + - `Optional> acknowledgedSafetyChecks` - - `Optional outputCompression` + The safety checks reported by the API that have been acknowledged by the developer. - Compression level for the output image. Default: 100. + - `String id` - - `Optional outputFormat` + The ID of the pending safety check. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `Optional code` - - `PNG("png")` + The type of the pending safety check. - - `WEBP("webp")` + - `Optional message` - - `JPEG("jpeg")` + Details about the pending safety check. - - `Optional partialImages` + - `Optional agent` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The agent that produced this item. - - `Optional quality` + - `String agentName` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The canonical name of the agent that produced this item. - - `LOW("low")` + - `Optional status` - - `MEDIUM("medium")` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `HIGH("high")` + - `IN_PROGRESS("in_progress")` - - `AUTO("auto")` + - `COMPLETED("completed")` - - `Optional size` + - `INCOMPLETE("incomplete")` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `class BetaResponseFunctionWebSearch:` - - `_1024X1024("1024x1024")` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `_1024X1536("1024x1536")` + - `String id` - - `_1536X1024("1536x1024")` + The unique ID of the web search tool call. - - `AUTO("auto")` + - `Action action` - - `JsonValue;` + 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). - - `JsonValue; type "local_shell"constant` + - `class Search:` - The type of the local shell tool. Always `local_shell`. + Action type "search" - Performs a web search query. - - `LOCAL_SHELL("local_shell")` + - `JsonValue; type "search"constant` - - `class BetaFunctionShellTool:` + The action type. - A tool that allows the model to execute shell commands. + - `SEARCH("search")` - - `JsonValue; type "shell"constant` + - `Optional> queries` - The type of the shell tool. Always `shell`. + The search queries. - - `SHELL("shell")` + - `Optional query` - - `Optional> allowedCallers` + The search query. - The tool invocation context(s). + - `Optional> sources` - - `DIRECT("direct")` + The sources used in the search. - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "url"constant` - - `Optional environment` + The type of source. Always `url`. - - `class BetaContainerAuto:` + - `URL("url")` - - `JsonValue; type "container_auto"constant` + - `String url` - Automatically creates a container for this request + The URL of the source. - - `CONTAINER_AUTO("container_auto")` + - `class OpenPage:` - - `Optional> fileIds` + Action type "open_page" - Opens a specific URL from search results. - An optional list of uploaded files to make available to your code. + - `JsonValue; type "open_page"constant` - - `Optional memoryLimit` + The action type. - The memory limit for the container. + - `OPEN_PAGE("open_page")` - - `_1G("1g")` + - `Optional url` - - `_4G("4g")` + The URL opened by the model. - - `_16G("16g")` + - `class FindInPage:` - - `_64G("64g")` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `Optional networkPolicy` + - `String pattern` - Network access policy for the container. + The pattern or text to search for within the page. - - `class BetaContainerNetworkPolicyDisabled:` + - `JsonValue; type "find_in_page"constant` - - `class BetaContainerNetworkPolicyAllowlist:` + The action type. - - `Optional> skills` + - `FIND_IN_PAGE("find_in_page")` - An optional list of skills referenced by id or inline data. + - `String url` - - `class BetaSkillReference:` + The URL of the page searched for the pattern. - - `String skillId` + - `Status status` - The ID of the referenced skill. + The status of the web search tool call. - - `JsonValue; type "skill_reference"constant` + - `IN_PROGRESS("in_progress")` - References a skill created with the /v1/skills endpoint. + - `SEARCHING("searching")` - - `SKILL_REFERENCE("skill_reference")` + - `COMPLETED("completed")` - - `Optional version` + - `FAILED("failed")` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `JsonValue; type "web_search_call"constant` - - `class BetaInlineSkill:` + The type of the web search tool call. Always `web_search_call`. - - `String description` + - `WEB_SEARCH_CALL("web_search_call")` - The description of the skill. + - `Optional agent` - - `String name` + The agent that produced this item. - The name of the skill. + - `String agentName` - - `BetaInlineSkillSource source` + The canonical name of the agent that produced this item. - Inline skill payload + - `class BetaResponseFunctionToolCall:` - - `String data` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Base64-encoded skill zip bundle. + - `String arguments` - - `JsonValue; mediaType "application/zip"constant` + A JSON string of the arguments to pass to the function. - The media type of the inline skill payload. Must be `application/zip`. + - `String callId` - - `APPLICATION_ZIP("application/zip")` + The unique ID of the function tool call generated by the model. - - `JsonValue; type "base64"constant` + - `String name` - The type of the inline skill source. Must be `base64`. + The name of the function to run. - - `BASE64("base64")` + - `JsonValue; type "function_call"constant` - - `JsonValue; type "inline"constant` + The type of the function tool call. Always `function_call`. - Defines an inline skill for this request. + - `FUNCTION_CALL("function_call")` - - `INLINE("inline")` + - `Optional id` - - `class BetaLocalEnvironment:` + The unique ID of the function tool call. - - `JsonValue; type "local"constant` + - `Optional agent` - Use a local computer environment. + The agent that produced this item. - - `LOCAL("local")` + - `String agentName` - - `Optional> skills` + The canonical name of the agent that produced this item. - An optional list of skills. + - `Optional caller` - - `String description` + The execution context that produced this tool call. - The description of the skill. + - `JsonValue;` - - `String name` + - `JsonValue; type "direct"constant` - The name of the skill. + - `DIRECT("direct")` - - `String path` + - `class Program:` - The path to the directory containing the skill. + - `String callerId` - - `class BetaContainerReference:` + The call ID of the program item that produced this tool call. - - `String containerId` + - `JsonValue; type "program"constant` - The ID of the referenced container. + - `PROGRAM("program")` - - `JsonValue; type "container_reference"constant` + - `Optional namespace` - References a container created with the /v1/containers endpoint + The namespace of the function to run. - - `CONTAINER_REFERENCE("container_reference")` + - `Optional status` - - `class BetaCustomTool:` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `IN_PROGRESS("in_progress")` - - `String name` + - `COMPLETED("completed")` - The name of the custom tool, used to identify it in tool calls. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "custom"constant` + - `FunctionCallOutput` - The type of the custom tool. Always `custom`. + - `String callId` - - `CUSTOM("custom")` + The unique ID of the function tool call generated by the model. - - `Optional> allowedCallers` + - `Output output` - The tool invocation context(s). + Text, image, or file output of the function tool call. - - `DIRECT("direct")` + - `String` - - `PROGRAMMATIC("programmatic")` + - `List` - - `Optional deferLoading` + - `class BetaResponseInputTextContent:` - Whether this tool should be deferred and discovered via tool search. + A text input to the model. - - `Optional description` + - `String text` - Optional description of the custom tool, used to provide more context. + The text input to the model. - - `Optional format` + - `JsonValue; type "input_text"constant` - The input format for the custom tool. Default is unconstrained text. + The type of the input item. Always `input_text`. - - `JsonValue;` + - `INPUT_TEXT("input_text")` - - `JsonValue; type "text"constant` + - `Optional promptCacheBreakpoint` - Unconstrained text format. Always `text`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `TEXT("text")` + - `JsonValue; mode "explicit"constant` - - `class Grammar:` + The breakpoint mode. Always `explicit`. - A grammar defined by the user. + - `EXPLICIT("explicit")` - - `String definition` + - `class BetaResponseInputImageContent:` - The grammar definition. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `Syntax syntax` + - `JsonValue; type "input_image"constant` - The syntax of the grammar definition. One of `lark` or `regex`. + The type of the input item. Always `input_image`. - - `LARK("lark")` + - `INPUT_IMAGE("input_image")` - - `REGEX("regex")` + - `Optional detail` - - `JsonValue; type "grammar"constant` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Grammar format. Always `grammar`. + - `LOW("low")` - - `GRAMMAR("grammar")` + - `HIGH("high")` - - `class BetaNamespaceTool:` + - `AUTO("auto")` - Groups function/custom tools under a shared namespace. + - `ORIGINAL("original")` - - `String description` + - `Optional fileId` - A description of the namespace shown to the model. + The ID of the file to be sent to the model. - - `String name` + - `Optional imageUrl` - The namespace name used in tool calls (for example, `crm`). + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `List tools` + - `Optional promptCacheBreakpoint` - The function/custom tools available inside this namespace. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class Function:` + - `JsonValue; mode "explicit"constant` - - `String name` + The breakpoint mode. Always `explicit`. - - `JsonValue; type "function"constant` + - `EXPLICIT("explicit")` - - `FUNCTION("function")` + - `class BetaResponseInputFileContent:` - - `Optional> allowedCallers` + A file input to the model. - The tool invocation context(s). + - `JsonValue; type "input_file"constant` - - `DIRECT("direct")` + The type of the input item. Always `input_file`. - - `PROGRAMMATIC("programmatic")` + - `INPUT_FILE("input_file")` - - `Optional deferLoading` + - `Optional detail` - Whether this function should be deferred and discovered via tool search. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `Optional description` + - `AUTO("auto")` - - `Optional outputSchema` + - `LOW("low")` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `HIGH("high")` - - `Optional parameters` + - `Optional fileData` - - `Optional strict` + The base64-encoded data of the file to be sent to the model. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `Optional fileId` - - `class BetaCustomTool:` + The ID of the file to be sent to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Optional fileUrl` - - `JsonValue; type "namespace"constant` + The URL of the file to be sent to the model. - The type of the tool. Always `namespace`. + - `Optional filename` - - `NAMESPACE("namespace")` + The name of the file to be sent to the model. - - `class BetaToolSearchTool:` + - `Optional promptCacheBreakpoint` - Hosted or BYOT tool search configuration for deferred tools. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "tool_search"constant` + - `JsonValue; mode "explicit"constant` - The type of the tool. Always `tool_search`. + The breakpoint mode. Always `explicit`. - - `TOOL_SEARCH("tool_search")` + - `EXPLICIT("explicit")` - - `Optional description` + - `JsonValue; type "function_call_output"constant` - Description shown to the model for a client-executed tool search tool. + The type of the function tool call output. Always `function_call_output`. - - `Optional execution` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - Whether tool search is executed by the server or by the client. + - `Optional id` - - `SERVER("server")` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `CLIENT("client")` + - `Optional agent` - - `Optional parameters` + The agent that produced this item. - Parameter schema for a client-executed tool search tool. + - `String agentName` - - `class BetaWebSearchPreviewTool:` + The canonical name of the agent that produced this item. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional caller` - - `Type type` + The execution context that produced this tool call. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `JsonValue;` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `JsonValue; type "direct"constant` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The caller type. Always `direct`. - - `Optional> searchContentTypes` + - `DIRECT("direct")` - - `TEXT("text")` + - `class Program:` - - `IMAGE("image")` + - `String callerId` - - `Optional searchContextSize` + The call ID of the program item that produced this tool call. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `JsonValue; type "program"constant` - - `LOW("low")` + The caller type. Always `program`. - - `MEDIUM("medium")` + - `PROGRAM("program")` - - `HIGH("high")` + - `Optional status` - - `Optional userLocation` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The user's location. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "approximate"constant` + - `COMPLETED("completed")` - The type of location approximation. Always `approximate`. + - `INCOMPLETE("incomplete")` - - `APPROXIMATE("approximate")` + - `AgentMessage` - - `Optional city` + - `String author` - Free text input for the city of the user, e.g. `San Francisco`. + The sending agent identity. - - `Optional country` + - `List content` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Plaintext, image, or encrypted content sent between agents. - - `Optional region` + - `class BetaResponseInputTextContent:` - Free text input for the region of the user, e.g. `California`. + A text input to the model. - - `Optional timezone` + - `class BetaResponseInputImageContent:` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class BetaApplyPatchTool:` + - `class EncryptedContent:` - Allows the assistant to create, delete, or update files using unified diffs. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `JsonValue; type "apply_patch"constant` + - `String encryptedContent` - The type of the tool. Always `apply_patch`. + Opaque encrypted content. - - `APPLY_PATCH("apply_patch")` + - `JsonValue; type "encrypted_content"constant` - - `Optional> allowedCallers` + The type of the input item. Always `encrypted_content`. - The tool invocation context(s). + - `ENCRYPTED_CONTENT("encrypted_content")` - - `DIRECT("direct")` + - `String recipient` - - `PROGRAMMATIC("programmatic")` + The destination agent identity. - - `JsonValue; type "tool_search_output"constant` + - `JsonValue; type "agent_message"constant` - The item type. Always `tool_search_output`. + The item type. Always `agent_message`. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `AGENT_MESSAGE("agent_message")` - `Optional id` - The unique ID of this tool search output. + The unique ID of this agent message item. - `Optional agent` @@ -72987,199 +86387,195 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional callId` + - `MultiAgentCall` - The unique ID of the tool search call generated by the model. + - `Action action` - - `Optional execution` + The multi-agent action that was executed. - Whether tool search was executed by the server or by the client. + - `SPAWN_AGENT("spawn_agent")` - - `SERVER("server")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `CLIENT("client")` + - `LIST_AGENTS("list_agents")` - - `Optional status` + - `SEND_MESSAGE("send_message")` - The status of the tool search output. + - `FOLLOWUP_TASK("followup_task")` - - `IN_PROGRESS("in_progress")` + - `WAIT_AGENT("wait_agent")` - - `COMPLETED("completed")` + - `String arguments` - - `INCOMPLETE("incomplete")` + The action arguments as a JSON string. - - `AdditionalTools` + - `String callId` - - `JsonValue; role "developer"constant` + The unique ID linking this call to its output. - The role that provided the additional tools. Only `developer` is supported. + - `JsonValue; type "multi_agent_call"constant` - - `DEVELOPER("developer")` + The item type. Always `multi_agent_call`. - - `List tools` + - `MULTI_AGENT_CALL("multi_agent_call")` - A list of additional tools made available at this item. + - `Optional id` - - `class BetaFunctionTool:` + The unique ID of this multi-agent call. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Optional agent` - - `class BetaFileSearchTool:` + The agent that produced this item. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `String agentName` - - `class BetaComputerTool:` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `MultiAgentCallOutput` - - `class BetaComputerUsePreviewTool:` + - `Action action` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The multi-agent action that produced this result. - - `class BetaWebSearchTool:` + - `SPAWN_AGENT("spawn_agent")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `INTERRUPT_AGENT("interrupt_agent")` - - `Mcp` + - `LIST_AGENTS("list_agents")` - - `CodeInterpreter` + - `SEND_MESSAGE("send_message")` - - `JsonValue;` + - `FOLLOWUP_TASK("followup_task")` - - `ImageGeneration` + - `WAIT_AGENT("wait_agent")` - - `JsonValue;` + - `String callId` - - `class BetaFunctionShellTool:` + The unique ID of the multi-agent call. - A tool that allows the model to execute shell commands. + - `List output` - - `class BetaCustomTool:` + Text output returned by the multi-agent action. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `String text` - - `class BetaNamespaceTool:` + The text content. - Groups function/custom tools under a shared namespace. + - `JsonValue; type "output_text"constant` - - `class BetaToolSearchTool:` + The content type. Always `output_text`. - Hosted or BYOT tool search configuration for deferred tools. + - `OUTPUT_TEXT("output_text")` - - `class BetaWebSearchPreviewTool:` + - `Optional annotations` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Citations associated with the text content. - - `class BetaApplyPatchTool:` + - `List` - Allows the assistant to create, delete, or update files using unified diffs. + - `String fileId` - - `JsonValue; type "additional_tools"constant` + The ID of the file. - The item type. Always `additional_tools`. + - `String filename` - - `ADDITIONAL_TOOLS("additional_tools")` + The filename of the file cited. - - `Optional id` + - `long index` - The unique ID of this additional tools item. + The index of the file in the list of files. - - `Optional agent` + - `JsonValue; type "file_citation"constant` - The agent that produced this item. + The citation type. Always `file_citation`. - - `String agentName` + - `FILE_CITATION("file_citation")` - The canonical name of the agent that produced this item. + - `List` - - `class BetaResponseReasoningItem:` + - `long endIndex` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The index of the last character of the citation in the message. - - `String id` + - `long startIndex` - The unique identifier of the reasoning content. + The index of the first character of the citation in the message. - - `List summary` + - `String title` - Reasoning summary content. + The title of the cited resource. - - `String text` + - `JsonValue; type "url_citation"constant` - A summary of the reasoning output from the model so far. + The citation type. Always `url_citation`. - - `JsonValue; type "summary_text"constant` + - `URL_CITATION("url_citation")` - The type of the object. Always `summary_text`. + - `String url` - - `SUMMARY_TEXT("summary_text")` + The URL of the cited resource. - - `JsonValue; type "reasoning"constant` + - `List` - The type of the object. Always `reasoning`. + - `String containerId` - - `REASONING("reasoning")` + The ID of the container. - - `Optional agent` + - `long endIndex` - The agent that produced this item. + The index of the last character of the citation in the message. - - `String agentName` + - `String fileId` - The canonical name of the agent that produced this item. + The ID of the container file. - - `Optional> content` + - `String filename` - Reasoning text content. + The filename of the container file cited. - - `String text` + - `long startIndex` - The reasoning text from the model. + The index of the first character of the citation in the message. - - `JsonValue; type "reasoning_text"constant` + - `JsonValue; type "container_file_citation"constant` - The type of the reasoning text. Always `reasoning_text`. + The citation type. Always `container_file_citation`. - - `REASONING_TEXT("reasoning_text")` + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `Optional encryptedContent` + - `JsonValue; type "multi_agent_call_output"constant` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The item type. Always `multi_agent_call_output`. - - `Optional status` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional id` - - `IN_PROGRESS("in_progress")` + The unique ID of this multi-agent call output. - - `COMPLETED("completed")` + - `Optional agent` - - `INCOMPLETE("incomplete")` + The agent that produced this item. - - `class BetaResponseCompactionItemParam:` + - `String agentName` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The canonical name of the agent that produced this item. - - `String encryptedContent` + - `ToolSearchCall` - The encrypted content of the compaction summary. + - `JsonValue arguments` - - `JsonValue; type "compaction"constant` + The arguments supplied to the tool search call. - The type of the item. Always `compaction`. + - `JsonValue; type "tool_search_call"constant` - - `COMPACTION("compaction")` + The item type. Always `tool_search_call`. + + - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional id` - The ID of the compaction item. + The unique ID of this tool search call. - `Optional agent` @@ -73189,1242 +86585,1285 @@ public final class Main { The canonical name of the agent that produced this item. - - `ImageGenerationCall` + - `Optional callId` - - `String id` + The unique ID of the tool search call generated by the model. - The unique ID of the image generation call. + - `Optional execution` - - `Optional result` + Whether tool search was executed by the server or by the client. - The generated image encoded in base64. + - `SERVER("server")` - - `Status status` + - `CLIENT("client")` - The status of the image generation call. + - `Optional status` + + The status of the tool search 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`. + - `INCOMPLETE("incomplete")` - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `class BetaResponseToolSearchOutputItemParam:` - - `Optional agent` + - `List tools` - The agent that produced this item. + The loaded tool definitions returned by the tool search output. - - `String agentName` + - `class BetaFunctionTool:` - The canonical name of the agent that produced this item. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class BetaResponseCodeInterpreterToolCall:` + - `String name` - A tool call to run code. + The name of the function to call. - - `String id` + - `Optional parameters` - The unique ID of the code interpreter tool call. + A JSON schema object describing the parameters of the function. - - `Optional code` + - `Optional strict` - The code to run, or null if not available. + Whether strict parameter validation is enforced for this function tool. - - `String containerId` + - `JsonValue; type "function"constant` - The ID of the container used to run the code. + The type of the function tool. Always `function`. - - `Optional> outputs` + - `FUNCTION("function")` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `Optional> allowedCallers` - - `class Logs:` + The tool invocation context(s). - The logs output from the code interpreter. + - `DIRECT("direct")` - - `String logs` + - `PROGRAMMATIC("programmatic")` - The logs output from the code interpreter. + - `Optional deferLoading` - - `JsonValue; type "logs"constant` + Whether this function is deferred and loaded via tool search. - The type of the output. Always `logs`. + - `Optional description` - - `LOGS("logs")` + A description of the function. Used by the model to determine whether or not to call the function. - - `class Image:` + - `Optional outputSchema` - The image output from the code interpreter. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `JsonValue; type "image"constant` + - `class BetaFileSearchTool:` - The type of the output. Always `image`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `IMAGE("image")` + - `JsonValue; type "file_search"constant` - - `String url` + The type of the file search tool. Always `file_search`. - The URL of the image output from the code interpreter. + - `FILE_SEARCH("file_search")` - - `Status status` + - `List vectorStoreIds` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The IDs of the vector stores to search. - - `IN_PROGRESS("in_progress")` + - `Optional filters` - - `COMPLETED("completed")` + A filter to apply. - - `INCOMPLETE("incomplete")` + - `class ComparisonFilter:` - - `INTERPRETING("interpreting")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `FAILED("failed")` + - `String key` - - `JsonValue; type "code_interpreter_call"constant` + The key to compare against the value. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `Type type` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `Optional agent` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The agent that produced this item. + - `EQ("eq")` - - `String agentName` + - `NE("ne")` - The canonical name of the agent that produced this item. + - `GT("gt")` - - `LocalShellCall` + - `GTE("gte")` - - `String id` + - `LT("lt")` - The unique ID of the local shell call. + - `LTE("lte")` - - `Action action` + - `IN("in")` - Execute a shell command on the server. + - `NIN("nin")` - - `List command` + - `Value value` - The command to run. + The value to compare against the attribute key; supports string, number, or boolean types. - - `Env env` + - `String` - Environment variables to set for the command. + - `double` - - `JsonValue; type "exec"constant` + - `boolean` - The type of the local shell action. Always `exec`. + - `List` - - `EXEC("exec")` + - `String` - - `Optional timeoutMs` + - `double` - Optional timeout in milliseconds for the command. + - `class CompoundFilter:` - - `Optional user` + Combine multiple filters using `and` or `or`. - Optional user to run the command as. + - `List filters` - - `Optional workingDirectory` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Optional working directory to run the command in. + - `class ComparisonFilter:` - - `String callId` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique ID of the local shell tool call generated by the model. + - `String key` - - `Status status` + The key to compare against the value. - The status of the local shell call. + - `Type type` - - `IN_PROGRESS("in_progress")` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `COMPLETED("completed")` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `INCOMPLETE("incomplete")` + - `EQ("eq")` - - `JsonValue; type "local_shell_call"constant` + - `NE("ne")` - The type of the local shell call. Always `local_shell_call`. + - `GT("gt")` - - `LOCAL_SHELL_CALL("local_shell_call")` + - `GTE("gte")` - - `Optional agent` + - `LT("lt")` - The agent that produced this item. + - `LTE("lte")` - - `String agentName` + - `IN("in")` - The canonical name of the agent that produced this item. + - `NIN("nin")` - - `LocalShellCallOutput` + - `Value value` - - `String id` + The value to compare against the attribute key; supports string, number, or boolean types. - The unique ID of the local shell tool call generated by the model. + - `String` - - `String output` + - `double` - A JSON string of the output of the local shell tool call. + - `boolean` - - `JsonValue; type "local_shell_call_output"constant` + - `List` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `String` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `double` - - `Optional agent` + - `JsonValue` - The agent that produced this item. + - `Type type` - - `String agentName` + Type of operation: `and` or `or`. - The canonical name of the agent that produced this item. + - `AND("and")` - - `Optional status` + - `OR("or")` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `Optional maxNumResults` - - `IN_PROGRESS("in_progress")` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `COMPLETED("completed")` + - `Optional rankingOptions` - - `INCOMPLETE("incomplete")` + Ranking options for search. - - `ShellCall` + - `Optional hybridSearch` - - `Action action` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The shell commands and limits that describe how to run the tool call. + - `double embeddingWeight` - - `List commands` + The weight of the embedding in the reciprocal ranking fusion. - Ordered shell commands for the execution environment to run. + - `double textWeight` - - `Optional maxOutputLength` + The weight of the text in the reciprocal ranking fusion. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `Optional ranker` - - `Optional timeoutMs` + The ranker to use for the file search. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `AUTO("auto")` - - `String callId` + - `DEFAULT_2024_11_15("default-2024-11-15")` - The unique ID of the shell tool call generated by the model. + - `Optional scoreThreshold` - - `JsonValue; type "shell_call"constant` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The type of the item. Always `shell_call`. + - `class BetaComputerTool:` - - `SHELL_CALL("shell_call")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional id` + - `JsonValue; type "computer"constant` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of the computer tool. Always `computer`. - - `Optional agent` + - `COMPUTER("computer")` - The agent that produced this item. + - `class BetaComputerUsePreviewTool:` - - `String agentName` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The canonical name of the agent that produced this item. + - `long displayHeight` - - `Optional caller` + The height of the computer display. - The execution context that produced this tool call. + - `long displayWidth` - - `JsonValue;` + The width of the computer display. - - `JsonValue; type "direct"constant` + - `Environment environment` - The caller type. Always `direct`. + The type of computer environment to control. - - `DIRECT("direct")` + - `WINDOWS("windows")` - - `class Program:` + - `MAC("mac")` - - `String callerId` + - `LINUX("linux")` - The call ID of the program item that produced this tool call. + - `UBUNTU("ubuntu")` - - `JsonValue; type "program"constant` + - `BROWSER("browser")` - The caller type. Always `program`. + - `JsonValue; type "computer_use_preview"constant` - - `PROGRAM("program")` + The type of the computer use tool. Always `computer_use_preview`. - - `Optional environment` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - The environment to execute the shell commands in. + - `class BetaWebSearchTool:` - - `class BetaLocalEnvironment:` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class BetaContainerReference:` + - `Type type` - - `Optional status` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `WEB_SEARCH("web_search")` - - `IN_PROGRESS("in_progress")` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `COMPLETED("completed")` + - `Optional filters` - - `INCOMPLETE("incomplete")` + Filters for the search. - - `ShellCallOutput` + - `Optional> allowedDomains` - - `String callId` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The unique ID of the shell tool call generated by the model. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `List output` + - `Optional searchContextSize` - Captured chunks of stdout and stderr output, along with their associated outcomes. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Outcome outcome` + - `LOW("low")` - The exit or timeout outcome associated with this shell call. + - `MEDIUM("medium")` - - `JsonValue;` + - `HIGH("high")` - - `JsonValue; type "timeout"constant` + - `Optional userLocation` - The outcome type. Always `timeout`. + The approximate location of the user. - - `TIMEOUT("timeout")` + - `Optional city` - - `class Exit:` + Free text input for the city of the user, e.g. `San Francisco`. - Indicates that the shell commands finished and returned an exit code. + - `Optional country` - - `long exitCode` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The exit code returned by the shell process. + - `Optional region` - - `JsonValue; type "exit"constant` + Free text input for the region of the user, e.g. `California`. - The outcome type. Always `exit`. + - `Optional timezone` - - `EXIT("exit")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `String stderr` + - `Optional type` - Captured stderr output for the shell call. + The type of location approximation. Always `approximate`. - - `String stdout` + - `APPROXIMATE("approximate")` - Captured stdout output for the shell call. + - `Mcp` - - `JsonValue; type "shell_call_output"constant` + - `String serverLabel` - The type of the item. Always `shell_call_output`. + A label for this MCP server, used to identify it in tool calls. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `JsonValue; type "mcp"constant` - - `Optional id` + The type of the MCP tool. Always `mcp`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `MCP("mcp")` - - `Optional agent` + - `Optional> allowedCallers` - The agent that produced this item. + The tool invocation context(s). - - `String agentName` + - `DIRECT("direct")` - The canonical name of the agent that produced this item. + - `PROGRAMMATIC("programmatic")` - - `Optional caller` + - `Optional allowedTools` - The execution context that produced this tool call. + List of allowed tool names or a filter object. - - `JsonValue;` + - `List` - - `JsonValue; type "direct"constant` + - `class McpToolFilter:` - The caller type. Always `direct`. + A filter object to specify which tools are allowed. - - `DIRECT("direct")` + - `Optional readOnly` - - `class Program:` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `String callerId` + - `Optional> toolNames` - The call ID of the program item that produced this tool call. + List of allowed tool names. - - `JsonValue; type "program"constant` + - `Optional authorization` - The caller type. Always `program`. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `PROGRAM("program")` + - `Optional connectorId` - - `Optional maxOutputLength` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The maximum number of UTF-8 characters captured for this shell call's combined output. + Currently supported `connector_id` values are: - - `Optional status` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The status of the shell call output. + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `IN_PROGRESS("in_progress")` + - `CONNECTOR_GMAIL("connector_gmail")` - - `COMPLETED("completed")` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `INCOMPLETE("incomplete")` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `ApplyPatchCall` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `String callId` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - The unique ID of the apply patch tool call generated by the model. + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `Operation operation` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - The specific create, delete, or update instruction for the apply_patch tool call. + - `Optional deferLoading` - - `class CreateFile:` + Whether this MCP tool is deferred and discovered via tool search. - Instruction for creating a new file via the apply_patch tool. + - `Optional headers` - - `String diff` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Unified diff content to apply when creating the file. + - `Optional requireApproval` - - `String path` + Specify which of the MCP server's tools require approval. - Path of the file to create relative to the workspace root. + - `class McpToolApprovalFilter:` - - `JsonValue; type "create_file"constant` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The operation type. Always `create_file`. + - `Optional always` - - `CREATE_FILE("create_file")` + A filter object to specify which tools are allowed. - - `class DeleteFile:` + - `Optional readOnly` - Instruction for deleting an existing file via the apply_patch tool. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `String path` + - `Optional> toolNames` - Path of the file to delete relative to the workspace root. + List of allowed tool names. - - `JsonValue; type "delete_file"constant` + - `Optional never` - The operation type. Always `delete_file`. + A filter object to specify which tools are allowed. - - `DELETE_FILE("delete_file")` + - `Optional readOnly` - - `class UpdateFile:` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Instruction for updating an existing file via the apply_patch tool. + - `Optional> toolNames` - - `String diff` + List of allowed tool names. - Unified diff content to apply to the existing file. + - `enum McpToolApprovalSetting:` - - `String path` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - Path of the file to update relative to the workspace root. + - `ALWAYS("always")` - - `JsonValue; type "update_file"constant` + - `NEVER("never")` - The operation type. Always `update_file`. + - `Optional serverDescription` - - `UPDATE_FILE("update_file")` + Optional description of the MCP server, used to provide more context. - - `Status status` + - `Optional serverUrl` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `IN_PROGRESS("in_progress")` + - `Optional tunnelId` - - `COMPLETED("completed")` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `JsonValue; type "apply_patch_call"constant` + - `CodeInterpreter` - The type of the item. Always `apply_patch_call`. + - `Container container` - - `APPLY_PATCH_CALL("apply_patch_call")` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `Optional id` + - `String` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `class CodeInterpreterToolAuto:` - - `Optional agent` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The agent that produced this item. + - `JsonValue; type "auto"constant` - - `String agentName` + Always `auto`. - The canonical name of the agent that produced this item. + - `AUTO("auto")` - - `Optional caller` + - `Optional> fileIds` - The execution context that produced this tool call. + An optional list of uploaded files to make available to your code. - - `JsonValue;` + - `Optional memoryLimit` - - `JsonValue; type "direct"constant` + The memory limit for the code interpreter container. - The caller type. Always `direct`. + - `_1G("1g")` - - `DIRECT("direct")` + - `_4G("4g")` - - `class Program:` + - `_16G("16g")` - - `String callerId` + - `_64G("64g")` - The call ID of the program item that produced this tool call. + - `Optional networkPolicy` - - `JsonValue; type "program"constant` + Network access policy for the container. - The caller type. Always `program`. + - `class BetaContainerNetworkPolicyDisabled:` - - `PROGRAM("program")` + - `JsonValue; type "disabled"constant` - - `ApplyPatchCallOutput` + Disable outbound network access. Always `disabled`. - - `String callId` + - `DISABLED("disabled")` - The unique ID of the apply patch tool call generated by the model. + - `class BetaContainerNetworkPolicyAllowlist:` - - `Status status` + - `List allowedDomains` - The status of the apply patch tool call output. One of `completed` or `failed`. + A list of allowed domains when type is `allowlist`. - - `COMPLETED("completed")` + - `JsonValue; type "allowlist"constant` - - `FAILED("failed")` + Allow outbound network access only to specified domains. Always `allowlist`. - - `JsonValue; type "apply_patch_call_output"constant` + - `ALLOWLIST("allowlist")` - The type of the item. Always `apply_patch_call_output`. + - `Optional> domainSecrets` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + Optional domain-scoped secrets for allowlisted domains. - - `Optional id` + - `String domain` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The domain associated with the secret. - - `Optional agent` + - `String name` - The agent that produced this item. + The name of the secret to inject for the domain. - - `String agentName` + - `String value` - The canonical name of the agent that produced this item. + The secret value to inject for the domain. - - `Optional caller` + - `JsonValue; type "code_interpreter"constant` - The execution context that produced this tool call. + The type of the code interpreter tool. Always `code_interpreter`. - - `JsonValue;` + - `CODE_INTERPRETER("code_interpreter")` - - `JsonValue; type "direct"constant` + - `Optional> allowedCallers` - The caller type. Always `direct`. + The tool invocation context(s). - `DIRECT("direct")` - - `class Program:` + - `PROGRAMMATIC("programmatic")` - - `String callerId` + - `JsonValue;` - The call ID of the program item that produced this tool call. + - `JsonValue; type "programmatic_tool_calling"constant` - - `JsonValue; type "program"constant` + The type of the tool. Always `programmatic_tool_calling`. - The caller type. Always `program`. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `PROGRAM("program")` + - `ImageGeneration` - - `Optional output` + - `JsonValue; type "image_generation"constant` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The type of the image generation tool. Always `image_generation`. - - `McpListTools` + - `IMAGE_GENERATION("image_generation")` - - `String id` + - `Optional action` - The unique ID of the list. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `String serverLabel` + - `GENERATE("generate")` - The label of the MCP server. + - `EDIT("edit")` - - `List tools` + - `AUTO("auto")` - The tools available on the server. + - `Optional background` - - `JsonValue inputSchema` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - The JSON schema describing the tool's input. + `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. - - `String name` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The name of the tool. + - `TRANSPARENT("transparent")` - - `Optional annotations` + - `OPAQUE("opaque")` - Additional annotations about the tool. + - `AUTO("auto")` - - `Optional description` + - `Optional inputFidelity` - The description of the tool. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `JsonValue; type "mcp_list_tools"constant` + - `HIGH("high")` - The type of the item. Always `mcp_list_tools`. + - `LOW("low")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `Optional inputImageMask` - - `Optional agent` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The agent that produced this item. + - `Optional fileId` - - `String agentName` + File ID for the mask image. - The canonical name of the agent that produced this item. + - `Optional imageUrl` - - `Optional error` + Base64-encoded mask image. - Error message if the server could not list tools. + - `Optional model` - - `McpApprovalRequest` + The image generation model to use. Default: `gpt-image-1`. - - `String id` + - `GPT_IMAGE_1("gpt-image-1")` - The unique ID of the approval request. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `String arguments` + - `GPT_IMAGE_2("gpt-image-2")` - A JSON string of arguments for the tool. + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `String name` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - The name of the tool to run. + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `String serverLabel` + - `Optional moderation` - The label of the MCP server making the request. + Moderation level for the generated image. Default: `auto`. - - `JsonValue; type "mcp_approval_request"constant` + - `AUTO("auto")` - The type of the item. Always `mcp_approval_request`. + - `LOW("low")` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `Optional outputCompression` - - `Optional agent` + Compression level for the output image. Default: 100. - The agent that produced this item. + - `Optional outputFormat` - - `String agentName` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The canonical name of the agent that produced this item. + - `PNG("png")` - - `McpApprovalResponse` + - `WEBP("webp")` - - `String approvalRequestId` + - `JPEG("jpeg")` - The ID of the approval request being answered. + - `Optional partialImages` - - `boolean approve` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Whether the request was approved. + - `Optional quality` - - `JsonValue; type "mcp_approval_response"constant` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The type of the item. Always `mcp_approval_response`. + - `LOW("low")` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `MEDIUM("medium")` - - `Optional id` + - `HIGH("high")` - The unique ID of the approval response + - `AUTO("auto")` - - `Optional agent` + - `Optional size` - The agent that produced this item. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `String agentName` + - `_1024X1024("1024x1024")` - The canonical name of the agent that produced this item. + - `_1024X1536("1024x1536")` - - `Optional reason` + - `_1536X1024("1536x1024")` - Optional reason for the decision. + - `AUTO("auto")` - - `McpCall` + - `JsonValue;` - - `String id` + - `JsonValue; type "local_shell"constant` - The unique ID of the tool call. + The type of the local shell tool. Always `local_shell`. - - `String arguments` + - `LOCAL_SHELL("local_shell")` - A JSON string of the arguments passed to the tool. + - `class BetaFunctionShellTool:` - - `String name` + A tool that allows the model to execute shell commands. - The name of the tool that was run. + - `JsonValue; type "shell"constant` - - `String serverLabel` + The type of the shell tool. Always `shell`. - The label of the MCP server running the tool. + - `SHELL("shell")` - - `JsonValue; type "mcp_call"constant` + - `Optional> allowedCallers` - The type of the item. Always `mcp_call`. + The tool invocation context(s). - - `MCP_CALL("mcp_call")` + - `DIRECT("direct")` - - `Optional agent` + - `PROGRAMMATIC("programmatic")` - The agent that produced this item. + - `Optional environment` - - `String agentName` + - `class BetaContainerAuto:` - The canonical name of the agent that produced this item. + - `JsonValue; type "container_auto"constant` - - `Optional approvalRequestId` + Automatically creates a container for this request - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `CONTAINER_AUTO("container_auto")` - - `Optional error` + - `Optional> fileIds` - The error from the tool call, if any. + An optional list of uploaded files to make available to your code. - - `Optional output` + - `Optional memoryLimit` - The output from the tool call. + The memory limit for the container. - - `Optional status` + - `_1G("1g")` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `_4G("4g")` - - `IN_PROGRESS("in_progress")` + - `_16G("16g")` - - `COMPLETED("completed")` + - `_64G("64g")` - - `INCOMPLETE("incomplete")` + - `Optional networkPolicy` - - `CALLING("calling")` + Network access policy for the container. - - `FAILED("failed")` + - `class BetaContainerNetworkPolicyDisabled:` - - `class BetaResponseCustomToolCallOutput:` + - `class BetaContainerNetworkPolicyAllowlist:` - The output of a custom tool call from your code, being sent back to the model. + - `Optional> skills` - - `String callId` + An optional list of skills referenced by id or inline data. - The call ID, used to map this custom tool call output to a custom tool call. + - `class BetaSkillReference:` - - `Output output` + - `String skillId` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The ID of the referenced skill. - - `String` + - `JsonValue; type "skill_reference"constant` - - `List` + References a skill created with the /v1/skills endpoint. - - `class BetaResponseInputText:` + - `SKILL_REFERENCE("skill_reference")` - A text input to the model. + - `Optional version` - - `class BetaResponseInputImage:` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class BetaInlineSkill:` - - `class BetaResponseInputFile:` + - `String description` - A file input to the model. + The description of the skill. - - `JsonValue; type "custom_tool_call_output"constant` + - `String name` - The type of the custom tool call output. Always `custom_tool_call_output`. + The name of the skill. - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `BetaInlineSkillSource source` - - `Optional id` + Inline skill payload - The unique ID of the custom tool call output in the OpenAI platform. + - `String data` - - `Optional agent` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `JsonValue; mediaType "application/zip"constant` - - `String agentName` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `APPLICATION_ZIP("application/zip")` - - `Optional caller` + - `JsonValue; type "base64"constant` - The execution context that produced this tool call. + The type of the inline skill source. Must be `base64`. - - `JsonValue;` + - `BASE64("base64")` - - `JsonValue; type "direct"constant` + - `JsonValue; type "inline"constant` - The caller type. Always `direct`. + Defines an inline skill for this request. - - `DIRECT("direct")` + - `INLINE("inline")` - - `class Program:` + - `class BetaLocalEnvironment:` - - `String callerId` + - `JsonValue; type "local"constant` - The call ID of the program item that produced this tool call. + Use a local computer environment. - - `JsonValue; type "program"constant` + - `LOCAL("local")` - The caller type. Always `program`. + - `Optional> skills` - - `PROGRAM("program")` + An optional list of skills. - - `class BetaResponseCustomToolCall:` + - `String description` - A call to a custom tool created by the model. + The description of the skill. - - `String callId` + - `String name` - An identifier used to map this custom tool call to a tool call output. + The name of the skill. - - `String input` + - `String path` - The input for the custom tool call generated by the model. + The path to the directory containing the skill. - - `String name` + - `class BetaContainerReference:` - The name of the custom tool being called. + - `String containerId` - - `JsonValue; type "custom_tool_call"constant` + The ID of the referenced container. - The type of the custom tool call. Always `custom_tool_call`. + - `JsonValue; type "container_reference"constant` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + References a container created with the /v1/containers endpoint - - `Optional id` + - `CONTAINER_REFERENCE("container_reference")` - The unique ID of the custom tool call in the OpenAI platform. + - `class BetaCustomTool:` - - `Optional agent` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The agent that produced this item. + - `String name` - - `String agentName` + The name of the custom tool, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `JsonValue; type "custom"constant` - - `Optional caller` + The type of the custom tool. Always `custom`. - The execution context that produced this tool call. + - `CUSTOM("custom")` - - `JsonValue;` + - `Optional> allowedCallers` - - `JsonValue; type "direct"constant` + The tool invocation context(s). - `DIRECT("direct")` - - `class Program:` + - `PROGRAMMATIC("programmatic")` - - `String callerId` + - `Optional deferLoading` - The call ID of the program item that produced this tool call. + Whether this tool should be deferred and discovered via tool search. - - `JsonValue; type "program"constant` + - `Optional description` - - `PROGRAM("program")` + Optional description of the custom tool, used to provide more context. - - `Optional namespace` + - `Optional format` - The namespace of the custom tool being called. + The input format for the custom tool. Default is unconstrained text. - - `CompactionTrigger` + - `JsonValue;` - - `JsonValue; type "compaction_trigger"constant` + - `JsonValue; type "text"constant` - The type of the item. Always `compaction_trigger`. + Unconstrained text format. Always `text`. - - `COMPACTION_TRIGGER("compaction_trigger")` + - `TEXT("text")` - - `Optional agent` + - `class Grammar:` - The agent that produced this item. + A grammar defined by the user. - - `String agentName` + - `String definition` - The canonical name of the agent that produced this item. + The grammar definition. - - `ItemReference` + - `Syntax syntax` - - `String id` + The syntax of the grammar definition. One of `lark` or `regex`. - The ID of the item to reference. + - `LARK("lark")` - - `Optional agent` + - `REGEX("regex")` - The agent that produced this item. + - `JsonValue; type "grammar"constant` - - `String agentName` + Grammar format. Always `grammar`. - The canonical name of the agent that produced this item. + - `GRAMMAR("grammar")` - - `Optional type` + - `class BetaNamespaceTool:` - The type of item to reference. Always `item_reference`. + Groups function/custom tools under a shared namespace. - - `ITEM_REFERENCE("item_reference")` + - `String description` - - `Program` + A description of the namespace shown to the model. - - `String id` + - `String name` - The unique ID of this program item. + The namespace name used in tool calls (for example, `crm`). - - `String callId` + - `List tools` - The stable call ID of the program item. + The function/custom tools available inside this namespace. - - `String code` + - `class Function:` - The JavaScript source executed by programmatic tool calling. + - `String name` - - `String fingerprint` + - `JsonValue; type "function"constant` - Opaque program replay fingerprint that must be round-tripped. + - `FUNCTION("function")` - - `JsonValue; type "program"constant` + - `Optional> allowedCallers` - The item type. Always `program`. + The tool invocation context(s). - - `PROGRAM("program")` + - `DIRECT("direct")` - - `Optional agent` + - `PROGRAMMATIC("programmatic")` - The agent that produced this item. + - `Optional deferLoading` - - `String agentName` + Whether this function should be deferred and discovered via tool search. - The canonical name of the agent that produced this item. + - `Optional description` - - `ProgramOutput` + - `Optional outputSchema` - - `String id` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The unique ID of this program output item. + - `Optional parameters` - - `String callId` + - `Optional strict` - The call ID of the program item. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `String result` + - `class BetaCustomTool:` - The result produced by the program item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Status status` + - `JsonValue; type "namespace"constant` - The terminal status of the program output. + The type of the tool. Always `namespace`. - - `COMPLETED("completed")` + - `NAMESPACE("namespace")` - - `INCOMPLETE("incomplete")` + - `class BetaToolSearchTool:` - - `JsonValue; type "program_output"constant` + Hosted or BYOT tool search configuration for deferred tools. - The item type. Always `program_output`. + - `JsonValue; type "tool_search"constant` - - `PROGRAM_OUTPUT("program_output")` + The type of the tool. Always `tool_search`. - - `Optional agent` + - `TOOL_SEARCH("tool_search")` - The agent that produced this item. + - `Optional description` - - `String agentName` + Description shown to the model for a client-executed tool search tool. - The canonical name of the agent that produced this item. + - `Optional execution` - - `Optional metadata` + Whether tool search is executed by the server or by the client. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `SERVER("server")` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `CLIENT("client")` - - `Model model` + - `Optional parameters` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + Parameter schema for a client-executed tool search tool. - - `GPT_5_6_SOL("gpt-5.6-sol")` + - `class BetaWebSearchPreviewTool:` - - `GPT_5_6_TERRA("gpt-5.6-terra")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `GPT_5_6_LUNA("gpt-5.6-luna")` + - `Type type` - - `GPT_5_4("gpt-5.4")` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `GPT_5_4_MINI("gpt-5.4-mini")` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `GPT_5_4_NANO("gpt-5.4-nano")` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `Optional> searchContentTypes` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + - `TEXT("text")` - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `IMAGE("image")` - - `GPT_5_2("gpt-5.2")` + - `Optional searchContextSize` - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + - `LOW("low")` - - `GPT_5_2_PRO("gpt-5.2-pro")` + - `MEDIUM("medium")` - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + - `HIGH("high")` - - `GPT_5_1("gpt-5.1")` + - `Optional userLocation` - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + The user's location. - - `GPT_5_1_CODEX("gpt-5.1-codex")` + - `JsonValue; type "approximate"constant` - - `GPT_5_1_MINI("gpt-5.1-mini")` + The type of location approximation. Always `approximate`. - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + - `APPROXIMATE("approximate")` - - `GPT_5("gpt-5")` + - `Optional city` - - `GPT_5_MINI("gpt-5-mini")` + Free text input for the city of the user, e.g. `San Francisco`. - - `GPT_5_NANO("gpt-5-nano")` + - `Optional country` - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - `Optional region` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + Free text input for the region of the user, e.g. `California`. - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `Optional timezone` - - `GPT_4_1("gpt-4.1")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `GPT_4_1_MINI("gpt-4.1-mini")` + - `class BetaApplyPatchTool:` - - `GPT_4_1_NANO("gpt-4.1-nano")` + Allows the assistant to create, delete, or update files using unified diffs. - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `JsonValue; type "apply_patch"constant` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + The type of the tool. Always `apply_patch`. - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + - `APPLY_PATCH("apply_patch")` - - `O4_MINI("o4-mini")` + - `Optional> allowedCallers` - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + The tool invocation context(s). - - `O3("o3")` + - `DIRECT("direct")` - - `O3_2025_04_16("o3-2025-04-16")` + - `PROGRAMMATIC("programmatic")` - - `O3_MINI("o3-mini")` + - `JsonValue; type "tool_search_output"constant` - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + The item type. Always `tool_search_output`. - - `O1("o1")` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `O1_2024_12_17("o1-2024-12-17")` + - `Optional id` - - `O1_PREVIEW("o1-preview")` + The unique ID of this tool search output. - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + - `Optional agent` - - `O1_MINI("o1-mini")` + The agent that produced this item. - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + - `String agentName` - - `GPT_4O("gpt-4o")` + The canonical name of the agent that produced this item. - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + - `Optional callId` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + The unique ID of the tool search call generated by the model. - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + - `Optional execution` - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + Whether tool search was executed by the server or by the client. - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + - `SERVER("server")` - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + - `CLIENT("client")` - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + - `Optional status` - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + The status of the tool search output. - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + - `IN_PROGRESS("in_progress")` - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + - `COMPLETED("completed")` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + - `INCOMPLETE("incomplete")` - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `AdditionalTools` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + - `JsonValue; role "developer"constant` - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + The role that provided the additional tools. Only `developer` is supported. - - `CODEX_MINI_LATEST("codex-mini-latest")` + - `DEVELOPER("developer")` - - `GPT_4O_MINI("gpt-4o-mini")` + - `List tools` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + A list of additional tools made available at this item. - - `GPT_4_TURBO("gpt-4-turbo")` + - `class BetaFunctionTool:` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + - `class BetaFileSearchTool:` - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `class BetaComputerTool:` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `GPT_4("gpt-4")` + - `class BetaComputerUsePreviewTool:` - - `GPT_4_0314("gpt-4-0314")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `GPT_4_0613("gpt-4-0613")` + - `class BetaWebSearchTool:` - - `GPT_4_32K("gpt-4-32k")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `GPT_4_32K_0314("gpt-4-32k-0314")` + - `Mcp` - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `CodeInterpreter` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `JsonValue;` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `ImageGeneration` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `JsonValue;` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `class BetaFunctionShellTool:` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + A tool that allows the model to execute shell commands. - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `class BetaCustomTool:` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `O1_PRO("o1-pro")` + - `class BetaNamespaceTool:` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + Groups function/custom tools under a shared namespace. - - `O3_PRO("o3-pro")` + - `class BetaToolSearchTool:` - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + Hosted or BYOT tool search configuration for deferred tools. - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `class BetaWebSearchPreviewTool:` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + - `class BetaApplyPatchTool:` - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + Allows the assistant to create, delete, or update files using unified diffs. - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `JsonValue; type "additional_tools"constant` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + The item type. Always `additional_tools`. - - `GPT_5_CODEX("gpt-5-codex")` + - `ADDITIONAL_TOOLS("additional_tools")` - - `GPT_5_PRO("gpt-5-pro")` + - `Optional id` - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + The unique ID of this additional tools item. - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + - `Optional agent` - - `JsonValue; object_ "response"constant` + The agent that produced this item. - The object type of this resource - always set to `response`. + - `String agentName` - - `RESPONSE("response")` + The canonical name of the agent that produced this item. - - `List output` + - `class BetaResponseReasoningItem:` - An array of content items generated by the model. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `String id` - - `class BetaResponseOutputMessage:` + The unique identifier of the reasoning content. - An output message from the model. + - `List summary` - - `class BetaResponseFileSearchToolCall:` + Reasoning summary content. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `String text` - - `class BetaResponseFunctionToolCall:` + A summary of the reasoning output from the model so far. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `JsonValue; type "summary_text"constant` - - `class BetaResponseFunctionToolCallOutputItem:` + The type of the object. Always `summary_text`. - - `String id` + - `SUMMARY_TEXT("summary_text")` - The unique ID of the function call tool output. + - `JsonValue; type "reasoning"constant` - - `String callId` + The type of the object. Always `reasoning`. - The unique ID of the function tool call generated by the model. + - `REASONING("reasoning")` - - `Output output` + - `Optional agent` - The output from the function call generated by your code. - Can be a string or an list of output content. + The agent that produced this item. - - `String` + - `String agentName` - - `List` + The canonical name of the agent that produced this item. - - `class BetaResponseInputText:` + - `Optional> content` - A text input to the model. + Reasoning text content. - - `class BetaResponseInputImage:` + - `String text` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The reasoning text from the model. - - `class BetaResponseInputFile:` + - `JsonValue; type "reasoning_text"constant` - A file input to the model. + The type of the reasoning text. Always `reasoning_text`. - - `Status status` + - `REASONING_TEXT("reasoning_text")` + + - `Optional encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -74435,11 +87874,23 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `JsonValue; type "function_call_output"constant` + - `class BetaResponseCompactionItemParam:` - The type of the function tool call output. Always `function_call_output`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `String encryptedContent` + + The encrypted content of the compaction summary. + + - `JsonValue; type "compaction"constant` + + The type of the item. Always `compaction`. + + - `COMPACTION("compaction")` + + - `Optional id` + + The ID of the compaction item. - `Optional agent` @@ -74449,169 +87900,174 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` + - `ImageGenerationCall` - The execution context that produced this tool call. + - `String id` - - `JsonValue;` + The unique ID of the image generation call. - - `JsonValue; type "direct"constant` + - `Optional result` - The caller type. Always `direct`. + The generated image encoded in base64. - - `DIRECT("direct")` + - `Status status` - - `class Program:` + The status of the image generation call. - - `String callerId` + - `IN_PROGRESS("in_progress")` - The call ID of the program item that produced this tool call. + - `COMPLETED("completed")` - - `JsonValue; type "program"constant` + - `GENERATING("generating")` - The caller type. Always `program`. + - `FAILED("failed")` - - `PROGRAM("program")` + - `JsonValue; type "image_generation_call"constant` - - `Optional createdBy` + The type of the image generation call. Always `image_generation_call`. - The identifier of the actor that created the item. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `AgentMessage` + - `Optional agent` - - `String id` + The agent that produced this item. - The unique ID of the agent message. + - `String agentName` - - `String author` + The canonical name of the agent that produced this item. - The sending agent identity. + - `class BetaResponseCodeInterpreterToolCall:` - - `List content` + A tool call to run code. - Encrypted content sent between agents. + - `String id` - - `class BetaResponseInputText:` + The unique ID of the code interpreter tool call. - A text input to the model. + - `Optional code` - - `class BetaResponseOutputText:` + The code to run, or null if not available. - A text output from the model. + - `String containerId` - - `class Text:` + The ID of the container used to run the code. - A text content. + - `Optional> outputs` - - `String text` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `JsonValue; type "text"constant` + - `class Logs:` - - `TEXT("text")` + The logs output from the code interpreter. - - `class SummaryText:` + - `String logs` - A summary text from the model. + The logs output from the code interpreter. - - `String text` + - `JsonValue; type "logs"constant` - A summary of the reasoning output from the model so far. + The type of the output. Always `logs`. - - `JsonValue; type "summary_text"constant` + - `LOGS("logs")` - The type of the object. Always `summary_text`. + - `class Image:` - - `SUMMARY_TEXT("summary_text")` + The image output from the code interpreter. - - `class ReasoningText:` + - `JsonValue; type "image"constant` - Reasoning text from the model. + The type of the output. Always `image`. - - `String text` + - `IMAGE("image")` - The reasoning text from the model. + - `String url` - - `JsonValue; type "reasoning_text"constant` + The URL of the image output from the code interpreter. - The type of the reasoning text. Always `reasoning_text`. + - `Status status` - - `REASONING_TEXT("reasoning_text")` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `class BetaResponseOutputRefusal:` + - `IN_PROGRESS("in_progress")` - A refusal from the model. + - `COMPLETED("completed")` - - `class BetaResponseInputImage:` + - `INCOMPLETE("incomplete")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `INTERPRETING("interpreting")` - - `class ComputerScreenshot:` + - `FAILED("failed")` - A screenshot of a computer. + - `JsonValue; type "code_interpreter_call"constant` - - `Detail detail` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `LOW("low")` + - `Optional agent` - - `HIGH("high")` + The agent that produced this item. - - `AUTO("auto")` + - `String agentName` - - `ORIGINAL("original")` + The canonical name of the agent that produced this item. - - `Optional fileId` + - `LocalShellCall` - The identifier of an uploaded file that contains the screenshot. + - `String id` - - `Optional imageUrl` + The unique ID of the local shell call. - The URL of the screenshot image. + - `Action action` - - `JsonValue; type "computer_screenshot"constant` + Execute a shell command on the server. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `List command` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + The command to run. - - `Optional promptCacheBreakpoint` + - `Env env` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Environment variables to set for the command. - - `JsonValue; mode "explicit"constant` + - `JsonValue; type "exec"constant` - The breakpoint mode. Always `explicit`. + The type of the local shell action. Always `exec`. - - `EXPLICIT("explicit")` + - `EXEC("exec")` - - `class BetaResponseInputFile:` + - `Optional timeoutMs` - A file input to the model. + Optional timeout in milliseconds for the command. - - `class EncryptedContent:` + - `Optional user` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Optional user to run the command as. - - `String encryptedContent` + - `Optional workingDirectory` - Opaque encrypted content. + Optional working directory to run the command in. - - `JsonValue; type "encrypted_content"constant` + - `String callId` - The type of the input item. Always `encrypted_content`. + The unique ID of the local shell tool call generated by the model. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `Status status` - - `String recipient` + The status of the local shell call. - The destination agent identity. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "agent_message"constant` + - `COMPLETED("completed")` - The type of the item. Always `agent_message`. + - `INCOMPLETE("incomplete")` - - `AGENT_MESSAGE("agent_message")` + - `JsonValue; type "local_shell_call"constant` + + The type of the local shell call. Always `local_shell_call`. + + - `LOCAL_SHELL_CALL("local_shell_call")` - `Optional agent` @@ -74621,167 +88077,175 @@ public final class Main { The canonical name of the agent that produced this item. - - `MultiAgentCall` + - `LocalShellCallOutput` - `String id` - The unique ID of the multi-agent call item. + The unique ID of the local shell tool call generated by the model. - - `Action action` + - `String output` - The multi-agent action to execute. + A JSON string of the output of the local shell tool call. - - `SPAWN_AGENT("spawn_agent")` + - `JsonValue; type "local_shell_call_output"constant` - - `INTERRUPT_AGENT("interrupt_agent")` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `LIST_AGENTS("list_agents")` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `SEND_MESSAGE("send_message")` + - `Optional agent` - - `FOLLOWUP_TASK("followup_task")` + The agent that produced this item. - - `WAIT_AGENT("wait_agent")` + - `String agentName` - - `String arguments` + The canonical name of the agent that produced this item. - The JSON string of arguments generated for the action. + - `Optional status` - - `String callId` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The unique ID linking this call to its output. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "multi_agent_call"constant` + - `COMPLETED("completed")` - The type of the multi-agent call. Always `multi_agent_call`. + - `INCOMPLETE("incomplete")` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `ShellCall` - - `Optional agent` + - `Action action` - The agent that produced this item. + The shell commands and limits that describe how to run the tool call. - - `String agentName` + - `List commands` - The canonical name of the agent that produced this item. + Ordered shell commands for the execution environment to run. - - `MultiAgentCallOutput` + - `Optional maxOutputLength` - - `String id` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The unique ID of the multi-agent call output item. + - `Optional timeoutMs` - - `Action action` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The multi-agent action that produced this result. + - `String callId` - - `SPAWN_AGENT("spawn_agent")` + The unique ID of the shell tool call generated by the model. - - `INTERRUPT_AGENT("interrupt_agent")` + - `JsonValue; type "shell_call"constant` - - `LIST_AGENTS("list_agents")` + The type of the item. Always `shell_call`. - - `SEND_MESSAGE("send_message")` + - `SHELL_CALL("shell_call")` - - `FOLLOWUP_TASK("followup_task")` + - `Optional id` - - `WAIT_AGENT("wait_agent")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `String callId` + - `Optional agent` - The unique ID of the multi-agent call. + The agent that produced this item. - - `List output` + - `String agentName` - Text output returned by the multi-agent action. + The canonical name of the agent that produced this item. - - `List annotations` + - `Optional caller` - The annotations of the text output. + The execution context that produced this tool call. - - `String text` + - `JsonValue;` - The text output from the model. + - `JsonValue; type "direct"constant` - - `JsonValue; type "output_text"constant` + The caller type. Always `direct`. - The type of the output text. Always `output_text`. + - `DIRECT("direct")` - - `Optional> logprobs` + - `class Program:` - - `JsonValue; type "multi_agent_call_output"constant` + - `String callerId` - The type of the multi-agent result. Always `multi_agent_call_output`. + The call ID of the program item that produced this tool call. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `JsonValue; type "program"constant` - - `Optional agent` + The caller type. Always `program`. - The agent that produced this item. + - `PROGRAM("program")` + + - `Optional environment` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment:` + + - `class BetaContainerReference:` + + - `Optional status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String agentName` + - `IN_PROGRESS("in_progress")` - The canonical name of the agent that produced this item. + - `COMPLETED("completed")` - - `class BetaResponseFunctionWebSearch:` + - `INCOMPLETE("incomplete")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `ShellCallOutput` - - `class BetaResponseComputerToolCall:` + - `String callId` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The unique ID of the shell tool call generated by the model. - - `class BetaResponseComputerToolCallOutputItem:` + - `List output` - - `String id` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The unique ID of the computer call tool output. + - `Outcome outcome` - - `String callId` + The exit or timeout outcome associated with this shell call. - The ID of the computer tool call that produced the output. + - `JsonValue;` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `JsonValue; type "timeout"constant` - A computer screenshot image used with the computer use tool. + The outcome type. Always `timeout`. - - `Status status` + - `TIMEOUT("timeout")` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class Exit:` - - `COMPLETED("completed")` + Indicates that the shell commands finished and returned an exit code. - - `INCOMPLETE("incomplete")` + - `long exitCode` - - `FAILED("failed")` + The exit code returned by the shell process. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "exit"constant` - - `JsonValue; type "computer_call_output"constant` + The outcome type. Always `exit`. - The type of the computer tool call output. Always `computer_call_output`. + - `EXIT("exit")` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `String stderr` - - `Optional> acknowledgedSafetyChecks` + Captured stderr output for the shell call. - The safety checks reported by the API that have been acknowledged by the - developer. + - `String stdout` - - `String id` + Captured stdout output for the shell call. - The ID of the pending safety check. + - `JsonValue; type "shell_call_output"constant` - - `Optional code` + The type of the item. Always `shell_call_output`. - The type of the pending safety check. + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `Optional message` + - `Optional id` - Details about the pending safety check. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `Optional agent` @@ -74791,122 +88255,121 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional caller` - The identifier of the actor that created the item. + The execution context that produced this tool call. - - `class BetaResponseReasoningItem:` + - `JsonValue;` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `JsonValue; type "direct"constant` - - `Program` + The caller type. Always `direct`. - - `String id` + - `DIRECT("direct")` - The unique ID of the program item. + - `class Program:` - - `String callId` + - `String callerId` - The stable call ID of the program item. + The call ID of the program item that produced this tool call. - - `String code` + - `JsonValue; type "program"constant` - The JavaScript source executed by programmatic tool calling. + The caller type. Always `program`. - - `String fingerprint` + - `PROGRAM("program")` - Opaque program replay fingerprint that must be round-tripped. + - `Optional maxOutputLength` - - `JsonValue; type "program"constant` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The type of the item. Always `program`. + - `Optional status` - - `PROGRAM("program")` + The status of the shell call output. - - `Optional agent` + - `IN_PROGRESS("in_progress")` - The agent that produced this item. + - `COMPLETED("completed")` - - `String agentName` + - `INCOMPLETE("incomplete")` - The canonical name of the agent that produced this item. + - `ApplyPatchCall` - - `ProgramOutput` + - `String callId` - - `String id` + The unique ID of the apply patch tool call generated by the model. - The unique ID of the program output item. + - `Operation operation` - - `String callId` + The specific create, delete, or update instruction for the apply_patch tool call. - The call ID of the program item. + - `class CreateFile:` - - `String result` + Instruction for creating a new file via the apply_patch tool. - The result produced by the program item. + - `String diff` - - `Status status` + Unified diff content to apply when creating the file. - The terminal status of the program output item. + - `String path` - - `COMPLETED("completed")` + Path of the file to create relative to the workspace root. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "create_file"constant` - - `JsonValue; type "program_output"constant` + The operation type. Always `create_file`. - The type of the item. Always `program_output`. + - `CREATE_FILE("create_file")` - - `PROGRAM_OUTPUT("program_output")` + - `class DeleteFile:` - - `Optional agent` + Instruction for deleting an existing file via the apply_patch tool. - The agent that produced this item. + - `String path` - - `String agentName` + Path of the file to delete relative to the workspace root. - The canonical name of the agent that produced this item. + - `JsonValue; type "delete_file"constant` - - `class BetaResponseToolSearchCall:` + The operation type. Always `delete_file`. - - `String id` + - `DELETE_FILE("delete_file")` - The unique ID of the tool search call item. + - `class UpdateFile:` - - `JsonValue arguments` + Instruction for updating an existing file via the apply_patch tool. - Arguments used for the tool search call. + - `String diff` - - `Optional callId` + Unified diff content to apply to the existing file. - The unique ID of the tool search call generated by the model. + - `String path` - - `Execution execution` + Path of the file to update relative to the workspace root. - Whether tool search was executed by the server or by the client. + - `JsonValue; type "update_file"constant` - - `SERVER("server")` + The operation type. Always `update_file`. - - `CLIENT("client")` + - `UPDATE_FILE("update_file")` - `Status status` - The status of the tool search call item that was recorded. + The status of the apply patch tool call. One of `in_progress` or `completed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - - `INCOMPLETE("incomplete")` + - `JsonValue; type "apply_patch_call"constant` - - `JsonValue; type "tool_search_call"constant` + The type of the item. Always `apply_patch_call`. - The type of the item. Always `tool_search_call`. + - `APPLY_PATCH_CALL("apply_patch_call")` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `Optional id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `Optional agent` @@ -74916,102 +88379,125 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional caller` - The identifier of the actor that created the item. + The execution context that produced this tool call. - - `class BetaResponseToolSearchOutputItem:` + - `JsonValue;` - - `String id` + - `JsonValue; type "direct"constant` - The unique ID of the tool search output item. + The caller type. Always `direct`. - - `Optional callId` + - `DIRECT("direct")` - The unique ID of the tool search call generated by the model. + - `class Program:` - - `Execution execution` + - `String callerId` - Whether tool search was executed by the server or by the client. + The call ID of the program item that produced this tool call. - - `SERVER("server")` + - `JsonValue; type "program"constant` - - `CLIENT("client")` + The caller type. Always `program`. - - `Status status` + - `PROGRAM("program")` - The status of the tool search output item that was recorded. + - `ApplyPatchCallOutput` - - `IN_PROGRESS("in_progress")` + - `String callId` - - `COMPLETED("completed")` + The unique ID of the apply patch tool call generated by the model. - - `INCOMPLETE("incomplete")` + - `Status status` - - `List tools` + The status of the apply patch tool call output. One of `completed` or `failed`. - The loaded tool definitions returned by tool search. + - `COMPLETED("completed")` - - `class BetaFunctionTool:` + - `FAILED("failed")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `JsonValue; type "apply_patch_call_output"constant` - - `class BetaFileSearchTool:` + The type of the item. Always `apply_patch_call_output`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `class BetaComputerTool:` + - `Optional id` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `class BetaComputerUsePreviewTool:` + - `Optional agent` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `class BetaWebSearchTool:` + - `String agentName` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `Mcp` + - `Optional caller` - - `CodeInterpreter` + The execution context that produced this tool call. - `JsonValue;` - - `ImageGeneration` + - `JsonValue; type "direct"constant` - - `JsonValue;` + The caller type. Always `direct`. - - `class BetaFunctionShellTool:` + - `DIRECT("direct")` - A tool that allows the model to execute shell commands. + - `class Program:` - - `class BetaCustomTool:` + - `String callerId` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The call ID of the program item that produced this tool call. - - `class BetaNamespaceTool:` + - `JsonValue; type "program"constant` - Groups function/custom tools under a shared namespace. + The caller type. Always `program`. - - `class BetaToolSearchTool:` + - `PROGRAM("program")` - Hosted or BYOT tool search configuration for deferred tools. + - `Optional output` - - `class BetaWebSearchPreviewTool:` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `McpListTools` - - `class BetaApplyPatchTool:` + - `String id` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the list. - - `JsonValue; type "tool_search_output"constant` + - `String serverLabel` - The type of the item. Always `tool_search_output`. + The label of the MCP server. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `List 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 annotations` + + Additional annotations about the tool. + + - `Optional 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 agent` @@ -75021,100 +88507,97 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional error` - The identifier of the actor that created the item. + Error message if the server could not list tools. - - `AdditionalTools` + - `McpApprovalRequest` - `String id` - The unique ID of the additional tools item. - - - `Role role` + The unique ID of the approval request. - The role that provided the additional tools. + - `String arguments` - - `UNKNOWN("unknown")` + A JSON string of arguments for the tool. - - `USER("user")` + - `String name` - - `ASSISTANT("assistant")` + The name of the tool to run. - - `SYSTEM("system")` + - `String serverLabel` - - `CRITIC("critic")` + The label of the MCP server making the request. - - `DISCRIMINATOR("discriminator")` + - `JsonValue; type "mcp_approval_request"constant` - - `DEVELOPER("developer")` + The type of the item. Always `mcp_approval_request`. - - `TOOL("tool")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `List tools` + - `Optional agent` - The additional tool definitions made available at this item. + The agent that produced this item. - - `class BetaFunctionTool:` + - `String agentName` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The canonical name of the agent that produced this item. - - `class BetaFileSearchTool:` + - `McpApprovalResponse` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `String approvalRequestId` - - `class BetaComputerTool:` + The ID of the approval request being answered. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `boolean approve` - - `class BetaComputerUsePreviewTool:` + Whether the request was approved. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JsonValue; type "mcp_approval_response"constant` - - `class BetaWebSearchTool:` + The type of the item. Always `mcp_approval_response`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `Mcp` + - `Optional id` - - `CodeInterpreter` + The unique ID of the approval response - - `JsonValue;` + - `Optional agent` - - `ImageGeneration` + The agent that produced this item. - - `JsonValue;` + - `String agentName` - - `class BetaFunctionShellTool:` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands. + - `Optional reason` - - `class BetaCustomTool:` + Optional reason for the decision. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `McpCall` - - `class BetaNamespaceTool:` + - `String id` - Groups function/custom tools under a shared namespace. + The unique ID of the tool call. - - `class BetaToolSearchTool:` + - `String arguments` - Hosted or BYOT tool search configuration for deferred tools. + A JSON string of the arguments passed to the tool. - - `class BetaWebSearchPreviewTool:` + - `String name` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The name of the tool that was run. - - `class BetaApplyPatchTool:` + - `String serverLabel` - Allows the assistant to create, delete, or update files using unified diffs. + The label of the MCP server running the tool. - - `JsonValue; type "additional_tools"constant` + - `JsonValue; type "mcp_call"constant` - The type of the item. Always `additional_tools`. + The type of the item. Always `mcp_call`. - - `ADDITIONAL_TOOLS("additional_tools")` + - `MCP_CALL("mcp_call")` - `Optional agent` @@ -75124,63 +88607,71 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` + - `Optional approvalRequestId` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + 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. - - `String id` + - `Optional error` - The unique ID of the compaction item. + The error from the tool call, if any. - - `String encryptedContent` + - `Optional output` - The encrypted content that was produced by compaction. + The output from the tool call. - - `JsonValue; type "compaction"constant` + - `Optional status` - The type of the item. Always `compaction`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `COMPACTION("compaction")` + - `IN_PROGRESS("in_progress")` - - `Optional agent` + - `COMPLETED("completed")` - The agent that produced this item. + - `INCOMPLETE("incomplete")` - - `String agentName` + - `CALLING("calling")` - The canonical name of the agent that produced this item. + - `FAILED("failed")` - - `Optional createdBy` + - `class BetaResponseCustomToolCallOutput:` - The identifier of the actor that created the item. + The output of a custom tool call from your code, being sent back to the model. - - `ImageGenerationCall` + - `String callId` - - `String id` + The call ID, used to map this custom tool call output to a custom tool call. - The unique ID of the image generation call. + - `Output output` - - `Optional result` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The generated image encoded in base64. + - `String` - - `Status status` + - `List` - The status of the image generation call. + - `class BetaResponseInputText:` - - `IN_PROGRESS("in_progress")` + A text input to the model. - - `COMPLETED("completed")` + - `class BetaResponseInputImage:` - - `GENERATING("generating")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `FAILED("failed")` + - `class BetaResponseInputFile:` - - `JsonValue; type "image_generation_call"constant` + A file input to the model. - The type of the image generation call. Always `image_generation_call`. + - `JsonValue; type "custom_tool_call_output"constant` - - `IMAGE_GENERATION_CALL("image_generation_call")` + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + + - `Optional id` + + The unique ID of the custom tool call output in the OpenAI platform. - `Optional agent` @@ -75190,89 +88681,95 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` + - `Optional caller` - A tool call to run code. + The execution context that produced this tool call. - - `LocalShellCall` + - `JsonValue;` - - `String id` + - `JsonValue; type "direct"constant` - The unique ID of the local shell call. + The caller type. Always `direct`. - - `Action action` + - `DIRECT("direct")` - Execute a shell command on the server. + - `class Program:` - - `List command` + - `String callerId` - The command to run. + The call ID of the program item that produced this tool call. - - `Env env` + - `JsonValue; type "program"constant` - Environment variables to set for the command. + The caller type. Always `program`. - - `JsonValue; type "exec"constant` + - `PROGRAM("program")` - The type of the local shell action. Always `exec`. + - `class BetaResponseCustomToolCall:` - - `EXEC("exec")` + A call to a custom tool created by the model. - - `Optional timeoutMs` + - `String callId` - Optional timeout in milliseconds for the command. + An identifier used to map this custom tool call to a tool call output. - - `Optional user` + - `String input` - Optional user to run the command as. + The input for the custom tool call generated by the model. - - `Optional workingDirectory` + - `String name` - Optional working directory to run the command in. + The name of the custom tool being called. - - `String callId` + - `JsonValue; type "custom_tool_call"constant` - The unique ID of the local shell tool call generated by the model. + The type of the custom tool call. Always `custom_tool_call`. - - `Status status` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - The status of the local shell call. + - `Optional id` - - `IN_PROGRESS("in_progress")` + The unique ID of the custom tool call in the OpenAI platform. - - `COMPLETED("completed")` + - `Optional agent` - - `INCOMPLETE("incomplete")` + The agent that produced this item. - - `JsonValue; type "local_shell_call"constant` + - `String agentName` - The type of the local shell call. Always `local_shell_call`. + The canonical name of the agent that produced this item. - - `LOCAL_SHELL_CALL("local_shell_call")` + - `Optional caller` - - `Optional agent` + The execution context that produced this tool call. - The agent that produced this item. + - `JsonValue;` - - `String agentName` + - `JsonValue; type "direct"constant` - The canonical name of the agent that produced this item. + - `DIRECT("direct")` - - `LocalShellCallOutput` + - `class Program:` - - `String id` + - `String callerId` - The unique ID of the local shell tool call generated by the model. + The call ID of the program item that produced this tool call. - - `String output` + - `JsonValue; type "program"constant` - A JSON string of the output of the local shell tool call. + - `PROGRAM("program")` - - `JsonValue; type "local_shell_call_output"constant` + - `Optional namespace` - The type of the local shell tool call output. Always `local_shell_call_output`. + The namespace of the custom tool being called. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `CompactionTrigger` + + - `JsonValue; type "compaction_trigger"constant` + + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` - `Optional agent` @@ -75282,83 +88779,85 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional status` + - `ItemReference` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `String id` - - `IN_PROGRESS("in_progress")` + The ID of the item to reference. - - `COMPLETED("completed")` + - `Optional agent` - - `INCOMPLETE("incomplete")` + The agent that produced this item. - - `class BetaResponseFunctionShellToolCall:` + - `String agentName` - A tool call that executes one or more shell commands in a managed environment. + The canonical name of the agent that produced this item. - - `String id` + - `Optional type` - The unique ID of the shell tool call. Populated when this item is returned via API. + The type of item to reference. Always `item_reference`. - - `Action action` + - `ITEM_REFERENCE("item_reference")` - The shell commands and limits that describe how to run the tool call. + - `Program` - - `List commands` + - `String id` - - `Optional maxOutputLength` + The unique ID of this program item. - Optional maximum number of characters to return from each command. + - `String callId` - - `Optional timeoutMs` + The stable call ID of the program item. - Optional timeout in milliseconds for the commands. + - `String code` - - `String callId` + The JavaScript source executed by programmatic tool calling. - The unique ID of the shell tool call generated by the model. + - `String fingerprint` - - `Optional environment` + Opaque program replay fingerprint that must be round-tripped. - Represents the use of a local environment to perform shell actions. + - `JsonValue; type "program"constant` - - `class BetaResponseLocalEnvironment:` + The item type. Always `program`. - Represents the use of a local environment to perform shell actions. + - `PROGRAM("program")` - - `JsonValue; type "local"constant` + - `Optional agent` - The environment type. Always `local`. + The agent that produced this item. - - `LOCAL("local")` + - `String agentName` - - `class BetaResponseContainerReference:` + The canonical name of the agent that produced this item. - Represents a container created with /v1/containers. + - `ProgramOutput` - - `String containerId` + - `String id` - - `JsonValue; type "container_reference"constant` + The unique ID of this program output item. - The environment type. Always `container_reference`. + - `String callId` - - `CONTAINER_REFERENCE("container_reference")` + The call ID of the program item. - - `Status status` + - `String result` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The result produced by the program item. - - `IN_PROGRESS("in_progress")` + - `Status status` + + The terminal status of the program output. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `JsonValue; type "shell_call"constant` + - `JsonValue; type "program_output"constant` - The type of the item. Always `shell_call`. + The item type. Always `program_output`. - - `SHELL_CALL("shell_call")` + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -75368,358 +88867,371 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` +### Beta Response Input Message Item - The execution context that produced this tool call. +- `class BetaResponseInputMessageItem:` - - `JsonValue;` + - `String id` - - `JsonValue; type "direct"constant` + The unique ID of the message input. - - `DIRECT("direct")` + - `List content` - - `class Program:` + A list of one or many input items to the model, containing different content + types. - - `String callerId` + - `class BetaResponseInputText:` - The call ID of the program item that produced this tool call. + A text input to the model. - - `JsonValue; type "program"constant` + - `String text` - - `PROGRAM("program")` + The text input to the model. - - `Optional createdBy` + - `JsonValue; type "input_text"constant` - The ID of the entity that created this tool call. + The type of the input item. Always `input_text`. - - `class BetaResponseFunctionShellToolCallOutput:` + - `INPUT_TEXT("input_text")` - The output of a shell tool call that was emitted. + - `Optional promptCacheBreakpoint` - - `String id` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The unique ID of the shell call output. Populated when this item is returned via API. + - `JsonValue; mode "explicit"constant` - - `String callId` + The breakpoint mode. Always `explicit`. - The unique ID of the shell tool call generated by the model. + - `EXPLICIT("explicit")` - - `Optional maxOutputLength` + - `class BetaResponseInputImage:` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `List output` + - `Detail detail` - An array of shell call output contents + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Outcome outcome` + - `LOW("low")` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `HIGH("high")` - - `JsonValue;` + - `AUTO("auto")` - - `JsonValue; type "timeout"constant` + - `ORIGINAL("original")` - The outcome type. Always `timeout`. + - `JsonValue; type "input_image"constant` - - `TIMEOUT("timeout")` + The type of the input item. Always `input_image`. - - `class Exit:` + - `INPUT_IMAGE("input_image")` - Indicates that the shell commands finished and returned an exit code. + - `Optional fileId` - - `long exitCode` + The ID of the file to be sent to the model. - Exit code from the shell process. + - `Optional imageUrl` - - `JsonValue; type "exit"constant` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The outcome type. Always `exit`. + - `Optional promptCacheBreakpoint` - - `EXIT("exit")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String stderr` + - `JsonValue; mode "explicit"constant` - The standard error output that was captured. + The breakpoint mode. Always `explicit`. - - `String stdout` + - `EXPLICIT("explicit")` - The standard output that was captured. + - `class BetaResponseInputFile:` - - `Optional createdBy` + A file input to the model. - The identifier of the actor that created the item. + - `JsonValue; type "input_file"constant` - - `Status status` + The type of the input item. Always `input_file`. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `INPUT_FILE("input_file")` - - `IN_PROGRESS("in_progress")` + - `Optional detail` - - `COMPLETED("completed")` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `INCOMPLETE("incomplete")` + - `AUTO("auto")` - - `JsonValue; type "shell_call_output"constant` + - `LOW("low")` - The type of the shell call output. Always `shell_call_output`. + - `HIGH("high")` - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional fileData` - - `Optional agent` + The content of the file to be sent to the model. - The agent that produced this item. + - `Optional fileId` - - `String agentName` + The ID of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `Optional fileUrl` - - `Optional caller` + The URL of the file to be sent to the model. - The execution context that produced this tool call. + - `Optional filename` - - `JsonValue;` + The name of the file to be sent to the model. - - `JsonValue; type "direct"constant` + - `Optional promptCacheBreakpoint` - - `DIRECT("direct")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class Program:` + - `JsonValue; mode "explicit"constant` - - `String callerId` + The breakpoint mode. Always `explicit`. - The call ID of the program item that produced this tool call. + - `EXPLICIT("explicit")` - - `JsonValue; type "program"constant` + - `Role role` - - `PROGRAM("program")` + The role of the message input. One of `user`, `system`, or `developer`. - - `Optional createdBy` + - `USER("user")` - The identifier of the actor that created the item. + - `SYSTEM("system")` - - `class BetaResponseApplyPatchToolCall:` + - `DEVELOPER("developer")` - A tool call that applies file diffs by creating, deleting, or updating files. + - `JsonValue; type "message"constant` - - `String id` + The type of the message input. Always set to `message`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `MESSAGE("message")` - - `String callId` + - `Optional agent` - The unique ID of the apply patch tool call generated by the model. + The agent that produced this item. - - `Operation operation` + - `String agentName` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The canonical name of the agent that produced this item. - - `class CreateFile:` + - `Optional status` - Instruction describing how to create a file via the apply_patch tool. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `String diff` + - `IN_PROGRESS("in_progress")` - Diff to apply. + - `COMPLETED("completed")` - - `String path` + - `INCOMPLETE("incomplete")` - Path of the file to create. +### Beta Response Input Text - - `JsonValue; type "create_file"constant` +- `class BetaResponseInputText:` - Create a new file with the provided diff. + A text input to the model. - - `CREATE_FILE("create_file")` + - `String text` - - `class DeleteFile:` + The text input to the model. - Instruction describing how to delete a file via the apply_patch tool. + - `JsonValue; type "input_text"constant` - - `String path` + The type of the input item. Always `input_text`. - Path of the file to delete. + - `INPUT_TEXT("input_text")` - - `JsonValue; type "delete_file"constant` + - `Optional promptCacheBreakpoint` - Delete the specified file. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `DELETE_FILE("delete_file")` + - `JsonValue; mode "explicit"constant` - - `class UpdateFile:` + The breakpoint mode. Always `explicit`. - Instruction describing how to update a file via the apply_patch tool. + - `EXPLICIT("explicit")` - - `String diff` +### Beta Response Input Text Content - Diff to apply. +- `class BetaResponseInputTextContent:` - - `String path` + A text input to the model. - Path of the file to update. + - `String text` - - `JsonValue; type "update_file"constant` + The text input to the model. - Update an existing file with the provided diff. + - `JsonValue; type "input_text"constant` - - `UPDATE_FILE("update_file")` + The type of the input item. Always `input_text`. - - `Status status` + - `INPUT_TEXT("input_text")` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `Optional promptCacheBreakpoint` - - `IN_PROGRESS("in_progress")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `COMPLETED("completed")` + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "apply_patch_call"constant` + The breakpoint mode. Always `explicit`. - The type of the item. Always `apply_patch_call`. + - `EXPLICIT("explicit")` - - `APPLY_PATCH_CALL("apply_patch_call")` +### Beta Response Item - - `Optional agent` +- `class BetaResponseItem: A class that can be one of several variants.union` - The agent that produced this item. + Content item used to generate a response. - - `String agentName` + - `class BetaResponseInputMessageItem:` - The canonical name of the agent that produced this item. + - `String id` - - `Optional caller` + The unique ID of the message input. - The execution context that produced this tool call. + - `List content` - - `JsonValue;` + A list of one or many input items to the model, containing different content + types. - - `JsonValue; type "direct"constant` + - `class BetaResponseInputText:` - - `DIRECT("direct")` + A text input to the model. - - `class Program:` + - `String text` - - `String callerId` + The text input to the model. - The call ID of the program item that produced this tool call. + - `JsonValue; type "input_text"constant` - - `JsonValue; type "program"constant` + The type of the input item. Always `input_text`. - - `PROGRAM("program")` + - `INPUT_TEXT("input_text")` - - `Optional createdBy` + - `Optional promptCacheBreakpoint` - The ID of the entity that created this tool call. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseApplyPatchToolCallOutput:` + - `JsonValue; mode "explicit"constant` - The output emitted by an apply patch tool call. + The breakpoint mode. Always `explicit`. - - `String id` + - `EXPLICIT("explicit")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `class BetaResponseInputImage:` - - `String callId` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The unique ID of the apply patch tool call generated by the model. + - `Detail detail` - - `Status status` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `LOW("low")` - - `COMPLETED("completed")` + - `HIGH("high")` - - `FAILED("failed")` + - `AUTO("auto")` - - `JsonValue; type "apply_patch_call_output"constant` + - `ORIGINAL("original")` - The type of the item. Always `apply_patch_call_output`. + - `JsonValue; type "input_image"constant` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The type of the input item. Always `input_image`. - - `Optional agent` + - `INPUT_IMAGE("input_image")` - The agent that produced this item. + - `Optional fileId` - - `String agentName` + The ID of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `Optional imageUrl` - - `Optional caller` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The execution context that produced this tool call. + - `Optional promptCacheBreakpoint` - - `JsonValue;` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "direct"constant` + - `JsonValue; mode "explicit"constant` - - `DIRECT("direct")` + The breakpoint mode. Always `explicit`. - - `class Program:` + - `EXPLICIT("explicit")` - - `String callerId` + - `class BetaResponseInputFile:` - The call ID of the program item that produced this tool call. + A file input to the model. - - `JsonValue; type "program"constant` + - `JsonValue; type "input_file"constant` - - `PROGRAM("program")` + The type of the input item. Always `input_file`. - - `Optional createdBy` + - `INPUT_FILE("input_file")` - The ID of the entity that created this tool call output. + - `Optional detail` - - `Optional output` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Optional textual output returned by the apply patch tool. + - `AUTO("auto")` - - `McpCall` + - `LOW("low")` - - `String id` + - `HIGH("high")` - The unique ID of the tool call. + - `Optional fileData` - - `String arguments` + The content of the file to be sent to the model. - A JSON string of the arguments passed to the tool. + - `Optional fileId` - - `String name` + The ID of the file to be sent to the model. - The name of the tool that was run. + - `Optional fileUrl` - - `String serverLabel` + The URL of the file to be sent to the model. - The label of the MCP server running the tool. + - `Optional filename` - - `JsonValue; type "mcp_call"constant` + The name of the file to be sent to the model. - The type of the item. Always `mcp_call`. + - `Optional promptCacheBreakpoint` - - `MCP_CALL("mcp_call")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional agent` + - `JsonValue; mode "explicit"constant` - The agent that produced this item. + The breakpoint mode. Always `explicit`. - - `String agentName` + - `EXPLICIT("explicit")` - The canonical name of the agent that produced this item. + - `Role role` - - `Optional approvalRequestId` + The role of the message input. One of `user`, `system`, or `developer`. - 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. + - `USER("user")` - - `Optional error` + - `SYSTEM("system")` - The error from the tool call, if any. + - `DEVELOPER("developer")` - - `Optional output` + - `JsonValue; type "message"constant` - The output from the tool call. + The type of the message input. Always set to `message`. + + - `MESSAGE("message")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. - `Optional status` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -75727,1058 +89239,1001 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `CALLING("calling")` - - - `FAILED("failed")` + - `class BetaResponseOutputMessage:` - - `McpListTools` + An output message from the model. - `String id` - The unique ID of the list. + The unique ID of the output message. - - `String serverLabel` + - `List content` - The label of the MCP server. + The content of the output message. - - `List tools` + - `class BetaResponseOutputText:` - The tools available on the server. + A text output from the model. - - `JsonValue inputSchema` + - `List annotations` - The JSON schema describing the tool's input. + The annotations of the text output. - - `String name` + - `class FileCitation:` - The name of the tool. + A citation to a file. - - `Optional annotations` + - `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` - Additional annotations about the tool. + The type of the file citation. Always `file_citation`. - - `Optional description` + - `FILE_CITATION("file_citation")` - The description of the tool. + - `class UrlCitation:` - - `JsonValue; type "mcp_list_tools"constant` + A citation for a web resource used to generate a model response. - The type of the item. Always `mcp_list_tools`. + - `long endIndex` - - `MCP_LIST_TOOLS("mcp_list_tools")` + The index of the last character of the URL citation in the message. - - `Optional agent` + - `long startIndex` - The agent that produced this item. + The index of the first character of the URL citation in the message. - - `String agentName` + - `String title` - The canonical name of the agent that produced this item. + The title of the web resource. - - `Optional error` + - `JsonValue; type "url_citation"constant` - Error message if the server could not list tools. + The type of the URL citation. Always `url_citation`. - - `McpApprovalRequest` + - `URL_CITATION("url_citation")` - - `String id` + - `String url` - The unique ID of the approval request. + The URL of the web resource. - - `String arguments` + - `class ContainerFileCitation:` - A JSON string of arguments for the tool. + A citation for a container file used to generate a model response. - - `String name` + - `String containerId` - The name of the tool to run. + The ID of the container file. - - `String serverLabel` + - `long endIndex` - The label of the MCP server making the request. + The index of the last character of the container file citation in the message. - - `JsonValue; type "mcp_approval_request"constant` + - `String fileId` - The type of the item. Always `mcp_approval_request`. + The ID of the file. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `String filename` - - `Optional agent` + The filename of the container file cited. - The agent that produced this item. + - `long startIndex` - - `String agentName` + The index of the first character of the container file citation in the message. - The canonical name of the agent that produced this item. + - `JsonValue; type "container_file_citation"constant` - - `McpApprovalResponse` + The type of the container file citation. Always `container_file_citation`. - - `String id` + - `CONTAINER_FILE_CITATION("container_file_citation")` - The unique ID of the approval response + - `class FilePath:` - - `String approvalRequestId` + A path to a file. - The ID of the approval request being answered. + - `String fileId` - - `boolean approve` + The ID of the file. - Whether the request was approved. + - `long index` - - `JsonValue; type "mcp_approval_response"constant` + The index of the file in the list of files. - The type of the item. Always `mcp_approval_response`. + - `JsonValue; type "file_path"constant` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + The type of the file path. Always `file_path`. - - `Optional agent` + - `FILE_PATH("file_path")` - The agent that produced this item. + - `String text` - - `String agentName` + The text output from the model. - The canonical name of the agent that produced this item. + - `JsonValue; type "output_text"constant` - - `Optional reason` + The type of the output text. Always `output_text`. - Optional reason for the decision. + - `OUTPUT_TEXT("output_text")` - - `class BetaResponseCustomToolCall:` + - `Optional> logprobs` - A call to a custom tool created by the model. + - `String token` - - `class BetaResponseCustomToolCallOutputItem:` + - `List bytes` - The output of a custom tool call from your code, being sent back to the model. + - `double logprob` - - `String id` + - `List topLogprobs` - The unique ID of the custom tool call output item. + - `String token` - - `Status status` + - `List bytes` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `double logprob` - - `IN_PROGRESS("in_progress")` + - `class BetaResponseOutputRefusal:` - - `COMPLETED("completed")` + A refusal from the model. - - `INCOMPLETE("incomplete")` + - `String refusal` - - `Optional createdBy` + The refusal explanation from the model. - The identifier of the actor that created the item. + - `JsonValue; type "refusal"constant` - - `boolean parallelToolCalls` + The type of the refusal. Always `refusal`. - Whether to allow the model to run tool calls in parallel. + - `REFUSAL("refusal")` - - `Optional temperature` + - `JsonValue; role "assistant"constant` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + The role of the output message. Always `assistant`. - - `ToolChoice toolChoice` + - `ASSISTANT("assistant")` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `Status status` - - `enum BetaToolChoiceOptions:` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Controls which (if any) tool is called by the model. + - `IN_PROGRESS("in_progress")` - `none` means the model will not call any tool and instead generates a message. + - `COMPLETED("completed")` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `INCOMPLETE("incomplete")` - `required` means the model must call one or more tools. + - `JsonValue; type "message"constant` - - `NONE("none")` + The type of the output message. Always `message`. - - `AUTO("auto")` + - `MESSAGE("message")` - - `REQUIRED("required")` + - `Optional agent` - - `class BetaToolChoiceAllowed:` + The agent that produced this item. - Constrains the tools available to the model to a pre-defined set. + - `String agentName` - - `Mode mode` + The canonical name of the agent that produced this item. - Constrains the tools available to the model to a pre-defined set. + - `Optional phase` - `auto` allows the model to pick from among the allowed tools and generate a - message. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `required` requires the model to call one or more of the allowed tools. + - `COMMENTARY("commentary")` - - `AUTO("auto")` + - `FINAL_ANSWER("final_answer")` - - `REQUIRED("required")` + - `class BetaResponseFileSearchToolCall:` - - `List tools` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - A list of tool definitions that the model should be allowed to call. + - `String id` - For the Responses API, the list of tool definitions might look like: + The unique ID of the file search tool call. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `List queries` - - `JsonValue; type "allowed_tools"constant` + The queries used to search for files. - Allowed tool configuration type. Always `allowed_tools`. + - `Status status` - - `ALLOWED_TOOLS("allowed_tools")` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `class BetaToolChoiceTypes:` + - `IN_PROGRESS("in_progress")` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `SEARCHING("searching")` - - `Type type` + - `COMPLETED("completed")` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `INCOMPLETE("incomplete")` - Allowed values are: + - `FAILED("failed")` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `JsonValue; type "file_search_call"constant` - - `FILE_SEARCH("file_search")` + The type of the file search tool call. Always `file_search_call`. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `FILE_SEARCH_CALL("file_search_call")` - - `COMPUTER("computer")` + - `Optional agent` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The agent that produced this item. - - `COMPUTER_USE("computer_use")` + - `String agentName` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The canonical name of the agent that produced this item. - - `IMAGE_GENERATION("image_generation")` + - `Optional> results` - - `CODE_INTERPRETER("code_interpreter")` + The results of the file search tool call. - - `class BetaToolChoiceFunction:` + - `Optional attributes` - Use this option to force the model to call a specific function. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `String name` + - `String` - The name of the function to call. + - `double` - - `JsonValue; type "function"constant` + - `boolean` - For function calling, the type is always `function`. + - `Optional fileId` - - `FUNCTION("function")` + The unique ID of the file. - - `class BetaToolChoiceMcp:` + - `Optional filename` - Use this option to force the model to call a specific tool on a remote MCP server. + The name of the file. - - `String serverLabel` + - `Optional score` - The label of the MCP server to use. + The relevance score of the file - a value between 0 and 1. - - `JsonValue; type "mcp"constant` + - `Optional text` - For MCP tools, the type is always `mcp`. + The text that was retrieved from the file. - - `MCP("mcp")` + - `class BetaResponseComputerToolCall:` - - `Optional name` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The name of the tool to call on the server. + - `String id` - - `class BetaToolChoiceCustom:` + The unique ID of the computer call. - Use this option to force the model to call a specific custom tool. + - `String callId` - - `String name` + An identifier used when responding to the tool call with output. - The name of the custom tool to call. + - `List pendingSafetyChecks` - - `JsonValue; type "custom"constant` + The pending safety checks for the computer call. - For custom tool calling, the type is always `custom`. + - `String id` - - `CUSTOM("custom")` + The ID of the pending safety check. - - `JsonValue;` + - `Optional code` - - `JsonValue; type "programmatic_tool_calling"constant` + The type of the pending safety check. - The tool to call. Always `programmatic_tool_calling`. + - `Optional message` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + Details about the pending safety check. - - `class BetaToolChoiceApplyPatch:` + - `Status status` - Forces the model to call the apply_patch tool when executing a tool call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue; type "apply_patch"constant` + - `IN_PROGRESS("in_progress")` - The tool to call. Always `apply_patch`. + - `COMPLETED("completed")` - - `APPLY_PATCH("apply_patch")` + - `INCOMPLETE("incomplete")` - - `class BetaToolChoiceShell:` + - `Type type` - Forces the model to call the shell tool when a tool call is required. + The type of the computer call. Always `computer_call`. - - `JsonValue; type "shell"constant` + - `COMPUTER_CALL("computer_call")` - The tool to call. Always `shell`. + - `Optional action` - - `SHELL("shell")` + A click action. - - `List tools` + - `Click` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `Button button` - We support the following categories of tools: + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `LEFT("left")` - - `class BetaFunctionTool:` + - `RIGHT("right")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `WHEEL("wheel")` - - `class BetaFileSearchTool:` + - `BACK("back")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `FORWARD("forward")` - - `class BetaComputerTool:` + - `JsonValue; type "click"constant` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the event type. For a click action, this property is always `click`. - - `class BetaComputerUsePreviewTool:` + - `CLICK("click")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `long x` - - `class BetaWebSearchTool:` + The x-coordinate where the click occurred. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `long y` - - `Mcp` + The y-coordinate where the click occurred. - - `CodeInterpreter` + - `Optional> keys` - - `JsonValue;` + The keys being held while clicking. - - `ImageGeneration` + - `DoubleClick` - - `JsonValue;` + - `Optional> keys` - - `class BetaFunctionShellTool:` + The keys being held while double-clicking. - A tool that allows the model to execute shell commands. + - `JsonValue; type "double_click"constant` - - `class BetaCustomTool:` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `DOUBLE_CLICK("double_click")` - - `class BetaNamespaceTool:` + - `long x` - Groups function/custom tools under a shared namespace. + The x-coordinate where the double click occurred. - - `class BetaToolSearchTool:` + - `long y` - Hosted or BYOT tool search configuration for deferred tools. + The y-coordinate where the double click occurred. - - `class BetaWebSearchPreviewTool:` + - `Drag` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `List path` - - `class BetaApplyPatchTool:` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Allows the assistant to create, delete, or update files using unified diffs. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `Optional topP` + - `long x` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The x-coordinate. - We generally recommend altering this or `temperature` but not both. + - `long y` - - `Optional background` + The y-coordinate. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `JsonValue; type "drag"constant` - - `Optional completedAt` + Specifies the event type. For a drag action, this property is always set to `drag`. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `DRAG("drag")` - - `Optional conversation` + - `Optional> keys` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The keys being held while dragging the mouse. - - `String id` + - `Keypress` - The unique ID of the conversation that this response was associated with. + - `List keys` - - `Optional maxOutputTokens` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `JsonValue; type "keypress"constant` - - `Optional maxToolCalls` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `KEYPRESS("keypress")` - - `Optional moderation` + - `Move` - Moderation results for the response input and output, if moderated completions were requested. + - `JsonValue; type "move"constant` - - `Input input` + Specifies the event type. For a move action, this property is always set to `move`. - Moderation for the response input. + - `MOVE("move")` - - `class ModerationResult:` + - `long x` - A moderation result produced for the response input or output. + The x-coordinate to move to. - - `Categories categories` + - `long y` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The y-coordinate to move to. - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `Optional> keys` - Which modalities of input are reflected by the score for each category. + The keys being held while moving the mouse. - - `TEXT("text")` + - `JsonValue;` - - `IMAGE("image")` + - `JsonValue; type "screenshot"constant` - - `CategoryScores categoryScores` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - A dictionary of moderation categories to scores. + - `SCREENSHOT("screenshot")` - - `boolean flagged` + - `Scroll` - A boolean indicating whether the content was flagged by any category. + - `long scrollX` - - `String model` + The horizontal scroll distance. - The moderation model that produced this result. + - `long scrollY` - - `JsonValue; type "moderation_result"constant` + The vertical scroll distance. - The object type, which was always `moderation_result` for successful moderation results. + - `JsonValue; type "scroll"constant` - - `MODERATION_RESULT("moderation_result")` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `class Error:` + - `SCROLL("scroll")` - An error produced while attempting moderation for the response input or output. + - `long x` - - `String code` + The x-coordinate where the scroll occurred. - The error code. + - `long y` - - `String message` + The y-coordinate where the scroll occurred. - The error message. + - `Optional> keys` - - `JsonValue; type "error"constant` + The keys being held while scrolling. - The object type, which was always `error` for moderation failures. + - `Type` - - `ERROR("error")` + - `String text` - - `Output output` + The text to type. - Moderation for the response output. + - `JsonValue; type "type"constant` - - `class ModerationResult:` + Specifies the event type. For a type action, this property is always set to `type`. - A moderation result produced for the response input or output. + - `TYPE("type")` - - `Categories categories` + - `JsonValue;` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `JsonValue; type "wait"constant` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + Specifies the event type. For a wait action, this property is always set to `wait`. - Which modalities of input are reflected by the score for each category. + - `WAIT("wait")` - - `TEXT("text")` + - `Optional> actions` - - `IMAGE("image")` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `CategoryScores categoryScores` + - `Click` - A dictionary of moderation categories to scores. + - `DoubleClick` - - `boolean flagged` + - `Drag` - A boolean indicating whether the content was flagged by any category. + - `Keypress` - - `String model` + - `Move` - The moderation model that produced this result. + - `JsonValue;` - - `JsonValue; type "moderation_result"constant` + - `Scroll` - The object type, which was always `moderation_result` for successful moderation results. + - `Type` - - `MODERATION_RESULT("moderation_result")` + - `JsonValue;` - - `class Error:` + - `Optional agent` - An error produced while attempting moderation for the response input or output. + The agent that produced this item. - - `String code` + - `String agentName` - The error code. + The canonical name of the agent that produced this item. - - `String message` + - `class BetaResponseComputerToolCallOutputItem:` - The error message. + - `String id` - - `JsonValue; type "error"constant` + The unique ID of the computer call tool output. - The object type, which was always `error` for moderation failures. + - `String callId` - - `ERROR("error")` + The ID of the computer tool call that produced the output. - - `Optional previousResponseId` + - `BetaResponseComputerToolCallOutputScreenshot output` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + A computer screenshot image used with the computer use tool. - - `Optional prompt` + - `JsonValue; type "computer_screenshot"constant` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `String id` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The unique identifier of the prompt template to use. + - `Optional fileId` - - `Optional variables` + The identifier of an uploaded file that contains the screenshot. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `Optional imageUrl` - - `String` + The URL of the screenshot image. - - `class BetaResponseInputText:` + - `Status status` - A text input to the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class BetaResponseInputImage:` + - `COMPLETED("completed")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `INCOMPLETE("incomplete")` - - `class BetaResponseInputFile:` + - `FAILED("failed")` - A file input to the model. + - `IN_PROGRESS("in_progress")` - - `Optional version` + - `JsonValue; type "computer_call_output"constant` - Optional version of the prompt template. + The type of the computer tool call output. Always `computer_call_output`. - - `Optional promptCacheKey` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `Optional> acknowledgedSafetyChecks` - - `Optional promptCacheOptions` + The safety checks reported by the API that have been acknowledged by the + developer. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `String id` - - `Mode mode` + The ID of the pending safety check. - Whether implicit prompt-cache breakpoints were enabled. + - `Optional code` - - `IMPLICIT("implicit")` + The type of the pending safety check. - - `EXPLICIT("explicit")` + - `Optional message` - - `Ttl ttl` + Details about the pending safety check. - The minimum lifetime applied to each cache breakpoint. + - `Optional agent` - - `_30M("30m")` + The agent that produced this item. - - `Optional promptCacheRetention` + - `String agentName` - Deprecated. Use `prompt_cache_options.ttl` instead. + The canonical name of the agent that produced this item. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `Optional createdBy` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The identifier of the actor that created the item. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `class BetaResponseFunctionWebSearch:` - - `IN_MEMORY("in_memory")` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `_24H("24h")` + - `String id` - - `Optional reasoning` + The unique ID of the web search tool call. - **gpt-5 and o-series models only** + - `Action action` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `Optional context` + - `class Search:` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + Action type "search" - Performs a web search query. - - `AUTO("auto")` + - `JsonValue; type "search"constant` - - `CURRENT_TURN("current_turn")` + The action type. - - `ALL_TURNS("all_turns")` + - `SEARCH("search")` - - `Optional effort` + - `Optional> queries` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The search queries. - - `NONE("none")` + - `Optional query` - - `MINIMAL("minimal")` + The search query. - - `LOW("low")` + - `Optional> sources` - - `MEDIUM("medium")` + The sources used in the search. - - `HIGH("high")` + - `JsonValue; type "url"constant` - - `XHIGH("xhigh")` + The type of source. Always `url`. - - `MAX("max")` + - `URL("url")` - - `Optional generateSummary` + - `String url` - **Deprecated:** use `summary` instead. + The URL of the source. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `class OpenPage:` - - `AUTO("auto")` + Action type "open_page" - Opens a specific URL from search results. - - `CONCISE("concise")` + - `JsonValue; type "open_page"constant` - - `DETAILED("detailed")` + The action type. - - `Optional mode` + - `OPEN_PAGE("open_page")` - Controls the reasoning execution mode for the request. + - `Optional url` - When returned on a response, this is the effective execution mode. + The URL opened by the model. - - `STANDARD("standard")` + - `class FindInPage:` - - `PRO("pro")` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `Optional summary` + - `String pattern` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The pattern or text to search for within the page. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `JsonValue; type "find_in_page"constant` - - `AUTO("auto")` + The action type. - - `CONCISE("concise")` + - `FIND_IN_PAGE("find_in_page")` - - `DETAILED("detailed")` + - `String url` - - `Optional safetyIdentifier` + The URL of the page searched for the pattern. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `Status status` - - `Optional serviceTier` + The status of the web search tool call. - Specifies the processing type used for serving the request. + - `IN_PROGRESS("in_progress")` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `SEARCHING("searching")` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `COMPLETED("completed")` - - `AUTO("auto")` + - `FAILED("failed")` - - `DEFAULT("default")` + - `JsonValue; type "web_search_call"constant` - - `FLEX("flex")` + The type of the web search tool call. Always `web_search_call`. - - `SCALE("scale")` + - `WEB_SEARCH_CALL("web_search_call")` - - `PRIORITY("priority")` + - `Optional agent` - - `Optional status` + The agent that produced this item. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `String agentName` - - `COMPLETED("completed")` + The canonical name of the agent that produced this item. - - `FAILED("failed")` + - `class BetaResponseFunctionToolCallItem:` - - `IN_PROGRESS("in_progress")` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `CANCELLED("cancelled")` + - `String id` - - `QUEUED("queued")` + The unique ID of the function tool call. - - `INCOMPLETE("incomplete")` + - `Status status` - - `Optional text` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `IN_PROGRESS("in_progress")` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `COMPLETED("completed")` - - `Optional format` + - `INCOMPLETE("incomplete")` - An object specifying the format that the model must output. + - `Optional createdBy` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The identifier of the actor that created the item. - The default format is `{ "type": "text" }` with no additional options. + - `class BetaResponseFunctionToolCallOutputItem:` - **Not recommended for gpt-4o and newer models:** + - `String id` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The unique ID of the function call tool output. - - `JsonValue;` + - `String callId` - - `JsonValue; type "text"constant` + The unique ID of the function tool call generated by the model. - The type of response format being defined. Always `text`. + - `Output output` - - `TEXT("text")` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `String` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `List` - - `String name` + - `class BetaResponseInputText:` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + A text input to the model. - - `Schema schema` + - `class BetaResponseInputImage:` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `JsonValue; type "json_schema"constant` + - `class BetaResponseInputFile:` - The type of response format being defined. Always `json_schema`. + A file input to the model. - - `JSON_SCHEMA("json_schema")` + - `Status status` - - `Optional description` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `IN_PROGRESS("in_progress")` - - `Optional strict` + - `COMPLETED("completed")` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `INCOMPLETE("incomplete")` - - `JsonValue;` + - `JsonValue; type "function_call_output"constant` - - `JsonValue; type "json_object"constant` + The type of the function tool call output. Always `function_call_output`. - The type of response format being defined. Always `json_object`. + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `JSON_OBJECT("json_object")` + - `Optional agent` - - `Optional verbosity` + The agent that produced this item. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `String agentName` - - `LOW("low")` + The canonical name of the agent that produced this item. - - `MEDIUM("medium")` + - `Optional caller` - - `HIGH("high")` + The execution context that produced this tool call. - - `Optional topLogprobs` + - `JsonValue;` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `JsonValue; type "direct"constant` - - `Optional truncation` + The caller type. Always `direct`. - The truncation strategy to use for the model response. + - `DIRECT("direct")` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `class Program:` - - `AUTO("auto")` + - `String callerId` - - `DISABLED("disabled")` + The call ID of the program item that produced this tool call. - - `Optional usage` + - `JsonValue; type "program"constant` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The caller type. Always `program`. - - `long inputTokens` + - `PROGRAM("program")` - The number of input tokens. + - `Optional createdBy` - - `InputTokensDetails inputTokensDetails` + The identifier of the actor that created the item. - A detailed breakdown of the input tokens. + - `AgentMessage` - - `long cacheWriteTokens` + - `String id` - The number of input tokens that were written to the cache. + The unique ID of the agent message. - - `long cachedTokens` + - `String author` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The sending agent identity. - - `long outputTokens` + - `List content` - The number of output tokens. + Encrypted content sent between agents. - - `OutputTokensDetails outputTokensDetails` + - `class BetaResponseInputText:` - A detailed breakdown of the output tokens. + A text input to the model. - - `long reasoningTokens` + - `class BetaResponseOutputText:` - The number of reasoning tokens. + A text output from the model. - - `long totalTokens` + - `class Text:` - The total number of tokens used. + A text content. - - `Optional user` + - `String text` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `JsonValue; type "text"constant` - - `long sequenceNumber` + - `TEXT("text")` - The sequence number of this event. + - `class SummaryText:` - - `JsonValue; type "response.failed"constant` + A summary text from the model. - The type of the event. Always `response.failed`. + - `String text` - - `RESPONSE_FAILED("response.failed")` + A summary of the reasoning output from the model so far. - - `Optional agent` + - `JsonValue; type "summary_text"constant` - The agent that owns this multi-agent streaming event. + The type of the object. Always `summary_text`. - - `String agentName` + - `SUMMARY_TEXT("summary_text")` - The canonical name of the agent that produced this item. + - `class ReasoningText:` -### Beta Response File Search Call Completed Event + Reasoning text from the model. -- `class BetaResponseFileSearchCallCompletedEvent:` + - `String text` - Emitted when a file search call is completed (results found). + The reasoning text from the model. - - `String itemId` + - `JsonValue; type "reasoning_text"constant` - The ID of the output item that the file search call is initiated. + The type of the reasoning text. Always `reasoning_text`. - - `long outputIndex` + - `REASONING_TEXT("reasoning_text")` - The index of the output item that the file search call is initiated. + - `class BetaResponseOutputRefusal:` - - `long sequenceNumber` + A refusal from the model. - The sequence number of this event. + - `class BetaResponseInputImage:` - - `JsonValue; type "response.file_search_call.completed"constant` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The type of the event. Always `response.file_search_call.completed`. + - `class ComputerScreenshot:` - - `RESPONSE_FILE_SEARCH_CALL_COMPLETED("response.file_search_call.completed")` + A screenshot of a computer. - - `Optional agent` + - `Detail detail` - The agent that owns this multi-agent streaming event. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String agentName` + - `LOW("low")` - The canonical name of the agent that produced this item. + - `HIGH("high")` -### Beta Response File Search Call In Progress Event + - `AUTO("auto")` -- `class BetaResponseFileSearchCallInProgressEvent:` + - `ORIGINAL("original")` - Emitted when a file search call is initiated. + - `Optional fileId` - - `String itemId` + The identifier of an uploaded file that contains the screenshot. - The ID of the output item that the file search call is initiated. + - `Optional imageUrl` - - `long outputIndex` + The URL of the screenshot image. - The index of the output item that the file search call is initiated. + - `JsonValue; type "computer_screenshot"constant` - - `long sequenceNumber` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The sequence number of this event. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `JsonValue; type "response.file_search_call.in_progress"constant` + - `Optional promptCacheBreakpoint` - The type of the event. Always `response.file_search_call.in_progress`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `RESPONSE_FILE_SEARCH_CALL_IN_PROGRESS("response.file_search_call.in_progress")` + - `JsonValue; mode "explicit"constant` - - `Optional agent` + The breakpoint mode. Always `explicit`. - The agent that owns this multi-agent streaming event. + - `EXPLICIT("explicit")` - - `String agentName` + - `class BetaResponseInputFile:` - The canonical name of the agent that produced this item. + A file input to the model. -### Beta Response File Search Call Searching Event + - `class EncryptedContent:` -- `class BetaResponseFileSearchCallSearchingEvent:` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - Emitted when a file search is currently searching. + - `String encryptedContent` - - `String itemId` + Opaque encrypted content. - The ID of the output item that the file search call is initiated. + - `JsonValue; type "encrypted_content"constant` - - `long outputIndex` + The type of the input item. Always `encrypted_content`. - The index of the output item that the file search call is searching. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `long sequenceNumber` + - `String recipient` - The sequence number of this event. + The destination agent identity. - - `JsonValue; type "response.file_search_call.searching"constant` + - `JsonValue; type "agent_message"constant` - The type of the event. Always `response.file_search_call.searching`. + The type of the item. Always `agent_message`. - - `RESPONSE_FILE_SEARCH_CALL_SEARCHING("response.file_search_call.searching")` + - `AGENT_MESSAGE("agent_message")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. -### Beta Response File Search Tool Call + - `MultiAgentCall` -- `class BetaResponseFileSearchToolCall:` + - `String id` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + The unique ID of the multi-agent call item. - - `String id` + - `Action action` - The unique ID of the file search tool call. + The multi-agent action to execute. - - `List queries` + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` - The queries used to search for files. + - `LIST_AGENTS("list_agents")` - - `Status status` + - `SEND_MESSAGE("send_message")` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `FOLLOWUP_TASK("followup_task")` - - `IN_PROGRESS("in_progress")` + - `WAIT_AGENT("wait_agent")` - - `SEARCHING("searching")` + - `String arguments` - - `COMPLETED("completed")` + The JSON string of arguments generated for the action. - - `INCOMPLETE("incomplete")` + - `String callId` - - `FAILED("failed")` + The unique ID linking this call to its output. - - `JsonValue; type "file_search_call"constant` + - `JsonValue; type "multi_agent_call"constant` - The type of the file search tool call. Always `file_search_call`. + The type of the multi-agent call. Always `multi_agent_call`. - - `FILE_SEARCH_CALL("file_search_call")` + - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional agent` @@ -76788,1382 +90243,1422 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional> results` + - `MultiAgentCallOutput` - The results of the file search tool call. + - `String id` - - `Optional attributes` + The unique ID of the multi-agent call output item. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `Action action` - - `String` + The multi-agent action that produced this result. - - `double` + - `SPAWN_AGENT("spawn_agent")` - - `boolean` + - `INTERRUPT_AGENT("interrupt_agent")` - - `Optional fileId` + - `LIST_AGENTS("list_agents")` - The unique ID of the file. + - `SEND_MESSAGE("send_message")` - - `Optional filename` + - `FOLLOWUP_TASK("followup_task")` - The name of the file. + - `WAIT_AGENT("wait_agent")` - - `Optional score` + - `String callId` - The relevance score of the file - a value between 0 and 1. + The unique ID of the multi-agent call. - - `Optional text` + - `List output` - The text that was retrieved from the file. + Text output returned by the multi-agent action. -### Beta Response Format Text Config + - `List annotations` -- `class BetaResponseFormatTextConfig: A class that can be one of several variants.union` + The annotations of the text output. - An object specifying the format that the model must output. + - `String text` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The text output from the model. - The default format is `{ "type": "text" }` with no additional options. + - `JsonValue; type "output_text"constant` - **Not recommended for gpt-4o and newer models:** + The type of the output text. Always `output_text`. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `Optional> logprobs` - - `JsonValue;` + - `JsonValue; type "multi_agent_call_output"constant` - - `JsonValue; type "text"constant` + The type of the multi-agent result. Always `multi_agent_call_output`. - The type of response format being defined. Always `text`. + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `TEXT("text")` + - `Optional agent` - - `class BetaResponseFormatTextJsonSchemaConfig:` + The agent that produced this item. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `String agentName` - - `String name` + The canonical name of the agent that produced this item. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `class BetaResponseToolSearchCall:` - - `Schema schema` + - `String id` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The unique ID of the tool search call item. - - `JsonValue; type "json_schema"constant` + - `JsonValue arguments` - The type of response format being defined. Always `json_schema`. + Arguments used for the tool search call. - - `JSON_SCHEMA("json_schema")` + - `Optional callId` - - `Optional description` + The unique ID of the tool search call generated by the model. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Execution execution` - - `Optional strict` + Whether tool search was executed by the server or by the client. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `SERVER("server")` - - `JsonValue;` + - `CLIENT("client")` - - `JsonValue; type "json_object"constant` + - `Status status` - The type of response format being defined. Always `json_object`. + The status of the tool search call item that was recorded. - - `JSON_OBJECT("json_object")` + - `IN_PROGRESS("in_progress")` -### Beta Response Format Text JSON Schema Config + - `COMPLETED("completed")` -- `class BetaResponseFormatTextJsonSchemaConfig:` + - `INCOMPLETE("incomplete")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `JsonValue; type "tool_search_call"constant` - - `String name` + The type of the item. Always `tool_search_call`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `TOOL_SEARCH_CALL("tool_search_call")` - - `Schema schema` + - `Optional agent` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The agent that produced this item. - - `JsonValue; type "json_schema"constant` + - `String agentName` - The type of response format being defined. Always `json_schema`. + The canonical name of the agent that produced this item. - - `JSON_SCHEMA("json_schema")` + - `Optional createdBy` - - `Optional description` + The identifier of the actor that created the item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `class BetaResponseToolSearchOutputItem:` - - `Optional strict` + - `String id` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The unique ID of the tool search output item. -### Beta Response Function Call Arguments Delta Event + - `Optional callId` -- `class BetaResponseFunctionCallArgumentsDeltaEvent:` + The unique ID of the tool search call generated by the model. - Emitted when there is a partial function-call arguments delta. + - `Execution execution` - - `String delta` + Whether tool search was executed by the server or by the client. - The function-call arguments delta that is added. + - `SERVER("server")` - - `String itemId` + - `CLIENT("client")` - The ID of the output item that the function-call arguments delta is added to. + - `Status status` - - `long outputIndex` + The status of the tool search output item that was recorded. - The index of the output item that the function-call arguments delta is added to. + - `IN_PROGRESS("in_progress")` - - `long sequenceNumber` + - `COMPLETED("completed")` - The sequence number of this event. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "response.function_call_arguments.delta"constant` + - `List tools` - The type of the event. Always `response.function_call_arguments.delta`. + The loaded tool definitions returned by tool search. - - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DELTA("response.function_call_arguments.delta")` + - `class BetaFunctionTool:` - - `Optional agent` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The agent that owns this multi-agent streaming event. + - `String name` - - `String agentName` + The name of the function to call. - The canonical name of the agent that produced this item. + - `Optional parameters` -### Beta Response Function Call Arguments Done Event + A JSON schema object describing the parameters of the function. -- `class BetaResponseFunctionCallArgumentsDoneEvent:` + - `Optional strict` - Emitted when function-call arguments are finalized. + Whether strict parameter validation is enforced for this function tool. - - `String arguments` + - `JsonValue; type "function"constant` - The function-call arguments. + The type of the function tool. Always `function`. - - `String itemId` + - `FUNCTION("function")` - The ID of the item. + - `Optional> allowedCallers` - - `String name` + The tool invocation context(s). - The name of the function that was called. + - `DIRECT("direct")` - - `long outputIndex` + - `PROGRAMMATIC("programmatic")` - The index of the output item. + - `Optional deferLoading` - - `long sequenceNumber` + Whether this function is deferred and loaded via tool search. - The sequence number of this event. + - `Optional description` - - `JsonValue; type "response.function_call_arguments.done"constant` + A description of the function. Used by the model to determine whether or not to call the function. - - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DONE("response.function_call_arguments.done")` + - `Optional outputSchema` - - `Optional agent` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The agent that owns this multi-agent streaming event. + - `class BetaFileSearchTool:` - - `String agentName` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The canonical name of the agent that produced this item. + - `JsonValue; type "file_search"constant` -### Beta Response Function Call Output Item + The type of the file search tool. Always `file_search`. -- `class BetaResponseFunctionCallOutputItem: A class that can be one of several variants.union` + - `FILE_SEARCH("file_search")` - A piece of message content, such as text, an image, or a file. + - `List vectorStoreIds` - - `class BetaResponseInputTextContent:` + The IDs of the vector stores to search. - A text input to the model. + - `Optional filters` - - `String text` + A filter to apply. - The text input to the model. + - `class ComparisonFilter:` - - `JsonValue; type "input_text"constant` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the input item. Always `input_text`. + - `String key` - - `INPUT_TEXT("input_text")` + The key to compare against the value. - - `Optional promptCacheBreakpoint` + - `Type type` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `JsonValue; mode "explicit"constant` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The breakpoint mode. Always `explicit`. + - `EQ("eq")` - - `EXPLICIT("explicit")` + - `NE("ne")` - - `class BetaResponseInputImageContent:` + - `GT("gt")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `GTE("gte")` - - `JsonValue; type "input_image"constant` + - `LT("lt")` - The type of the input item. Always `input_image`. + - `LTE("lte")` - - `INPUT_IMAGE("input_image")` + - `IN("in")` - - `Optional detail` + - `NIN("nin")` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Value value` - - `LOW("low")` + The value to compare against the attribute key; supports string, number, or boolean types. - - `HIGH("high")` + - `String` - - `AUTO("auto")` + - `double` - - `ORIGINAL("original")` + - `boolean` - - `Optional fileId` + - `List` - The ID of the file to be sent to the model. + - `String` - - `Optional imageUrl` + - `double` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class CompoundFilter:` - - `Optional promptCacheBreakpoint` + Combine multiple filters using `and` or `or`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `List filters` - - `JsonValue; mode "explicit"constant` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The breakpoint mode. Always `explicit`. + - `class ComparisonFilter:` - - `EXPLICIT("explicit")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `class BetaResponseInputFileContent:` + - `String key` - A file input to the model. + The key to compare against the value. - - `JsonValue; type "input_file"constant` + - `Type type` - The type of the input item. Always `input_file`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `INPUT_FILE("input_file")` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Optional detail` + - `EQ("eq")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `NE("ne")` - - `AUTO("auto")` + - `GT("gt")` - - `LOW("low")` + - `GTE("gte")` - - `HIGH("high")` + - `LT("lt")` - - `Optional fileData` + - `LTE("lte")` - The base64-encoded data of the file to be sent to the model. + - `IN("in")` - - `Optional fileId` + - `NIN("nin")` - The ID of the file to be sent to the model. + - `Value value` - - `Optional fileUrl` + The value to compare against the attribute key; supports string, number, or boolean types. - The URL of the file to be sent to the model. + - `String` - - `Optional filename` + - `double` - The name of the file to be sent to the model. + - `boolean` - - `Optional promptCacheBreakpoint` + - `List` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String` - - `JsonValue; mode "explicit"constant` + - `double` - The breakpoint mode. Always `explicit`. + - `JsonValue` - - `EXPLICIT("explicit")` + - `Type type` -### Beta Response Function Shell Call Output Content + Type of operation: `and` or `or`. -- `class BetaResponseFunctionShellCallOutputContent:` + - `AND("and")` - Captured stdout and stderr for a portion of a shell tool call output. + - `OR("or")` - - `Outcome outcome` + - `Optional maxNumResults` - The exit or timeout outcome associated with this shell call. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `JsonValue;` + - `Optional rankingOptions` - - `JsonValue; type "timeout"constant` + Ranking options for search. - The outcome type. Always `timeout`. + - `Optional hybridSearch` - - `TIMEOUT("timeout")` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `class Exit:` + - `double embeddingWeight` - Indicates that the shell commands finished and returned an exit code. + The weight of the embedding in the reciprocal ranking fusion. - - `long exitCode` + - `double textWeight` - The exit code returned by the shell process. + The weight of the text in the reciprocal ranking fusion. - - `JsonValue; type "exit"constant` + - `Optional ranker` - The outcome type. Always `exit`. + The ranker to use for the file search. - - `EXIT("exit")` + - `AUTO("auto")` - - `String stderr` + - `DEFAULT_2024_11_15("default-2024-11-15")` - Captured stderr output for the shell call. + - `Optional scoreThreshold` - - `String stdout` + 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. - Captured stdout output for the shell call. + - `class BetaComputerTool:` -### Beta Response Function Shell Tool Call + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -- `class BetaResponseFunctionShellToolCall:` + - `JsonValue; type "computer"constant` - A tool call that executes one or more shell commands in a managed environment. + The type of the computer tool. Always `computer`. - - `String id` + - `COMPUTER("computer")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `class BetaComputerUsePreviewTool:` - - `Action action` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The shell commands and limits that describe how to run the tool call. + - `long displayHeight` - - `List commands` + The height of the computer display. - - `Optional maxOutputLength` + - `long displayWidth` - Optional maximum number of characters to return from each command. + The width of the computer display. - - `Optional timeoutMs` + - `Environment environment` - Optional timeout in milliseconds for the commands. + The type of computer environment to control. - - `String callId` + - `WINDOWS("windows")` - The unique ID of the shell tool call generated by the model. + - `MAC("mac")` - - `Optional environment` + - `LINUX("linux")` - Represents the use of a local environment to perform shell actions. + - `UBUNTU("ubuntu")` - - `class BetaResponseLocalEnvironment:` + - `BROWSER("browser")` - Represents the use of a local environment to perform shell actions. + - `JsonValue; type "computer_use_preview"constant` - - `JsonValue; type "local"constant` + The type of the computer use tool. Always `computer_use_preview`. - The environment type. Always `local`. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `LOCAL("local")` + - `class BetaWebSearchTool:` - - `class BetaResponseContainerReference:` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Represents a container created with /v1/containers. + - `Type type` - - `String containerId` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `JsonValue; type "container_reference"constant` + - `WEB_SEARCH("web_search")` - The environment type. Always `container_reference`. + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `CONTAINER_REFERENCE("container_reference")` + - `Optional filters` - - `Status status` + Filters for the search. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `Optional> allowedDomains` - - `IN_PROGRESS("in_progress")` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `COMPLETED("completed")` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `INCOMPLETE("incomplete")` + - `Optional searchContextSize` - - `JsonValue; type "shell_call"constant` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The type of the item. Always `shell_call`. + - `LOW("low")` - - `SHELL_CALL("shell_call")` + - `MEDIUM("medium")` - - `Optional agent` + - `HIGH("high")` - The agent that produced this item. + - `Optional userLocation` - - `String agentName` + The approximate location of the user. - The canonical name of the agent that produced this item. + - `Optional city` - - `Optional caller` + Free text input for the city of the user, e.g. `San Francisco`. - The execution context that produced this tool call. + - `Optional country` - - `JsonValue;` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `JsonValue; type "direct"constant` + - `Optional region` - - `DIRECT("direct")` + Free text input for the region of the user, e.g. `California`. - - `class Program:` + - `Optional timezone` - - `String callerId` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The call ID of the program item that produced this tool call. + - `Optional type` - - `JsonValue; type "program"constant` + The type of location approximation. Always `approximate`. - - `PROGRAM("program")` + - `APPROXIMATE("approximate")` - - `Optional createdBy` + - `Mcp` - The ID of the entity that created this tool call. + - `String serverLabel` -### Beta Response Function Shell Tool Call Output + A label for this MCP server, used to identify it in tool calls. -- `class BetaResponseFunctionShellToolCallOutput:` + - `JsonValue; type "mcp"constant` - The output of a shell tool call that was emitted. + The type of the MCP tool. Always `mcp`. - - `String id` + - `MCP("mcp")` - The unique ID of the shell call output. Populated when this item is returned via API. + - `Optional> allowedCallers` - - `String callId` + The tool invocation context(s). - The unique ID of the shell tool call generated by the model. + - `DIRECT("direct")` - - `Optional maxOutputLength` + - `PROGRAMMATIC("programmatic")` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `Optional allowedTools` - - `List output` + List of allowed tool names or a filter object. - An array of shell call output contents + - `List` - - `Outcome outcome` + - `class McpToolFilter:` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + A filter object to specify which tools are allowed. - - `JsonValue;` + - `Optional readOnly` - - `JsonValue; type "timeout"constant` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The outcome type. Always `timeout`. + - `Optional> toolNames` - - `TIMEOUT("timeout")` + List of allowed tool names. - - `class Exit:` + - `Optional authorization` - Indicates that the shell commands finished and returned an exit code. + 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. - - `long exitCode` + - `Optional connectorId` - Exit code from the shell process. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `JsonValue; type "exit"constant` + Currently supported `connector_id` values are: - The outcome type. Always `exit`. + - 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` - - `EXIT("exit")` + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `String stderr` + - `CONNECTOR_GMAIL("connector_gmail")` - The standard error output that was captured. + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `String stdout` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - The standard output that was captured. + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `Optional createdBy` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - The identifier of the actor that created the item. + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `Status status` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `Optional deferLoading` - - `IN_PROGRESS("in_progress")` + Whether this MCP tool is deferred and discovered via tool search. - - `COMPLETED("completed")` + - `Optional headers` - - `INCOMPLETE("incomplete")` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `JsonValue; type "shell_call_output"constant` + - `Optional requireApproval` - The type of the shell call output. Always `shell_call_output`. + Specify which of the MCP server's tools require approval. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `class McpToolApprovalFilter:` - - `Optional agent` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The agent that produced this item. + - `Optional always` - - `String agentName` + A filter object to specify which tools are allowed. - The canonical name of the agent that produced this item. + - `Optional readOnly` - - `Optional caller` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The execution context that produced this tool call. + - `Optional> toolNames` - - `JsonValue;` + List of allowed tool names. - - `JsonValue; type "direct"constant` + - `Optional never` - - `DIRECT("direct")` + A filter object to specify which tools are allowed. - - `class Program:` + - `Optional readOnly` - - `String callerId` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The call ID of the program item that produced this tool call. + - `Optional> toolNames` - - `JsonValue; type "program"constant` + List of allowed tool names. - - `PROGRAM("program")` + - `enum McpToolApprovalSetting:` - - `Optional createdBy` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The identifier of the actor that created the item. + - `ALWAYS("always")` -### Beta Response Function Tool Call + - `NEVER("never")` -- `class BetaResponseFunctionToolCall:` + - `Optional serverDescription` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Optional description of the MCP server, used to provide more context. - - `String arguments` + - `Optional serverUrl` - A JSON string of the arguments to pass to the function. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `String callId` + - `Optional tunnelId` - The unique ID of the function tool call generated by the model. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `String name` + - `CodeInterpreter` - The name of the function to run. + - `Container container` - - `JsonValue; type "function_call"constant` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of the function tool call. Always `function_call`. + - `String` - - `FUNCTION_CALL("function_call")` + - `class CodeInterpreterToolAuto:` - - `Optional id` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The unique ID of the function tool call. + - `JsonValue; type "auto"constant` - - `Optional agent` + Always `auto`. - The agent that produced this item. + - `AUTO("auto")` - - `String agentName` + - `Optional> fileIds` - The canonical name of the agent that produced this item. + An optional list of uploaded files to make available to your code. - - `Optional caller` + - `Optional memoryLimit` - The execution context that produced this tool call. + The memory limit for the code interpreter container. - - `JsonValue;` + - `_1G("1g")` - - `JsonValue; type "direct"constant` + - `_4G("4g")` - - `DIRECT("direct")` + - `_16G("16g")` - - `class Program:` + - `_64G("64g")` - - `String callerId` + - `Optional networkPolicy` - The call ID of the program item that produced this tool call. + Network access policy for the container. - - `JsonValue; type "program"constant` + - `class BetaContainerNetworkPolicyDisabled:` - - `PROGRAM("program")` + - `JsonValue; type "disabled"constant` - - `Optional namespace` + Disable outbound network access. Always `disabled`. - The namespace of the function to run. + - `DISABLED("disabled")` - - `Optional status` + - `class BetaContainerNetworkPolicyAllowlist:` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `List allowedDomains` - - `IN_PROGRESS("in_progress")` + A list of allowed domains when type is `allowlist`. - - `COMPLETED("completed")` + - `JsonValue; type "allowlist"constant` - - `INCOMPLETE("incomplete")` + Allow outbound network access only to specified domains. Always `allowlist`. -### Beta Response Function Tool Call Item + - `ALLOWLIST("allowlist")` -- `class BetaResponseFunctionToolCallItem:` + - `Optional> domainSecrets` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Optional domain-scoped secrets for allowlisted domains. - - `String id` + - `String domain` - The unique ID of the function tool call. + The domain associated with the secret. - - `Status status` + - `String name` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the secret to inject for the domain. - - `IN_PROGRESS("in_progress")` + - `String value` - - `COMPLETED("completed")` + The secret value to inject for the domain. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "code_interpreter"constant` - - `Optional createdBy` + The type of the code interpreter tool. Always `code_interpreter`. - The identifier of the actor that created the item. + - `CODE_INTERPRETER("code_interpreter")` -### Beta Response Function Tool Call Output Item + - `Optional> allowedCallers` -- `class BetaResponseFunctionToolCallOutputItem:` + The tool invocation context(s). - - `String id` + - `DIRECT("direct")` - The unique ID of the function call tool output. + - `PROGRAMMATIC("programmatic")` - - `String callId` + - `JsonValue;` - The unique ID of the function tool call generated by the model. + - `JsonValue; type "programmatic_tool_calling"constant` - - `Output output` + The type of the tool. Always `programmatic_tool_calling`. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `String` + - `ImageGeneration` - - `List` + - `JsonValue; type "image_generation"constant` - - `class BetaResponseInputText:` + The type of the image generation tool. Always `image_generation`. - A text input to the model. + - `IMAGE_GENERATION("image_generation")` - - `String text` + - `Optional action` - The text input to the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `JsonValue; type "input_text"constant` + - `GENERATE("generate")` - The type of the input item. Always `input_text`. + - `EDIT("edit")` - - `INPUT_TEXT("input_text")` + - `AUTO("auto")` - - `Optional promptCacheBreakpoint` + - `Optional background` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `JsonValue; mode "explicit"constant` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The breakpoint mode. Always `explicit`. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `EXPLICIT("explicit")` + - `TRANSPARENT("transparent")` - - `class BetaResponseInputImage:` + - `OPAQUE("opaque")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `AUTO("auto")` - - `Detail detail` + - `Optional inputFidelity` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `HIGH("high")` - `LOW("low")` - - `HIGH("high")` + - `Optional inputImageMask` - - `AUTO("auto")` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `ORIGINAL("original")` + - `Optional fileId` - - `JsonValue; type "input_image"constant` + File ID for the mask image. - The type of the input item. Always `input_image`. + - `Optional imageUrl` - - `INPUT_IMAGE("input_image")` + Base64-encoded mask image. - - `Optional fileId` + - `Optional model` - The ID of the file to be sent to the model. + The image generation model to use. Default: `gpt-image-1`. - - `Optional imageUrl` + - `GPT_IMAGE_1("gpt-image-1")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `Optional promptCacheBreakpoint` + - `GPT_IMAGE_2("gpt-image-2")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `JsonValue; mode "explicit"constant` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - The breakpoint mode. Always `explicit`. + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `EXPLICIT("explicit")` + - `Optional moderation` - - `class BetaResponseInputFile:` + Moderation level for the generated image. Default: `auto`. - A file input to the model. + - `AUTO("auto")` - - `JsonValue; type "input_file"constant` + - `LOW("low")` - The type of the input item. Always `input_file`. + - `Optional outputCompression` - - `INPUT_FILE("input_file")` + Compression level for the output image. Default: 100. - - `Optional detail` + - `Optional outputFormat` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `AUTO("auto")` + - `PNG("png")` + + - `WEBP("webp")` + + - `JPEG("jpeg")` + + - `Optional partialImages` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `Optional quality` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - `LOW("low")` + - `MEDIUM("medium")` + - `HIGH("high")` - - `Optional fileData` + - `AUTO("auto")` - The content of the file to be sent to the model. + - `Optional size` - - `Optional fileId` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The ID of the file to be sent to the model. + - `_1024X1024("1024x1024")` - - `Optional fileUrl` + - `_1024X1536("1024x1536")` - The URL of the file to be sent to the model. + - `_1536X1024("1536x1024")` - - `Optional filename` + - `AUTO("auto")` - The name of the file to be sent to the model. + - `JsonValue;` - - `Optional promptCacheBreakpoint` + - `JsonValue; type "local_shell"constant` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The type of the local shell tool. Always `local_shell`. - - `JsonValue; mode "explicit"constant` + - `LOCAL_SHELL("local_shell")` - The breakpoint mode. Always `explicit`. + - `class BetaFunctionShellTool:` - - `EXPLICIT("explicit")` + A tool that allows the model to execute shell commands. - - `Status status` + - `JsonValue; type "shell"constant` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the shell tool. Always `shell`. - - `IN_PROGRESS("in_progress")` + - `SHELL("shell")` - - `COMPLETED("completed")` + - `Optional> allowedCallers` - - `INCOMPLETE("incomplete")` + The tool invocation context(s). - - `JsonValue; type "function_call_output"constant` + - `DIRECT("direct")` - The type of the function tool call output. Always `function_call_output`. + - `PROGRAMMATIC("programmatic")` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `Optional environment` - - `Optional agent` + - `class BetaContainerAuto:` - The agent that produced this item. + - `JsonValue; type "container_auto"constant` - - `String agentName` + Automatically creates a container for this request - The canonical name of the agent that produced this item. + - `CONTAINER_AUTO("container_auto")` - - `Optional caller` + - `Optional> fileIds` - The execution context that produced this tool call. + An optional list of uploaded files to make available to your code. - - `JsonValue;` + - `Optional memoryLimit` - - `JsonValue; type "direct"constant` + The memory limit for the container. - The caller type. Always `direct`. + - `_1G("1g")` - - `DIRECT("direct")` + - `_4G("4g")` - - `class Program:` + - `_16G("16g")` - - `String callerId` + - `_64G("64g")` - The call ID of the program item that produced this tool call. + - `Optional networkPolicy` - - `JsonValue; type "program"constant` + Network access policy for the container. - The caller type. Always `program`. + - `class BetaContainerNetworkPolicyDisabled:` - - `PROGRAM("program")` + - `class BetaContainerNetworkPolicyAllowlist:` - - `Optional createdBy` + - `Optional> skills` - The identifier of the actor that created the item. + An optional list of skills referenced by id or inline data. -### Beta Response Function Web Search + - `class BetaSkillReference:` -- `class BetaResponseFunctionWebSearch:` + - `String skillId` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The ID of the referenced skill. - - `String id` + - `JsonValue; type "skill_reference"constant` - The unique ID of the web search tool call. + References a skill created with the /v1/skills endpoint. - - `Action action` + - `SKILL_REFERENCE("skill_reference")` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `Optional version` - - `class Search:` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Action type "search" - Performs a web search query. + - `class BetaInlineSkill:` - - `JsonValue; type "search"constant` + - `String description` - The action type. + The description of the skill. - - `SEARCH("search")` + - `String name` - - `Optional> queries` + The name of the skill. - The search queries. + - `BetaInlineSkillSource source` - - `Optional query` + Inline skill payload - The search query. + - `String data` - - `Optional> sources` + Base64-encoded skill zip bundle. - The sources used in the search. + - `JsonValue; mediaType "application/zip"constant` - - `JsonValue; type "url"constant` + The media type of the inline skill payload. Must be `application/zip`. - The type of source. Always `url`. + - `APPLICATION_ZIP("application/zip")` - - `URL("url")` + - `JsonValue; type "base64"constant` - - `String url` + The type of the inline skill source. Must be `base64`. - The URL of the source. + - `BASE64("base64")` - - `class OpenPage:` + - `JsonValue; type "inline"constant` - Action type "open_page" - Opens a specific URL from search results. + Defines an inline skill for this request. - - `JsonValue; type "open_page"constant` + - `INLINE("inline")` - The action type. + - `class BetaLocalEnvironment:` - - `OPEN_PAGE("open_page")` + - `JsonValue; type "local"constant` - - `Optional url` + Use a local computer environment. - The URL opened by the model. + - `LOCAL("local")` - - `class FindInPage:` + - `Optional> skills` - Action type "find_in_page": Searches for a pattern within a loaded page. + An optional list of skills. - - `String pattern` + - `String description` - The pattern or text to search for within the page. + The description of the skill. - - `JsonValue; type "find_in_page"constant` + - `String name` + + The name of the skill. + + - `String path` + + The path to the directory containing the skill. + + - `class BetaContainerReference:` - The action type. + - `String containerId` - - `FIND_IN_PAGE("find_in_page")` + The ID of the referenced container. - - `String url` + - `JsonValue; type "container_reference"constant` - The URL of the page searched for the pattern. + References a container created with the /v1/containers endpoint - - `Status status` + - `CONTAINER_REFERENCE("container_reference")` - The status of the web search tool call. + - `class BetaCustomTool:` - - `IN_PROGRESS("in_progress")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `SEARCHING("searching")` + - `String name` - - `COMPLETED("completed")` + The name of the custom tool, used to identify it in tool calls. - - `FAILED("failed")` + - `JsonValue; type "custom"constant` - - `JsonValue; type "web_search_call"constant` + The type of the custom tool. Always `custom`. - The type of the web search tool call. Always `web_search_call`. + - `CUSTOM("custom")` - - `WEB_SEARCH_CALL("web_search_call")` + - `Optional> allowedCallers` - - `Optional agent` + The tool invocation context(s). - The agent that produced this item. + - `DIRECT("direct")` - - `String agentName` + - `PROGRAMMATIC("programmatic")` - The canonical name of the agent that produced this item. + - `Optional deferLoading` -### Beta Response Image Gen Call Completed Event + Whether this tool should be deferred and discovered via tool search. -- `class BetaResponseImageGenCallCompletedEvent:` + - `Optional description` - Emitted when an image generation tool call has completed and the final image is available. + Optional description of the custom tool, used to provide more context. - - `String itemId` + - `Optional format` - The unique identifier of the image generation item being processed. + The input format for the custom tool. Default is unconstrained text. - - `long outputIndex` + - `JsonValue;` - The index of the output item in the response's output array. + - `JsonValue; type "text"constant` - - `long sequenceNumber` + Unconstrained text format. Always `text`. - The sequence number of this event. + - `TEXT("text")` - - `JsonValue; type "response.image_generation_call.completed"constant` + - `class Grammar:` - The type of the event. Always 'response.image_generation_call.completed'. + A grammar defined by the user. - - `RESPONSE_IMAGE_GENERATION_CALL_COMPLETED("response.image_generation_call.completed")` + - `String definition` - - `Optional agent` + The grammar definition. - The agent that owns this multi-agent streaming event. + - `Syntax syntax` - - `String agentName` + The syntax of the grammar definition. One of `lark` or `regex`. - The canonical name of the agent that produced this item. + - `LARK("lark")` -### Beta Response Image Gen Call Generating Event + - `REGEX("regex")` -- `class BetaResponseImageGenCallGeneratingEvent:` + - `JsonValue; type "grammar"constant` - Emitted when an image generation tool call is actively generating an image (intermediate state). + Grammar format. Always `grammar`. - - `String itemId` + - `GRAMMAR("grammar")` - The unique identifier of the image generation item being processed. + - `class BetaNamespaceTool:` - - `long outputIndex` + Groups function/custom tools under a shared namespace. - The index of the output item in the response's output array. + - `String description` - - `long sequenceNumber` + A description of the namespace shown to the model. - The sequence number of the image generation item being processed. + - `String name` - - `JsonValue; type "response.image_generation_call.generating"constant` + The namespace name used in tool calls (for example, `crm`). - The type of the event. Always 'response.image_generation_call.generating'. + - `List tools` - - `RESPONSE_IMAGE_GENERATION_CALL_GENERATING("response.image_generation_call.generating")` + The function/custom tools available inside this namespace. - - `Optional agent` + - `class Function:` - The agent that owns this multi-agent streaming event. + - `String name` - - `String agentName` + - `JsonValue; type "function"constant` - The canonical name of the agent that produced this item. + - `FUNCTION("function")` -### Beta Response Image Gen Call In Progress Event + - `Optional> allowedCallers` -- `class BetaResponseImageGenCallInProgressEvent:` + The tool invocation context(s). - Emitted when an image generation tool call is in progress. + - `DIRECT("direct")` - - `String itemId` + - `PROGRAMMATIC("programmatic")` - The unique identifier of the image generation item being processed. + - `Optional deferLoading` - - `long outputIndex` + Whether this function should be deferred and discovered via tool search. - The index of the output item in the response's output array. + - `Optional description` - - `long sequenceNumber` + - `Optional outputSchema` - The sequence number of the image generation item being processed. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `JsonValue; type "response.image_generation_call.in_progress"constant` + - `Optional parameters` - The type of the event. Always 'response.image_generation_call.in_progress'. + - `Optional strict` - - `RESPONSE_IMAGE_GENERATION_CALL_IN_PROGRESS("response.image_generation_call.in_progress")` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `Optional agent` + - `class BetaCustomTool:` - The agent that owns this multi-agent streaming event. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `String agentName` + - `JsonValue; type "namespace"constant` - The canonical name of the agent that produced this item. + The type of the tool. Always `namespace`. -### Beta Response Image Gen Call Partial Image Event + - `NAMESPACE("namespace")` -- `class BetaResponseImageGenCallPartialImageEvent:` + - `class BetaToolSearchTool:` - Emitted when a partial image is available during image generation streaming. + Hosted or BYOT tool search configuration for deferred tools. - - `String itemId` + - `JsonValue; type "tool_search"constant` - The unique identifier of the image generation item being processed. + The type of the tool. Always `tool_search`. - - `long outputIndex` + - `TOOL_SEARCH("tool_search")` - The index of the output item in the response's output array. + - `Optional description` - - `String partialImageB64` + Description shown to the model for a client-executed tool search tool. - Base64-encoded partial image data, suitable for rendering as an image. + - `Optional execution` - - `long partialImageIndex` + Whether tool search is executed by the server or by the client. - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `SERVER("server")` - - `long sequenceNumber` + - `CLIENT("client")` - The sequence number of the image generation item being processed. + - `Optional parameters` - - `JsonValue; type "response.image_generation_call.partial_image"constant` + Parameter schema for a client-executed tool search tool. - The type of the event. Always 'response.image_generation_call.partial_image'. + - `class BetaWebSearchPreviewTool:` - - `RESPONSE_IMAGE_GENERATION_CALL_PARTIAL_IMAGE("response.image_generation_call.partial_image")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional agent` + - `Type type` - The agent that owns this multi-agent streaming event. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `String agentName` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - The canonical name of the agent that produced this item. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` -### Beta Response In Progress Event + - `Optional> searchContentTypes` -- `class BetaResponseInProgressEvent:` + - `TEXT("text")` - Emitted when the response is in progress. + - `IMAGE("image")` - - `BetaResponse response` + - `Optional searchContextSize` - The response that is in progress. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `String id` + - `LOW("low")` - Unique identifier for this Response. + - `MEDIUM("medium")` - - `double createdAt` + - `HIGH("high")` - Unix timestamp (in seconds) of when this Response was created. + - `Optional userLocation` - - `Optional error` + The user's location. - An error object returned when the model fails to generate a Response. + - `JsonValue; type "approximate"constant` - - `Code code` + The type of location approximation. Always `approximate`. - The error code for the response. + - `APPROXIMATE("approximate")` - - `SERVER_ERROR("server_error")` + - `Optional city` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + Free text input for the city of the user, e.g. `San Francisco`. - - `INVALID_PROMPT("invalid_prompt")` + - `Optional country` - - `BIO_POLICY("bio_policy")` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + - `Optional region` - - `INVALID_IMAGE("invalid_image")` + Free text input for the region of the user, e.g. `California`. - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + - `Optional timezone` - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `INVALID_IMAGE_URL("invalid_image_url")` + - `class BetaApplyPatchTool:` - - `IMAGE_TOO_LARGE("image_too_large")` + Allows the assistant to create, delete, or update files using unified diffs. - - `IMAGE_TOO_SMALL("image_too_small")` + - `JsonValue; type "apply_patch"constant` - - `IMAGE_PARSE_ERROR("image_parse_error")` + The type of the tool. Always `apply_patch`. - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + - `APPLY_PATCH("apply_patch")` - - `INVALID_IMAGE_MODE("invalid_image_mode")` + - `Optional> allowedCallers` - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + The tool invocation context(s). - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + - `DIRECT("direct")` - - `EMPTY_IMAGE_FILE("empty_image_file")` + - `PROGRAMMATIC("programmatic")` - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + - `JsonValue; type "tool_search_output"constant` - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + The type of the item. Always `tool_search_output`. - - `String message` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - A human-readable description of the error. + - `Optional agent` - - `Optional incompleteDetails` + The agent that produced this item. - Details about why the response is incomplete. + - `String agentName` - - `Optional reason` + The canonical name of the agent that produced this item. - The reason why the response is incomplete. + - `Optional createdBy` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + The identifier of the actor that created the item. - - `CONTENT_FILTER("content_filter")` + - `AdditionalTools` - - `Optional instructions` + - `String id` - A system (or developer) message inserted into the model's context. + The unique ID of the additional tools item. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `Role role` - - `String` + The role that provided the additional tools. - - `List` + - `UNKNOWN("unknown")` - - `class BetaEasyInputMessage:` + - `USER("user")` - 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. + - `ASSISTANT("assistant")` - - `Content content` + - `SYSTEM("system")` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `CRITIC("critic")` - - `String` + - `DISCRIMINATOR("discriminator")` - - `List` + - `DEVELOPER("developer")` - - `class BetaResponseInputText:` + - `TOOL("tool")` - A text input to the model. + - `List tools` - - `String text` + The additional tool definitions made available at this item. - The text input to the model. + - `class BetaFunctionTool:` - - `JsonValue; type "input_text"constant` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of the input item. Always `input_text`. + - `class BetaFileSearchTool:` - - `INPUT_TEXT("input_text")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional promptCacheBreakpoint` + - `class BetaComputerTool:` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; mode "explicit"constant` + - `class BetaComputerUsePreviewTool:` - The breakpoint mode. Always `explicit`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `EXPLICIT("explicit")` + - `class BetaWebSearchTool:` - - `class BetaResponseInputImage:` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Mcp` - - `Detail detail` + - `CodeInterpreter` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `JsonValue;` - - `LOW("low")` + - `ImageGeneration` - - `HIGH("high")` + - `JsonValue;` - - `AUTO("auto")` + - `class BetaFunctionShellTool:` - - `ORIGINAL("original")` + A tool that allows the model to execute shell commands. - - `JsonValue; type "input_image"constant` + - `class BetaCustomTool:` - The type of the input item. Always `input_image`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `INPUT_IMAGE("input_image")` + - `class BetaNamespaceTool:` - - `Optional fileId` + Groups function/custom tools under a shared namespace. - The ID of the file to be sent to the model. + - `class BetaToolSearchTool:` - - `Optional imageUrl` + Hosted or BYOT tool search configuration for deferred tools. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class BetaWebSearchPreviewTool:` - - `Optional promptCacheBreakpoint` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaApplyPatchTool:` - - `JsonValue; mode "explicit"constant` + Allows the assistant to create, delete, or update files using unified diffs. - The breakpoint mode. Always `explicit`. + - `JsonValue; type "additional_tools"constant` - - `EXPLICIT("explicit")` + The type of the item. Always `additional_tools`. - - `class BetaResponseInputFile:` + - `ADDITIONAL_TOOLS("additional_tools")` - A file input to the model. + - `Optional agent` - - `JsonValue; type "input_file"constant` + The agent that produced this item. - The type of the input item. Always `input_file`. + - `String agentName` - - `INPUT_FILE("input_file")` + The canonical name of the agent that produced this item. - - `Optional detail` + - `class BetaResponseReasoningItem:` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `AUTO("auto")` + - `String id` - - `LOW("low")` + The unique identifier of the reasoning content. - - `HIGH("high")` + - `List summary` - - `Optional fileData` + Reasoning summary content. - The content of the file to be sent to the model. + - `String text` - - `Optional fileId` + A summary of the reasoning output from the model so far. - The ID of the file to be sent to the model. + - `JsonValue; type "summary_text"constant` - - `Optional fileUrl` + The type of the object. Always `summary_text`. - The URL of the file to be sent to the model. + - `SUMMARY_TEXT("summary_text")` - - `Optional filename` + - `JsonValue; type "reasoning"constant` - The name of the file to be sent to the model. + The type of the object. Always `reasoning`. - - `Optional promptCacheBreakpoint` + - `REASONING("reasoning")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional agent` - - `JsonValue; mode "explicit"constant` + The agent that produced this item. - The breakpoint mode. Always `explicit`. + - `String agentName` - - `EXPLICIT("explicit")` + The canonical name of the agent that produced this item. - - `Role role` + - `Optional> content` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Reasoning text content. - - `USER("user")` + - `String text` - - `ASSISTANT("assistant")` + The reasoning text from the model. - - `SYSTEM("system")` + - `JsonValue; type "reasoning_text"constant` - - `DEVELOPER("developer")` + The type of the reasoning text. Always `reasoning_text`. - - `Optional phase` + - `REASONING_TEXT("reasoning_text")` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `Optional encryptedContent` - - `COMMENTARY("commentary")` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `Optional type` + - `Optional status` - The type of the message input. Always `message`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `MESSAGE("message")` + - `IN_PROGRESS("in_progress")` - - `Message` + - `COMPLETED("completed")` - - `List content` + - `INCOMPLETE("incomplete")` - A list of one or many input items to the model, containing different content - types. + - `Program` - - `class BetaResponseInputText:` + - `String id` - A text input to the model. + The unique ID of the program item. - - `class BetaResponseInputImage:` + - `String callId` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The stable call ID of the program item. - - `class BetaResponseInputFile:` + - `String code` - A file input to the model. + The JavaScript source executed by programmatic tool calling. - - `Role role` + - `String fingerprint` - The role of the message input. One of `user`, `system`, or `developer`. + Opaque program replay fingerprint that must be round-tripped. - - `USER("user")` + - `JsonValue; type "program"constant` - - `SYSTEM("system")` + The type of the item. Always `program`. - - `DEVELOPER("developer")` + - `PROGRAM("program")` - `Optional agent` @@ -78173,251 +91668,240 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional status` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `ProgramOutput` - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The unique ID of the program output item. - - `INCOMPLETE("incomplete")` + - `String callId` - - `Optional type` + The call ID of the program item. - The type of the message input. Always set to `message`. + - `String result` - - `MESSAGE("message")` + The result produced by the program item. - - `class BetaResponseOutputMessage:` + - `Status status` - An output message from the model. + The terminal status of the program output item. - - `String id` + - `COMPLETED("completed")` - The unique ID of the output message. + - `INCOMPLETE("incomplete")` - - `List content` + - `JsonValue; type "program_output"constant` - The content of the output message. + The type of the item. Always `program_output`. - - `class BetaResponseOutputText:` + - `PROGRAM_OUTPUT("program_output")` - A text output from the model. + - `Optional agent` - - `List annotations` + The agent that produced this item. - The annotations of the text output. + - `String agentName` - - `class FileCitation:` + The canonical name of the agent that produced this item. - A citation to a file. + - `class BetaResponseCompactionItem:` - - `String fileId` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The ID of the file. + - `String id` - - `String filename` + The unique ID of the compaction item. - The filename of the file cited. + - `String encryptedContent` - - `long index` + The encrypted content that was produced by compaction. - The index of the file in the list of files. + - `JsonValue; type "compaction"constant` - - `JsonValue; type "file_citation"constant` + The type of the item. Always `compaction`. - The type of the file citation. Always `file_citation`. + - `COMPACTION("compaction")` - - `FILE_CITATION("file_citation")` + - `Optional agent` - - `class UrlCitation:` + The agent that produced this item. - A citation for a web resource used to generate a model response. + - `String agentName` - - `long endIndex` + The canonical name of the agent that produced this item. - The index of the last character of the URL citation in the message. + - `Optional createdBy` - - `long startIndex` + The identifier of the actor that created the item. - The index of the first character of the URL citation in the message. + - `ImageGenerationCall` - - `String title` + - `String id` - The title of the web resource. + The unique ID of the image generation call. - - `JsonValue; type "url_citation"constant` + - `Optional result` - The type of the URL citation. Always `url_citation`. + The generated image encoded in base64. - - `URL_CITATION("url_citation")` + - `Status status` - - `String url` + The status of the image generation call. - The URL of the web resource. + - `IN_PROGRESS("in_progress")` - - `class ContainerFileCitation:` + - `COMPLETED("completed")` - A citation for a container file used to generate a model response. + - `GENERATING("generating")` - - `String containerId` + - `FAILED("failed")` - The ID of the container file. + - `JsonValue; type "image_generation_call"constant` - - `long endIndex` + The type of the image generation call. Always `image_generation_call`. - The index of the last character of the container file citation in the message. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `String fileId` + - `Optional agent` - The ID of the file. + The agent that produced this item. - - `String filename` + - `String agentName` - The filename of the container file cited. + The canonical name of the agent that produced this item. - - `long startIndex` + - `class BetaResponseCodeInterpreterToolCall:` - The index of the first character of the container file citation in the message. + A tool call to run code. - - `JsonValue; type "container_file_citation"constant` + - `String id` - The type of the container file citation. Always `container_file_citation`. + The unique ID of the code interpreter tool call. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `Optional code` - - `class FilePath:` + The code to run, or null if not available. - A path to a file. + - `String containerId` - - `String fileId` + The ID of the container used to run the code. - The ID of the file. + - `Optional> outputs` - - `long index` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The index of the file in the list of files. + - `class Logs:` - - `JsonValue; type "file_path"constant` + The logs output from the code interpreter. - The type of the file path. Always `file_path`. + - `String logs` - - `FILE_PATH("file_path")` + The logs output from the code interpreter. - - `String text` + - `JsonValue; type "logs"constant` - The text output from the model. + The type of the output. Always `logs`. - - `JsonValue; type "output_text"constant` + - `LOGS("logs")` - The type of the output text. Always `output_text`. + - `class Image:` - - `OUTPUT_TEXT("output_text")` + The image output from the code interpreter. - - `Optional> logprobs` + - `JsonValue; type "image"constant` - - `String token` + The type of the output. Always `image`. - - `List bytes` + - `IMAGE("image")` - - `double logprob` + - `String url` - - `List topLogprobs` + The URL of the image output from the code interpreter. - - `String token` + - `Status status` - - `List bytes` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `double logprob` + - `IN_PROGRESS("in_progress")` - - `class BetaResponseOutputRefusal:` + - `COMPLETED("completed")` - A refusal from the model. + - `INCOMPLETE("incomplete")` - - `String refusal` + - `INTERPRETING("interpreting")` - The refusal explanation from the model. + - `FAILED("failed")` - - `JsonValue; type "refusal"constant` + - `JsonValue; type "code_interpreter_call"constant` - The type of the refusal. Always `refusal`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `REFUSAL("refusal")` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `JsonValue; role "assistant"constant` + - `Optional agent` - The role of the output message. Always `assistant`. + The agent that produced this item. - - `ASSISTANT("assistant")` + - `String agentName` - - `Status status` + The canonical name of the agent that produced this item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `LocalShellCall` - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The unique ID of the local shell call. - - `INCOMPLETE("incomplete")` + - `Action action` - - `JsonValue; type "message"constant` + Execute a shell command on the server. - The type of the output message. Always `message`. + - `List command` - - `MESSAGE("message")` + The command to run. - - `Optional agent` + - `Env env` - The agent that produced this item. + Environment variables to set for the command. - - `String agentName` + - `JsonValue; type "exec"constant` - The canonical name of the agent that produced this item. + The type of the local shell action. Always `exec`. - - `Optional phase` + - `EXEC("exec")` - 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. + - `Optional timeoutMs` - - `COMMENTARY("commentary")` + Optional timeout in milliseconds for the command. - - `class BetaResponseFileSearchToolCall:` + - `Optional user` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Optional user to run the command as. - - `String id` + - `Optional workingDirectory` - The unique ID of the file search tool call. + Optional working directory to run the command in. - - `List queries` + - `String callId` - The queries used to search for files. + The unique ID of the local shell tool call generated by the model. - `Status status` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The status of the local shell call. - `IN_PROGRESS("in_progress")` - - `SEARCHING("searching")` - - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `FAILED("failed")` - - - `JsonValue; type "file_search_call"constant` + - `JsonValue; type "local_shell_call"constant` - The type of the file search tool call. Always `file_search_call`. + The type of the local shell call. Always `local_shell_call`. - - `FILE_SEARCH_CALL("file_search_call")` + - `LOCAL_SHELL_CALL("local_shell_call")` - `Optional agent` @@ -78427,344 +91911,325 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional> results` - - The results of the file search tool call. - - - `Optional 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` + - `LocalShellCallOutput` - - `double` + - `String id` - - `boolean` + The unique ID of the local shell tool call generated by the model. - - `Optional fileId` + - `String output` - The unique ID of the file. + A JSON string of the output of the local shell tool call. - - `Optional filename` + - `JsonValue; type "local_shell_call_output"constant` - The name of the file. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `Optional score` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - The relevance score of the file - a value between 0 and 1. + - `Optional agent` - - `Optional text` + The agent that produced this item. - The text that was retrieved from the file. + - `String agentName` - - `class BetaResponseComputerToolCall:` + The canonical name of the agent that produced this item. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `Optional status` - - `String id` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the computer call. + - `IN_PROGRESS("in_progress")` - - `String callId` + - `COMPLETED("completed")` - An identifier used when responding to the tool call with output. + - `INCOMPLETE("incomplete")` - - `List pendingSafetyChecks` + - `class BetaResponseFunctionShellToolCall:` - The pending safety checks for the computer call. + A tool call that executes one or more shell commands in a managed environment. - `String id` - The ID of the pending safety check. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `Optional code` + - `Action action` - The type of the pending safety check. + The shell commands and limits that describe how to run the tool call. - - `Optional message` + - `List commands` - Details about the pending safety check. + - `Optional maxOutputLength` - - `Status status` + Optional maximum number of characters to return from each command. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional timeoutMs` - - `IN_PROGRESS("in_progress")` + Optional timeout in milliseconds for the commands. - - `COMPLETED("completed")` + - `String callId` - - `INCOMPLETE("incomplete")` + The unique ID of the shell tool call generated by the model. - - `Type type` + - `Optional environment` - The type of the computer call. Always `computer_call`. + Represents the use of a local environment to perform shell actions. - - `COMPUTER_CALL("computer_call")` + - `class BetaResponseLocalEnvironment:` - - `Optional action` + Represents the use of a local environment to perform shell actions. - A click action. + - `JsonValue; type "local"constant` - - `Click` + The environment type. Always `local`. - - `Button button` + - `LOCAL("local")` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class BetaResponseContainerReference:` - - `LEFT("left")` + Represents a container created with /v1/containers. - - `RIGHT("right")` + - `String containerId` - - `WHEEL("wheel")` + - `JsonValue; type "container_reference"constant` - - `BACK("back")` + The environment type. Always `container_reference`. - - `FORWARD("forward")` + - `CONTAINER_REFERENCE("container_reference")` - - `JsonValue; type "click"constant` + - `Status status` - Specifies the event type. For a click action, this property is always `click`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `CLICK("click")` + - `IN_PROGRESS("in_progress")` - - `long x` + - `COMPLETED("completed")` - The x-coordinate where the click occurred. + - `INCOMPLETE("incomplete")` - - `long y` + - `JsonValue; type "shell_call"constant` - The y-coordinate where the click occurred. + The type of the item. Always `shell_call`. - - `Optional> keys` + - `SHELL_CALL("shell_call")` - The keys being held while clicking. + - `Optional agent` - - `DoubleClick` + The agent that produced this item. - - `Optional> keys` + - `String agentName` - The keys being held while double-clicking. + The canonical name of the agent that produced this item. - - `JsonValue; type "double_click"constant` + - `Optional caller` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The execution context that produced this tool call. - - `DOUBLE_CLICK("double_click")` + - `JsonValue;` - - `long x` + - `JsonValue; type "direct"constant` - The x-coordinate where the double click occurred. + - `DIRECT("direct")` - - `long y` + - `class Program:` - The y-coordinate where the double click occurred. + - `String callerId` - - `Drag` + The call ID of the program item that produced this tool call. - - `List path` + - `JsonValue; type "program"constant` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `PROGRAM("program")` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `Optional createdBy` - - `long x` + The ID of the entity that created this tool call. - The x-coordinate. + - `class BetaResponseFunctionShellToolCallOutput:` - - `long y` + The output of a shell tool call that was emitted. - The y-coordinate. + - `String id` - - `JsonValue; type "drag"constant` + The unique ID of the shell call output. Populated when this item is returned via API. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `String callId` - - `DRAG("drag")` + The unique ID of the shell tool call generated by the model. - - `Optional> keys` + - `Optional maxOutputLength` - The keys being held while dragging the mouse. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `Keypress` + - `List output` - - `List keys` + An array of shell call output contents - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `Outcome outcome` - - `JsonValue; type "keypress"constant` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `JsonValue;` - - `KEYPRESS("keypress")` + - `JsonValue; type "timeout"constant` - - `Move` + The outcome type. Always `timeout`. - - `JsonValue; type "move"constant` + - `TIMEOUT("timeout")` - Specifies the event type. For a move action, this property is always set to `move`. + - `class Exit:` - - `MOVE("move")` + Indicates that the shell commands finished and returned an exit code. - - `long x` + - `long exitCode` - The x-coordinate to move to. + Exit code from the shell process. - - `long y` + - `JsonValue; type "exit"constant` - The y-coordinate to move to. + The outcome type. Always `exit`. - - `Optional> keys` + - `EXIT("exit")` - The keys being held while moving the mouse. + - `String stderr` - - `JsonValue;` + The standard error output that was captured. - - `JsonValue; type "screenshot"constant` + - `String stdout` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The standard output that was captured. - - `SCREENSHOT("screenshot")` + - `Optional createdBy` - - `Scroll` + The identifier of the actor that created the item. - - `long scrollX` + - `Status status` - The horizontal scroll distance. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `long scrollY` + - `IN_PROGRESS("in_progress")` - The vertical scroll distance. + - `COMPLETED("completed")` - - `JsonValue; type "scroll"constant` + - `INCOMPLETE("incomplete")` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `JsonValue; type "shell_call_output"constant` - - `SCROLL("scroll")` + The type of the shell call output. Always `shell_call_output`. - - `long x` + - `SHELL_CALL_OUTPUT("shell_call_output")` - The x-coordinate where the scroll occurred. + - `Optional agent` - - `long y` + The agent that produced this item. - The y-coordinate where the scroll occurred. + - `String agentName` - - `Optional> keys` + The canonical name of the agent that produced this item. - The keys being held while scrolling. + - `Optional caller` - - `Type` + The execution context that produced this tool call. - - `String text` + - `JsonValue;` - The text to type. + - `JsonValue; type "direct"constant` - - `JsonValue; type "type"constant` + - `DIRECT("direct")` - Specifies the event type. For a type action, this property is always set to `type`. + - `class Program:` - - `TYPE("type")` + - `String callerId` - - `JsonValue;` + The call ID of the program item that produced this tool call. - - `JsonValue; type "wait"constant` + - `JsonValue; type "program"constant` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `PROGRAM("program")` - - `WAIT("wait")` + - `Optional createdBy` - - `Optional> actions` + The identifier of the actor that created the item. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `class BetaResponseApplyPatchToolCall:` - - `Click` + A tool call that applies file diffs by creating, deleting, or updating files. - - `DoubleClick` + - `String id` - - `Drag` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `Keypress` + - `String callId` - - `Move` + The unique ID of the apply patch tool call generated by the model. - - `JsonValue;` + - `Operation operation` - - `Scroll` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `Type` + - `class CreateFile:` - - `JsonValue;` + Instruction describing how to create a file via the apply_patch tool. - - `Optional agent` + - `String diff` - The agent that produced this item. + Diff to apply. - - `String agentName` + - `String path` - The canonical name of the agent that produced this item. + Path of the file to create. - - `ComputerCallOutput` + - `JsonValue; type "create_file"constant` - - `String callId` + Create a new file with the provided diff. - The ID of the computer tool call that produced the output. + - `CREATE_FILE("create_file")` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `class DeleteFile:` - A computer screenshot image used with the computer use tool. + Instruction describing how to delete a file via the apply_patch tool. - - `JsonValue; type "computer_screenshot"constant` + - `String path` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Path of the file to delete. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `JsonValue; type "delete_file"constant` - - `Optional fileId` + Delete the specified file. - The identifier of an uploaded file that contains the screenshot. + - `DELETE_FILE("delete_file")` - - `Optional imageUrl` + - `class UpdateFile:` - The URL of the screenshot image. + Instruction describing how to update a file via the apply_patch tool. - - `JsonValue; type "computer_call_output"constant` + - `String diff` - The type of the computer tool call output. Always `computer_call_output`. + Diff to apply. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `String path` - - `Optional id` + Path of the file to update. - The ID of the computer tool call output. + - `JsonValue; type "update_file"constant` - - `Optional> acknowledgedSafetyChecks` + Update an existing file with the provided diff. - The safety checks reported by the API that have been acknowledged by the developer. + - `UPDATE_FILE("update_file")` - - `String id` + - `Status status` - The ID of the pending safety check. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `Optional code` + - `IN_PROGRESS("in_progress")` - The type of the pending safety check. + - `COMPLETED("completed")` + + - `JsonValue; type "apply_patch_call"constant` - - `Optional message` + The type of the item. Always `apply_patch_call`. - Details about the pending safety check. + - `APPLY_PATCH_CALL("apply_patch_call")` - `Optional agent` @@ -78774,111 +92239,127 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional status` + - `Optional caller` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The execution context that produced this tool call. - - `IN_PROGRESS("in_progress")` + - `JsonValue;` - - `COMPLETED("completed")` + - `JsonValue; type "direct"constant` - - `INCOMPLETE("incomplete")` + - `DIRECT("direct")` - - `class BetaResponseFunctionWebSearch:` + - `class Program:` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput:` + + The output emitted by an apply patch tool call. - `String id` - The unique ID of the web search tool call. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `Action action` + - `String callId` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The unique ID of the apply patch tool call generated by the model. - - `class Search:` + - `Status status` - Action type "search" - Performs a web search query. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `JsonValue; type "search"constant` + - `COMPLETED("completed")` - The action type. + - `FAILED("failed")` - - `SEARCH("search")` + - `JsonValue; type "apply_patch_call_output"constant` - - `Optional> queries` + The type of the item. Always `apply_patch_call_output`. - The search queries. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `Optional query` + - `Optional agent` - The search query. + The agent that produced this item. - - `Optional> sources` + - `String agentName` - The sources used in the search. + The canonical name of the agent that produced this item. - - `JsonValue; type "url"constant` + - `Optional caller` - The type of source. Always `url`. + The execution context that produced this tool call. - - `URL("url")` + - `JsonValue;` - - `String url` + - `JsonValue; type "direct"constant` - The URL of the source. + - `DIRECT("direct")` - - `class OpenPage:` + - `class Program:` - Action type "open_page" - Opens a specific URL from search results. + - `String callerId` - - `JsonValue; type "open_page"constant` + The call ID of the program item that produced this tool call. - The action type. + - `JsonValue; type "program"constant` - - `OPEN_PAGE("open_page")` + - `PROGRAM("program")` - - `Optional url` + - `Optional createdBy` - The URL opened by the model. + The ID of the entity that created this tool call output. - - `class FindInPage:` + - `Optional output` - Action type "find_in_page": Searches for a pattern within a loaded page. + Optional textual output returned by the apply patch tool. - - `String pattern` + - `McpListTools` - The pattern or text to search for within the page. + - `String id` - - `JsonValue; type "find_in_page"constant` + The unique ID of the list. - The action type. + - `String serverLabel` - - `FIND_IN_PAGE("find_in_page")` + The label of the MCP server. - - `String url` + - `List tools` - The URL of the page searched for the pattern. + The tools available on the server. - - `Status status` + - `JsonValue inputSchema` - The status of the web search tool call. + The JSON schema describing the tool's input. - - `IN_PROGRESS("in_progress")` + - `String name` - - `SEARCHING("searching")` + The name of the tool. - - `COMPLETED("completed")` + - `Optional annotations` - - `FAILED("failed")` + Additional annotations about the tool. - - `JsonValue; type "web_search_call"constant` + - `Optional description` - The type of the web search tool call. Always `web_search_call`. + The description of the tool. - - `WEB_SEARCH_CALL("web_search_call")` + - `JsonValue; type "mcp_list_tools"constant` + + The type of the item. Always `mcp_list_tools`. + + - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` @@ -78888,32 +92369,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall:` + - `Optional error` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Error message if the server could not list tools. - - `String arguments` + - `McpApprovalRequest` - A JSON string of the arguments to pass to the function. + - `String id` - - `String callId` + The unique ID of the approval request. - The unique ID of the function tool call generated by the model. + - `String arguments` + + A JSON string of arguments for the tool. - `String name` - The name of the function to run. + The name of the tool to run. - - `JsonValue; type "function_call"constant` + - `String serverLabel` - The type of the function tool call. Always `function_call`. + The label of the MCP server making the request. - - `FUNCTION_CALL("function_call")` + - `JsonValue; type "mcp_approval_request"constant` - - `Optional id` + The type of the item. Always `mcp_approval_request`. - The unique ID of the function tool call. + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - `Optional agent` @@ -78923,1672 +92405,1638 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` + - `McpApprovalResponse` - The execution context that produced this tool call. + - `String id` - - `JsonValue;` + The unique ID of the approval response - - `JsonValue; type "direct"constant` + - `String approvalRequestId` - - `DIRECT("direct")` + The ID of the approval request being answered. - - `class Program:` + - `boolean approve` - - `String callerId` + Whether the request was approved. - The call ID of the program item that produced this tool call. + - `JsonValue; type "mcp_approval_response"constant` - - `JsonValue; type "program"constant` + The type of the item. Always `mcp_approval_response`. - - `PROGRAM("program")` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `Optional namespace` + - `Optional agent` - The namespace of the function to run. + The agent that produced this item. - - `Optional status` + - `String agentName` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The canonical name of the agent that produced this item. - - `IN_PROGRESS("in_progress")` + - `Optional reason` - - `COMPLETED("completed")` + Optional reason for the decision. - - `INCOMPLETE("incomplete")` + - `McpCall` - - `FunctionCallOutput` + - `String id` - - `String callId` + The unique ID of the tool call. - The unique ID of the function tool call generated by the model. + - `String arguments` - - `Output output` + A JSON string of the arguments passed to the tool. - Text, image, or file output of the function tool call. + - `String name` - - `String` + The name of the tool that was run. - - `List` + - `String serverLabel` - - `class BetaResponseInputTextContent:` + The label of the MCP server running the tool. - A text input to the model. + - `JsonValue; type "mcp_call"constant` - - `String text` + The type of the item. Always `mcp_call`. - The text input to the model. + - `MCP_CALL("mcp_call")` - - `JsonValue; type "input_text"constant` + - `Optional agent` - The type of the input item. Always `input_text`. + The agent that produced this item. - - `INPUT_TEXT("input_text")` + - `String agentName` - - `Optional promptCacheBreakpoint` + The canonical name of the agent that produced this item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional approvalRequestId` - - `JsonValue; mode "explicit"constant` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The breakpoint mode. Always `explicit`. + - `Optional error` - - `EXPLICIT("explicit")` + The error from the tool call, if any. - - `class BetaResponseInputImageContent:` + - `Optional output` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The output from the tool call. - - `JsonValue; type "input_image"constant` + - `Optional status` - The type of the input item. Always `input_image`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `INPUT_IMAGE("input_image")` + - `IN_PROGRESS("in_progress")` - - `Optional detail` + - `COMPLETED("completed")` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `INCOMPLETE("incomplete")` - - `LOW("low")` + - `CALLING("calling")` - - `HIGH("high")` + - `FAILED("failed")` - - `AUTO("auto")` + - `class BetaResponseCustomToolCallItem:` - - `ORIGINAL("original")` + A call to a custom tool created by the model. - - `Optional fileId` + - `String id` - The ID of the file to be sent to the model. + The unique ID of the custom tool call item. - - `Optional imageUrl` + - `Status status` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional promptCacheBreakpoint` + - `IN_PROGRESS("in_progress")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `COMPLETED("completed")` - - `JsonValue; mode "explicit"constant` + - `INCOMPLETE("incomplete")` - The breakpoint mode. Always `explicit`. + - `Optional createdBy` - - `EXPLICIT("explicit")` + The identifier of the actor that created the item. - - `class BetaResponseInputFileContent:` + - `class BetaResponseCustomToolCallOutputItem:` - A file input to the model. + The output of a custom tool call from your code, being sent back to the model. - - `JsonValue; type "input_file"constant` + - `String id` - The type of the input item. Always `input_file`. + The unique ID of the custom tool call output item. - - `INPUT_FILE("input_file")` + - `Status status` - - `Optional detail` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `IN_PROGRESS("in_progress")` - - `AUTO("auto")` + - `COMPLETED("completed")` - - `LOW("low")` + - `INCOMPLETE("incomplete")` - - `HIGH("high")` + - `Optional createdBy` - - `Optional fileData` + The identifier of the actor that created the item. - The base64-encoded data of the file to be sent to the model. +### Beta Response Local Environment - - `Optional fileId` +- `class BetaResponseLocalEnvironment:` - The ID of the file to be sent to the model. + Represents the use of a local environment to perform shell actions. - - `Optional fileUrl` + - `JsonValue; type "local"constant` - The URL of the file to be sent to the model. + The environment type. Always `local`. - - `Optional filename` + - `LOCAL("local")` - The name of the file to be sent to the model. +### Beta Response Mcp Call Arguments Delta Event - - `Optional promptCacheBreakpoint` +- `class BetaResponseMcpCallArgumentsDeltaEvent:` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `JsonValue; mode "explicit"constant` + - `String delta` - The breakpoint mode. Always `explicit`. + A JSON string containing the partial update to the arguments for the MCP tool call. - - `EXPLICIT("explicit")` + - `String itemId` - - `JsonValue; type "function_call_output"constant` + The unique identifier of the MCP tool call item being processed. - The type of the function tool call output. Always `function_call_output`. + - `long outputIndex` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + The index of the output item in the response's output array. - - `Optional id` + - `long sequenceNumber` - The unique ID of the function tool call output. Populated when this item is returned via API. + The sequence number of this event. + + - `JsonValue; type "response.mcp_call_arguments.delta"constant` + + The type of the event. Always 'response.mcp_call_arguments.delta'. + + - `RESPONSE_MCP_CALL_ARGUMENTS_DELTA("response.mcp_call_arguments.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` +### Beta Response Mcp Call Arguments Done Event - The execution context that produced this tool call. +- `class BetaResponseMcpCallArgumentsDoneEvent:` - - `JsonValue;` + Emitted when the arguments for an MCP tool call are finalized. - - `JsonValue; type "direct"constant` + - `String arguments` - The caller type. Always `direct`. + A JSON string containing the finalized arguments for the MCP tool call. - - `DIRECT("direct")` + - `String itemId` - - `class Program:` + The unique identifier of the MCP tool call item being processed. - - `String callerId` + - `long outputIndex` - The call ID of the program item that produced this tool call. + The index of the output item in the response's output array. - - `JsonValue; type "program"constant` + - `long sequenceNumber` - The caller type. Always `program`. + The sequence number of this event. - - `PROGRAM("program")` + - `JsonValue; type "response.mcp_call_arguments.done"constant` - - `Optional status` + The type of the event. Always 'response.mcp_call_arguments.done'. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `RESPONSE_MCP_CALL_ARGUMENTS_DONE("response.mcp_call_arguments.done")` - - `IN_PROGRESS("in_progress")` + - `Optional agent` - - `COMPLETED("completed")` + The agent that owns this multi-agent streaming event. - - `INCOMPLETE("incomplete")` + - `String agentName` - - `AgentMessage` + The canonical name of the agent that produced this item. - - `String author` +### Beta Response Mcp Call Completed Event - The sending agent identity. +- `class BetaResponseMcpCallCompletedEvent:` - - `List content` + Emitted when an MCP tool call has completed successfully. - Plaintext, image, or encrypted content sent between agents. + - `String itemId` - - `class BetaResponseInputTextContent:` + The ID of the MCP tool call item that completed. - A text input to the model. + - `long outputIndex` - - `class BetaResponseInputImageContent:` + The index of the output item that completed. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `long sequenceNumber` - - `class EncryptedContent:` + The sequence number of this event. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `JsonValue; type "response.mcp_call.completed"constant` - - `String encryptedContent` + The type of the event. Always 'response.mcp_call.completed'. - Opaque encrypted content. + - `RESPONSE_MCP_CALL_COMPLETED("response.mcp_call.completed")` - - `JsonValue; type "encrypted_content"constant` + - `Optional agent` - The type of the input item. Always `encrypted_content`. + The agent that owns this multi-agent streaming event. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `String agentName` - - `String recipient` + The canonical name of the agent that produced this item. - The destination agent identity. +### Beta Response Mcp Call Failed Event - - `JsonValue; type "agent_message"constant` +- `class BetaResponseMcpCallFailedEvent:` - The item type. Always `agent_message`. + Emitted when an MCP tool call has failed. - - `AGENT_MESSAGE("agent_message")` + - `String itemId` - - `Optional id` + The ID of the MCP tool call item that failed. - The unique ID of this agent message item. + - `long outputIndex` - - `Optional agent` + The index of the output item that failed. - The agent that produced this item. + - `long sequenceNumber` - - `String agentName` + The sequence number of this event. - The canonical name of the agent that produced this item. + - `JsonValue; type "response.mcp_call.failed"constant` - - `MultiAgentCall` + The type of the event. Always 'response.mcp_call.failed'. - - `Action action` + - `RESPONSE_MCP_CALL_FAILED("response.mcp_call.failed")` - The multi-agent action that was executed. + - `Optional agent` - - `SPAWN_AGENT("spawn_agent")` + The agent that owns this multi-agent streaming event. - - `INTERRUPT_AGENT("interrupt_agent")` + - `String agentName` - - `LIST_AGENTS("list_agents")` + The canonical name of the agent that produced this item. - - `SEND_MESSAGE("send_message")` +### Beta Response Mcp Call In Progress Event - - `FOLLOWUP_TASK("followup_task")` +- `class BetaResponseMcpCallInProgressEvent:` - - `WAIT_AGENT("wait_agent")` + Emitted when an MCP tool call is in progress. - - `String arguments` + - `String itemId` - The action arguments as a JSON string. + The unique identifier of the MCP tool call item being processed. - - `String callId` + - `long outputIndex` - The unique ID linking this call to its output. + The index of the output item in the response's output array. - - `JsonValue; type "multi_agent_call"constant` + - `long sequenceNumber` - The item type. Always `multi_agent_call`. + The sequence number of this event. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `JsonValue; type "response.mcp_call.in_progress"constant` - - `Optional id` + The type of the event. Always 'response.mcp_call.in_progress'. - The unique ID of this multi-agent call. + - `RESPONSE_MCP_CALL_IN_PROGRESS("response.mcp_call.in_progress")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `Action action` - - The multi-agent action that produced this result. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` - - - `SEND_MESSAGE("send_message")` - - - `FOLLOWUP_TASK("followup_task")` +### Beta Response Mcp List Tools Completed Event - - `WAIT_AGENT("wait_agent")` +- `class BetaResponseMcpListToolsCompletedEvent:` - - `String callId` + Emitted when the list of available MCP tools has been successfully retrieved. - The unique ID of the multi-agent call. + - `String itemId` - - `List output` + The ID of the MCP tool call item that produced this output. - Text output returned by the multi-agent action. + - `long outputIndex` - - `String text` + The index of the output item that was processed. - The text content. + - `long sequenceNumber` - - `JsonValue; type "output_text"constant` + The sequence number of this event. - The content type. Always `output_text`. + - `JsonValue; type "response.mcp_list_tools.completed"constant` - - `OUTPUT_TEXT("output_text")` + The type of the event. Always 'response.mcp_list_tools.completed'. - - `Optional annotations` + - `RESPONSE_MCP_LIST_TOOLS_COMPLETED("response.mcp_list_tools.completed")` - Citations associated with the text content. + - `Optional agent` - - `List` + The agent that owns this multi-agent streaming event. - - `String fileId` + - `String agentName` - The ID of the file. + The canonical name of the agent that produced this item. - - `String filename` +### Beta Response Mcp List Tools Failed Event - The filename of the file cited. +- `class BetaResponseMcpListToolsFailedEvent:` - - `long index` + Emitted when the attempt to list available MCP tools has failed. - The index of the file in the list of files. + - `String itemId` - - `JsonValue; type "file_citation"constant` + The ID of the MCP tool call item that failed. - The citation type. Always `file_citation`. + - `long outputIndex` - - `FILE_CITATION("file_citation")` + The index of the output item that failed. - - `List` + - `long sequenceNumber` - - `long endIndex` + The sequence number of this event. - The index of the last character of the citation in the message. + - `JsonValue; type "response.mcp_list_tools.failed"constant` - - `long startIndex` + The type of the event. Always 'response.mcp_list_tools.failed'. - The index of the first character of the citation in the message. + - `RESPONSE_MCP_LIST_TOOLS_FAILED("response.mcp_list_tools.failed")` - - `String title` + - `Optional agent` - The title of the cited resource. + The agent that owns this multi-agent streaming event. - - `JsonValue; type "url_citation"constant` + - `String agentName` - The citation type. Always `url_citation`. + The canonical name of the agent that produced this item. - - `URL_CITATION("url_citation")` +### Beta Response Mcp List Tools In Progress Event - - `String url` +- `class BetaResponseMcpListToolsInProgressEvent:` - The URL of the cited resource. + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `List` + - `String itemId` - - `String containerId` + The ID of the MCP tool call item that is being processed. - The ID of the container. + - `long outputIndex` - - `long endIndex` + The index of the output item that is being processed. - The index of the last character of the citation in the message. + - `long sequenceNumber` - - `String fileId` + The sequence number of this event. - The ID of the container file. + - `JsonValue; type "response.mcp_list_tools.in_progress"constant` - - `String filename` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - The filename of the container file cited. + - `RESPONSE_MCP_LIST_TOOLS_IN_PROGRESS("response.mcp_list_tools.in_progress")` - - `long startIndex` + - `Optional agent` - The index of the first character of the citation in the message. + The agent that owns this multi-agent streaming event. - - `JsonValue; type "container_file_citation"constant` + - `String agentName` - The citation type. Always `container_file_citation`. + The canonical name of the agent that produced this item. - - `CONTAINER_FILE_CITATION("container_file_citation")` +### Beta Response Output Audio - - `JsonValue; type "multi_agent_call_output"constant` +- `class BetaResponseOutputAudio:` - The item type. Always `multi_agent_call_output`. + An audio output from the model. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `String data` - - `Optional id` + Base64-encoded audio data from the model. - The unique ID of this multi-agent call output. + - `String transcript` - - `Optional agent` + The transcript of the audio data from the model. - The agent that produced this item. + - `JsonValue; type "output_audio"constant` - - `String agentName` + The type of the output audio. Always `output_audio`. - The canonical name of the agent that produced this item. + - `OUTPUT_AUDIO("output_audio")` - - `ToolSearchCall` +### Beta Response Output Item - - `JsonValue arguments` +- `class BetaResponseOutputItem: A class that can be one of several variants.union` - The arguments supplied to the tool search call. + An output message from the model. - - `JsonValue; type "tool_search_call"constant` + - `class BetaResponseOutputMessage:` - The item type. Always `tool_search_call`. + An output message from the model. - - `TOOL_SEARCH_CALL("tool_search_call")` + - `String id` - - `Optional id` + The unique ID of the output message. - The unique ID of this tool search call. + - `List content` - - `Optional agent` + The content of the output message. - The agent that produced this item. + - `class BetaResponseOutputText:` - - `String agentName` + A text output from the model. - The canonical name of the agent that produced this item. + - `List annotations` - - `Optional callId` + The annotations of the text output. - The unique ID of the tool search call generated by the model. + - `class FileCitation:` - - `Optional execution` + A citation to a file. - Whether tool search was executed by the server or by the client. + - `String fileId` - - `SERVER("server")` + The ID of the file. - - `CLIENT("client")` + - `String filename` - - `Optional status` + The filename of the file cited. - The status of the tool search call. + - `long index` - - `IN_PROGRESS("in_progress")` + The index of the file in the list of files. - - `COMPLETED("completed")` + - `JsonValue; type "file_citation"constant` - - `INCOMPLETE("incomplete")` + The type of the file citation. Always `file_citation`. - - `class BetaResponseToolSearchOutputItemParam:` + - `FILE_CITATION("file_citation")` - - `List tools` + - `class UrlCitation:` - The loaded tool definitions returned by the tool search output. + A citation for a web resource used to generate a model response. - - `class BetaFunctionTool:` + - `long endIndex` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The index of the last character of the URL citation in the message. - - `String name` + - `long startIndex` - The name of the function to call. + The index of the first character of the URL citation in the message. - - `Optional parameters` + - `String title` - A JSON schema object describing the parameters of the function. + The title of the web resource. - - `Optional strict` + - `JsonValue; type "url_citation"constant` - Whether strict parameter validation is enforced for this function tool. + The type of the URL citation. Always `url_citation`. - - `JsonValue; type "function"constant` + - `URL_CITATION("url_citation")` - The type of the function tool. Always `function`. + - `String url` - - `FUNCTION("function")` + The URL of the web resource. - - `Optional> allowedCallers` + - `class ContainerFileCitation:` - The tool invocation context(s). + A citation for a container file used to generate a model response. - - `DIRECT("direct")` + - `String containerId` - - `PROGRAMMATIC("programmatic")` + The ID of the container file. - - `Optional deferLoading` + - `long endIndex` - Whether this function is deferred and loaded via tool search. + The index of the last character of the container file citation in the message. - - `Optional description` + - `String fileId` - A description of the function. Used by the model to determine whether or not to call the function. + The ID of the file. - - `Optional outputSchema` + - `String filename` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The filename of the container file cited. - - `class BetaFileSearchTool:` + - `long startIndex` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The index of the first character of the container file citation in the message. - - `JsonValue; type "file_search"constant` + - `JsonValue; type "container_file_citation"constant` - The type of the file search tool. Always `file_search`. + The type of the container file citation. Always `container_file_citation`. - - `FILE_SEARCH("file_search")` + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `List vectorStoreIds` + - `class FilePath:` - The IDs of the vector stores to search. + A path to a file. - - `Optional filters` + - `String fileId` - A filter to apply. + The ID of the file. - - `class ComparisonFilter:` + - `long index` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The index of the file in the list of files. - - `String key` + - `JsonValue; type "file_path"constant` - The key to compare against the value. + The type of the file path. Always `file_path`. - - `Type type` + - `FILE_PATH("file_path")` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `String text` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The text output from the model. - - `EQ("eq")` + - `JsonValue; type "output_text"constant` - - `NE("ne")` + The type of the output text. Always `output_text`. - - `GT("gt")` + - `OUTPUT_TEXT("output_text")` - - `GTE("gte")` + - `Optional> logprobs` - - `LT("lt")` + - `String token` - - `LTE("lte")` + - `List bytes` - - `IN("in")` + - `double logprob` - - `NIN("nin")` + - `List topLogprobs` - - `Value value` + - `String token` - The value to compare against the attribute key; supports string, number, or boolean types. + - `List bytes` - - `String` + - `double logprob` - - `double` + - `class BetaResponseOutputRefusal:` - - `boolean` + A refusal from the model. - - `List` + - `String refusal` - - `class CompoundFilter:` + The refusal explanation from the model. - Combine multiple filters using `and` or `or`. + - `JsonValue; type "refusal"constant` - - `List filters` + The type of the refusal. Always `refusal`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `REFUSAL("refusal")` - - `class ComparisonFilter:` + - `JsonValue; role "assistant"constant` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The role of the output message. Always `assistant`. - - `String key` + - `ASSISTANT("assistant")` - The key to compare against the value. + - `Status status` - - `Type type` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `IN_PROGRESS("in_progress")` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `COMPLETED("completed")` - - `EQ("eq")` + - `INCOMPLETE("incomplete")` - - `NE("ne")` + - `JsonValue; type "message"constant` - - `GT("gt")` + The type of the output message. Always `message`. - - `GTE("gte")` + - `MESSAGE("message")` - - `LT("lt")` + - `Optional agent` - - `LTE("lte")` + The agent that produced this item. - - `IN("in")` + - `String agentName` - - `NIN("nin")` + The canonical name of the agent that produced this item. - - `Value value` + - `Optional phase` - The value to compare against the attribute key; supports string, number, or boolean types. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `String` + - `COMMENTARY("commentary")` - - `double` + - `FINAL_ANSWER("final_answer")` - - `boolean` + - `class BetaResponseFileSearchToolCall:` - - `List` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `JsonValue` + - `String id` - - `Type type` + The unique ID of the file search tool call. - Type of operation: `and` or `or`. + - `List queries` - - `AND("and")` + The queries used to search for files. - - `OR("or")` + - `Status status` - - `Optional maxNumResults` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `IN_PROGRESS("in_progress")` - - `Optional rankingOptions` + - `SEARCHING("searching")` - Ranking options for search. + - `COMPLETED("completed")` - - `Optional hybridSearch` + - `INCOMPLETE("incomplete")` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `FAILED("failed")` - - `double embeddingWeight` + - `JsonValue; type "file_search_call"constant` - The weight of the embedding in the reciprocal ranking fusion. + The type of the file search tool call. Always `file_search_call`. - - `double textWeight` + - `FILE_SEARCH_CALL("file_search_call")` - The weight of the text in the reciprocal ranking fusion. + - `Optional agent` - - `Optional ranker` + The agent that produced this item. - The ranker to use for the file search. + - `String agentName` - - `AUTO("auto")` + The canonical name of the agent that produced this item. - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `Optional> results` - - `Optional scoreThreshold` + The results of the file search tool call. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `Optional attributes` - - `class BetaComputerTool:` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String` - - `JsonValue; type "computer"constant` + - `double` - The type of the computer tool. Always `computer`. + - `boolean` - - `COMPUTER("computer")` + - `Optional fileId` - - `class BetaComputerUsePreviewTool:` + The unique ID of the file. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional filename` - - `long displayHeight` + The name of the file. - The height of the computer display. + - `Optional score` - - `long displayWidth` + The relevance score of the file - a value between 0 and 1. - The width of the computer display. + - `Optional text` - - `Environment environment` + The text that was retrieved from the file. - The type of computer environment to control. + - `class BetaResponseFunctionToolCall:` - - `WINDOWS("windows")` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `MAC("mac")` + - `String arguments` - - `LINUX("linux")` + A JSON string of the arguments to pass to the function. - - `UBUNTU("ubuntu")` + - `String callId` - - `BROWSER("browser")` + The unique ID of the function tool call generated by the model. - - `JsonValue; type "computer_use_preview"constant` + - `String name` - The type of the computer use tool. Always `computer_use_preview`. + The name of the function to run. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `JsonValue; type "function_call"constant` - - `class BetaWebSearchTool:` + The type of the function tool call. Always `function_call`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `FUNCTION_CALL("function_call")` - - `Type type` + - `Optional id` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The unique ID of the function tool call. - - `WEB_SEARCH("web_search")` + - `Optional agent` - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + The agent that produced this item. - - `Optional filters` + - `String agentName` - Filters for the search. + The canonical name of the agent that produced this item. - - `Optional> allowedDomains` + - `Optional caller` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The execution context that produced this tool call. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `JsonValue;` - - `Optional searchContextSize` + - `JsonValue; type "direct"constant` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `DIRECT("direct")` - - `LOW("low")` + - `class Program:` - - `MEDIUM("medium")` + - `String callerId` - - `HIGH("high")` + The call ID of the program item that produced this tool call. - - `Optional userLocation` + - `JsonValue; type "program"constant` - The approximate location of the user. + - `PROGRAM("program")` - - `Optional city` + - `Optional namespace` - Free text input for the city of the user, e.g. `San Francisco`. + The namespace of the function to run. - - `Optional country` + - `Optional status` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional region` + - `IN_PROGRESS("in_progress")` - Free text input for the region of the user, e.g. `California`. + - `COMPLETED("completed")` - - `Optional timezone` + - `INCOMPLETE("incomplete")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `class BetaResponseFunctionToolCallOutputItem:` - - `Optional type` + - `String id` - The type of location approximation. Always `approximate`. + The unique ID of the function call tool output. - - `APPROXIMATE("approximate")` + - `String callId` - - `Mcp` + The unique ID of the function tool call generated by the model. - - `String serverLabel` + - `Output output` - A label for this MCP server, used to identify it in tool calls. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `JsonValue; type "mcp"constant` + - `String` - The type of the MCP tool. Always `mcp`. + - `List` - - `MCP("mcp")` + - `class BetaResponseInputText:` - - `Optional> allowedCallers` + A text input to the model. - The tool invocation context(s). + - `String text` - - `DIRECT("direct")` + The text input to the model. - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "input_text"constant` - - `Optional allowedTools` + The type of the input item. Always `input_text`. - List of allowed tool names or a filter object. + - `INPUT_TEXT("input_text")` - - `List` + - `Optional promptCacheBreakpoint` - - `class McpToolFilter:` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - A filter object to specify which tools are allowed. + - `JsonValue; mode "explicit"constant` - - `Optional readOnly` + The breakpoint mode. Always `explicit`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `EXPLICIT("explicit")` - - `Optional> toolNames` + - `class BetaResponseInputImage:` - List of allowed tool names. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional authorization` + - `Detail detail` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Optional connectorId` + - `LOW("low")` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `HIGH("high")` - Currently supported `connector_id` values are: + - `AUTO("auto")` - - 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` + - `ORIGINAL("original")` - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `JsonValue; type "input_image"constant` - - `CONNECTOR_GMAIL("connector_gmail")` + The type of the input item. Always `input_image`. - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `INPUT_IMAGE("input_image")` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `Optional fileId` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + The ID of the file to be sent to the model. - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `Optional imageUrl` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `Optional promptCacheBreakpoint` - - `Optional deferLoading` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Whether this MCP tool is deferred and discovered via tool search. + - `JsonValue; mode "explicit"constant` - - `Optional headers` + The breakpoint mode. Always `explicit`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `EXPLICIT("explicit")` - - `Optional requireApproval` + - `class BetaResponseInputFile:` - Specify which of the MCP server's tools require approval. + A file input to the model. - - `class McpToolApprovalFilter:` + - `JsonValue; type "input_file"constant` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The type of the input item. Always `input_file`. - - `Optional always` + - `INPUT_FILE("input_file")` - A filter object to specify which tools are allowed. + - `Optional detail` - - `Optional readOnly` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `AUTO("auto")` - - `Optional> toolNames` + - `LOW("low")` - List of allowed tool names. + - `HIGH("high")` - - `Optional never` + - `Optional fileData` - A filter object to specify which tools are allowed. + The content of the file to be sent to the model. - - `Optional readOnly` + - `Optional fileId` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The ID of the file to be sent to the model. - - `Optional> toolNames` + - `Optional fileUrl` - List of allowed tool names. + The URL of the file to be sent to the model. - - `enum McpToolApprovalSetting:` + - `Optional filename` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The name of the file to be sent to the model. - - `ALWAYS("always")` + - `Optional promptCacheBreakpoint` - - `NEVER("never")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional serverDescription` + - `JsonValue; mode "explicit"constant` - Optional description of the MCP server, used to provide more context. + The breakpoint mode. Always `explicit`. - - `Optional serverUrl` + - `EXPLICIT("explicit")` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `Status status` - - `Optional tunnelId` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `IN_PROGRESS("in_progress")` - - `CodeInterpreter` + - `COMPLETED("completed")` - - `Container container` + - `INCOMPLETE("incomplete")` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `JsonValue; type "function_call_output"constant` - - `String` + The type of the function tool call output. Always `function_call_output`. - - `class CodeInterpreterToolAuto:` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `Optional agent` - - `JsonValue; type "auto"constant` + The agent that produced this item. - Always `auto`. + - `String agentName` - - `AUTO("auto")` + The canonical name of the agent that produced this item. - - `Optional> fileIds` + - `Optional caller` - An optional list of uploaded files to make available to your code. + The execution context that produced this tool call. - - `Optional memoryLimit` + - `JsonValue;` - The memory limit for the code interpreter container. + - `JsonValue; type "direct"constant` - - `_1G("1g")` + The caller type. Always `direct`. - - `_4G("4g")` + - `DIRECT("direct")` - - `_16G("16g")` + - `class Program:` - - `_64G("64g")` + - `String callerId` - - `Optional networkPolicy` + The call ID of the program item that produced this tool call. - Network access policy for the container. + - `JsonValue; type "program"constant` - - `class BetaContainerNetworkPolicyDisabled:` + The caller type. Always `program`. - - `JsonValue; type "disabled"constant` + - `PROGRAM("program")` - Disable outbound network access. Always `disabled`. + - `Optional createdBy` - - `DISABLED("disabled")` + The identifier of the actor that created the item. - - `class BetaContainerNetworkPolicyAllowlist:` + - `AgentMessage` - - `List allowedDomains` + - `String id` - A list of allowed domains when type is `allowlist`. + The unique ID of the agent message. - - `JsonValue; type "allowlist"constant` + - `String author` - Allow outbound network access only to specified domains. Always `allowlist`. + The sending agent identity. - - `ALLOWLIST("allowlist")` + - `List content` - - `Optional> domainSecrets` + Encrypted content sent between agents. - Optional domain-scoped secrets for allowlisted domains. + - `class BetaResponseInputText:` - - `String domain` + A text input to the model. - The domain associated with the secret. + - `class BetaResponseOutputText:` - - `String name` + A text output from the model. - The name of the secret to inject for the domain. + - `class Text:` - - `String value` + A text content. - The secret value to inject for the domain. + - `String text` - - `JsonValue; type "code_interpreter"constant` + - `JsonValue; type "text"constant` - The type of the code interpreter tool. Always `code_interpreter`. + - `TEXT("text")` - - `CODE_INTERPRETER("code_interpreter")` + - `class SummaryText:` - - `Optional> allowedCallers` + A summary text from the model. - The tool invocation context(s). + - `String text` - - `DIRECT("direct")` + A summary of the reasoning output from the model so far. - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "summary_text"constant` - - `JsonValue;` + The type of the object. Always `summary_text`. - - `JsonValue; type "programmatic_tool_calling"constant` + - `SUMMARY_TEXT("summary_text")` - The type of the tool. Always `programmatic_tool_calling`. + - `class ReasoningText:` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + Reasoning text from the model. - - `ImageGeneration` + - `String text` - - `JsonValue; type "image_generation"constant` + The reasoning text from the model. - The type of the image generation tool. Always `image_generation`. + - `JsonValue; type "reasoning_text"constant` - - `IMAGE_GENERATION("image_generation")` + The type of the reasoning text. Always `reasoning_text`. - - `Optional action` + - `REASONING_TEXT("reasoning_text")` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class BetaResponseOutputRefusal:` - - `GENERATE("generate")` + A refusal from the model. - - `EDIT("edit")` + - `class BetaResponseInputImage:` - - `AUTO("auto")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional background` + - `class ComputerScreenshot:` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + A screenshot of a computer. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `Detail detail` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `TRANSPARENT("transparent")` + - `LOW("low")` - - `OPAQUE("opaque")` + - `HIGH("high")` - `AUTO("auto")` - - `Optional inputFidelity` + - `ORIGINAL("original")` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `Optional fileId` - - `HIGH("high")` + The identifier of an uploaded file that contains the screenshot. - - `LOW("low")` + - `Optional imageUrl` - - `Optional inputImageMask` + The URL of the screenshot image. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `JsonValue; type "computer_screenshot"constant` - - `Optional fileId` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - File ID for the mask image. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `Optional imageUrl` + - `Optional promptCacheBreakpoint` - Base64-encoded mask image. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional model` + - `JsonValue; mode "explicit"constant` - The image generation model to use. Default: `gpt-image-1`. + The breakpoint mode. Always `explicit`. - - `GPT_IMAGE_1("gpt-image-1")` + - `EXPLICIT("explicit")` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `class BetaResponseInputFile:` - - `GPT_IMAGE_2("gpt-image-2")` + A file input to the model. - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + - `class EncryptedContent:` - - `GPT_IMAGE_1_5("gpt-image-1.5")` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `String encryptedContent` - - `Optional moderation` + Opaque encrypted content. - Moderation level for the generated image. Default: `auto`. + - `JsonValue; type "encrypted_content"constant` - - `AUTO("auto")` + The type of the input item. Always `encrypted_content`. - - `LOW("low")` + - `ENCRYPTED_CONTENT("encrypted_content")` - - `Optional outputCompression` + - `String recipient` - Compression level for the output image. Default: 100. + The destination agent identity. - - `Optional outputFormat` + - `JsonValue; type "agent_message"constant` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The type of the item. Always `agent_message`. - - `PNG("png")` + - `AGENT_MESSAGE("agent_message")` - - `WEBP("webp")` + - `Optional agent` - - `JPEG("jpeg")` + The agent that produced this item. - - `Optional partialImages` + - `String agentName` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The canonical name of the agent that produced this item. - - `Optional quality` + - `MultiAgentCall` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `String id` - - `LOW("low")` + The unique ID of the multi-agent call item. - - `MEDIUM("medium")` + - `Action action` - - `HIGH("high")` + The multi-agent action to execute. - - `AUTO("auto")` + - `SPAWN_AGENT("spawn_agent")` - - `Optional size` + - `INTERRUPT_AGENT("interrupt_agent")` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `LIST_AGENTS("list_agents")` - - `_1024X1024("1024x1024")` + - `SEND_MESSAGE("send_message")` - - `_1024X1536("1024x1536")` + - `FOLLOWUP_TASK("followup_task")` - - `_1536X1024("1536x1024")` + - `WAIT_AGENT("wait_agent")` - - `AUTO("auto")` + - `String arguments` - - `JsonValue;` + The JSON string of arguments generated for the action. - - `JsonValue; type "local_shell"constant` + - `String callId` - The type of the local shell tool. Always `local_shell`. + The unique ID linking this call to its output. - - `LOCAL_SHELL("local_shell")` + - `JsonValue; type "multi_agent_call"constant` - - `class BetaFunctionShellTool:` + The type of the multi-agent call. Always `multi_agent_call`. - A tool that allows the model to execute shell commands. + - `MULTI_AGENT_CALL("multi_agent_call")` - - `JsonValue; type "shell"constant` + - `Optional agent` - The type of the shell tool. Always `shell`. + The agent that produced this item. - - `SHELL("shell")` + - `String agentName` - - `Optional> allowedCallers` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `MultiAgentCallOutput` - - `DIRECT("direct")` + - `String id` - - `PROGRAMMATIC("programmatic")` + The unique ID of the multi-agent call output item. - - `Optional environment` + - `Action action` - - `class BetaContainerAuto:` + The multi-agent action that produced this result. - - `JsonValue; type "container_auto"constant` + - `SPAWN_AGENT("spawn_agent")` - Automatically creates a container for this request + - `INTERRUPT_AGENT("interrupt_agent")` - - `CONTAINER_AUTO("container_auto")` + - `LIST_AGENTS("list_agents")` - - `Optional> fileIds` + - `SEND_MESSAGE("send_message")` - An optional list of uploaded files to make available to your code. + - `FOLLOWUP_TASK("followup_task")` - - `Optional memoryLimit` + - `WAIT_AGENT("wait_agent")` - The memory limit for the container. + - `String callId` - - `_1G("1g")` + The unique ID of the multi-agent call. - - `_4G("4g")` + - `List output` - - `_16G("16g")` + Text output returned by the multi-agent action. - - `_64G("64g")` + - `List annotations` - - `Optional networkPolicy` + The annotations of the text output. - Network access policy for the container. + - `String text` - - `class BetaContainerNetworkPolicyDisabled:` + The text output from the model. - - `class BetaContainerNetworkPolicyAllowlist:` + - `JsonValue; type "output_text"constant` - - `Optional> skills` + The type of the output text. Always `output_text`. - An optional list of skills referenced by id or inline data. + - `Optional> logprobs` - - `class BetaSkillReference:` + - `JsonValue; type "multi_agent_call_output"constant` - - `String skillId` + The type of the multi-agent result. Always `multi_agent_call_output`. - The ID of the referenced skill. + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `JsonValue; type "skill_reference"constant` + - `Optional agent` - References a skill created with the /v1/skills endpoint. + The agent that produced this item. - - `SKILL_REFERENCE("skill_reference")` + - `String agentName` - - `Optional version` + The canonical name of the agent that produced this item. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `class BetaResponseFunctionWebSearch:` - - `class BetaInlineSkill:` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `String description` + - `String id` - The description of the skill. + The unique ID of the web search tool call. - - `String name` + - `Action action` - The name of the skill. + 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). - - `BetaInlineSkillSource source` + - `class Search:` - Inline skill payload + Action type "search" - Performs a web search query. - - `String data` + - `JsonValue; type "search"constant` - Base64-encoded skill zip bundle. + The action type. - - `JsonValue; mediaType "application/zip"constant` + - `SEARCH("search")` - The media type of the inline skill payload. Must be `application/zip`. + - `Optional> queries` - - `APPLICATION_ZIP("application/zip")` + The search queries. - - `JsonValue; type "base64"constant` + - `Optional query` - The type of the inline skill source. Must be `base64`. + The search query. - - `BASE64("base64")` + - `Optional> sources` - - `JsonValue; type "inline"constant` + The sources used in the search. - Defines an inline skill for this request. + - `JsonValue; type "url"constant` - - `INLINE("inline")` + The type of source. Always `url`. - - `class BetaLocalEnvironment:` + - `URL("url")` - - `JsonValue; type "local"constant` + - `String url` - Use a local computer environment. + The URL of the source. - - `LOCAL("local")` + - `class OpenPage:` - - `Optional> skills` + Action type "open_page" - Opens a specific URL from search results. - An optional list of skills. + - `JsonValue; type "open_page"constant` - - `String description` + The action type. - The description of the skill. + - `OPEN_PAGE("open_page")` - - `String name` + - `Optional url` - The name of the skill. + The URL opened by the model. - - `String path` + - `class FindInPage:` - The path to the directory containing the skill. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `class BetaContainerReference:` + - `String pattern` - - `String containerId` + The pattern or text to search for within the page. - The ID of the referenced container. + - `JsonValue; type "find_in_page"constant` - - `JsonValue; type "container_reference"constant` + The action type. - References a container created with the /v1/containers endpoint + - `FIND_IN_PAGE("find_in_page")` - - `CONTAINER_REFERENCE("container_reference")` + - `String url` - - `class BetaCustomTool:` + The URL of the page searched for the pattern. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Status status` - - `String name` + The status of the web search tool call. - The name of the custom tool, used to identify it in tool calls. + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "custom"constant` + - `SEARCHING("searching")` - The type of the custom tool. Always `custom`. + - `COMPLETED("completed")` - - `CUSTOM("custom")` + - `FAILED("failed")` - - `Optional> allowedCallers` + - `JsonValue; type "web_search_call"constant` - The tool invocation context(s). + The type of the web search tool call. Always `web_search_call`. - - `DIRECT("direct")` + - `WEB_SEARCH_CALL("web_search_call")` - - `PROGRAMMATIC("programmatic")` + - `Optional agent` - - `Optional deferLoading` + The agent that produced this item. - Whether this tool should be deferred and discovered via tool search. + - `String agentName` - - `Optional description` + The canonical name of the agent that produced this item. - Optional description of the custom tool, used to provide more context. + - `class BetaResponseComputerToolCall:` - - `Optional format` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The input format for the custom tool. Default is unconstrained text. + - `String id` - - `JsonValue;` + The unique ID of the computer call. - - `JsonValue; type "text"constant` + - `String callId` - Unconstrained text format. Always `text`. + An identifier used when responding to the tool call with output. - - `TEXT("text")` + - `List pendingSafetyChecks` - - `class Grammar:` + The pending safety checks for the computer call. - A grammar defined by the user. + - `String id` - - `String definition` + The ID of the pending safety check. - The grammar definition. + - `Optional code` - - `Syntax syntax` + The type of the pending safety check. - The syntax of the grammar definition. One of `lark` or `regex`. + - `Optional message` - - `LARK("lark")` + Details about the pending safety check. - - `REGEX("regex")` + - `Status status` - - `JsonValue; type "grammar"constant` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Grammar format. Always `grammar`. + - `IN_PROGRESS("in_progress")` - - `GRAMMAR("grammar")` + - `COMPLETED("completed")` - - `class BetaNamespaceTool:` + - `INCOMPLETE("incomplete")` - Groups function/custom tools under a shared namespace. + - `Type type` - - `String description` + The type of the computer call. Always `computer_call`. - A description of the namespace shown to the model. + - `COMPUTER_CALL("computer_call")` - - `String name` + - `Optional action` - The namespace name used in tool calls (for example, `crm`). + A click action. - - `List tools` + - `Click` - The function/custom tools available inside this namespace. + - `Button button` - - `class Function:` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `String name` + - `LEFT("left")` - - `JsonValue; type "function"constant` + - `RIGHT("right")` - - `FUNCTION("function")` + - `WHEEL("wheel")` - - `Optional> allowedCallers` + - `BACK("back")` - The tool invocation context(s). + - `FORWARD("forward")` - - `DIRECT("direct")` + - `JsonValue; type "click"constant` - - `PROGRAMMATIC("programmatic")` + Specifies the event type. For a click action, this property is always `click`. - - `Optional deferLoading` + - `CLICK("click")` - Whether this function should be deferred and discovered via tool search. + - `long x` - - `Optional description` + The x-coordinate where the click occurred. - - `Optional outputSchema` + - `long y` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The y-coordinate where the click occurred. - - `Optional parameters` + - `Optional> keys` - - `Optional strict` + The keys being held while clicking. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `DoubleClick` - - `class BetaCustomTool:` + - `Optional> keys` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The keys being held while double-clicking. - - `JsonValue; type "namespace"constant` + - `JsonValue; type "double_click"constant` - The type of the tool. Always `namespace`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `NAMESPACE("namespace")` + - `DOUBLE_CLICK("double_click")` - - `class BetaToolSearchTool:` + - `long x` - Hosted or BYOT tool search configuration for deferred tools. + The x-coordinate where the double click occurred. - - `JsonValue; type "tool_search"constant` + - `long y` - The type of the tool. Always `tool_search`. + The y-coordinate where the double click occurred. - - `TOOL_SEARCH("tool_search")` + - `Drag` - - `Optional description` + - `List path` - Description shown to the model for a client-executed tool search tool. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `Optional execution` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Whether tool search is executed by the server or by the client. + - `long x` - - `SERVER("server")` + The x-coordinate. - - `CLIENT("client")` + - `long y` - - `Optional parameters` + The y-coordinate. - Parameter schema for a client-executed tool search tool. + - `JsonValue; type "drag"constant` - - `class BetaWebSearchPreviewTool:` + Specifies the event type. For a drag action, this property is always set to `drag`. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `DRAG("drag")` - - `Type type` + - `Optional> keys` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The keys being held while dragging the mouse. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `Keypress` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `List keys` - - `Optional> searchContentTypes` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `TEXT("text")` + - `JsonValue; type "keypress"constant` - - `IMAGE("image")` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `Optional searchContextSize` + - `KEYPRESS("keypress")` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `Move` - - `LOW("low")` + - `JsonValue; type "move"constant` - - `MEDIUM("medium")` + Specifies the event type. For a move action, this property is always set to `move`. - - `HIGH("high")` + - `MOVE("move")` - - `Optional userLocation` + - `long x` - The user's location. + The x-coordinate to move to. - - `JsonValue; type "approximate"constant` + - `long y` - The type of location approximation. Always `approximate`. + The y-coordinate to move to. - - `APPROXIMATE("approximate")` + - `Optional> keys` - - `Optional city` + The keys being held while moving the mouse. - Free text input for the city of the user, e.g. `San Francisco`. + - `JsonValue;` - - `Optional country` + - `JsonValue; type "screenshot"constant` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `Optional region` + - `SCREENSHOT("screenshot")` - Free text input for the region of the user, e.g. `California`. + - `Scroll` - - `Optional timezone` + - `long scrollX` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The horizontal scroll distance. - - `class BetaApplyPatchTool:` + - `long scrollY` - Allows the assistant to create, delete, or update files using unified diffs. + The vertical scroll distance. - - `JsonValue; type "apply_patch"constant` + - `JsonValue; type "scroll"constant` - The type of the tool. Always `apply_patch`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `APPLY_PATCH("apply_patch")` + - `SCROLL("scroll")` - - `Optional> allowedCallers` + - `long x` - The tool invocation context(s). + The x-coordinate where the scroll occurred. - - `DIRECT("direct")` + - `long y` - - `PROGRAMMATIC("programmatic")` + The y-coordinate where the scroll occurred. - - `JsonValue; type "tool_search_output"constant` + - `Optional> keys` - The item type. Always `tool_search_output`. + The keys being held while scrolling. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `Type` - - `Optional id` + - `String text` - The unique ID of this tool search output. + The text to type. - - `Optional agent` + - `JsonValue; type "type"constant` - The agent that produced this item. + Specifies the event type. For a type action, this property is always set to `type`. - - `String agentName` + - `TYPE("type")` - The canonical name of the agent that produced this item. + - `JsonValue;` - - `Optional callId` + - `JsonValue; type "wait"constant` - The unique ID of the tool search call generated by the model. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `Optional execution` + - `WAIT("wait")` - Whether tool search was executed by the server or by the client. + - `Optional> actions` - - `SERVER("server")` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `CLIENT("client")` + - `Click` - - `Optional status` + - `DoubleClick` - The status of the tool search output. + - `Drag` - - `IN_PROGRESS("in_progress")` + - `Keypress` - - `COMPLETED("completed")` + - `Move` - - `INCOMPLETE("incomplete")` + - `JsonValue;` - - `AdditionalTools` + - `Scroll` - - `JsonValue; role "developer"constant` + - `Type` - The role that provided the additional tools. Only `developer` is supported. + - `JsonValue;` - - `DEVELOPER("developer")` + - `Optional agent` - - `List tools` + The agent that produced this item. - A list of additional tools made available at this item. + - `String agentName` - - `class BetaFunctionTool:` + The canonical name of the agent that produced this item. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class BetaResponseComputerToolCallOutputItem:` - - `class BetaFileSearchTool:` + - `String id` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The unique ID of the computer call tool output. - - `class BetaComputerTool:` + - `String callId` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the computer tool call that produced the output. - - `class BetaComputerUsePreviewTool:` + - `BetaResponseComputerToolCallOutputScreenshot output` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A computer screenshot image used with the computer use tool. - - `class BetaWebSearchTool:` + - `JsonValue; type "computer_screenshot"constant` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `Mcp` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `CodeInterpreter` + - `Optional fileId` - - `JsonValue;` + The identifier of an uploaded file that contains the screenshot. - - `ImageGeneration` + - `Optional imageUrl` - - `JsonValue;` + The URL of the screenshot image. - - `class BetaFunctionShellTool:` + - `Status status` - A tool that allows the model to execute shell commands. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `class BetaCustomTool:` + - `COMPLETED("completed")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `INCOMPLETE("incomplete")` - - `class BetaNamespaceTool:` + - `FAILED("failed")` - Groups function/custom tools under a shared namespace. + - `IN_PROGRESS("in_progress")` - - `class BetaToolSearchTool:` + - `JsonValue; type "computer_call_output"constant` - Hosted or BYOT tool search configuration for deferred tools. + The type of the computer tool call output. Always `computer_call_output`. - - `class BetaWebSearchPreviewTool:` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional> acknowledgedSafetyChecks` - - `class BetaApplyPatchTool:` + The safety checks reported by the API that have been acknowledged by the + developer. - Allows the assistant to create, delete, or update files using unified diffs. + - `String id` - - `JsonValue; type "additional_tools"constant` + The ID of the pending safety check. - The item type. Always `additional_tools`. + - `Optional code` - - `ADDITIONAL_TOOLS("additional_tools")` + The type of the pending safety check. - - `Optional id` + - `Optional message` - The unique ID of this additional tools item. + Details about the pending safety check. - `Optional agent` @@ -80598,6 +94046,10 @@ public final class Main { The canonical name of the agent that produced this item. + - `Optional createdBy` + + The identifier of the actor that created the item. + - `class BetaResponseReasoningItem:` A description of the chain of thought used by a reasoning model while generating @@ -80667,23 +94119,29 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseCompactionItemParam:` + - `Program` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `String id` - - `String encryptedContent` + The unique ID of the program item. - The encrypted content of the compaction summary. + - `String callId` - - `JsonValue; type "compaction"constant` + The stable call ID of the program item. - The type of the item. Always `compaction`. + - `String code` - - `COMPACTION("compaction")` + The JavaScript source executed by programmatic tool calling. - - `Optional id` + - `String fingerprint` - The ID of the compaction item. + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The type of the item. Always `program`. + + - `PROGRAM("program")` - `Optional agent` @@ -80693,33 +94151,79 @@ public final class Main { The canonical name of the agent that produced this item. - - `ImageGenerationCall` + - `ProgramOutput` - `String id` - The unique ID of the image generation call. + The unique ID of the program output item. - - `Optional result` + - `String callId` - The generated image encoded in base64. + The call ID of the program item. + + - `String result` + + The result produced by the program item. - `Status status` - The status of the image generation call. + The terminal status of the program output item. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The type of the item. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall:` + + - `String id` + + The unique ID of the tool search call item. + + - `JsonValue arguments` + + Arguments used for the tool search call. + + - `Optional callId` + + The unique ID of the tool search call generated by the model. + + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search call item that was recorded. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - - `GENERATING("generating")` - - - `FAILED("failed")` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "tool_search_call"constant` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `tool_search_call`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional agent` @@ -80729,1209 +94233,1344 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` + - `Optional createdBy` - A tool call to run code. + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem:` - `String id` - The unique ID of the code interpreter tool call. + The unique ID of the tool search output item. - - `Optional code` + - `Optional callId` - The code to run, or null if not available. + The unique ID of the tool search call generated by the model. - - `String containerId` + - `Execution execution` + + Whether tool search was executed by the server or by the client. + + - `SERVER("server")` + + - `CLIENT("client")` + + - `Status status` + + The status of the tool search output item that was recorded. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `List tools` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `String name` + + The name of the function to call. + + - `Optional parameters` + + A JSON schema object describing the parameters of the function. + + - `Optional strict` + + Whether strict parameter validation is enforced for this function tool. + + - `JsonValue; type "function"constant` + + The type of the function tool. Always `function`. + + - `FUNCTION("function")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` + + - `Optional deferLoading` + + Whether this function is deferred and loaded via tool search. + + - `Optional description` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `Optional outputSchema` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `JsonValue; type "file_search"constant` + + The type of the file search tool. Always `file_search`. + + - `FILE_SEARCH("file_search")` + + - `List vectorStoreIds` + + The IDs of the vector stores to search. + + - `Optional 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 - The ID of the container used to run the code. + - `EQ("eq")` - - `Optional> outputs` + - `NE("ne")` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `GT("gt")` - - `class Logs:` + - `GTE("gte")` - The logs output from the code interpreter. + - `LT("lt")` - - `String logs` + - `LTE("lte")` - The logs output from the code interpreter. + - `IN("in")` - - `JsonValue; type "logs"constant` + - `NIN("nin")` - The type of the output. Always `logs`. + - `Value value` - - `LOGS("logs")` + The value to compare against the attribute key; supports string, number, or boolean types. - - `class Image:` + - `String` - The image output from the code interpreter. + - `double` - - `JsonValue; type "image"constant` + - `boolean` - The type of the output. Always `image`. + - `List` - - `IMAGE("image")` + - `String` - - `String url` + - `double` - The URL of the image output from the code interpreter. + - `class CompoundFilter:` - - `Status status` + Combine multiple filters using `and` or `or`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `List filters` - - `IN_PROGRESS("in_progress")` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `COMPLETED("completed")` + - `class ComparisonFilter:` - - `INCOMPLETE("incomplete")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `INTERPRETING("interpreting")` + - `String key` - - `FAILED("failed")` + The key to compare against the value. - - `JsonValue; type "code_interpreter_call"constant` + - `Type type` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Optional agent` + - `EQ("eq")` - The agent that produced this item. + - `NE("ne")` - - `String agentName` + - `GT("gt")` - The canonical name of the agent that produced this item. + - `GTE("gte")` - - `LocalShellCall` + - `LT("lt")` - - `String id` + - `LTE("lte")` - The unique ID of the local shell call. + - `IN("in")` - - `Action action` + - `NIN("nin")` - Execute a shell command on the server. + - `Value value` - - `List command` + The value to compare against the attribute key; supports string, number, or boolean types. - The command to run. + - `String` - - `Env env` + - `double` - Environment variables to set for the command. + - `boolean` - - `JsonValue; type "exec"constant` + - `List` - The type of the local shell action. Always `exec`. + - `String` - - `EXEC("exec")` + - `double` - - `Optional timeoutMs` + - `JsonValue` - Optional timeout in milliseconds for the command. + - `Type type` - - `Optional user` + Type of operation: `and` or `or`. - Optional user to run the command as. + - `AND("and")` - - `Optional workingDirectory` + - `OR("or")` - Optional working directory to run the command in. + - `Optional maxNumResults` - - `String callId` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The unique ID of the local shell tool call generated by the model. + - `Optional rankingOptions` - - `Status status` + Ranking options for search. - The status of the local shell call. + - `Optional hybridSearch` - - `IN_PROGRESS("in_progress")` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `COMPLETED("completed")` + - `double embeddingWeight` - - `INCOMPLETE("incomplete")` + The weight of the embedding in the reciprocal ranking fusion. - - `JsonValue; type "local_shell_call"constant` + - `double textWeight` - The type of the local shell call. Always `local_shell_call`. + The weight of the text in the reciprocal ranking fusion. - - `LOCAL_SHELL_CALL("local_shell_call")` + - `Optional ranker` - - `Optional agent` + The ranker to use for the file search. - The agent that produced this item. + - `AUTO("auto")` - - `String agentName` + - `DEFAULT_2024_11_15("default-2024-11-15")` - The canonical name of the agent that produced this item. + - `Optional scoreThreshold` - - `LocalShellCallOutput` + 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. - - `String id` + - `class BetaComputerTool:` - The unique ID of the local shell tool call generated by the model. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String output` + - `JsonValue; type "computer"constant` - A JSON string of the output of the local shell tool call. + The type of the computer tool. Always `computer`. - - `JsonValue; type "local_shell_call_output"constant` + - `COMPUTER("computer")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `class BetaComputerUsePreviewTool:` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional agent` + - `long displayHeight` - The agent that produced this item. + The height of the computer display. - - `String agentName` + - `long displayWidth` - The canonical name of the agent that produced this item. + The width of the computer display. - - `Optional status` + - `Environment environment` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The type of computer environment to control. - - `IN_PROGRESS("in_progress")` + - `WINDOWS("windows")` - - `COMPLETED("completed")` + - `MAC("mac")` - - `INCOMPLETE("incomplete")` + - `LINUX("linux")` - - `ShellCall` + - `UBUNTU("ubuntu")` - - `Action action` + - `BROWSER("browser")` - The shell commands and limits that describe how to run the tool call. + - `JsonValue; type "computer_use_preview"constant` - - `List commands` + The type of the computer use tool. Always `computer_use_preview`. - Ordered shell commands for the execution environment to run. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `Optional maxOutputLength` + - `class BetaWebSearchTool:` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional timeoutMs` + - `Type type` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `String callId` + - `WEB_SEARCH("web_search")` - The unique ID of the shell tool call generated by the model. + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `JsonValue; type "shell_call"constant` + - `Optional filters` - The type of the item. Always `shell_call`. + Filters for the search. - - `SHELL_CALL("shell_call")` + - `Optional> allowedDomains` - - `Optional id` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The unique ID of the shell tool call. Populated when this item is returned via API. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `Optional agent` + - `Optional searchContextSize` - The agent that produced this item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `String agentName` + - `LOW("low")` - The canonical name of the agent that produced this item. + - `MEDIUM("medium")` - - `Optional caller` + - `HIGH("high")` - The execution context that produced this tool call. + - `Optional userLocation` - - `JsonValue;` + The approximate location of the user. - - `JsonValue; type "direct"constant` + - `Optional city` - The caller type. Always `direct`. + Free text input for the city of the user, e.g. `San Francisco`. - - `DIRECT("direct")` + - `Optional country` - - `class Program:` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `String callerId` + - `Optional region` - The call ID of the program item that produced this tool call. + Free text input for the region of the user, e.g. `California`. - - `JsonValue; type "program"constant` + - `Optional timezone` - The caller type. Always `program`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `PROGRAM("program")` + - `Optional type` - - `Optional environment` + The type of location approximation. Always `approximate`. - The environment to execute the shell commands in. + - `APPROXIMATE("approximate")` - - `class BetaLocalEnvironment:` + - `Mcp` - - `class BetaContainerReference:` + - `String serverLabel` - - `Optional status` + A label for this MCP server, used to identify it in tool calls. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `JsonValue; type "mcp"constant` - - `IN_PROGRESS("in_progress")` + The type of the MCP tool. Always `mcp`. - - `COMPLETED("completed")` + - `MCP("mcp")` - - `INCOMPLETE("incomplete")` + - `Optional> allowedCallers` - - `ShellCallOutput` + The tool invocation context(s). - - `String callId` + - `DIRECT("direct")` - The unique ID of the shell tool call generated by the model. + - `PROGRAMMATIC("programmatic")` - - `List output` + - `Optional allowedTools` - Captured chunks of stdout and stderr output, along with their associated outcomes. + List of allowed tool names or a filter object. - - `Outcome outcome` + - `List` - The exit or timeout outcome associated with this shell call. + - `class McpToolFilter:` - - `JsonValue;` + A filter object to specify which tools are allowed. - - `JsonValue; type "timeout"constant` + - `Optional readOnly` - The outcome type. Always `timeout`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `TIMEOUT("timeout")` + - `Optional> toolNames` - - `class Exit:` + List of allowed tool names. - Indicates that the shell commands finished and returned an exit code. + - `Optional authorization` - - `long exitCode` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The exit code returned by the shell process. + - `Optional connectorId` - - `JsonValue; type "exit"constant` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The outcome type. Always `exit`. + Currently supported `connector_id` values are: - - `EXIT("exit")` + - 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` - - `String stderr` + - `CONNECTOR_DROPBOX("connector_dropbox")` - Captured stderr output for the shell call. + - `CONNECTOR_GMAIL("connector_gmail")` - - `String stdout` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - Captured stdout output for the shell call. + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `JsonValue; type "shell_call_output"constant` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - The type of the item. Always `shell_call_output`. + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `Optional id` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `Optional deferLoading` - - `Optional agent` + Whether this MCP tool is deferred and discovered via tool search. - The agent that produced this item. + - `Optional headers` - - `String agentName` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The canonical name of the agent that produced this item. + - `Optional requireApproval` - - `Optional caller` + Specify which of the MCP server's tools require approval. - The execution context that produced this tool call. + - `class McpToolApprovalFilter:` - - `JsonValue;` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `JsonValue; type "direct"constant` + - `Optional always` - The caller type. Always `direct`. + A filter object to specify which tools are allowed. - - `DIRECT("direct")` + - `Optional readOnly` - - `class Program:` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `String callerId` + - `Optional> toolNames` - The call ID of the program item that produced this tool call. + List of allowed tool names. - - `JsonValue; type "program"constant` + - `Optional never` - The caller type. Always `program`. + A filter object to specify which tools are allowed. - - `PROGRAM("program")` + - `Optional readOnly` - - `Optional maxOutputLength` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `Optional> toolNames` - - `Optional status` + List of allowed tool names. - The status of the shell call output. + - `enum McpToolApprovalSetting:` - - `IN_PROGRESS("in_progress")` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `COMPLETED("completed")` + - `ALWAYS("always")` - - `INCOMPLETE("incomplete")` + - `NEVER("never")` - - `ApplyPatchCall` + - `Optional serverDescription` - - `String callId` + Optional description of the MCP server, used to provide more context. - The unique ID of the apply patch tool call generated by the model. + - `Optional serverUrl` - - `Operation operation` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The specific create, delete, or update instruction for the apply_patch tool call. + - `Optional tunnelId` - - `class CreateFile:` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - Instruction for creating a new file via the apply_patch tool. + - `CodeInterpreter` - - `String diff` + - `Container container` - Unified diff content to apply when creating the file. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `String path` + - `String` - Path of the file to create relative to the workspace root. + - `class CodeInterpreterToolAuto:` - - `JsonValue; type "create_file"constant` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The operation type. Always `create_file`. + - `JsonValue; type "auto"constant` - - `CREATE_FILE("create_file")` + Always `auto`. - - `class DeleteFile:` + - `AUTO("auto")` - Instruction for deleting an existing file via the apply_patch tool. + - `Optional> fileIds` - - `String path` + An optional list of uploaded files to make available to your code. - Path of the file to delete relative to the workspace root. + - `Optional memoryLimit` - - `JsonValue; type "delete_file"constant` + The memory limit for the code interpreter container. - The operation type. Always `delete_file`. + - `_1G("1g")` - - `DELETE_FILE("delete_file")` + - `_4G("4g")` - - `class UpdateFile:` + - `_16G("16g")` - Instruction for updating an existing file via the apply_patch tool. + - `_64G("64g")` - - `String diff` + - `Optional networkPolicy` - Unified diff content to apply to the existing file. + Network access policy for the container. - - `String path` + - `class BetaContainerNetworkPolicyDisabled:` - Path of the file to update relative to the workspace root. + - `JsonValue; type "disabled"constant` - - `JsonValue; type "update_file"constant` + Disable outbound network access. Always `disabled`. - The operation type. Always `update_file`. + - `DISABLED("disabled")` - - `UPDATE_FILE("update_file")` + - `class BetaContainerNetworkPolicyAllowlist:` - - `Status status` + - `List allowedDomains` - The status of the apply patch tool call. One of `in_progress` or `completed`. + A list of allowed domains when type is `allowlist`. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "allowlist"constant` - - `COMPLETED("completed")` + Allow outbound network access only to specified domains. Always `allowlist`. - - `JsonValue; type "apply_patch_call"constant` + - `ALLOWLIST("allowlist")` - The type of the item. Always `apply_patch_call`. + - `Optional> domainSecrets` - - `APPLY_PATCH_CALL("apply_patch_call")` + Optional domain-scoped secrets for allowlisted domains. - - `Optional id` + - `String domain` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The domain associated with the secret. - - `Optional agent` + - `String name` - The agent that produced this item. + The name of the secret to inject for the domain. - - `String agentName` + - `String value` - The canonical name of the agent that produced this item. + The secret value to inject for the domain. - - `Optional caller` + - `JsonValue; type "code_interpreter"constant` - The execution context that produced this tool call. + The type of the code interpreter tool. Always `code_interpreter`. - - `JsonValue;` + - `CODE_INTERPRETER("code_interpreter")` - - `JsonValue; type "direct"constant` + - `Optional> allowedCallers` - The caller type. Always `direct`. + The tool invocation context(s). - `DIRECT("direct")` - - `class Program:` + - `PROGRAMMATIC("programmatic")` - - `String callerId` + - `JsonValue;` - The call ID of the program item that produced this tool call. + - `JsonValue; type "programmatic_tool_calling"constant` - - `JsonValue; type "program"constant` + The type of the tool. Always `programmatic_tool_calling`. - The caller type. Always `program`. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `PROGRAM("program")` + - `ImageGeneration` - - `ApplyPatchCallOutput` + - `JsonValue; type "image_generation"constant` - - `String callId` + The type of the image generation tool. Always `image_generation`. - The unique ID of the apply patch tool call generated by the model. + - `IMAGE_GENERATION("image_generation")` - - `Status status` + - `Optional action` - The status of the apply patch tool call output. One of `completed` or `failed`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `COMPLETED("completed")` + - `GENERATE("generate")` - - `FAILED("failed")` + - `EDIT("edit")` - - `JsonValue; type "apply_patch_call_output"constant` + - `AUTO("auto")` - The type of the item. Always `apply_patch_call_output`. + - `Optional background` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `Optional id` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `Optional agent` + - `TRANSPARENT("transparent")` - The agent that produced this item. + - `OPAQUE("opaque")` - - `String agentName` + - `AUTO("auto")` - The canonical name of the agent that produced this item. + - `Optional inputFidelity` - - `Optional caller` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The execution context that produced this tool call. + - `HIGH("high")` - - `JsonValue;` + - `LOW("low")` - - `JsonValue; type "direct"constant` + - `Optional inputImageMask` - The caller type. Always `direct`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `DIRECT("direct")` + - `Optional fileId` - - `class Program:` + File ID for the mask image. - - `String callerId` + - `Optional imageUrl` - The call ID of the program item that produced this tool call. + Base64-encoded mask image. - - `JsonValue; type "program"constant` + - `Optional model` - The caller type. Always `program`. + The image generation model to use. Default: `gpt-image-1`. - - `PROGRAM("program")` + - `GPT_IMAGE_1("gpt-image-1")` - - `Optional output` + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `GPT_IMAGE_2("gpt-image-2")` - - `McpListTools` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `String id` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - The unique ID of the list. + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `String serverLabel` + - `Optional moderation` - The label of the MCP server. + Moderation level for the generated image. Default: `auto`. - - `List tools` + - `AUTO("auto")` - The tools available on the server. + - `LOW("low")` - - `JsonValue inputSchema` + - `Optional outputCompression` - The JSON schema describing the tool's input. + Compression level for the output image. Default: 100. - - `String name` + - `Optional outputFormat` - The name of the tool. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `Optional annotations` + - `PNG("png")` - Additional annotations about the tool. + - `WEBP("webp")` - - `Optional description` + - `JPEG("jpeg")` - The description of the tool. + - `Optional partialImages` - - `JsonValue; type "mcp_list_tools"constant` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of the item. Always `mcp_list_tools`. + - `Optional quality` - - `MCP_LIST_TOOLS("mcp_list_tools")` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `Optional agent` + - `LOW("low")` - The agent that produced this item. + - `MEDIUM("medium")` - - `String agentName` + - `HIGH("high")` - The canonical name of the agent that produced this item. + - `AUTO("auto")` - - `Optional error` + - `Optional size` - Error message if the server could not list tools. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `McpApprovalRequest` + - `_1024X1024("1024x1024")` - - `String id` + - `_1024X1536("1024x1536")` - The unique ID of the approval request. + - `_1536X1024("1536x1024")` - - `String arguments` + - `AUTO("auto")` - A JSON string of arguments for the tool. + - `JsonValue;` - - `String name` + - `JsonValue; type "local_shell"constant` - The name of the tool to run. + The type of the local shell tool. Always `local_shell`. - - `String serverLabel` + - `LOCAL_SHELL("local_shell")` - The label of the MCP server making the request. + - `class BetaFunctionShellTool:` - - `JsonValue; type "mcp_approval_request"constant` + A tool that allows the model to execute shell commands. - The type of the item. Always `mcp_approval_request`. + - `JsonValue; type "shell"constant` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + The type of the shell tool. Always `shell`. - - `Optional agent` + - `SHELL("shell")` - The agent that produced this item. + - `Optional> allowedCallers` - - `String agentName` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `DIRECT("direct")` - - `McpApprovalResponse` + - `PROGRAMMATIC("programmatic")` - - `String approvalRequestId` + - `Optional environment` - The ID of the approval request being answered. + - `class BetaContainerAuto:` - - `boolean approve` + - `JsonValue; type "container_auto"constant` - Whether the request was approved. + Automatically creates a container for this request - - `JsonValue; type "mcp_approval_response"constant` + - `CONTAINER_AUTO("container_auto")` - The type of the item. Always `mcp_approval_response`. + - `Optional> fileIds` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + An optional list of uploaded files to make available to your code. - - `Optional id` + - `Optional memoryLimit` - The unique ID of the approval response + The memory limit for the container. - - `Optional agent` + - `_1G("1g")` - The agent that produced this item. + - `_4G("4g")` - - `String agentName` + - `_16G("16g")` - The canonical name of the agent that produced this item. + - `_64G("64g")` - - `Optional reason` + - `Optional networkPolicy` - Optional reason for the decision. + Network access policy for the container. - - `McpCall` + - `class BetaContainerNetworkPolicyDisabled:` - - `String id` + - `class BetaContainerNetworkPolicyAllowlist:` - The unique ID of the tool call. + - `Optional> skills` - - `String arguments` + An optional list of skills referenced by id or inline data. - A JSON string of the arguments passed to the tool. + - `class BetaSkillReference:` - - `String name` + - `String skillId` - The name of the tool that was run. + The ID of the referenced skill. - - `String serverLabel` + - `JsonValue; type "skill_reference"constant` - The label of the MCP server running the tool. + References a skill created with the /v1/skills endpoint. - - `JsonValue; type "mcp_call"constant` + - `SKILL_REFERENCE("skill_reference")` - The type of the item. Always `mcp_call`. + - `Optional version` - - `MCP_CALL("mcp_call")` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `Optional agent` + - `class BetaInlineSkill:` - The agent that produced this item. + - `String description` - - `String agentName` + The description of the skill. - The canonical name of the agent that produced this item. + - `String name` - - `Optional approvalRequestId` + The name of the skill. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `BetaInlineSkillSource source` - - `Optional error` + Inline skill payload - The error from the tool call, if any. + - `String data` - - `Optional output` + Base64-encoded skill zip bundle. - The output from the tool call. + - `JsonValue; mediaType "application/zip"constant` - - `Optional status` + The media type of the inline skill payload. Must be `application/zip`. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `APPLICATION_ZIP("application/zip")` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "base64"constant` - - `COMPLETED("completed")` + The type of the inline skill source. Must be `base64`. - - `INCOMPLETE("incomplete")` + - `BASE64("base64")` - - `CALLING("calling")` + - `JsonValue; type "inline"constant` - - `FAILED("failed")` + Defines an inline skill for this request. - - `class BetaResponseCustomToolCallOutput:` + - `INLINE("inline")` - The output of a custom tool call from your code, being sent back to the model. + - `class BetaLocalEnvironment:` - - `String callId` + - `JsonValue; type "local"constant` - The call ID, used to map this custom tool call output to a custom tool call. + Use a local computer environment. - - `Output output` + - `LOCAL("local")` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `Optional> skills` - - `String` + An optional list of skills. - - `List` + - `String description` - - `class BetaResponseInputText:` + The description of the skill. - A text input to the model. + - `String name` - - `class BetaResponseInputImage:` + The name of the skill. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `String path` - - `class BetaResponseInputFile:` + The path to the directory containing the skill. - A file input to the model. + - `class BetaContainerReference:` - - `JsonValue; type "custom_tool_call_output"constant` + - `String containerId` - The type of the custom tool call output. Always `custom_tool_call_output`. + The ID of the referenced container. - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `JsonValue; type "container_reference"constant` - - `Optional id` + References a container created with the /v1/containers endpoint - The unique ID of the custom tool call output in the OpenAI platform. + - `CONTAINER_REFERENCE("container_reference")` - - `Optional agent` + - `class BetaCustomTool:` - The agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `String agentName` + - `String name` - The canonical name of the agent that produced this item. + The name of the custom tool, used to identify it in tool calls. - - `Optional caller` + - `JsonValue; type "custom"constant` - The execution context that produced this tool call. + The type of the custom tool. Always `custom`. - - `JsonValue;` + - `CUSTOM("custom")` - - `JsonValue; type "direct"constant` + - `Optional> allowedCallers` - The caller type. Always `direct`. + The tool invocation context(s). - `DIRECT("direct")` - - `class Program:` + - `PROGRAMMATIC("programmatic")` - - `String callerId` + - `Optional deferLoading` - The call ID of the program item that produced this tool call. + Whether this tool should be deferred and discovered via tool search. - - `JsonValue; type "program"constant` + - `Optional description` - The caller type. Always `program`. + Optional description of the custom tool, used to provide more context. - - `PROGRAM("program")` + - `Optional format` - - `class BetaResponseCustomToolCall:` + The input format for the custom tool. Default is unconstrained text. - A call to a custom tool created by the model. + - `JsonValue;` - - `String callId` + - `JsonValue; type "text"constant` - An identifier used to map this custom tool call to a tool call output. + Unconstrained text format. Always `text`. - - `String input` + - `TEXT("text")` - The input for the custom tool call generated by the model. + - `class Grammar:` - - `String name` + A grammar defined by the user. - The name of the custom tool being called. + - `String definition` - - `JsonValue; type "custom_tool_call"constant` + The grammar definition. - The type of the custom tool call. Always `custom_tool_call`. + - `Syntax syntax` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + The syntax of the grammar definition. One of `lark` or `regex`. - - `Optional id` + - `LARK("lark")` - The unique ID of the custom tool call in the OpenAI platform. + - `REGEX("regex")` - - `Optional agent` + - `JsonValue; type "grammar"constant` - The agent that produced this item. + Grammar format. Always `grammar`. - - `String agentName` + - `GRAMMAR("grammar")` - The canonical name of the agent that produced this item. + - `class BetaNamespaceTool:` - - `Optional caller` + Groups function/custom tools under a shared namespace. - The execution context that produced this tool call. + - `String description` - - `JsonValue;` + A description of the namespace shown to the model. - - `JsonValue; type "direct"constant` + - `String name` - - `DIRECT("direct")` + The namespace name used in tool calls (for example, `crm`). - - `class Program:` + - `List tools` - - `String callerId` + The function/custom tools available inside this namespace. - The call ID of the program item that produced this tool call. + - `class Function:` - - `JsonValue; type "program"constant` + - `String name` - - `PROGRAM("program")` + - `JsonValue; type "function"constant` - - `Optional namespace` + - `FUNCTION("function")` - The namespace of the custom tool being called. + - `Optional> allowedCallers` - - `CompactionTrigger` + The tool invocation context(s). - - `JsonValue; type "compaction_trigger"constant` + - `DIRECT("direct")` - The type of the item. Always `compaction_trigger`. + - `PROGRAMMATIC("programmatic")` - - `COMPACTION_TRIGGER("compaction_trigger")` + - `Optional deferLoading` - - `Optional agent` + Whether this function should be deferred and discovered via tool search. - The agent that produced this item. + - `Optional description` - - `String agentName` + - `Optional outputSchema` - The canonical name of the agent that produced this item. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `ItemReference` + - `Optional parameters` - - `String id` + - `Optional strict` - The ID of the item to reference. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `Optional agent` + - `class BetaCustomTool:` - The agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `String agentName` + - `JsonValue; type "namespace"constant` - The canonical name of the agent that produced this item. + The type of the tool. Always `namespace`. - - `Optional type` + - `NAMESPACE("namespace")` - The type of item to reference. Always `item_reference`. + - `class BetaToolSearchTool:` - - `ITEM_REFERENCE("item_reference")` + Hosted or BYOT tool search configuration for deferred tools. - - `Program` + - `JsonValue; type "tool_search"constant` - - `String id` + The type of the tool. Always `tool_search`. - The unique ID of this program item. + - `TOOL_SEARCH("tool_search")` - - `String callId` + - `Optional description` - The stable call ID of the program item. + Description shown to the model for a client-executed tool search tool. - - `String code` + - `Optional execution` - The JavaScript source executed by programmatic tool calling. + Whether tool search is executed by the server or by the client. - - `String fingerprint` + - `SERVER("server")` - Opaque program replay fingerprint that must be round-tripped. + - `CLIENT("client")` - - `JsonValue; type "program"constant` + - `Optional parameters` - The item type. Always `program`. + Parameter schema for a client-executed tool search tool. - - `PROGRAM("program")` + - `class BetaWebSearchPreviewTool:` - - `Optional agent` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The agent that produced this item. + - `Type type` - - `String agentName` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The canonical name of the agent that produced this item. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `ProgramOutput` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `String id` + - `Optional> searchContentTypes` - The unique ID of this program output item. + - `TEXT("text")` - - `String callId` + - `IMAGE("image")` - The call ID of the program item. + - `Optional searchContextSize` - - `String result` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The result produced by the program item. + - `LOW("low")` - - `Status status` + - `MEDIUM("medium")` - The terminal status of the program output. + - `HIGH("high")` - - `COMPLETED("completed")` + - `Optional userLocation` - - `INCOMPLETE("incomplete")` + The user's location. - - `JsonValue; type "program_output"constant` + - `JsonValue; type "approximate"constant` - The item type. Always `program_output`. + The type of location approximation. Always `approximate`. - - `PROGRAM_OUTPUT("program_output")` + - `APPROXIMATE("approximate")` - - `Optional agent` + - `Optional city` - The agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `String agentName` + - `Optional country` - The canonical name of the agent that produced this item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `Optional metadata` + - `Optional region` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Free text input for the region of the user, e.g. `California`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `Optional timezone` - - `Model model` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `class BetaApplyPatchTool:` - - `GPT_5_6_SOL("gpt-5.6-sol")` + Allows the assistant to create, delete, or update files using unified diffs. - - `GPT_5_6_TERRA("gpt-5.6-terra")` + - `JsonValue; type "apply_patch"constant` - - `GPT_5_6_LUNA("gpt-5.6-luna")` + The type of the tool. Always `apply_patch`. - - `GPT_5_4("gpt-5.4")` + - `APPLY_PATCH("apply_patch")` - - `GPT_5_4_MINI("gpt-5.4-mini")` + - `Optional> allowedCallers` - - `GPT_5_4_NANO("gpt-5.4-nano")` + The tool invocation context(s). - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `DIRECT("direct")` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + - `PROGRAMMATIC("programmatic")` - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `JsonValue; type "tool_search_output"constant` - - `GPT_5_2("gpt-5.2")` + The type of the item. Always `tool_search_output`. - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + - `Optional agent` - - `GPT_5_2_PRO("gpt-5.2-pro")` + The agent that produced this item. - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + - `String agentName` - - `GPT_5_1("gpt-5.1")` + The canonical name of the agent that produced this item. - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `Optional createdBy` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + The identifier of the actor that created the item. - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `AdditionalTools` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + - `String id` - - `GPT_5("gpt-5")` + The unique ID of the additional tools item. - - `GPT_5_MINI("gpt-5-mini")` + - `Role role` - - `GPT_5_NANO("gpt-5-nano")` + The role that provided the additional tools. - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + - `UNKNOWN("unknown")` - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - `USER("user")` + + - `ASSISTANT("assistant")` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `SYSTEM("system")` - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `CRITIC("critic")` - - `GPT_4_1("gpt-4.1")` + - `DISCRIMINATOR("discriminator")` - - `GPT_4_1_MINI("gpt-4.1-mini")` + - `DEVELOPER("developer")` - - `GPT_4_1_NANO("gpt-4.1-nano")` + - `TOOL("tool")` - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `List tools` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + The additional tool definitions made available at this item. - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + - `class BetaFunctionTool:` - - `O4_MINI("o4-mini")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + - `class BetaFileSearchTool:` - - `O3("o3")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `O3_2025_04_16("o3-2025-04-16")` + - `class BetaComputerTool:` - - `O3_MINI("o3-mini")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + - `class BetaComputerUsePreviewTool:` - - `O1("o1")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `O1_2024_12_17("o1-2024-12-17")` + - `class BetaWebSearchTool:` - - `O1_PREVIEW("o1-preview")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + - `Mcp` - - `O1_MINI("o1-mini")` + - `CodeInterpreter` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + - `JsonValue;` - - `GPT_4O("gpt-4o")` + - `ImageGeneration` - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + - `JsonValue;` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + - `class BetaFunctionShellTool:` - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + A tool that allows the model to execute shell commands. - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + - `class BetaCustomTool:` - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + - `class BetaNamespaceTool:` - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + Groups function/custom tools under a shared namespace. - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + - `class BetaToolSearchTool:` - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + Hosted or BYOT tool search configuration for deferred tools. - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + - `class BetaWebSearchPreviewTool:` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `class BetaApplyPatchTool:` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + Allows the assistant to create, delete, or update files using unified diffs. - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `JsonValue; type "additional_tools"constant` - - `CODEX_MINI_LATEST("codex-mini-latest")` + The type of the item. Always `additional_tools`. - - `GPT_4O_MINI("gpt-4o-mini")` + - `ADDITIONAL_TOOLS("additional_tools")` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + - `Optional agent` - - `GPT_4_TURBO("gpt-4-turbo")` + The agent that produced this item. - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `String agentName` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + The canonical name of the agent that produced this item. - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + - `class BetaResponseCompactionItem:` - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + - `String id` - - `GPT_4("gpt-4")` + The unique ID of the compaction item. - - `GPT_4_0314("gpt-4-0314")` + - `String encryptedContent` - - `GPT_4_0613("gpt-4-0613")` + The encrypted content that was produced by compaction. - - `GPT_4_32K("gpt-4-32k")` + - `JsonValue; type "compaction"constant` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + The type of the item. Always `compaction`. - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `COMPACTION("compaction")` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `Optional agent` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + The agent that produced this item. - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `String agentName` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + The canonical name of the agent that produced this item. - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `Optional createdBy` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + The identifier of the actor that created the item. - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + - `ImageGenerationCall` - - `O1_PRO("o1-pro")` + - `String id` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + The unique ID of the image generation call. - - `O3_PRO("o3-pro")` + - `Optional result` - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + The generated image encoded in base64. - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `Status status` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + The status of the image generation call. - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + - `IN_PROGRESS("in_progress")` - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `COMPLETED("completed")` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `GENERATING("generating")` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `FAILED("failed")` - - `GPT_5_CODEX("gpt-5-codex")` + - `JsonValue; type "image_generation_call"constant` - - `GPT_5_PRO("gpt-5-pro")` + The type of the image generation call. Always `image_generation_call`. - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + - `Optional agent` - - `JsonValue; object_ "response"constant` + The agent that produced this item. - The object type of this resource - always set to `response`. + - `String agentName` - - `RESPONSE("response")` + The canonical name of the agent that produced this item. - - `List output` + - `class BetaResponseCodeInterpreterToolCall:` - An array of content items generated by the model. + A tool call to run code. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `String id` - - `class BetaResponseOutputMessage:` + The unique ID of the code interpreter tool call. - An output message from the model. + - `Optional code` - - `class BetaResponseFileSearchToolCall:` + The code to run, or null if not available. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `String containerId` - - `class BetaResponseFunctionToolCall:` + The ID of the container used to run the code. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `Optional> outputs` - - `class BetaResponseFunctionToolCallOutputItem:` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `String id` + - `class Logs:` - The unique ID of the function call tool output. + The logs output from the code interpreter. - - `String callId` + - `String logs` - The unique ID of the function tool call generated by the model. + The logs output from the code interpreter. - - `Output output` + - `JsonValue; type "logs"constant` - The output from the function call generated by your code. - Can be a string or an list of output content. + The type of the output. Always `logs`. - - `String` + - `LOGS("logs")` - - `List` + - `class Image:` - - `class BetaResponseInputText:` + The image output from the code interpreter. - A text input to the model. + - `JsonValue; type "image"constant` - - `class BetaResponseInputImage:` + The type of the output. Always `image`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `IMAGE("image")` - - `class BetaResponseInputFile:` + - `String url` - A file input to the model. + The URL of the image output from the code interpreter. - `Status status` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `IN_PROGRESS("in_progress")` @@ -81939,11 +95578,15 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `JsonValue; type "function_call_output"constant` + - `INTERPRETING("interpreting")` - The type of the function tool call output. Always `function_call_output`. + - `FAILED("failed")` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `JsonValue; type "code_interpreter_call"constant` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - `Optional agent` @@ -81953,169 +95596,171 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` + - `LocalShellCall` - The execution context that produced this tool call. + - `String id` - - `JsonValue;` + The unique ID of the local shell call. - - `JsonValue; type "direct"constant` + - `Action action` - The caller type. Always `direct`. + Execute a shell command on the server. - - `DIRECT("direct")` + - `List command` - - `class Program:` + The command to run. - - `String callerId` + - `Env env` - The call ID of the program item that produced this tool call. + Environment variables to set for the command. - - `JsonValue; type "program"constant` + - `JsonValue; type "exec"constant` - The caller type. Always `program`. + The type of the local shell action. Always `exec`. - - `PROGRAM("program")` + - `EXEC("exec")` - - `Optional createdBy` + - `Optional timeoutMs` - The identifier of the actor that created the item. + Optional timeout in milliseconds for the command. - - `AgentMessage` + - `Optional user` - - `String id` + Optional user to run the command as. - The unique ID of the agent message. + - `Optional workingDirectory` - - `String author` + Optional working directory to run the command in. - The sending agent identity. + - `String callId` - - `List content` + The unique ID of the local shell tool call generated by the model. - Encrypted content sent between agents. + - `Status status` - - `class BetaResponseInputText:` + The status of the local shell call. - A text input to the model. + - `IN_PROGRESS("in_progress")` - - `class BetaResponseOutputText:` + - `COMPLETED("completed")` - A text output from the model. + - `INCOMPLETE("incomplete")` - - `class Text:` + - `JsonValue; type "local_shell_call"constant` - A text content. + The type of the local shell call. Always `local_shell_call`. - - `String text` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `JsonValue; type "text"constant` + - `Optional agent` - - `TEXT("text")` + The agent that produced this item. - - `class SummaryText:` + - `String agentName` - A summary text from the model. + The canonical name of the agent that produced this item. - - `String text` + - `LocalShellCallOutput` - A summary of the reasoning output from the model so far. + - `String id` - - `JsonValue; type "summary_text"constant` + The unique ID of the local shell tool call generated by the model. - The type of the object. Always `summary_text`. + - `String output` - - `SUMMARY_TEXT("summary_text")` + A JSON string of the output of the local shell tool call. - - `class ReasoningText:` + - `JsonValue; type "local_shell_call_output"constant` - Reasoning text from the model. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `String text` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - The reasoning text from the model. + - `Optional agent` - - `JsonValue; type "reasoning_text"constant` + The agent that produced this item. - The type of the reasoning text. Always `reasoning_text`. + - `String agentName` - - `REASONING_TEXT("reasoning_text")` + The canonical name of the agent that produced this item. - - `class BetaResponseOutputRefusal:` + - `Optional status` - A refusal from the model. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `class BetaResponseInputImage:` + - `IN_PROGRESS("in_progress")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `COMPLETED("completed")` - - `class ComputerScreenshot:` + - `INCOMPLETE("incomplete")` - A screenshot of a computer. + - `class BetaResponseFunctionShellToolCall:` - - `Detail detail` + A tool call that executes one or more shell commands in a managed environment. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `String id` - - `LOW("low")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `HIGH("high")` + - `Action action` - - `AUTO("auto")` + The shell commands and limits that describe how to run the tool call. - - `ORIGINAL("original")` + - `List commands` - - `Optional fileId` + - `Optional maxOutputLength` - The identifier of an uploaded file that contains the screenshot. + Optional maximum number of characters to return from each command. - - `Optional imageUrl` + - `Optional timeoutMs` - The URL of the screenshot image. + Optional timeout in milliseconds for the commands. - - `JsonValue; type "computer_screenshot"constant` + - `String callId` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The unique ID of the shell tool call generated by the model. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `Optional environment` - - `Optional promptCacheBreakpoint` + Represents the use of a local environment to perform shell actions. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaResponseLocalEnvironment:` - - `JsonValue; mode "explicit"constant` + Represents the use of a local environment to perform shell actions. - The breakpoint mode. Always `explicit`. + - `JsonValue; type "local"constant` - - `EXPLICIT("explicit")` + The environment type. Always `local`. - - `class BetaResponseInputFile:` + - `LOCAL("local")` - A file input to the model. + - `class BetaResponseContainerReference:` - - `class EncryptedContent:` + Represents a container created with /v1/containers. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `String containerId` - - `String encryptedContent` + - `JsonValue; type "container_reference"constant` - Opaque encrypted content. + The environment type. Always `container_reference`. - - `JsonValue; type "encrypted_content"constant` + - `CONTAINER_REFERENCE("container_reference")` - The type of the input item. Always `encrypted_content`. + - `Status status` - - `ENCRYPTED_CONTENT("encrypted_content")` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String recipient` + - `IN_PROGRESS("in_progress")` - The destination agent identity. + - `COMPLETED("completed")` - - `JsonValue; type "agent_message"constant` + - `INCOMPLETE("incomplete")` - The type of the item. Always `agent_message`. + - `JsonValue; type "shell_call"constant` - - `AGENT_MESSAGE("agent_message")` + The type of the item. Always `shell_call`. + + - `SHELL_CALL("shell_call")` - `Optional agent` @@ -82125,99 +95770,103 @@ public final class Main { The canonical name of the agent that produced this item. - - `MultiAgentCall` + - `Optional caller` - - `String id` + The execution context that produced this tool call. - The unique ID of the multi-agent call item. + - `JsonValue;` - - `Action action` + - `JsonValue; type "direct"constant` - The multi-agent action to execute. + - `DIRECT("direct")` - - `SPAWN_AGENT("spawn_agent")` + - `class Program:` - - `INTERRUPT_AGENT("interrupt_agent")` + - `String callerId` - - `LIST_AGENTS("list_agents")` + The call ID of the program item that produced this tool call. - - `SEND_MESSAGE("send_message")` + - `JsonValue; type "program"constant` - - `FOLLOWUP_TASK("followup_task")` + - `PROGRAM("program")` - - `WAIT_AGENT("wait_agent")` + - `Optional createdBy` - - `String arguments` + The ID of the entity that created this tool call. - The JSON string of arguments generated for the action. + - `class BetaResponseFunctionShellToolCallOutput:` - - `String callId` + The output of a shell tool call that was emitted. - The unique ID linking this call to its output. + - `String id` - - `JsonValue; type "multi_agent_call"constant` + The unique ID of the shell call output. Populated when this item is returned via API. - The type of the multi-agent call. Always `multi_agent_call`. + - `String callId` - - `MULTI_AGENT_CALL("multi_agent_call")` + The unique ID of the shell tool call generated by the model. - - `Optional agent` + - `Optional maxOutputLength` - The agent that produced this item. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `String agentName` + - `List output` - The canonical name of the agent that produced this item. + An array of shell call output contents - - `MultiAgentCallOutput` + - `Outcome outcome` - - `String id` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The unique ID of the multi-agent call output item. + - `JsonValue;` - - `Action action` + - `JsonValue; type "timeout"constant` - The multi-agent action that produced this result. + The outcome type. Always `timeout`. - - `SPAWN_AGENT("spawn_agent")` + - `TIMEOUT("timeout")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `class Exit:` - - `LIST_AGENTS("list_agents")` + Indicates that the shell commands finished and returned an exit code. - - `SEND_MESSAGE("send_message")` + - `long exitCode` - - `FOLLOWUP_TASK("followup_task")` + Exit code from the shell process. - - `WAIT_AGENT("wait_agent")` + - `JsonValue; type "exit"constant` - - `String callId` + The outcome type. Always `exit`. - The unique ID of the multi-agent call. + - `EXIT("exit")` - - `List output` + - `String stderr` - Text output returned by the multi-agent action. + The standard error output that was captured. - - `List annotations` + - `String stdout` - The annotations of the text output. + The standard output that was captured. - - `String text` + - `Optional createdBy` - The text output from the model. + The identifier of the actor that created the item. - - `JsonValue; type "output_text"constant` + - `Status status` - The type of the output text. Always `output_text`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `Optional> logprobs` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "multi_agent_call_output"constant` + - `COMPLETED("completed")` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `INCOMPLETE("incomplete")` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `JsonValue; type "shell_call_output"constant` + + The type of the shell call output. Always `shell_call_output`. + + - `SHELL_CALL_OUTPUT("shell_call_output")` - `Optional agent` @@ -82227,108 +95876,109 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch:` + - `Optional caller` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The execution context that produced this tool call. - - `class BetaResponseComputerToolCall:` + - `JsonValue;` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `JsonValue; type "direct"constant` - - `class BetaResponseComputerToolCallOutputItem:` + - `DIRECT("direct")` - - `String id` + - `class Program:` - The unique ID of the computer call tool output. + - `String callerId` - - `String callId` + The call ID of the program item that produced this tool call. - The ID of the computer tool call that produced the output. + - `JsonValue; type "program"constant` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `PROGRAM("program")` - A computer screenshot image used with the computer use tool. + - `Optional createdBy` - - `Status status` + The identifier of the actor that created the item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaResponseApplyPatchToolCall:` - - `COMPLETED("completed")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `INCOMPLETE("incomplete")` + - `String id` - - `FAILED("failed")` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `IN_PROGRESS("in_progress")` + - `String callId` - - `JsonValue; type "computer_call_output"constant` + The unique ID of the apply patch tool call generated by the model. - The type of the computer tool call output. Always `computer_call_output`. + - `Operation operation` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `Optional> acknowledgedSafetyChecks` + - `class CreateFile:` - The safety checks reported by the API that have been acknowledged by the - developer. + Instruction describing how to create a file via the apply_patch tool. - - `String id` + - `String diff` - The ID of the pending safety check. + Diff to apply. - - `Optional code` + - `String path` - The type of the pending safety check. + Path of the file to create. - - `Optional message` + - `JsonValue; type "create_file"constant` - Details about the pending safety check. + Create a new file with the provided diff. - - `Optional agent` + - `CREATE_FILE("create_file")` - The agent that produced this item. + - `class DeleteFile:` - - `String agentName` + Instruction describing how to delete a file via the apply_patch tool. - The canonical name of the agent that produced this item. + - `String path` - - `Optional createdBy` + Path of the file to delete. - The identifier of the actor that created the item. + - `JsonValue; type "delete_file"constant` - - `class BetaResponseReasoningItem:` + Delete the specified file. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `DELETE_FILE("delete_file")` - - `Program` + - `class UpdateFile:` - - `String id` + Instruction describing how to update a file via the apply_patch tool. - The unique ID of the program item. + - `String diff` - - `String callId` + Diff to apply. - The stable call ID of the program item. + - `String path` - - `String code` + Path of the file to update. - The JavaScript source executed by programmatic tool calling. + - `JsonValue; type "update_file"constant` - - `String fingerprint` + Update an existing file with the provided diff. - Opaque program replay fingerprint that must be round-tripped. + - `UPDATE_FILE("update_file")` - - `JsonValue; type "program"constant` + - `Status status` - The type of the item. Always `program`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `PROGRAM("program")` + - `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 agent` @@ -82338,184 +95988,186 @@ public final class Main { The canonical name of the agent that produced this item. - - `ProgramOutput` + - `Optional caller` - - `String id` + The execution context that produced this tool call. - The unique ID of the program output item. + - `JsonValue;` - - `String callId` + - `JsonValue; type "direct"constant` - The call ID of the program item. + - `DIRECT("direct")` - - `String result` + - `class Program:` - The result produced by the program item. + - `String callerId` - - `Status status` + The call ID of the program item that produced this tool call. - The terminal status of the program output item. + - `JsonValue; type "program"constant` - - `COMPLETED("completed")` + - `PROGRAM("program")` - - `INCOMPLETE("incomplete")` + - `Optional createdBy` - - `JsonValue; type "program_output"constant` + The ID of the entity that created this tool call. - The type of the item. Always `program_output`. + - `class BetaResponseApplyPatchToolCallOutput:` - - `PROGRAM_OUTPUT("program_output")` + The output emitted by an apply patch tool call. - - `Optional agent` + - `String id` - The agent that produced this item. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `String agentName` + - `String callId` - The canonical name of the agent that produced this item. + The unique ID of the apply patch tool call generated by the model. - - `class BetaResponseToolSearchCall:` + - `Status status` - - `String id` + The status of the apply patch tool call output. One of `completed` or `failed`. - The unique ID of the tool search call item. + - `COMPLETED("completed")` - - `JsonValue arguments` + - `FAILED("failed")` - Arguments used for the tool search call. + - `JsonValue; type "apply_patch_call_output"constant` - - `Optional callId` + The type of the item. Always `apply_patch_call_output`. - The unique ID of the tool search call generated by the model. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `Execution execution` + - `Optional agent` - Whether tool search was executed by the server or by the client. + The agent that produced this item. - - `SERVER("server")` + - `String agentName` - - `CLIENT("client")` + The canonical name of the agent that produced this item. - - `Status status` + - `Optional caller` - The status of the tool search call item that was recorded. + The execution context that produced this tool call. - - `IN_PROGRESS("in_progress")` + - `JsonValue;` - - `COMPLETED("completed")` + - `JsonValue; type "direct"constant` - - `INCOMPLETE("incomplete")` + - `DIRECT("direct")` - - `JsonValue; type "tool_search_call"constant` + - `class Program:` - The type of the item. Always `tool_search_call`. + - `String callerId` - - `TOOL_SEARCH_CALL("tool_search_call")` + The call ID of the program item that produced this tool call. - - `Optional agent` + - `JsonValue; type "program"constant` - The agent that produced this item. + - `PROGRAM("program")` - - `String agentName` + - `Optional createdBy` - The canonical name of the agent that produced this item. + The ID of the entity that created this tool call output. - - `Optional createdBy` + - `Optional output` - The identifier of the actor that created the item. + Optional textual output returned by the apply patch tool. - - `class BetaResponseToolSearchOutputItem:` + - `McpCall` - `String id` - The unique ID of the tool search output item. + The unique ID of the tool call. - - `Optional callId` + - `String arguments` - The unique ID of the tool search call generated by the model. + A JSON string of the arguments passed to the tool. - - `Execution execution` + - `String name` - Whether tool search was executed by the server or by the client. + The name of the tool that was run. - - `SERVER("server")` + - `String serverLabel` - - `CLIENT("client")` + The label of the MCP server running the tool. - - `Status status` + - `JsonValue; type "mcp_call"constant` - The status of the tool search output item that was recorded. + The type of the item. Always `mcp_call`. - - `IN_PROGRESS("in_progress")` + - `MCP_CALL("mcp_call")` - - `COMPLETED("completed")` + - `Optional agent` - - `INCOMPLETE("incomplete")` + The agent that produced this item. - - `List tools` + - `String agentName` - The loaded tool definitions returned by tool search. + The canonical name of the agent that produced this item. - - `class BetaFunctionTool:` + - `Optional approvalRequestId` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `class BetaFileSearchTool:` + - `Optional error` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The error from the tool call, if any. - - `class BetaComputerTool:` + - `Optional output` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output from the tool call. - - `class BetaComputerUsePreviewTool:` + - `Optional status` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `class BetaWebSearchTool:` + - `IN_PROGRESS("in_progress")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `COMPLETED("completed")` - - `Mcp` + - `INCOMPLETE("incomplete")` - - `CodeInterpreter` + - `CALLING("calling")` - - `JsonValue;` + - `FAILED("failed")` - - `ImageGeneration` + - `McpListTools` - - `JsonValue;` + - `String id` - - `class BetaFunctionShellTool:` + The unique ID of the list. - A tool that allows the model to execute shell commands. + - `String serverLabel` - - `class BetaCustomTool:` + The label of the MCP server. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `List tools` - - `class BetaNamespaceTool:` + The tools available on the server. - Groups function/custom tools under a shared namespace. + - `JsonValue inputSchema` - - `class BetaToolSearchTool:` + The JSON schema describing the tool's input. - Hosted or BYOT tool search configuration for deferred tools. + - `String name` - - `class BetaWebSearchPreviewTool:` + The name of the tool. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional annotations` - - `class BetaApplyPatchTool:` + Additional annotations about the tool. - Allows the assistant to create, delete, or update files using unified diffs. + - `Optional description` - - `JsonValue; type "tool_search_output"constant` + The description of the tool. - The type of the item. Always `tool_search_output`. + - `JsonValue; type "mcp_list_tools"constant` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + The type of the item. Always `mcp_list_tools`. + + - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` @@ -82525,100 +96177,99 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional error` - The identifier of the actor that created the item. + Error message if the server could not list tools. - - `AdditionalTools` + - `McpApprovalRequest` - `String id` - The unique ID of the additional tools item. + The unique ID of the approval request. - - `Role role` + - `String arguments` - The role that provided the additional tools. + A JSON string of arguments for the tool. - - `UNKNOWN("unknown")` + - `String name` - - `USER("user")` + The name of the tool to run. - - `ASSISTANT("assistant")` + - `String serverLabel` - - `SYSTEM("system")` + The label of the MCP server making the request. - - `CRITIC("critic")` + - `JsonValue; type "mcp_approval_request"constant` - - `DISCRIMINATOR("discriminator")` + The type of the item. Always `mcp_approval_request`. - - `DEVELOPER("developer")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `TOOL("tool")` + - `Optional agent` - - `List tools` + The agent that produced this item. - The additional tool definitions made available at this item. + - `String agentName` - - `class BetaFunctionTool:` + The canonical name of the agent that produced this item. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `McpApprovalResponse` - - `class BetaFileSearchTool:` + - `String id` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The unique ID of the approval response - - `class BetaComputerTool:` + - `String approvalRequestId` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the approval request being answered. - - `class BetaComputerUsePreviewTool:` + - `boolean approve` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Whether the request was approved. - - `class BetaWebSearchTool:` + - `JsonValue; type "mcp_approval_response"constant` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of the item. Always `mcp_approval_response`. - - `Mcp` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `CodeInterpreter` + - `Optional agent` - - `JsonValue;` + The agent that produced this item. - - `ImageGeneration` + - `String agentName` - - `JsonValue;` + The canonical name of the agent that produced this item. - - `class BetaFunctionShellTool:` + - `Optional reason` - A tool that allows the model to execute shell commands. + Optional reason for the decision. - - `class BetaCustomTool:` + - `class BetaResponseCustomToolCall:` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A call to a custom tool created by the model. - - `class BetaNamespaceTool:` + - `String callId` - Groups function/custom tools under a shared namespace. + An identifier used to map this custom tool call to a tool call output. - - `class BetaToolSearchTool:` + - `String input` - Hosted or BYOT tool search configuration for deferred tools. + The input for the custom tool call generated by the model. - - `class BetaWebSearchPreviewTool:` + - `String name` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The name of the custom tool being called. - - `class BetaApplyPatchTool:` + - `JsonValue; type "custom_tool_call"constant` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the custom tool call. Always `custom_tool_call`. - - `JsonValue; type "additional_tools"constant` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - The type of the item. Always `additional_tools`. + - `Optional id` - - `ADDITIONAL_TOOLS("additional_tools")` + The unique ID of the custom tool call in the OpenAI platform. - `Optional agent` @@ -82628,229 +96279,229 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `String id` + - `Optional caller` - The unique ID of the compaction item. + The execution context that produced this tool call. - - `String encryptedContent` + - `JsonValue;` - The encrypted content that was produced by compaction. + - `JsonValue; type "direct"constant` - - `JsonValue; type "compaction"constant` + - `DIRECT("direct")` - The type of the item. Always `compaction`. + - `class Program:` - - `COMPACTION("compaction")` + - `String callerId` - - `Optional agent` + The call ID of the program item that produced this tool call. - The agent that produced this item. + - `JsonValue; type "program"constant` - - `String agentName` + - `PROGRAM("program")` - The canonical name of the agent that produced this item. + - `Optional namespace` - - `Optional createdBy` + The namespace of the custom tool being called. - The identifier of the actor that created the item. + - `class BetaResponseCustomToolCallOutputItem:` - - `ImageGenerationCall` + The output of a custom tool call from your code, being sent back to the model. - `String id` - The unique ID of the image generation call. - - - `Optional result` - - The generated image encoded in base64. + The unique ID of the custom tool call output item. - `Status status` - The status of the image generation call. + 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")` - - `GENERATING("generating")` + - `INCOMPLETE("incomplete")` - - `FAILED("failed")` + - `Optional createdBy` - - `JsonValue; type "image_generation_call"constant` + The identifier of the actor that created the item. - The type of the image generation call. Always `image_generation_call`. +### Beta Response Output Item Added Event - - `IMAGE_GENERATION_CALL("image_generation_call")` +- `class BetaResponseOutputItemAddedEvent:` - - `Optional agent` + Emitted when a new output item is added. - The agent that produced this item. + - `BetaResponseOutputItem item` - - `String agentName` + The output item that was added. - The canonical name of the agent that produced this item. + - `class BetaResponseOutputMessage:` - - `class BetaResponseCodeInterpreterToolCall:` + An output message from the model. - A tool call to run code. + - `String id` - - `LocalShellCall` + The unique ID of the output message. - - `String id` + - `List content` - The unique ID of the local shell call. + The content of the output message. - - `Action action` + - `class BetaResponseOutputText:` - Execute a shell command on the server. + A text output from the model. - - `List command` + - `List annotations` - The command to run. + The annotations of the text output. - - `Env env` + - `class FileCitation:` - Environment variables to set for the command. + A citation to a file. - - `JsonValue; type "exec"constant` + - `String fileId` - The type of the local shell action. Always `exec`. + The ID of the file. - - `EXEC("exec")` + - `String filename` - - `Optional timeoutMs` + The filename of the file cited. - Optional timeout in milliseconds for the command. + - `long index` - - `Optional user` + The index of the file in the list of files. - Optional user to run the command as. + - `JsonValue; type "file_citation"constant` - - `Optional workingDirectory` + The type of the file citation. Always `file_citation`. - Optional working directory to run the command in. + - `FILE_CITATION("file_citation")` - - `String callId` + - `class UrlCitation:` - The unique ID of the local shell tool call generated by the model. + A citation for a web resource used to generate a model response. - - `Status status` + - `long endIndex` - The status of the local shell call. + The index of the last character of the URL citation in the message. - - `IN_PROGRESS("in_progress")` + - `long startIndex` - - `COMPLETED("completed")` + The index of the first character of the URL citation in the message. - - `INCOMPLETE("incomplete")` + - `String title` - - `JsonValue; type "local_shell_call"constant` + The title of the web resource. - The type of the local shell call. Always `local_shell_call`. + - `JsonValue; type "url_citation"constant` - - `LOCAL_SHELL_CALL("local_shell_call")` + The type of the URL citation. Always `url_citation`. - - `Optional agent` + - `URL_CITATION("url_citation")` - The agent that produced this item. + - `String url` - - `String agentName` + The URL of the web resource. - The canonical name of the agent that produced this item. + - `class ContainerFileCitation:` - - `LocalShellCallOutput` + A citation for a container file used to generate a model response. - - `String id` + - `String containerId` - The unique ID of the local shell tool call generated by the model. + The ID of the container file. - - `String output` + - `long endIndex` - A JSON string of the output of the local shell tool call. + The index of the last character of the container file citation in the message. - - `JsonValue; type "local_shell_call_output"constant` + - `String fileId` - The type of the local shell tool call output. Always `local_shell_call_output`. + The ID of the file. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `String filename` - - `Optional agent` + The filename of the container file cited. - The agent that produced this item. + - `long startIndex` - - `String agentName` + The index of the first character of the container file citation in the message. - The canonical name of the agent that produced this item. + - `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:` - - `Optional status` + A path to a file. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `String fileId` - - `IN_PROGRESS("in_progress")` + The ID of the file. - - `COMPLETED("completed")` + - `long index` - - `INCOMPLETE("incomplete")` + The index of the file in the list of files. - - `class BetaResponseFunctionShellToolCall:` + - `JsonValue; type "file_path"constant` - A tool call that executes one or more shell commands in a managed environment. + The type of the file path. Always `file_path`. - - `String id` + - `FILE_PATH("file_path")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `String text` - - `Action action` + The text output from the model. - The shell commands and limits that describe how to run the tool call. + - `JsonValue; type "output_text"constant` - - `List commands` + The type of the output text. Always `output_text`. - - `Optional maxOutputLength` + - `OUTPUT_TEXT("output_text")` - Optional maximum number of characters to return from each command. + - `Optional> logprobs` - - `Optional timeoutMs` + - `String token` - Optional timeout in milliseconds for the commands. + - `List bytes` - - `String callId` + - `double logprob` - The unique ID of the shell tool call generated by the model. + - `List topLogprobs` - - `Optional environment` + - `String token` - Represents the use of a local environment to perform shell actions. + - `List bytes` - - `class BetaResponseLocalEnvironment:` + - `double logprob` - Represents the use of a local environment to perform shell actions. + - `class BetaResponseOutputRefusal:` - - `JsonValue; type "local"constant` + A refusal from the model. - The environment type. Always `local`. + - `String refusal` - - `LOCAL("local")` + The refusal explanation from the model. - - `class BetaResponseContainerReference:` + - `JsonValue; type "refusal"constant` - Represents a container created with /v1/containers. + The type of the refusal. Always `refusal`. - - `String containerId` + - `REFUSAL("refusal")` - - `JsonValue; type "container_reference"constant` + - `JsonValue; role "assistant"constant` - The environment type. Always `container_reference`. + The role of the output message. Always `assistant`. - - `CONTAINER_REFERENCE("container_reference")` + - `ASSISTANT("assistant")` - `Status status` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `IN_PROGRESS("in_progress")` @@ -82858,11 +96509,11 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `JsonValue; type "shell_call"constant` + - `JsonValue; type "message"constant` - The type of the item. Always `shell_call`. + The type of the output message. Always `message`. - - `SHELL_CALL("shell_call")` + - `MESSAGE("message")` - `Optional agent` @@ -82872,103 +96523,118 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` + - `Optional phase` - The execution context that produced this tool call. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `JsonValue;` + - `COMMENTARY("commentary")` - - `JsonValue; type "direct"constant` + - `FINAL_ANSWER("final_answer")` - - `DIRECT("direct")` + - `class BetaResponseFileSearchToolCall:` - - `class Program:` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `String callerId` + - `String id` - The call ID of the program item that produced this tool call. + The unique ID of the file search tool call. - - `JsonValue; type "program"constant` + - `List queries` - - `PROGRAM("program")` + The queries used to search for files. - - `Optional createdBy` + - `Status status` - The ID of the entity that created this tool call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `class BetaResponseFunctionShellToolCallOutput:` + - `IN_PROGRESS("in_progress")` - The output of a shell tool call that was emitted. + - `SEARCHING("searching")` - - `String id` + - `COMPLETED("completed")` - The unique ID of the shell call output. Populated when this item is returned via API. + - `INCOMPLETE("incomplete")` - - `String callId` + - `FAILED("failed")` - The unique ID of the shell tool call generated by the model. + - `JsonValue; type "file_search_call"constant` - - `Optional maxOutputLength` + The type of the file search tool call. Always `file_search_call`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `FILE_SEARCH_CALL("file_search_call")` - - `List output` + - `Optional agent` - An array of shell call output contents + The agent that produced this item. - - `Outcome outcome` + - `String agentName` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The canonical name of the agent that produced this item. - - `JsonValue;` + - `Optional> results` - - `JsonValue; type "timeout"constant` + The results of the file search tool call. - The outcome type. Always `timeout`. + - `Optional attributes` - - `TIMEOUT("timeout")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `class Exit:` + - `String` - Indicates that the shell commands finished and returned an exit code. + - `double` - - `long exitCode` + - `boolean` - Exit code from the shell process. + - `Optional fileId` - - `JsonValue; type "exit"constant` + The unique ID of the file. - The outcome type. Always `exit`. + - `Optional filename` - - `EXIT("exit")` + The name of the file. - - `String stderr` + - `Optional score` - The standard error output that was captured. + The relevance score of the file - a value between 0 and 1. - - `String stdout` + - `Optional text` - The standard output that was captured. + The text that was retrieved from the file. - - `Optional createdBy` + - `class BetaResponseFunctionToolCall:` - The identifier of the actor that created the item. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `Status status` + - `String arguments` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + A JSON string of the arguments to pass to the function. - - `IN_PROGRESS("in_progress")` + - `String callId` - - `COMPLETED("completed")` + The unique ID of the function tool call generated by the model. - - `INCOMPLETE("incomplete")` + - `String name` - - `JsonValue; type "shell_call_output"constant` + The name of the function to run. - The type of the shell call output. Always `shell_call_output`. + - `JsonValue; type "function_call"constant` - - `SHELL_CALL_OUTPUT("shell_call_output")` + The type of the function tool call. Always `function_call`. + + - `FUNCTION_CALL("function_call")` + + - `Optional id` + + The unique ID of the function tool call. - `Optional agent` @@ -82998,147 +96664,166 @@ public final class Main { - `PROGRAM("program")` - - `Optional createdBy` + - `Optional namespace` - The identifier of the actor that created the item. + The namespace of the function to run. - - `class BetaResponseApplyPatchToolCall:` + - `Optional status` - A tool call that applies file diffs by creating, deleting, or updating files. + 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 BetaResponseFunctionToolCallOutputItem:` - `String id` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of the function call tool output. - `String callId` - The unique ID of the apply patch tool call generated by the model. + The unique ID of the function tool call generated by the model. - - `Operation operation` + - `Output output` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `class CreateFile:` + - `String` - Instruction describing how to create a file via the apply_patch tool. + - `List` - - `String diff` + - `class BetaResponseInputText:` - Diff to apply. + A text input to the model. - - `String path` + - `String text` - Path of the file to create. + The text input to the model. - - `JsonValue; type "create_file"constant` + - `JsonValue; type "input_text"constant` - Create a new file with the provided diff. + The type of the input item. Always `input_text`. - - `CREATE_FILE("create_file")` + - `INPUT_TEXT("input_text")` - - `class DeleteFile:` + - `Optional promptCacheBreakpoint` - Instruction describing how to delete a file via the apply_patch tool. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String path` + - `JsonValue; mode "explicit"constant` - Path of the file to delete. + The breakpoint mode. Always `explicit`. - - `JsonValue; type "delete_file"constant` + - `EXPLICIT("explicit")` - Delete the specified file. + - `class BetaResponseInputImage:` - - `DELETE_FILE("delete_file")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class UpdateFile:` + - `Detail detail` - Instruction describing how to update a file via the apply_patch tool. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String diff` + - `LOW("low")` - Diff to apply. + - `HIGH("high")` - - `String path` + - `AUTO("auto")` - Path of the file to update. + - `ORIGINAL("original")` - - `JsonValue; type "update_file"constant` + - `JsonValue; type "input_image"constant` - Update an existing file with the provided diff. + The type of the input item. Always `input_image`. - - `UPDATE_FILE("update_file")` + - `INPUT_IMAGE("input_image")` - - `Status status` + - `Optional fileId` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The ID of the file to be sent to the model. - - `IN_PROGRESS("in_progress")` + - `Optional imageUrl` - - `COMPLETED("completed")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `JsonValue; type "apply_patch_call"constant` + - `Optional promptCacheBreakpoint` - The type of the item. Always `apply_patch_call`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `JsonValue; mode "explicit"constant` - - `Optional agent` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `EXPLICIT("explicit")` - - `String agentName` + - `class BetaResponseInputFile:` - The canonical name of the agent that produced this item. + A file input to the model. - - `Optional caller` + - `JsonValue; type "input_file"constant` - The execution context that produced this tool call. + The type of the input item. Always `input_file`. - - `JsonValue;` + - `INPUT_FILE("input_file")` - - `JsonValue; type "direct"constant` + - `Optional detail` - - `DIRECT("direct")` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class Program:` + - `AUTO("auto")` - - `String callerId` + - `LOW("low")` - The call ID of the program item that produced this tool call. + - `HIGH("high")` - - `JsonValue; type "program"constant` + - `Optional fileData` - - `PROGRAM("program")` + The content of the file to be sent to the model. - - `Optional createdBy` + - `Optional fileId` - The ID of the entity that created this tool call. + The ID of the file to be sent to the model. - - `class BetaResponseApplyPatchToolCallOutput:` + - `Optional fileUrl` - The output emitted by an apply patch tool call. + The URL of the file to be sent to the model. - - `String id` + - `Optional filename` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The name of the file to be sent to the model. - - `String callId` + - `Optional promptCacheBreakpoint` - The unique ID of the apply patch tool call generated by the model. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `JsonValue; mode "explicit"constant` + + The breakpoint mode. Always `explicit`. + + - `EXPLICIT("explicit")` - `Status status` - The status of the apply patch tool call output. One of `completed` or `failed`. + 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")` - - `FAILED("failed")` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "apply_patch_call_output"constant` + - `JsonValue; type "function_call_output"constant` - The type of the item. Always `apply_patch_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional agent` @@ -83156,6 +96841,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -83166,174 +96853,149 @@ public final class Main { - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - `Optional createdBy` - The ID of the entity that created this tool call output. - - - `Optional output` - - Optional textual output returned by the apply patch tool. + The identifier of the actor that created the item. - - `McpCall` + - `AgentMessage` - `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 agent` - - The agent that produced this item. + The unique ID of the agent message. - - `String agentName` + - `String author` - The canonical name of the agent that produced this item. + The sending agent identity. - - `Optional approvalRequestId` + - `List content` - 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. + Encrypted content sent between agents. - - `Optional error` + - `class BetaResponseInputText:` - The error from the tool call, if any. + A text input to the model. - - `Optional output` + - `class BetaResponseOutputText:` - The output from the tool call. + A text output from the model. - - `Optional status` + - `class Text:` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A text content. - - `IN_PROGRESS("in_progress")` + - `String text` - - `COMPLETED("completed")` + - `JsonValue; type "text"constant` - - `INCOMPLETE("incomplete")` + - `TEXT("text")` - - `CALLING("calling")` + - `class SummaryText:` - - `FAILED("failed")` + A summary text from the model. - - `McpListTools` + - `String text` - - `String id` + A summary of the reasoning output from the model so far. - The unique ID of the list. + - `JsonValue; type "summary_text"constant` - - `String serverLabel` + The type of the object. Always `summary_text`. - The label of the MCP server. + - `SUMMARY_TEXT("summary_text")` - - `List tools` + - `class ReasoningText:` - The tools available on the server. + Reasoning text from the model. - - `JsonValue inputSchema` + - `String text` - The JSON schema describing the tool's input. + The reasoning text from the model. - - `String name` + - `JsonValue; type "reasoning_text"constant` - The name of the tool. + The type of the reasoning text. Always `reasoning_text`. - - `Optional annotations` + - `REASONING_TEXT("reasoning_text")` - Additional annotations about the tool. + - `class BetaResponseOutputRefusal:` - - `Optional description` + A refusal from the model. - The description of the tool. + - `class BetaResponseInputImage:` - - `JsonValue; type "mcp_list_tools"constant` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The type of the item. Always `mcp_list_tools`. + - `class ComputerScreenshot:` - - `MCP_LIST_TOOLS("mcp_list_tools")` + A screenshot of a computer. - - `Optional agent` + - `Detail detail` - The agent that produced this item. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String agentName` + - `LOW("low")` - The canonical name of the agent that produced this item. + - `HIGH("high")` - - `Optional error` + - `AUTO("auto")` - Error message if the server could not list tools. + - `ORIGINAL("original")` - - `McpApprovalRequest` + - `Optional fileId` - - `String id` + The identifier of an uploaded file that contains the screenshot. - The unique ID of the approval request. + - `Optional imageUrl` - - `String arguments` + The URL of the screenshot image. - A JSON string of arguments for the tool. + - `JsonValue; type "computer_screenshot"constant` - - `String name` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The name of the tool to run. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `String serverLabel` + - `Optional promptCacheBreakpoint` - The label of the MCP server making the request. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "mcp_approval_request"constant` + - `JsonValue; mode "explicit"constant` - The type of the item. Always `mcp_approval_request`. + The breakpoint mode. Always `explicit`. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `EXPLICIT("explicit")` - - `Optional agent` + - `class BetaResponseInputFile:` - The agent that produced this item. + A file input to the model. - - `String agentName` + - `class EncryptedContent:` - The canonical name of the agent that produced this item. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `McpApprovalResponse` + - `String encryptedContent` - - `String id` + Opaque encrypted content. - The unique ID of the approval response + - `JsonValue; type "encrypted_content"constant` - - `String approvalRequestId` + The type of the input item. Always `encrypted_content`. - The ID of the approval request being answered. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `boolean approve` + - `String recipient` - Whether the request was approved. + The destination agent identity. - - `JsonValue; type "mcp_approval_response"constant` + - `JsonValue; type "agent_message"constant` - The type of the item. Always `mcp_approval_response`. + The type of the item. Always `agent_message`. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `AGENT_MESSAGE("agent_message")` - `Optional agent` @@ -83343,2047 +97005,1963 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional reason` - - Optional reason for the decision. - - - `class BetaResponseCustomToolCall:` - - A call to a custom tool created by the model. - - - `class BetaResponseCustomToolCallOutputItem:` - - The output of a custom tool call from your code, being sent back to the model. + - `MultiAgentCall` - `String id` - The unique ID of the custom tool call output item. - - - `Status status` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique ID of the multi-agent call item. - - `IN_PROGRESS("in_progress")` + - `Action action` - - `COMPLETED("completed")` + The multi-agent action to execute. - - `INCOMPLETE("incomplete")` + - `SPAWN_AGENT("spawn_agent")` - - `Optional createdBy` + - `INTERRUPT_AGENT("interrupt_agent")` - The identifier of the actor that created the item. + - `LIST_AGENTS("list_agents")` - - `boolean parallelToolCalls` + - `SEND_MESSAGE("send_message")` - Whether to allow the model to run tool calls in parallel. + - `FOLLOWUP_TASK("followup_task")` - - `Optional temperature` + - `WAIT_AGENT("wait_agent")` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `String arguments` - - `ToolChoice toolChoice` + The JSON string of arguments generated for the action. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `String callId` - - `enum BetaToolChoiceOptions:` + The unique ID linking this call to its output. - Controls which (if any) tool is called by the model. + - `JsonValue; type "multi_agent_call"constant` - `none` means the model will not call any tool and instead generates a message. + The type of the multi-agent call. Always `multi_agent_call`. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `MULTI_AGENT_CALL("multi_agent_call")` - `required` means the model must call one or more tools. + - `Optional agent` - - `NONE("none")` + The agent that produced this item. - - `AUTO("auto")` + - `String agentName` - - `REQUIRED("required")` + The canonical name of the agent that produced this item. - - `class BetaToolChoiceAllowed:` + - `MultiAgentCallOutput` - Constrains the tools available to the model to a pre-defined set. + - `String id` - - `Mode mode` + The unique ID of the multi-agent call output item. - Constrains the tools available to the model to a pre-defined set. + - `Action action` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The multi-agent action that produced this result. - `required` requires the model to call one or more of the allowed tools. + - `SPAWN_AGENT("spawn_agent")` - - `AUTO("auto")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `REQUIRED("required")` + - `LIST_AGENTS("list_agents")` - - `List tools` + - `SEND_MESSAGE("send_message")` - A list of tool definitions that the model should be allowed to call. + - `FOLLOWUP_TASK("followup_task")` - For the Responses API, the list of tool definitions might look like: + - `WAIT_AGENT("wait_agent")` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `String callId` - - `JsonValue; type "allowed_tools"constant` + The unique ID of the multi-agent call. - Allowed tool configuration type. Always `allowed_tools`. + - `List output` - - `ALLOWED_TOOLS("allowed_tools")` + Text output returned by the multi-agent action. - - `class BetaToolChoiceTypes:` + - `List annotations` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + The annotations of the text output. - - `Type type` + - `String text` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + The text output from the model. - Allowed values are: + - `JsonValue; type "output_text"constant` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The type of the output text. Always `output_text`. - - `FILE_SEARCH("file_search")` + - `Optional> logprobs` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `JsonValue; type "multi_agent_call_output"constant` - - `COMPUTER("computer")` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `COMPUTER_USE("computer_use")` + - `Optional agent` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The agent that produced this item. - - `IMAGE_GENERATION("image_generation")` + - `String agentName` - - `CODE_INTERPRETER("code_interpreter")` + The canonical name of the agent that produced this item. - - `class BetaToolChoiceFunction:` + - `class BetaResponseFunctionWebSearch:` - Use this option to force the model to call a specific function. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `String name` + - `String id` - The name of the function to call. + The unique ID of the web search tool call. - - `JsonValue; type "function"constant` + - `Action action` - For function calling, the type is always `function`. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `FUNCTION("function")` + - `class Search:` - - `class BetaToolChoiceMcp:` + Action type "search" - Performs a web search query. - Use this option to force the model to call a specific tool on a remote MCP server. + - `JsonValue; type "search"constant` - - `String serverLabel` + The action type. - The label of the MCP server to use. + - `SEARCH("search")` - - `JsonValue; type "mcp"constant` + - `Optional> queries` - For MCP tools, the type is always `mcp`. + The search queries. - - `MCP("mcp")` + - `Optional query` - - `Optional name` + The search query. - The name of the tool to call on the server. + - `Optional> sources` - - `class BetaToolChoiceCustom:` + The sources used in the search. - Use this option to force the model to call a specific custom tool. + - `JsonValue; type "url"constant` - - `String name` + The type of source. Always `url`. - The name of the custom tool to call. + - `URL("url")` - - `JsonValue; type "custom"constant` + - `String url` - For custom tool calling, the type is always `custom`. + The URL of the source. - - `CUSTOM("custom")` + - `class OpenPage:` - - `JsonValue;` + Action type "open_page" - Opens a specific URL from search results. - - `JsonValue; type "programmatic_tool_calling"constant` + - `JsonValue; type "open_page"constant` - The tool to call. Always `programmatic_tool_calling`. + The action type. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `OPEN_PAGE("open_page")` - - `class BetaToolChoiceApplyPatch:` + - `Optional url` - Forces the model to call the apply_patch tool when executing a tool call. + The URL opened by the model. - - `JsonValue; type "apply_patch"constant` + - `class FindInPage:` - The tool to call. Always `apply_patch`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `APPLY_PATCH("apply_patch")` + - `String pattern` - - `class BetaToolChoiceShell:` + The pattern or text to search for within the page. - Forces the model to call the shell tool when a tool call is required. + - `JsonValue; type "find_in_page"constant` - - `JsonValue; type "shell"constant` + The action type. - The tool to call. Always `shell`. + - `FIND_IN_PAGE("find_in_page")` - - `SHELL("shell")` + - `String url` - - `List tools` + The URL of the page searched for the pattern. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `Status status` - We support the following categories of tools: + The status of the web search tool call. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `IN_PROGRESS("in_progress")` - - `class BetaFunctionTool:` + - `SEARCHING("searching")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `COMPLETED("completed")` - - `class BetaFileSearchTool:` + - `FAILED("failed")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `JsonValue; type "web_search_call"constant` - - `class BetaComputerTool:` + The type of the web search tool call. Always `web_search_call`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `WEB_SEARCH_CALL("web_search_call")` - - `class BetaComputerUsePreviewTool:` + - `Optional agent` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `class BetaWebSearchTool:` + - `String agentName` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `Mcp` + - `class BetaResponseComputerToolCall:` - - `CodeInterpreter` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `JsonValue;` + - `String id` - - `ImageGeneration` + The unique ID of the computer call. - - `JsonValue;` + - `String callId` - - `class BetaFunctionShellTool:` + An identifier used when responding to the tool call with output. - A tool that allows the model to execute shell commands. + - `List pendingSafetyChecks` - - `class BetaCustomTool:` + The pending safety checks for the computer call. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `String id` - - `class BetaNamespaceTool:` + The ID of the pending safety check. - Groups function/custom tools under a shared namespace. + - `Optional code` - - `class BetaToolSearchTool:` + The type of the pending safety check. - Hosted or BYOT tool search configuration for deferred tools. + - `Optional message` - - `class BetaWebSearchPreviewTool:` + Details about the pending safety check. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Status status` - - `class BetaApplyPatchTool:` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Allows the assistant to create, delete, or update files using unified diffs. + - `IN_PROGRESS("in_progress")` - - `Optional topP` + - `COMPLETED("completed")` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `INCOMPLETE("incomplete")` - We generally recommend altering this or `temperature` but not both. + - `Type type` - - `Optional background` + The type of the computer call. Always `computer_call`. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `COMPUTER_CALL("computer_call")` - - `Optional completedAt` + - `Optional action` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + A click action. - - `Optional conversation` + - `Click` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `Button button` - - `String id` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The unique ID of the conversation that this response was associated with. + - `LEFT("left")` - - `Optional maxOutputTokens` + - `RIGHT("right")` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `WHEEL("wheel")` - - `Optional maxToolCalls` + - `BACK("back")` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `FORWARD("forward")` - - `Optional moderation` + - `JsonValue; type "click"constant` - Moderation results for the response input and output, if moderated completions were requested. + Specifies the event type. For a click action, this property is always `click`. - - `Input input` + - `CLICK("click")` - Moderation for the response input. + - `long x` - - `class ModerationResult:` + The x-coordinate where the click occurred. - A moderation result produced for the response input or output. + - `long y` - - `Categories categories` + The y-coordinate where the click occurred. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `Optional> keys` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + The keys being held while clicking. - Which modalities of input are reflected by the score for each category. + - `DoubleClick` - - `TEXT("text")` + - `Optional> keys` - - `IMAGE("image")` + The keys being held while double-clicking. - - `CategoryScores categoryScores` + - `JsonValue; type "double_click"constant` - A dictionary of moderation categories to scores. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `boolean flagged` + - `DOUBLE_CLICK("double_click")` - A boolean indicating whether the content was flagged by any category. + - `long x` - - `String model` + The x-coordinate where the double click occurred. - The moderation model that produced this result. + - `long y` - - `JsonValue; type "moderation_result"constant` + The y-coordinate where the double click occurred. - The object type, which was always `moderation_result` for successful moderation results. + - `Drag` - - `MODERATION_RESULT("moderation_result")` + - `List path` - - `class Error:` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - An error produced while attempting moderation for the response input or output. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `String code` + - `long x` - The error code. + The x-coordinate. - - `String message` + - `long y` - The error message. + The y-coordinate. - - `JsonValue; type "error"constant` + - `JsonValue; type "drag"constant` - The object type, which was always `error` for moderation failures. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `ERROR("error")` + - `DRAG("drag")` - - `Output output` + - `Optional> keys` - Moderation for the response output. + The keys being held while dragging the mouse. - - `class ModerationResult:` + - `Keypress` - A moderation result produced for the response input or output. + - `List keys` - - `Categories categories` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `JsonValue; type "keypress"constant` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Which modalities of input are reflected by the score for each category. + - `KEYPRESS("keypress")` - - `TEXT("text")` + - `Move` - - `IMAGE("image")` + - `JsonValue; type "move"constant` - - `CategoryScores categoryScores` + Specifies the event type. For a move action, this property is always set to `move`. - A dictionary of moderation categories to scores. + - `MOVE("move")` - - `boolean flagged` + - `long x` - A boolean indicating whether the content was flagged by any category. + The x-coordinate to move to. - - `String model` + - `long y` - The moderation model that produced this result. + The y-coordinate to move to. - - `JsonValue; type "moderation_result"constant` + - `Optional> keys` - The object type, which was always `moderation_result` for successful moderation results. + The keys being held while moving the mouse. - - `MODERATION_RESULT("moderation_result")` + - `JsonValue;` - - `class Error:` + - `JsonValue; type "screenshot"constant` - An error produced while attempting moderation for the response input or output. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `String code` + - `SCREENSHOT("screenshot")` - The error code. + - `Scroll` - - `String message` + - `long scrollX` - The error message. + The horizontal scroll distance. - - `JsonValue; type "error"constant` + - `long scrollY` - The object type, which was always `error` for moderation failures. + The vertical scroll distance. - - `ERROR("error")` + - `JsonValue; type "scroll"constant` - - `Optional previousResponseId` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `SCROLL("scroll")` - - `Optional prompt` + - `long x` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The x-coordinate where the scroll occurred. - - `String id` + - `long y` - The unique identifier of the prompt template to use. + The y-coordinate where the scroll occurred. - - `Optional variables` + - `Optional> keys` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The keys being held while scrolling. - - `String` + - `Type` - - `class BetaResponseInputText:` + - `String text` - A text input to the model. + The text to type. - - `class BetaResponseInputImage:` + - `JsonValue; type "type"constant` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Specifies the event type. For a type action, this property is always set to `type`. - - `class BetaResponseInputFile:` + - `TYPE("type")` - A file input to the model. + - `JsonValue;` - - `Optional version` + - `JsonValue; type "wait"constant` - Optional version of the prompt template. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `Optional promptCacheKey` + - `WAIT("wait")` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `Optional> actions` - - `Optional promptCacheOptions` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `Click` - - `Mode mode` + - `DoubleClick` - Whether implicit prompt-cache breakpoints were enabled. + - `Drag` - - `IMPLICIT("implicit")` + - `Keypress` - - `EXPLICIT("explicit")` + - `Move` - - `Ttl ttl` + - `JsonValue;` - The minimum lifetime applied to each cache breakpoint. + - `Scroll` - - `_30M("30m")` + - `Type` - - `Optional promptCacheRetention` + - `JsonValue;` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `Optional agent` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The agent that produced this item. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `String agentName` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The canonical name of the agent that produced this item. - - `IN_MEMORY("in_memory")` + - `class BetaResponseComputerToolCallOutputItem:` - - `_24H("24h")` + - `String id` - - `Optional reasoning` + The unique ID of the computer call tool output. - **gpt-5 and o-series models only** + - `String callId` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The ID of the computer tool call that produced the output. - - `Optional context` + - `BetaResponseComputerToolCallOutputScreenshot output` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + A computer screenshot image used with the computer use tool. - - `AUTO("auto")` + - `JsonValue; type "computer_screenshot"constant` - - `CURRENT_TURN("current_turn")` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `ALL_TURNS("all_turns")` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `Optional effort` + - `Optional fileId` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The identifier of an uploaded file that contains the screenshot. - - `NONE("none")` + - `Optional imageUrl` - - `MINIMAL("minimal")` + The URL of the screenshot image. - - `LOW("low")` + - `Status status` - - `MEDIUM("medium")` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `HIGH("high")` + - `COMPLETED("completed")` - - `XHIGH("xhigh")` + - `INCOMPLETE("incomplete")` - - `MAX("max")` + - `FAILED("failed")` - - `Optional generateSummary` + - `IN_PROGRESS("in_progress")` - **Deprecated:** use `summary` instead. + - `JsonValue; type "computer_call_output"constant` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The type of the computer tool call output. Always `computer_call_output`. - - `AUTO("auto")` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `CONCISE("concise")` + - `Optional> acknowledgedSafetyChecks` - - `DETAILED("detailed")` + The safety checks reported by the API that have been acknowledged by the + developer. - - `Optional mode` + - `String id` - Controls the reasoning execution mode for the request. + The ID of the pending safety check. - When returned on a response, this is the effective execution mode. + - `Optional code` - - `STANDARD("standard")` + The type of the pending safety check. - - `PRO("pro")` + - `Optional message` - - `Optional summary` + Details about the pending safety check. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `Optional agent` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The agent that produced this item. - - `AUTO("auto")` + - `String agentName` - - `CONCISE("concise")` + The canonical name of the agent that produced this item. - - `DETAILED("detailed")` + - `Optional createdBy` - - `Optional safetyIdentifier` + The identifier of the actor that created the item. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `class BetaResponseReasoningItem:` - - `Optional serviceTier` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - Specifies the processing type used for serving the request. + - `String id` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The unique identifier of the reasoning content. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `List summary` - - `AUTO("auto")` + Reasoning summary content. - - `DEFAULT("default")` + - `String text` - - `FLEX("flex")` + A summary of the reasoning output from the model so far. - - `SCALE("scale")` + - `JsonValue; type "summary_text"constant` - - `PRIORITY("priority")` + The type of the object. Always `summary_text`. - - `Optional status` + - `SUMMARY_TEXT("summary_text")` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `JsonValue; type "reasoning"constant` - - `COMPLETED("completed")` + The type of the object. Always `reasoning`. - - `FAILED("failed")` + - `REASONING("reasoning")` - - `IN_PROGRESS("in_progress")` + - `Optional agent` - - `CANCELLED("cancelled")` + The agent that produced this item. - - `QUEUED("queued")` + - `String agentName` - - `INCOMPLETE("incomplete")` + The canonical name of the agent that produced this item. - - `Optional text` + - `Optional> content` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Reasoning text content. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `String text` - - `Optional format` + The reasoning text from the model. - An object specifying the format that the model must output. + - `JsonValue; type "reasoning_text"constant` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The type of the reasoning text. Always `reasoning_text`. - The default format is `{ "type": "text" }` with no additional options. + - `REASONING_TEXT("reasoning_text")` - **Not recommended for gpt-4o and newer models:** + - `Optional encryptedContent` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `JsonValue;` + - `Optional status` - - `JsonValue; type "text"constant` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of response format being defined. Always `text`. + - `IN_PROGRESS("in_progress")` - - `TEXT("text")` + - `COMPLETED("completed")` - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `INCOMPLETE("incomplete")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `Program` - - `String name` + - `String id` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The unique ID of the program item. - - `Schema schema` + - `String callId` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The stable call ID of the program item. - - `JsonValue; type "json_schema"constant` + - `String code` - The type of response format being defined. Always `json_schema`. + The JavaScript source executed by programmatic tool calling. - - `JSON_SCHEMA("json_schema")` + - `String fingerprint` - - `Optional description` + Opaque program replay fingerprint that must be round-tripped. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `JsonValue; type "program"constant` - - `Optional strict` + The type of the item. Always `program`. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `PROGRAM("program")` - - `JsonValue;` + - `Optional agent` - - `JsonValue; type "json_object"constant` + The agent that produced this item. - The type of response format being defined. Always `json_object`. + - `String agentName` - - `JSON_OBJECT("json_object")` + The canonical name of the agent that produced this item. - - `Optional verbosity` + - `ProgramOutput` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `String id` - - `LOW("low")` + The unique ID of the program output item. - - `MEDIUM("medium")` + - `String callId` - - `HIGH("high")` + The call ID of the program item. - - `Optional topLogprobs` + - `String result` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The result produced by the program item. - - `Optional truncation` + - `Status status` - The truncation strategy to use for the model response. + The terminal status of the program output item. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `COMPLETED("completed")` - - `AUTO("auto")` + - `INCOMPLETE("incomplete")` - - `DISABLED("disabled")` + - `JsonValue; type "program_output"constant` - - `Optional usage` + The type of the item. Always `program_output`. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `PROGRAM_OUTPUT("program_output")` - - `long inputTokens` + - `Optional agent` - The number of input tokens. + The agent that produced this item. - - `InputTokensDetails inputTokensDetails` + - `String agentName` - A detailed breakdown of the input tokens. + The canonical name of the agent that produced this item. - - `long cacheWriteTokens` + - `class BetaResponseToolSearchCall:` - The number of input tokens that were written to the cache. + - `String id` - - `long cachedTokens` + The unique ID of the tool search call item. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `JsonValue arguments` - - `long outputTokens` + Arguments used for the tool search call. - The number of output tokens. + - `Optional callId` - - `OutputTokensDetails outputTokensDetails` + The unique ID of the tool search call generated by the model. - A detailed breakdown of the output tokens. + - `Execution execution` - - `long reasoningTokens` + Whether tool search was executed by the server or by the client. - The number of reasoning tokens. + - `SERVER("server")` - - `long totalTokens` + - `CLIENT("client")` - The total number of tokens used. + - `Status status` - - `Optional user` + The status of the tool search call item that was recorded. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `IN_PROGRESS("in_progress")` - - `long sequenceNumber` + - `COMPLETED("completed")` - The sequence number of this event. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "response.in_progress"constant` + - `JsonValue; type "tool_search_call"constant` - The type of the event. Always `response.in_progress`. + The type of the item. Always `tool_search_call`. - - `RESPONSE_IN_PROGRESS("response.in_progress")` + - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. -### Beta Response Includable - -- `enum BetaResponseIncludable:` - - Specify additional output data to include in the model response. Currently supported values are: - - - `web_search_call.results`: Include the search results of the web search tool call. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` + - `Optional createdBy` - - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` + The identifier of the actor that created the item. - - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` + - `class BetaResponseToolSearchOutputItem:` - - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` + - `String id` - - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` + The unique ID of the tool search output item. - - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` + - `Optional callId` - - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` + The unique ID of the tool search call generated by the model. - - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` + - `Execution execution` -### Beta Response Incomplete Event + Whether tool search was executed by the server or by the client. -- `class BetaResponseIncompleteEvent:` + - `SERVER("server")` - An event that is emitted when a response finishes as incomplete. + - `CLIENT("client")` - - `BetaResponse response` + - `Status status` - The response that was incomplete. + The status of the tool search output item that was recorded. - - `String id` + - `IN_PROGRESS("in_progress")` - Unique identifier for this Response. + - `COMPLETED("completed")` - - `double createdAt` + - `INCOMPLETE("incomplete")` - Unix timestamp (in seconds) of when this Response was created. + - `List tools` - - `Optional error` + The loaded tool definitions returned by tool search. - An error object returned when the model fails to generate a Response. + - `class BetaFunctionTool:` - - `Code code` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The error code for the response. + - `String name` - - `SERVER_ERROR("server_error")` + The name of the function to call. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `Optional parameters` - - `INVALID_PROMPT("invalid_prompt")` + A JSON schema object describing the parameters of the function. - - `BIO_POLICY("bio_policy")` + - `Optional strict` - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + Whether strict parameter validation is enforced for this function tool. - - `INVALID_IMAGE("invalid_image")` + - `JsonValue; type "function"constant` - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + The type of the function tool. Always `function`. - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `FUNCTION("function")` - - `INVALID_IMAGE_URL("invalid_image_url")` + - `Optional> allowedCallers` - - `IMAGE_TOO_LARGE("image_too_large")` + The tool invocation context(s). - - `IMAGE_TOO_SMALL("image_too_small")` + - `DIRECT("direct")` - - `IMAGE_PARSE_ERROR("image_parse_error")` + - `PROGRAMMATIC("programmatic")` - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + - `Optional deferLoading` - - `INVALID_IMAGE_MODE("invalid_image_mode")` + Whether this function is deferred and loaded via tool search. - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + - `Optional description` - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + A description of the function. Used by the model to determine whether or not to call the function. - - `EMPTY_IMAGE_FILE("empty_image_file")` + - `Optional outputSchema` - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + - `class BetaFileSearchTool:` - - `String message` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - A human-readable description of the error. + - `JsonValue; type "file_search"constant` - - `Optional incompleteDetails` + The type of the file search tool. Always `file_search`. - Details about why the response is incomplete. + - `FILE_SEARCH("file_search")` - - `Optional reason` + - `List vectorStoreIds` - The reason why the response is incomplete. + The IDs of the vector stores to search. - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + - `Optional filters` - - `CONTENT_FILTER("content_filter")` + A filter to apply. - - `Optional instructions` + - `class ComparisonFilter:` - A system (or developer) message inserted into the model's context. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `String key` - - `String` + The key to compare against the value. - - `List` + - `Type type` - - `class BetaEasyInputMessage:` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - 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. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Content content` + - `EQ("eq")` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `NE("ne")` - - `String` + - `GT("gt")` - - `List` + - `GTE("gte")` - - `class BetaResponseInputText:` + - `LT("lt")` - A text input to the model. + - `LTE("lte")` - - `String text` + - `IN("in")` - The text input to the model. + - `NIN("nin")` - - `JsonValue; type "input_text"constant` + - `Value value` - The type of the input item. Always `input_text`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `INPUT_TEXT("input_text")` + - `String` - - `Optional promptCacheBreakpoint` + - `double` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `boolean` - - `JsonValue; mode "explicit"constant` + - `List` - The breakpoint mode. Always `explicit`. + - `String` - - `EXPLICIT("explicit")` + - `double` - - `class BetaResponseInputImage:` + - `class CompoundFilter:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Combine multiple filters using `and` or `or`. - - `Detail detail` + - `List filters` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `LOW("low")` + - `class ComparisonFilter:` - - `HIGH("high")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `AUTO("auto")` + - `String key` - - `ORIGINAL("original")` + The key to compare against the value. - - `JsonValue; type "input_image"constant` + - `Type type` - The type of the input item. Always `input_image`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `INPUT_IMAGE("input_image")` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Optional fileId` + - `EQ("eq")` - The ID of the file to be sent to the model. + - `NE("ne")` - - `Optional imageUrl` + - `GT("gt")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `GTE("gte")` - - `Optional promptCacheBreakpoint` + - `LT("lt")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `LTE("lte")` - - `JsonValue; mode "explicit"constant` + - `IN("in")` - The breakpoint mode. Always `explicit`. + - `NIN("nin")` - - `EXPLICIT("explicit")` + - `Value value` - - `class BetaResponseInputFile:` + The value to compare against the attribute key; supports string, number, or boolean types. - A file input to the model. + - `String` - - `JsonValue; type "input_file"constant` + - `double` - The type of the input item. Always `input_file`. + - `boolean` - - `INPUT_FILE("input_file")` + - `List` - - `Optional detail` + - `String` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `double` - - `AUTO("auto")` + - `JsonValue` - - `LOW("low")` + - `Type type` - - `HIGH("high")` + Type of operation: `and` or `or`. - - `Optional fileData` + - `AND("and")` - The content of the file to be sent to the model. + - `OR("or")` - - `Optional fileId` + - `Optional maxNumResults` - The ID of the file to be sent to the model. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `Optional fileUrl` + - `Optional rankingOptions` - The URL of the file to be sent to the model. + Ranking options for search. - - `Optional filename` + - `Optional hybridSearch` - The name of the file to be sent to the model. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `Optional promptCacheBreakpoint` + - `double embeddingWeight` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The weight of the embedding in the reciprocal ranking fusion. - - `JsonValue; mode "explicit"constant` + - `double textWeight` - The breakpoint mode. Always `explicit`. + The weight of the text in the reciprocal ranking fusion. - - `EXPLICIT("explicit")` + - `Optional ranker` - - `Role role` + The ranker to use for the file search. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `AUTO("auto")` - - `USER("user")` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `ASSISTANT("assistant")` + - `Optional scoreThreshold` - - `SYSTEM("system")` + 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. - - `DEVELOPER("developer")` + - `class BetaComputerTool:` - - `Optional phase` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - 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. + - `JsonValue; type "computer"constant` - - `COMMENTARY("commentary")` + The type of the computer tool. Always `computer`. - - `Optional type` + - `COMPUTER("computer")` - The type of the message input. Always `message`. + - `class BetaComputerUsePreviewTool:` - - `MESSAGE("message")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Message` + - `long displayHeight` - - `List content` + The height of the computer display. - A list of one or many input items to the model, containing different content - types. + - `long displayWidth` - - `class BetaResponseInputText:` + The width of the computer display. - A text input to the model. + - `Environment environment` - - `class BetaResponseInputImage:` + The type of computer environment to control. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `WINDOWS("windows")` - - `class BetaResponseInputFile:` + - `MAC("mac")` - A file input to the model. + - `LINUX("linux")` - - `Role role` + - `UBUNTU("ubuntu")` - The role of the message input. One of `user`, `system`, or `developer`. + - `BROWSER("browser")` - - `USER("user")` + - `JsonValue; type "computer_use_preview"constant` - - `SYSTEM("system")` + The type of the computer use tool. Always `computer_use_preview`. - - `DEVELOPER("developer")` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `Optional agent` + - `class BetaWebSearchTool:` - The agent that produced this item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String agentName` + - `Type type` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `Optional status` + - `WEB_SEARCH("web_search")` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `IN_PROGRESS("in_progress")` + - `Optional filters` - - `COMPLETED("completed")` + Filters for the search. - - `INCOMPLETE("incomplete")` + - `Optional> allowedDomains` - - `Optional type` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The type of the message input. Always set to `message`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `MESSAGE("message")` + - `Optional searchContextSize` - - `class BetaResponseOutputMessage:` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - An output message from the model. + - `LOW("low")` - - `String id` + - `MEDIUM("medium")` - The unique ID of the output message. + - `HIGH("high")` - - `List content` + - `Optional userLocation` - The content of the output message. + The approximate location of the user. - - `class BetaResponseOutputText:` + - `Optional city` - A text output from the model. + Free text input for the city of the user, e.g. `San Francisco`. - - `List annotations` + - `Optional country` - The annotations of the text output. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class FileCitation:` + - `Optional region` - A citation to a file. + Free text input for the region of the user, e.g. `California`. - - `String fileId` + - `Optional timezone` - The ID of the file. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `String filename` + - `Optional type` - The filename of the file cited. + The type of location approximation. Always `approximate`. - - `long index` + - `APPROXIMATE("approximate")` - The index of the file in the list of files. + - `Mcp` - - `JsonValue; type "file_citation"constant` + - `String serverLabel` - The type of the file citation. Always `file_citation`. + A label for this MCP server, used to identify it in tool calls. - - `FILE_CITATION("file_citation")` + - `JsonValue; type "mcp"constant` - - `class UrlCitation:` + The type of the MCP tool. Always `mcp`. - A citation for a web resource used to generate a model response. + - `MCP("mcp")` - - `long endIndex` + - `Optional> allowedCallers` - The index of the last character of the URL citation in the message. + The tool invocation context(s). - - `long startIndex` + - `DIRECT("direct")` - The index of the first character of the URL citation in the message. + - `PROGRAMMATIC("programmatic")` - - `String title` + - `Optional allowedTools` - The title of the web resource. + List of allowed tool names or a filter object. - - `JsonValue; type "url_citation"constant` + - `List` - The type of the URL citation. Always `url_citation`. + - `class McpToolFilter:` - - `URL_CITATION("url_citation")` + A filter object to specify which tools are allowed. - - `String url` + - `Optional readOnly` - The URL of the web resource. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `class ContainerFileCitation:` + - `Optional> toolNames` - A citation for a container file used to generate a model response. + List of allowed tool names. - - `String containerId` + - `Optional authorization` - The ID of the container file. + 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. - - `long endIndex` + - `Optional connectorId` - The index of the last character of the container file citation in the message. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `String fileId` + Currently supported `connector_id` values are: - The ID of the file. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `String filename` + - `CONNECTOR_DROPBOX("connector_dropbox")` - The filename of the container file cited. + - `CONNECTOR_GMAIL("connector_gmail")` - - `long startIndex` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - The index of the first character of the container file citation in the message. + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `JsonValue; type "container_file_citation"constant` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - The type of the container file citation. Always `container_file_citation`. + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `class FilePath:` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - A path to a file. + - `Optional deferLoading` - - `String fileId` + Whether this MCP tool is deferred and discovered via tool search. - The ID of the file. + - `Optional headers` - - `long index` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The index of the file in the list of files. + - `Optional requireApproval` - - `JsonValue; type "file_path"constant` + Specify which of the MCP server's tools require approval. - The type of the file path. Always `file_path`. + - `class McpToolApprovalFilter:` - - `FILE_PATH("file_path")` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `String text` + - `Optional always` - The text output from the model. + A filter object to specify which tools are allowed. - - `JsonValue; type "output_text"constant` + - `Optional readOnly` - The type of the output text. Always `output_text`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `OUTPUT_TEXT("output_text")` + - `Optional> toolNames` - - `Optional> logprobs` + List of allowed tool names. - - `String token` + - `Optional never` - - `List bytes` + A filter object to specify which tools are allowed. - - `double logprob` + - `Optional readOnly` - - `List topLogprobs` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `String token` + - `Optional> toolNames` - - `List bytes` + List of allowed tool names. - - `double logprob` + - `enum McpToolApprovalSetting:` - - `class BetaResponseOutputRefusal:` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - A refusal from the model. + - `ALWAYS("always")` - - `String refusal` + - `NEVER("never")` - The refusal explanation from the model. + - `Optional serverDescription` - - `JsonValue; type "refusal"constant` + Optional description of the MCP server, used to provide more context. - The type of the refusal. Always `refusal`. + - `Optional serverUrl` - - `REFUSAL("refusal")` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `JsonValue; role "assistant"constant` + - `Optional tunnelId` - The role of the output message. Always `assistant`. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `ASSISTANT("assistant")` + - `CodeInterpreter` - - `Status status` + - `Container container` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + 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. - - `IN_PROGRESS("in_progress")` + - `String` - - `COMPLETED("completed")` + - `class CodeInterpreterToolAuto:` - - `INCOMPLETE("incomplete")` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `JsonValue; type "message"constant` + - `JsonValue; type "auto"constant` - The type of the output message. Always `message`. + Always `auto`. - - `MESSAGE("message")` + - `AUTO("auto")` - - `Optional agent` + - `Optional> fileIds` - The agent that produced this item. + An optional list of uploaded files to make available to your code. - - `String agentName` + - `Optional memoryLimit` - The canonical name of the agent that produced this item. + The memory limit for the code interpreter container. - - `Optional phase` + - `_1G("1g")` - 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. + - `_4G("4g")` - - `COMMENTARY("commentary")` + - `_16G("16g")` - - `class BetaResponseFileSearchToolCall:` + - `_64G("64g")` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `Optional networkPolicy` - - `String id` + Network access policy for the container. - The unique ID of the file search tool call. + - `class BetaContainerNetworkPolicyDisabled:` - - `List queries` + - `JsonValue; type "disabled"constant` - The queries used to search for files. + Disable outbound network access. Always `disabled`. - - `Status status` + - `DISABLED("disabled")` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `class BetaContainerNetworkPolicyAllowlist:` - - `IN_PROGRESS("in_progress")` + - `List allowedDomains` - - `SEARCHING("searching")` + A list of allowed domains when type is `allowlist`. - - `COMPLETED("completed")` + - `JsonValue; type "allowlist"constant` - - `INCOMPLETE("incomplete")` + Allow outbound network access only to specified domains. Always `allowlist`. - - `FAILED("failed")` + - `ALLOWLIST("allowlist")` - - `JsonValue; type "file_search_call"constant` + - `Optional> domainSecrets` - The type of the file search tool call. Always `file_search_call`. + Optional domain-scoped secrets for allowlisted domains. - - `FILE_SEARCH_CALL("file_search_call")` + - `String domain` - - `Optional agent` + The domain associated with the secret. - The agent that produced this item. + - `String name` - - `String agentName` + The name of the secret to inject for the domain. - The canonical name of the agent that produced this item. + - `String value` - - `Optional> results` + The secret value to inject for the domain. - The results of the file search tool call. + - `JsonValue; type "code_interpreter"constant` - - `Optional attributes` + The type of the code interpreter tool. Always `code_interpreter`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `CODE_INTERPRETER("code_interpreter")` - - `String` + - `Optional> allowedCallers` - - `double` + The tool invocation context(s). - - `boolean` + - `DIRECT("direct")` - - `Optional fileId` + - `PROGRAMMATIC("programmatic")` - The unique ID of the file. + - `JsonValue;` - - `Optional filename` + - `JsonValue; type "programmatic_tool_calling"constant` - The name of the file. + The type of the tool. Always `programmatic_tool_calling`. - - `Optional score` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - The relevance score of the file - a value between 0 and 1. + - `ImageGeneration` - - `Optional text` + - `JsonValue; type "image_generation"constant` - The text that was retrieved from the file. + The type of the image generation tool. Always `image_generation`. - - `class BetaResponseComputerToolCall:` + - `IMAGE_GENERATION("image_generation")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `Optional action` - - `String id` + Whether to generate a new image or edit an existing image. Default: `auto`. - The unique ID of the computer call. + - `GENERATE("generate")` - - `String callId` + - `EDIT("edit")` - An identifier used when responding to the tool call with output. + - `AUTO("auto")` - - `List pendingSafetyChecks` + - `Optional background` - The pending safety checks for the computer call. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `String id` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The ID of the pending safety check. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `Optional code` + - `TRANSPARENT("transparent")` - The type of the pending safety check. + - `OPAQUE("opaque")` - - `Optional message` + - `AUTO("auto")` - Details about the pending safety check. + - `Optional inputFidelity` - - `Status status` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `HIGH("high")` - - `IN_PROGRESS("in_progress")` + - `LOW("low")` - - `COMPLETED("completed")` + - `Optional inputImageMask` - - `INCOMPLETE("incomplete")` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Type type` + - `Optional fileId` - The type of the computer call. Always `computer_call`. + File ID for the mask image. - - `COMPUTER_CALL("computer_call")` + - `Optional imageUrl` - - `Optional action` + Base64-encoded mask image. - A click action. + - `Optional model` - - `Click` + The image generation model to use. Default: `gpt-image-1`. - - `Button button` + - `GPT_IMAGE_1("gpt-image-1")` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `LEFT("left")` + - `GPT_IMAGE_2("gpt-image-2")` - - `RIGHT("right")` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `WHEEL("wheel")` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - - `BACK("back")` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `FORWARD("forward")` + - `Optional moderation` - - `JsonValue; type "click"constant` + Moderation level for the generated image. Default: `auto`. - Specifies the event type. For a click action, this property is always `click`. + - `AUTO("auto")` - - `CLICK("click")` + - `LOW("low")` - - `long x` + - `Optional outputCompression` - The x-coordinate where the click occurred. + Compression level for the output image. Default: 100. - - `long y` + - `Optional outputFormat` - The y-coordinate where the click occurred. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `Optional> keys` + - `PNG("png")` - The keys being held while clicking. + - `WEBP("webp")` - - `DoubleClick` + - `JPEG("jpeg")` - - `Optional> keys` + - `Optional partialImages` - The keys being held while double-clicking. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `JsonValue; type "double_click"constant` + - `Optional quality` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `DOUBLE_CLICK("double_click")` + - `LOW("low")` - - `long x` + - `MEDIUM("medium")` - The x-coordinate where the double click occurred. + - `HIGH("high")` - - `long y` + - `AUTO("auto")` - The y-coordinate where the double click occurred. + - `Optional size` - - `Drag` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `List path` + - `_1024X1024("1024x1024")` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `_1024X1536("1024x1536")` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `_1536X1024("1536x1024")` - - `long x` + - `AUTO("auto")` - The x-coordinate. + - `JsonValue;` - - `long y` + - `JsonValue; type "local_shell"constant` - The y-coordinate. + The type of the local shell tool. Always `local_shell`. - - `JsonValue; type "drag"constant` + - `LOCAL_SHELL("local_shell")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `class BetaFunctionShellTool:` - - `DRAG("drag")` + A tool that allows the model to execute shell commands. - - `Optional> keys` + - `JsonValue; type "shell"constant` - The keys being held while dragging the mouse. + The type of the shell tool. Always `shell`. - - `Keypress` + - `SHELL("shell")` - - `List keys` + - `Optional> allowedCallers` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The tool invocation context(s). - - `JsonValue; type "keypress"constant` + - `DIRECT("direct")` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `PROGRAMMATIC("programmatic")` - - `KEYPRESS("keypress")` + - `Optional environment` - - `Move` + - `class BetaContainerAuto:` - - `JsonValue; type "move"constant` + - `JsonValue; type "container_auto"constant` - Specifies the event type. For a move action, this property is always set to `move`. + Automatically creates a container for this request - - `MOVE("move")` + - `CONTAINER_AUTO("container_auto")` - - `long x` + - `Optional> fileIds` - The x-coordinate to move to. + An optional list of uploaded files to make available to your code. - - `long y` + - `Optional memoryLimit` - The y-coordinate to move to. + The memory limit for the container. - - `Optional> keys` + - `_1G("1g")` - The keys being held while moving the mouse. + - `_4G("4g")` - - `JsonValue;` + - `_16G("16g")` - - `JsonValue; type "screenshot"constant` + - `_64G("64g")` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `Optional networkPolicy` - - `SCREENSHOT("screenshot")` + Network access policy for the container. - - `Scroll` + - `class BetaContainerNetworkPolicyDisabled:` - - `long scrollX` + - `class BetaContainerNetworkPolicyAllowlist:` - The horizontal scroll distance. + - `Optional> skills` - - `long scrollY` + An optional list of skills referenced by id or inline data. - The vertical scroll distance. + - `class BetaSkillReference:` - - `JsonValue; type "scroll"constant` + - `String skillId` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The ID of the referenced skill. - - `SCROLL("scroll")` + - `JsonValue; type "skill_reference"constant` - - `long x` + References a skill created with the /v1/skills endpoint. - The x-coordinate where the scroll occurred. + - `SKILL_REFERENCE("skill_reference")` - - `long y` + - `Optional version` - The y-coordinate where the scroll occurred. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `Optional> keys` + - `class BetaInlineSkill:` - The keys being held while scrolling. + - `String description` - - `Type` + The description of the skill. - - `String text` + - `String name` - The text to type. + The name of the skill. - - `JsonValue; type "type"constant` + - `BetaInlineSkillSource source` - Specifies the event type. For a type action, this property is always set to `type`. + Inline skill payload - - `TYPE("type")` + - `String data` - - `JsonValue;` + Base64-encoded skill zip bundle. - - `JsonValue; type "wait"constant` + - `JsonValue; mediaType "application/zip"constant` - Specifies the event type. For a wait action, this property is always set to `wait`. + The media type of the inline skill payload. Must be `application/zip`. - - `WAIT("wait")` + - `APPLICATION_ZIP("application/zip")` - - `Optional> actions` + - `JsonValue; type "base64"constant` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The type of the inline skill source. Must be `base64`. - - `Click` + - `BASE64("base64")` - - `DoubleClick` + - `JsonValue; type "inline"constant` - - `Drag` + Defines an inline skill for this request. - - `Keypress` + - `INLINE("inline")` - - `Move` + - `class BetaLocalEnvironment:` - - `JsonValue;` + - `JsonValue; type "local"constant` - - `Scroll` + Use a local computer environment. - - `Type` + - `LOCAL("local")` - - `JsonValue;` + - `Optional> skills` - - `Optional agent` + An optional list of skills. - The agent that produced this item. + - `String description` - - `String agentName` + The description of the skill. - The canonical name of the agent that produced this item. + - `String name` - - `ComputerCallOutput` + The name of the skill. - - `String callId` + - `String path` - The ID of the computer tool call that produced the output. + The path to the directory containing the skill. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `class BetaContainerReference:` - A computer screenshot image used with the computer use tool. + - `String containerId` - - `JsonValue; type "computer_screenshot"constant` + The ID of the referenced container. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `JsonValue; type "container_reference"constant` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + References a container created with the /v1/containers endpoint - - `Optional fileId` + - `CONTAINER_REFERENCE("container_reference")` - The identifier of an uploaded file that contains the screenshot. + - `class BetaCustomTool:` - - `Optional imageUrl` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The URL of the screenshot image. + - `String name` - - `JsonValue; type "computer_call_output"constant` + The name of the custom tool, used to identify it in tool calls. - The type of the computer tool call output. Always `computer_call_output`. + - `JsonValue; type "custom"constant` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The type of the custom tool. Always `custom`. - - `Optional id` + - `CUSTOM("custom")` - The ID of the computer tool call output. + - `Optional> allowedCallers` - - `Optional> acknowledgedSafetyChecks` + The tool invocation context(s). - The safety checks reported by the API that have been acknowledged by the developer. + - `DIRECT("direct")` - - `String id` + - `PROGRAMMATIC("programmatic")` - The ID of the pending safety check. + - `Optional deferLoading` - - `Optional code` + Whether this tool should be deferred and discovered via tool search. - The type of the pending safety check. + - `Optional description` - - `Optional message` + Optional description of the custom tool, used to provide more context. - Details about the pending safety check. + - `Optional format` - - `Optional agent` + The input format for the custom tool. Default is unconstrained text. - The agent that produced this item. + - `JsonValue;` - - `String agentName` + - `JsonValue; type "text"constant` - The canonical name of the agent that produced this item. + Unconstrained text format. Always `text`. - - `Optional status` + - `TEXT("text")` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `class Grammar:` - - `IN_PROGRESS("in_progress")` + A grammar defined by the user. - - `COMPLETED("completed")` + - `String definition` - - `INCOMPLETE("incomplete")` + The grammar definition. - - `class BetaResponseFunctionWebSearch:` + - `Syntax syntax` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The syntax of the grammar definition. One of `lark` or `regex`. - - `String id` + - `LARK("lark")` - The unique ID of the web search tool call. + - `REGEX("regex")` - - `Action action` + - `JsonValue; type "grammar"constant` - 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). + Grammar format. Always `grammar`. - - `class Search:` + - `GRAMMAR("grammar")` - Action type "search" - Performs a web search query. + - `class BetaNamespaceTool:` - - `JsonValue; type "search"constant` + Groups function/custom tools under a shared namespace. - The action type. + - `String description` - - `SEARCH("search")` + A description of the namespace shown to the model. - - `Optional> queries` + - `String name` - The search queries. + The namespace name used in tool calls (for example, `crm`). - - `Optional query` + - `List tools` - The search query. + The function/custom tools available inside this namespace. - - `Optional> sources` + - `class Function:` - The sources used in the search. + - `String name` - - `JsonValue; type "url"constant` + - `JsonValue; type "function"constant` - The type of source. Always `url`. + - `FUNCTION("function")` - - `URL("url")` + - `Optional> allowedCallers` - - `String url` + The tool invocation context(s). - The URL of the source. + - `DIRECT("direct")` - - `class OpenPage:` + - `PROGRAMMATIC("programmatic")` - Action type "open_page" - Opens a specific URL from search results. + - `Optional deferLoading` - - `JsonValue; type "open_page"constant` + Whether this function should be deferred and discovered via tool search. - The action type. + - `Optional description` - - `OPEN_PAGE("open_page")` + - `Optional outputSchema` - - `Optional url` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The URL opened by the model. + - `Optional parameters` - - `class FindInPage:` + - `Optional strict` - Action type "find_in_page": Searches for a pattern within a loaded page. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `String pattern` + - `class BetaCustomTool:` - The pattern or text to search for within the page. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `JsonValue; type "find_in_page"constant` + - `JsonValue; type "namespace"constant` - The action type. + The type of the tool. Always `namespace`. - - `FIND_IN_PAGE("find_in_page")` + - `NAMESPACE("namespace")` - - `String url` + - `class BetaToolSearchTool:` - The URL of the page searched for the pattern. + Hosted or BYOT tool search configuration for deferred tools. - - `Status status` + - `JsonValue; type "tool_search"constant` - The status of the web search tool call. + The type of the tool. Always `tool_search`. - - `IN_PROGRESS("in_progress")` + - `TOOL_SEARCH("tool_search")` - - `SEARCHING("searching")` + - `Optional description` - - `COMPLETED("completed")` + Description shown to the model for a client-executed tool search tool. - - `FAILED("failed")` + - `Optional execution` - - `JsonValue; type "web_search_call"constant` + Whether tool search is executed by the server or by the client. - The type of the web search tool call. Always `web_search_call`. + - `SERVER("server")` - - `WEB_SEARCH_CALL("web_search_call")` + - `CLIENT("client")` - - `Optional agent` + - `Optional parameters` - The agent that produced this item. + Parameter schema for a client-executed tool search tool. - - `String agentName` + - `class BetaWebSearchPreviewTool:` - The canonical name of the agent that produced this item. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class BetaResponseFunctionToolCall:` + - `Type type` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `String arguments` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - A JSON string of the arguments to pass to the function. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `String callId` + - `Optional> searchContentTypes` - The unique ID of the function tool call generated by the model. + - `TEXT("text")` - - `String name` + - `IMAGE("image")` - The name of the function to run. + - `Optional searchContextSize` - - `JsonValue; type "function_call"constant` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The type of the function tool call. Always `function_call`. + - `LOW("low")` - - `FUNCTION_CALL("function_call")` + - `MEDIUM("medium")` - - `Optional id` + - `HIGH("high")` - The unique ID of the function tool call. + - `Optional userLocation` - - `Optional agent` + The user's location. - The agent that produced this item. + - `JsonValue; type "approximate"constant` - - `String agentName` + The type of location approximation. Always `approximate`. - The canonical name of the agent that produced this item. + - `APPROXIMATE("approximate")` - - `Optional caller` + - `Optional city` - The execution context that produced this tool call. + Free text input for the city of the user, e.g. `San Francisco`. - - `JsonValue;` + - `Optional country` - - `JsonValue; type "direct"constant` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `DIRECT("direct")` + - `Optional region` - - `class Program:` + Free text input for the region of the user, e.g. `California`. - - `String callerId` + - `Optional timezone` - The call ID of the program item that produced this tool call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `JsonValue; type "program"constant` + - `class BetaApplyPatchTool:` - - `PROGRAM("program")` + Allows the assistant to create, delete, or update files using unified diffs. - - `Optional namespace` + - `JsonValue; type "apply_patch"constant` - The namespace of the function to run. + The type of the tool. Always `apply_patch`. - - `Optional status` + - `APPLY_PATCH("apply_patch")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional> allowedCallers` - - `IN_PROGRESS("in_progress")` + The tool invocation context(s). - - `COMPLETED("completed")` + - `DIRECT("direct")` - - `INCOMPLETE("incomplete")` + - `PROGRAMMATIC("programmatic")` - - `FunctionCallOutput` + - `JsonValue; type "tool_search_output"constant` - - `String callId` + The type of the item. Always `tool_search_output`. - The unique ID of the function tool call generated by the model. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `Output output` + - `Optional agent` - Text, image, or file output of the function tool call. + The agent that produced this item. - - `String` + - `String agentName` - - `List` + The canonical name of the agent that produced this item. - - `class BetaResponseInputTextContent:` + - `Optional createdBy` - A text input to the model. + The identifier of the actor that created the item. - - `String text` + - `AdditionalTools` - The text input to the model. + - `String id` - - `JsonValue; type "input_text"constant` + The unique ID of the additional tools item. - The type of the input item. Always `input_text`. + - `Role role` - - `INPUT_TEXT("input_text")` + The role that provided the additional tools. - - `Optional promptCacheBreakpoint` + - `UNKNOWN("unknown")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `USER("user")` - - `JsonValue; mode "explicit"constant` + - `ASSISTANT("assistant")` - The breakpoint mode. Always `explicit`. + - `SYSTEM("system")` - - `EXPLICIT("explicit")` + - `CRITIC("critic")` - - `class BetaResponseInputImageContent:` + - `DISCRIMINATOR("discriminator")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `DEVELOPER("developer")` - - `JsonValue; type "input_image"constant` + - `TOOL("tool")` - The type of the input item. Always `input_image`. + - `List tools` - - `INPUT_IMAGE("input_image")` + The additional tool definitions made available at this item. - - `Optional detail` + - `class BetaFunctionTool:` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `LOW("low")` + - `class BetaFileSearchTool:` - - `HIGH("high")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `AUTO("auto")` + - `class BetaComputerTool:` - - `ORIGINAL("original")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional fileId` + - `class BetaComputerUsePreviewTool:` - The ID of the file to be sent to the model. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional imageUrl` + - `class BetaWebSearchTool:` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional promptCacheBreakpoint` + - `Mcp` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `CodeInterpreter` - - `JsonValue; mode "explicit"constant` + - `JsonValue;` - The breakpoint mode. Always `explicit`. + - `ImageGeneration` - - `EXPLICIT("explicit")` + - `JsonValue;` - - `class BetaResponseInputFileContent:` + - `class BetaFunctionShellTool:` - A file input to the model. + A tool that allows the model to execute shell commands. - - `JsonValue; type "input_file"constant` + - `class BetaCustomTool:` - The type of the input item. Always `input_file`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `INPUT_FILE("input_file")` + - `class BetaNamespaceTool:` - - `Optional detail` + Groups function/custom tools under a shared namespace. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `class BetaToolSearchTool:` - - `AUTO("auto")` + Hosted or BYOT tool search configuration for deferred tools. - - `LOW("low")` + - `class BetaWebSearchPreviewTool:` - - `HIGH("high")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional fileData` + - `class BetaApplyPatchTool:` - The base64-encoded data of the file to be sent to the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `Optional fileId` + - `JsonValue; type "additional_tools"constant` - The ID of the file to be sent to the model. + The type of the item. Always `additional_tools`. - - `Optional fileUrl` + - `ADDITIONAL_TOOLS("additional_tools")` - The URL of the file to be sent to the model. + - `Optional agent` - - `Optional filename` + The agent that produced this item. - The name of the file to be sent to the model. + - `String agentName` - - `Optional promptCacheBreakpoint` + The canonical name of the agent that produced this item. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaResponseCompactionItem:` - - `JsonValue; mode "explicit"constant` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The breakpoint mode. Always `explicit`. + - `String id` - - `EXPLICIT("explicit")` + The unique ID of the compaction item. - - `JsonValue; type "function_call_output"constant` + - `String encryptedContent` - The type of the function tool call output. Always `function_call_output`. + The encrypted content that was produced by compaction. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `JsonValue; type "compaction"constant` - - `Optional id` + The type of the item. Always `compaction`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `COMPACTION("compaction")` - `Optional agent` @@ -85393,129 +98971,114 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` + - `Optional createdBy` - - `class Program:` + The identifier of the actor that created the item. - - `String callerId` + - `ImageGenerationCall` - The call ID of the program item that produced this tool call. + - `String id` - - `JsonValue; type "program"constant` + The unique ID of the image generation call. - The caller type. Always `program`. + - `Optional result` - - `PROGRAM("program")` + The generated image encoded in base64. - - `Optional status` + - `Status status` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the image generation call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - - `INCOMPLETE("incomplete")` - - - `AgentMessage` - - - `String author` - - The sending agent identity. + - `GENERATING("generating")` - - `List content` + - `FAILED("failed")` - Plaintext, image, or encrypted content sent between agents. + - `JsonValue; type "image_generation_call"constant` - - `class BetaResponseInputTextContent:` + The type of the image generation call. Always `image_generation_call`. - A text input to the model. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `class BetaResponseInputImageContent:` + - `Optional agent` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The agent that produced this item. - - `class EncryptedContent:` + - `String agentName` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The canonical name of the agent that produced this item. - - `String encryptedContent` + - `class BetaResponseCodeInterpreterToolCall:` - Opaque encrypted content. + A tool call to run code. - - `JsonValue; type "encrypted_content"constant` + - `String id` - The type of the input item. Always `encrypted_content`. + The unique ID of the code interpreter tool call. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `Optional code` - - `String recipient` + The code to run, or null if not available. - The destination agent identity. + - `String containerId` - - `JsonValue; type "agent_message"constant` + The ID of the container used to run the code. - The item type. Always `agent_message`. + - `Optional> outputs` - - `AGENT_MESSAGE("agent_message")` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `Optional id` + - `class Logs:` - The unique ID of this agent message item. + The logs output from the code interpreter. - - `Optional agent` + - `String logs` - The agent that produced this item. + The logs output from the code interpreter. - - `String agentName` + - `JsonValue; type "logs"constant` - The canonical name of the agent that produced this item. + The type of the output. Always `logs`. - - `MultiAgentCall` + - `LOGS("logs")` - - `Action action` + - `class Image:` - The multi-agent action that was executed. + The image output from the code interpreter. - - `SPAWN_AGENT("spawn_agent")` + - `JsonValue; type "image"constant` - - `INTERRUPT_AGENT("interrupt_agent")` + The type of the output. Always `image`. - - `LIST_AGENTS("list_agents")` + - `IMAGE("image")` - - `SEND_MESSAGE("send_message")` + - `String url` - - `FOLLOWUP_TASK("followup_task")` + The URL of the image output from the code interpreter. - - `WAIT_AGENT("wait_agent")` + - `Status status` - - `String arguments` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The action arguments as a JSON string. + - `IN_PROGRESS("in_progress")` - - `String callId` + - `COMPLETED("completed")` - The unique ID linking this call to its output. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "multi_agent_call"constant` + - `INTERPRETING("interpreting")` - The item type. Always `multi_agent_call`. + - `FAILED("failed")` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `JsonValue; type "code_interpreter_call"constant` - - `Optional id` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The unique ID of this multi-agent call. + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - `Optional agent` @@ -85525,1280 +99088,1244 @@ public final class Main { The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` + - `LocalShellCall` + + - `String id` + + The unique ID of the local shell call. - `Action action` - The multi-agent action that produced this result. + Execute a shell command on the server. - - `SPAWN_AGENT("spawn_agent")` + - `List command` - - `INTERRUPT_AGENT("interrupt_agent")` + The command to run. - - `LIST_AGENTS("list_agents")` + - `Env env` - - `SEND_MESSAGE("send_message")` + Environment variables to set for the command. - - `FOLLOWUP_TASK("followup_task")` + - `JsonValue; type "exec"constant` - - `WAIT_AGENT("wait_agent")` + The type of the local shell action. Always `exec`. - - `String callId` + - `EXEC("exec")` - The unique ID of the multi-agent call. + - `Optional timeoutMs` - - `List output` + Optional timeout in milliseconds for the command. - Text output returned by the multi-agent action. + - `Optional user` - - `String text` + Optional user to run the command as. - The text content. + - `Optional workingDirectory` - - `JsonValue; type "output_text"constant` + Optional working directory to run the command in. - The content type. Always `output_text`. + - `String callId` - - `OUTPUT_TEXT("output_text")` + The unique ID of the local shell tool call generated by the model. - - `Optional annotations` + - `Status status` - Citations associated with the text content. + The status of the local shell call. - - `List` + - `IN_PROGRESS("in_progress")` - - `String fileId` + - `COMPLETED("completed")` - The ID of the file. + - `INCOMPLETE("incomplete")` - - `String filename` + - `JsonValue; type "local_shell_call"constant` - The filename of the file cited. + The type of the local shell call. Always `local_shell_call`. - - `long index` + - `LOCAL_SHELL_CALL("local_shell_call")` - The index of the file in the list of files. + - `Optional agent` - - `JsonValue; type "file_citation"constant` + The agent that produced this item. - The citation type. Always `file_citation`. + - `String agentName` - - `FILE_CITATION("file_citation")` + The canonical name of the agent that produced this item. - - `List` + - `LocalShellCallOutput` - - `long endIndex` + - `String id` - The index of the last character of the citation in the message. + The unique ID of the local shell tool call generated by the model. - - `long startIndex` + - `String output` - The index of the first character of the citation in the message. + A JSON string of the output of the local shell tool call. - - `String title` + - `JsonValue; type "local_shell_call_output"constant` - The title of the cited resource. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `JsonValue; type "url_citation"constant` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - The citation type. Always `url_citation`. + - `Optional agent` - - `URL_CITATION("url_citation")` + The agent that produced this item. - - `String url` + - `String agentName` - The URL of the cited resource. + The canonical name of the agent that produced this item. - - `List` + - `Optional status` - - `String containerId` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The ID of the container. + - `IN_PROGRESS("in_progress")` - - `long endIndex` + - `COMPLETED("completed")` - The index of the last character of the citation in the message. + - `INCOMPLETE("incomplete")` - - `String fileId` + - `class BetaResponseFunctionShellToolCall:` - The ID of the container file. + A tool call that executes one or more shell commands in a managed environment. - - `String filename` + - `String id` - The filename of the container file cited. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `long startIndex` + - `Action action` - The index of the first character of the citation in the message. + The shell commands and limits that describe how to run the tool call. - - `JsonValue; type "container_file_citation"constant` + - `List commands` - The citation type. Always `container_file_citation`. + - `Optional maxOutputLength` - - `CONTAINER_FILE_CITATION("container_file_citation")` + Optional maximum number of characters to return from each command. - - `JsonValue; type "multi_agent_call_output"constant` + - `Optional timeoutMs` - The item type. Always `multi_agent_call_output`. + Optional timeout in milliseconds for the commands. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `String callId` - - `Optional id` + The unique ID of the shell tool call generated by the model. - The unique ID of this multi-agent call output. + - `Optional environment` - - `Optional agent` + Represents the use of a local environment to perform shell actions. - The agent that produced this item. + - `class BetaResponseLocalEnvironment:` - - `String agentName` + Represents the use of a local environment to perform shell actions. - The canonical name of the agent that produced this item. + - `JsonValue; type "local"constant` - - `ToolSearchCall` + The environment type. Always `local`. - - `JsonValue arguments` + - `LOCAL("local")` - The arguments supplied to the tool search call. + - `class BetaResponseContainerReference:` - - `JsonValue; type "tool_search_call"constant` + Represents a container created with /v1/containers. - The item type. Always `tool_search_call`. + - `String containerId` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `JsonValue; type "container_reference"constant` - - `Optional id` + The environment type. Always `container_reference`. - The unique ID of this tool search call. + - `CONTAINER_REFERENCE("container_reference")` - - `Optional agent` + - `Status status` - The agent that produced this item. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String agentName` + - `IN_PROGRESS("in_progress")` - The canonical name of the agent that produced this item. + - `COMPLETED("completed")` - - `Optional callId` + - `INCOMPLETE("incomplete")` - The unique ID of the tool search call generated by the model. + - `JsonValue; type "shell_call"constant` - - `Optional execution` + The type of the item. Always `shell_call`. - Whether tool search was executed by the server or by the client. + - `SHELL_CALL("shell_call")` - - `SERVER("server")` + - `Optional agent` - - `CLIENT("client")` + The agent that produced this item. - - `Optional status` + - `String agentName` - The status of the tool search call. + The canonical name of the agent that produced this item. - - `IN_PROGRESS("in_progress")` + - `Optional caller` - - `COMPLETED("completed")` + The execution context that produced this tool call. - - `INCOMPLETE("incomplete")` + - `JsonValue;` - - `class BetaResponseToolSearchOutputItemParam:` + - `JsonValue; type "direct"constant` - - `List tools` + - `DIRECT("direct")` - The loaded tool definitions returned by the tool search output. + - `class Program:` - - `class BetaFunctionTool:` + - `String callerId` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The call ID of the program item that produced this tool call. - - `String name` + - `JsonValue; type "program"constant` - The name of the function to call. + - `PROGRAM("program")` - - `Optional parameters` + - `Optional createdBy` - A JSON schema object describing the parameters of the function. + The ID of the entity that created this tool call. - - `Optional strict` + - `class BetaResponseFunctionShellToolCallOutput:` - Whether strict parameter validation is enforced for this function tool. + The output of a shell tool call that was emitted. - - `JsonValue; type "function"constant` + - `String id` - The type of the function tool. Always `function`. + The unique ID of the shell call output. Populated when this item is returned via API. - - `FUNCTION("function")` + - `String callId` - - `Optional> allowedCallers` + The unique ID of the shell tool call generated by the model. - The tool invocation context(s). + - `Optional maxOutputLength` - - `DIRECT("direct")` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `PROGRAMMATIC("programmatic")` + - `List output` - - `Optional deferLoading` + An array of shell call output contents - Whether this function is deferred and loaded via tool search. + - `Outcome outcome` - - `Optional description` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - A description of the function. Used by the model to determine whether or not to call the function. + - `JsonValue;` - - `Optional outputSchema` + - `JsonValue; type "timeout"constant` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The outcome type. Always `timeout`. - - `class BetaFileSearchTool:` + - `TIMEOUT("timeout")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class Exit:` - - `JsonValue; type "file_search"constant` + Indicates that the shell commands finished and returned an exit code. - The type of the file search tool. Always `file_search`. + - `long exitCode` - - `FILE_SEARCH("file_search")` + Exit code from the shell process. - - `List vectorStoreIds` + - `JsonValue; type "exit"constant` - The IDs of the vector stores to search. + The outcome type. Always `exit`. - - `Optional filters` + - `EXIT("exit")` - A filter to apply. + - `String stderr` - - `class ComparisonFilter:` + The standard error output that was captured. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `String stdout` - - `String key` + The standard output that was captured. - The key to compare against the value. + - `Optional createdBy` - - `Type type` + The identifier of the actor that created the item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `Status status` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `EQ("eq")` + - `IN_PROGRESS("in_progress")` - - `NE("ne")` + - `COMPLETED("completed")` - - `GT("gt")` + - `INCOMPLETE("incomplete")` - - `GTE("gte")` + - `JsonValue; type "shell_call_output"constant` - - `LT("lt")` + The type of the shell call output. Always `shell_call_output`. - - `LTE("lte")` + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `IN("in")` + - `Optional agent` - - `NIN("nin")` + The agent that produced this item. - - `Value value` + - `String agentName` - The value to compare against the attribute key; supports string, number, or boolean types. + The canonical name of the agent that produced this item. - - `String` + - `Optional caller` - - `double` + The execution context that produced this tool call. - - `boolean` + - `JsonValue;` - - `List` + - `JsonValue; type "direct"constant` - - `class CompoundFilter:` + - `DIRECT("direct")` - Combine multiple filters using `and` or `or`. + - `class Program:` - - `List filters` + - `String callerId` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The call ID of the program item that produced this tool call. - - `class ComparisonFilter:` + - `JsonValue; type "program"constant` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `PROGRAM("program")` - - `String key` + - `Optional createdBy` - The key to compare against the value. + The identifier of the actor that created the item. - - `Type type` + - `class BetaResponseApplyPatchToolCall:` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A tool call that applies file diffs by creating, deleting, or updating files. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `String id` - - `EQ("eq")` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `NE("ne")` + - `String callId` - - `GT("gt")` + The unique ID of the apply patch tool call generated by the model. - - `GTE("gte")` + - `Operation operation` - - `LT("lt")` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `LTE("lte")` + - `class CreateFile:` - - `IN("in")` + Instruction describing how to create a file via the apply_patch tool. - - `NIN("nin")` + - `String diff` - - `Value value` + Diff to apply. - The value to compare against the attribute key; supports string, number, or boolean types. + - `String path` - - `String` + Path of the file to create. - - `double` + - `JsonValue; type "create_file"constant` - - `boolean` + Create a new file with the provided diff. - - `List` + - `CREATE_FILE("create_file")` - - `JsonValue` + - `class DeleteFile:` - - `Type type` + Instruction describing how to delete a file via the apply_patch tool. - Type of operation: `and` or `or`. + - `String path` - - `AND("and")` + Path of the file to delete. - - `OR("or")` + - `JsonValue; type "delete_file"constant` - - `Optional maxNumResults` + Delete the specified file. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `DELETE_FILE("delete_file")` - - `Optional rankingOptions` + - `class UpdateFile:` - Ranking options for search. + Instruction describing how to update a file via the apply_patch tool. - - `Optional hybridSearch` + - `String diff` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + Diff to apply. - - `double embeddingWeight` + - `String path` - The weight of the embedding in the reciprocal ranking fusion. + Path of the file to update. - - `double textWeight` + - `JsonValue; type "update_file"constant` - The weight of the text in the reciprocal ranking fusion. + Update an existing file with the provided diff. - - `Optional ranker` + - `UPDATE_FILE("update_file")` - The ranker to use for the file search. + - `Status status` - - `AUTO("auto")` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `IN_PROGRESS("in_progress")` - - `Optional scoreThreshold` + - `COMPLETED("completed")` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `JsonValue; type "apply_patch_call"constant` - - `class BetaComputerTool:` + The type of the item. Always `apply_patch_call`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `APPLY_PATCH_CALL("apply_patch_call")` - - `JsonValue; type "computer"constant` + - `Optional agent` - The type of the computer tool. Always `computer`. + The agent that produced this item. - - `COMPUTER("computer")` + - `String agentName` - - `class BetaComputerUsePreviewTool:` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional caller` - - `long displayHeight` + The execution context that produced this tool call. - The height of the computer display. + - `JsonValue;` - - `long displayWidth` + - `JsonValue; type "direct"constant` - The width of the computer display. + - `DIRECT("direct")` - - `Environment environment` + - `class Program:` - The type of computer environment to control. + - `String callerId` - - `WINDOWS("windows")` + The call ID of the program item that produced this tool call. - - `MAC("mac")` + - `JsonValue; type "program"constant` - - `LINUX("linux")` + - `PROGRAM("program")` - - `UBUNTU("ubuntu")` + - `Optional createdBy` - - `BROWSER("browser")` + The ID of the entity that created this tool call. - - `JsonValue; type "computer_use_preview"constant` + - `class BetaResponseApplyPatchToolCallOutput:` - The type of the computer use tool. Always `computer_use_preview`. + The output emitted by an apply patch tool call. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `String id` - - `class BetaWebSearchTool:` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String callId` - - `Type type` + The unique ID of the apply patch tool call generated by the model. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `Status status` - - `WEB_SEARCH("web_search")` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `COMPLETED("completed")` - - `Optional filters` + - `FAILED("failed")` - Filters for the search. + - `JsonValue; type "apply_patch_call_output"constant` - - `Optional> allowedDomains` + The type of the item. Always `apply_patch_call_output`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `Optional agent` - - `Optional searchContextSize` + The agent that produced this item. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `String agentName` - - `LOW("low")` + The canonical name of the agent that produced this item. - - `MEDIUM("medium")` + - `Optional caller` - - `HIGH("high")` + The execution context that produced this tool call. - - `Optional userLocation` + - `JsonValue;` - The approximate location of the user. + - `JsonValue; type "direct"constant` - - `Optional city` + - `DIRECT("direct")` - Free text input for the city of the user, e.g. `San Francisco`. + - `class Program:` - - `Optional country` + - `String callerId` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The call ID of the program item that produced this tool call. - - `Optional region` + - `JsonValue; type "program"constant` - Free text input for the region of the user, e.g. `California`. + - `PROGRAM("program")` - - `Optional timezone` + - `Optional createdBy` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The ID of the entity that created this tool call output. - - `Optional type` + - `Optional output` - The type of location approximation. Always `approximate`. + Optional textual output returned by the apply patch tool. - - `APPROXIMATE("approximate")` + - `McpCall` - - `Mcp` + - `String id` - - `String serverLabel` + The unique ID of the tool call. - A label for this MCP server, used to identify it in tool calls. + - `String arguments` - - `JsonValue; type "mcp"constant` + A JSON string of the arguments passed to the tool. - The type of the MCP tool. Always `mcp`. + - `String name` - - `MCP("mcp")` + The name of the tool that was run. - - `Optional> allowedCallers` + - `String serverLabel` - The tool invocation context(s). + The label of the MCP server running the tool. - - `DIRECT("direct")` + - `JsonValue; type "mcp_call"constant` - - `PROGRAMMATIC("programmatic")` + The type of the item. Always `mcp_call`. - - `Optional allowedTools` + - `MCP_CALL("mcp_call")` - List of allowed tool names or a filter object. + - `Optional agent` - - `List` + The agent that produced this item. - - `class McpToolFilter:` + - `String agentName` - A filter object to specify which tools are allowed. + The canonical name of the agent that produced this item. - - `Optional readOnly` + - `Optional approvalRequestId` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Unique identifier for 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> toolNames` + - `Optional error` - List of allowed tool names. + The error from the tool call, if any. - - `Optional authorization` + - `Optional output` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The output from the tool call. - - `Optional connectorId` + - `Optional status` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Currently supported `connector_id` values are: + - `IN_PROGRESS("in_progress")` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `COMPLETED("completed")` - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `INCOMPLETE("incomplete")` - - `CONNECTOR_GMAIL("connector_gmail")` + - `CALLING("calling")` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `FAILED("failed")` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `McpListTools` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `String id` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + The unique ID of the list. - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `String serverLabel` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + The label of the MCP server. - - `Optional deferLoading` + - `List tools` - Whether this MCP tool is deferred and discovered via tool search. + The tools available on the server. - - `Optional headers` + - `JsonValue inputSchema` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The JSON schema describing the tool's input. - - `Optional requireApproval` + - `String name` - Specify which of the MCP server's tools require approval. + The name of the tool. - - `class McpToolApprovalFilter:` + - `Optional annotations` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Additional annotations about the tool. - - `Optional always` + - `Optional description` - A filter object to specify which tools are allowed. + The description of the tool. - - `Optional readOnly` + - `JsonValue; type "mcp_list_tools"constant` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The type of the item. Always `mcp_list_tools`. - - `Optional> toolNames` + - `MCP_LIST_TOOLS("mcp_list_tools")` - List of allowed tool names. + - `Optional agent` - - `Optional never` + The agent that produced this item. - A filter object to specify which tools are allowed. + - `String agentName` - - `Optional readOnly` + The canonical name of the agent that produced this item. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Optional error` - - `Optional> toolNames` + Error message if the server could not list tools. - List of allowed tool names. + - `McpApprovalRequest` - - `enum McpToolApprovalSetting:` + - `String id` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The unique ID of the approval request. - - `ALWAYS("always")` + - `String arguments` - - `NEVER("never")` + A JSON string of arguments for the tool. - - `Optional serverDescription` + - `String name` - Optional description of the MCP server, used to provide more context. + The name of the tool to run. - - `Optional serverUrl` + - `String serverLabel` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The label of the MCP server making the request. - - `Optional tunnelId` + - `JsonValue; type "mcp_approval_request"constant` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The type of the item. Always `mcp_approval_request`. - - `CodeInterpreter` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `Container container` + - `Optional agent` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The agent that produced this item. - - `String` + - `String agentName` - - `class CodeInterpreterToolAuto:` + The canonical name of the agent that produced this item. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `McpApprovalResponse` - - `JsonValue; type "auto"constant` + - `String id` - Always `auto`. + The unique ID of the approval response - - `AUTO("auto")` + - `String approvalRequestId` - - `Optional> fileIds` + The ID of the approval request being answered. - An optional list of uploaded files to make available to your code. + - `boolean approve` - - `Optional memoryLimit` + Whether the request was approved. - The memory limit for the code interpreter container. + - `JsonValue; type "mcp_approval_response"constant` - - `_1G("1g")` + The type of the item. Always `mcp_approval_response`. - - `_4G("4g")` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `_16G("16g")` + - `Optional agent` - - `_64G("64g")` + The agent that produced this item. - - `Optional networkPolicy` + - `String agentName` - Network access policy for the container. + The canonical name of the agent that produced this item. - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional reason` - - `JsonValue; type "disabled"constant` + Optional reason for the decision. - Disable outbound network access. Always `disabled`. + - `class BetaResponseCustomToolCall:` - - `DISABLED("disabled")` + A call to a custom tool created by the model. - - `class BetaContainerNetworkPolicyAllowlist:` + - `String callId` - - `List allowedDomains` + An identifier used to map this custom tool call to a tool call output. - A list of allowed domains when type is `allowlist`. + - `String input` - - `JsonValue; type "allowlist"constant` + The input for the custom tool call generated by the model. - Allow outbound network access only to specified domains. Always `allowlist`. + - `String name` - - `ALLOWLIST("allowlist")` + The name of the custom tool being called. - - `Optional> domainSecrets` + - `JsonValue; type "custom_tool_call"constant` - Optional domain-scoped secrets for allowlisted domains. + The type of the custom tool call. Always `custom_tool_call`. - - `String domain` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - The domain associated with the secret. + - `Optional id` - - `String name` + The unique ID of the custom tool call in the OpenAI platform. - The name of the secret to inject for the domain. + - `Optional agent` - - `String value` + The agent that produced this item. - The secret value to inject for the domain. + - `String agentName` - - `JsonValue; type "code_interpreter"constant` + The canonical name of the agent that produced this item. - The type of the code interpreter tool. Always `code_interpreter`. + - `Optional caller` - - `CODE_INTERPRETER("code_interpreter")` + The execution context that produced this tool call. - - `Optional> allowedCallers` + - `JsonValue;` - The tool invocation context(s). + - `JsonValue; type "direct"constant` - `DIRECT("direct")` - - `PROGRAMMATIC("programmatic")` + - `class Program:` - - `JsonValue;` + - `String callerId` - - `JsonValue; type "programmatic_tool_calling"constant` + The call ID of the program item that produced this tool call. - The type of the tool. Always `programmatic_tool_calling`. + - `JsonValue; type "program"constant` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `PROGRAM("program")` - - `ImageGeneration` + - `Optional namespace` - - `JsonValue; type "image_generation"constant` + The namespace of the custom tool being called. - The type of the image generation tool. Always `image_generation`. + - `class BetaResponseCustomToolCallOutputItem:` - - `IMAGE_GENERATION("image_generation")` + The output of a custom tool call from your code, being sent back to the model. - - `Optional action` + - `String id` - Whether to generate a new image or edit an existing image. Default: `auto`. + The unique ID of the custom tool call output item. - - `GENERATE("generate")` + - `Status status` - - `EDIT("edit")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `AUTO("auto")` + - `IN_PROGRESS("in_progress")` - - `Optional background` + - `COMPLETED("completed")` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `INCOMPLETE("incomplete")` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `Optional createdBy` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The identifier of the actor that created the item. - - `TRANSPARENT("transparent")` + - `long outputIndex` - - `OPAQUE("opaque")` + The index of the output item that was added. - - `AUTO("auto")` + - `long sequenceNumber` - - `Optional inputFidelity` + The sequence number of this event. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `JsonValue; type "response.output_item.added"constant` - - `HIGH("high")` + The type of the event. Always `response.output_item.added`. - - `LOW("low")` + - `RESPONSE_OUTPUT_ITEM_ADDED("response.output_item.added")` - - `Optional inputImageMask` + - `Optional agent` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The agent that owns this multi-agent streaming event. - - `Optional fileId` + - `String agentName` - File ID for the mask image. + The canonical name of the agent that produced this item. - - `Optional imageUrl` +### Beta Response Output Item Done Event - Base64-encoded mask image. +- `class BetaResponseOutputItemDoneEvent:` - - `Optional model` + Emitted when an output item is marked done. - The image generation model to use. Default: `gpt-image-1`. + - `BetaResponseOutputItem item` - - `GPT_IMAGE_1("gpt-image-1")` + The output item that was marked done. - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `class BetaResponseOutputMessage:` - - `GPT_IMAGE_2("gpt-image-2")` + An output message from the model. - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + - `String id` - - `GPT_IMAGE_1_5("gpt-image-1.5")` + The unique ID of the output message. - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `List content` - - `Optional moderation` + The content of the output message. - Moderation level for the generated image. Default: `auto`. + - `class BetaResponseOutputText:` - - `AUTO("auto")` + A text output from the model. - - `LOW("low")` + - `List annotations` - - `Optional outputCompression` + The annotations of the text output. - Compression level for the output image. Default: 100. + - `class FileCitation:` - - `Optional outputFormat` + A citation to a file. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `String fileId` - - `PNG("png")` + The ID of the file. - - `WEBP("webp")` + - `String filename` - - `JPEG("jpeg")` + The filename of the file cited. - - `Optional partialImages` + - `long index` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The index of the file in the list of files. - - `Optional quality` + - `JsonValue; type "file_citation"constant` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the file citation. Always `file_citation`. - - `LOW("low")` + - `FILE_CITATION("file_citation")` - - `MEDIUM("medium")` + - `class UrlCitation:` - - `HIGH("high")` + A citation for a web resource used to generate a model response. - - `AUTO("auto")` + - `long endIndex` - - `Optional size` + The index of the last character of the URL citation in the message. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `long startIndex` - - `_1024X1024("1024x1024")` + The index of the first character of the URL citation in the message. - - `_1024X1536("1024x1536")` + - `String title` - - `_1536X1024("1536x1024")` + The title of the web resource. - - `AUTO("auto")` + - `JsonValue; type "url_citation"constant` - - `JsonValue;` + The type of the URL citation. Always `url_citation`. - - `JsonValue; type "local_shell"constant` + - `URL_CITATION("url_citation")` - The type of the local shell tool. Always `local_shell`. + - `String url` - - `LOCAL_SHELL("local_shell")` + The URL of the web resource. - - `class BetaFunctionShellTool:` + - `class ContainerFileCitation:` - A tool that allows the model to execute shell commands. + A citation for a container file used to generate a model response. - - `JsonValue; type "shell"constant` + - `String containerId` - The type of the shell tool. Always `shell`. + The ID of the container file. - - `SHELL("shell")` + - `long endIndex` - - `Optional> allowedCallers` + The index of the last character of the container file citation in the message. - The tool invocation context(s). + - `String fileId` - - `DIRECT("direct")` + The ID of the file. - - `PROGRAMMATIC("programmatic")` + - `String filename` - - `Optional environment` + The filename of the container file cited. - - `class BetaContainerAuto:` + - `long startIndex` - - `JsonValue; type "container_auto"constant` + The index of the first character of the container file citation in the message. - Automatically creates a container for this request + - `JsonValue; type "container_file_citation"constant` - - `CONTAINER_AUTO("container_auto")` + The type of the container file citation. Always `container_file_citation`. - - `Optional> fileIds` + - `CONTAINER_FILE_CITATION("container_file_citation")` - An optional list of uploaded files to make available to your code. + - `class FilePath:` - - `Optional memoryLimit` + A path to a file. - The memory limit for the container. + - `String fileId` - - `_1G("1g")` + The ID of the file. - - `_4G("4g")` + - `long index` - - `_16G("16g")` + The index of the file in the list of files. - - `_64G("64g")` + - `JsonValue; type "file_path"constant` - - `Optional networkPolicy` + The type of the file path. Always `file_path`. - Network access policy for the container. + - `FILE_PATH("file_path")` - - `class BetaContainerNetworkPolicyDisabled:` + - `String text` - - `class BetaContainerNetworkPolicyAllowlist:` + The text output from the model. - - `Optional> skills` + - `JsonValue; type "output_text"constant` - An optional list of skills referenced by id or inline data. + The type of the output text. Always `output_text`. - - `class BetaSkillReference:` + - `OUTPUT_TEXT("output_text")` - - `String skillId` + - `Optional> logprobs` - The ID of the referenced skill. + - `String token` - - `JsonValue; type "skill_reference"constant` + - `List bytes` - References a skill created with the /v1/skills endpoint. + - `double logprob` - - `SKILL_REFERENCE("skill_reference")` + - `List topLogprobs` - - `Optional version` + - `String token` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `List bytes` - - `class BetaInlineSkill:` + - `double logprob` - - `String description` + - `class BetaResponseOutputRefusal:` - The description of the skill. + A refusal from the model. - - `String name` + - `String refusal` - The name of the skill. + The refusal explanation from the model. - - `BetaInlineSkillSource source` + - `JsonValue; type "refusal"constant` - Inline skill payload + The type of the refusal. Always `refusal`. - - `String data` + - `REFUSAL("refusal")` - Base64-encoded skill zip bundle. + - `JsonValue; role "assistant"constant` - - `JsonValue; mediaType "application/zip"constant` + The role of the output message. Always `assistant`. - The media type of the inline skill payload. Must be `application/zip`. + - `ASSISTANT("assistant")` - - `APPLICATION_ZIP("application/zip")` + - `Status status` - - `JsonValue; type "base64"constant` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The type of the inline skill source. Must be `base64`. + - `IN_PROGRESS("in_progress")` - - `BASE64("base64")` + - `COMPLETED("completed")` - - `JsonValue; type "inline"constant` + - `INCOMPLETE("incomplete")` - Defines an inline skill for this request. + - `JsonValue; type "message"constant` - - `INLINE("inline")` + The type of the output message. Always `message`. - - `class BetaLocalEnvironment:` + - `MESSAGE("message")` - - `JsonValue; type "local"constant` + - `Optional agent` - Use a local computer environment. + The agent that produced this item. - - `LOCAL("local")` + - `String agentName` - - `Optional> skills` + The canonical name of the agent that produced this item. - An optional list of skills. + - `Optional phase` - - `String description` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The description of the skill. + - `COMMENTARY("commentary")` - - `String name` + - `FINAL_ANSWER("final_answer")` - The name of the skill. + - `class BetaResponseFileSearchToolCall:` - - `String path` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The path to the directory containing the skill. + - `String id` - - `class BetaContainerReference:` + The unique ID of the file search tool call. - - `String containerId` + - `List queries` - The ID of the referenced container. + The queries used to search for files. - - `JsonValue; type "container_reference"constant` + - `Status status` - References a container created with the /v1/containers endpoint + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `CONTAINER_REFERENCE("container_reference")` + - `IN_PROGRESS("in_progress")` - - `class BetaCustomTool:` + - `SEARCHING("searching")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `COMPLETED("completed")` - - `String name` + - `INCOMPLETE("incomplete")` - The name of the custom tool, used to identify it in tool calls. + - `FAILED("failed")` - - `JsonValue; type "custom"constant` + - `JsonValue; type "file_search_call"constant` - The type of the custom tool. Always `custom`. + The type of the file search tool call. Always `file_search_call`. - - `CUSTOM("custom")` + - `FILE_SEARCH_CALL("file_search_call")` - - `Optional> allowedCallers` + - `Optional agent` - The tool invocation context(s). + The agent that produced this item. - - `DIRECT("direct")` + - `String agentName` - - `PROGRAMMATIC("programmatic")` + The canonical name of the agent that produced this item. - - `Optional deferLoading` + - `Optional> results` - Whether this tool should be deferred and discovered via tool search. + The results of the file search tool call. - - `Optional description` + - `Optional attributes` - Optional description of the custom tool, used to provide more context. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `Optional format` + - `String` - The input format for the custom tool. Default is unconstrained text. + - `double` - - `JsonValue;` + - `boolean` - - `JsonValue; type "text"constant` + - `Optional fileId` - Unconstrained text format. Always `text`. + The unique ID of the file. - - `TEXT("text")` + - `Optional filename` - - `class Grammar:` + The name of the file. - A grammar defined by the user. + - `Optional score` - - `String definition` + The relevance score of the file - a value between 0 and 1. - The grammar definition. + - `Optional text` - - `Syntax syntax` + The text that was retrieved from the file. - The syntax of the grammar definition. One of `lark` or `regex`. + - `class BetaResponseFunctionToolCall:` - - `LARK("lark")` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `REGEX("regex")` + - `String arguments` - - `JsonValue; type "grammar"constant` + A JSON string of the arguments to pass to the function. - Grammar format. Always `grammar`. + - `String callId` - - `GRAMMAR("grammar")` + The unique ID of the function tool call generated by the model. - - `class BetaNamespaceTool:` + - `String name` - Groups function/custom tools under a shared namespace. + The name of the function to run. - - `String description` + - `JsonValue; type "function_call"constant` - A description of the namespace shown to the model. + The type of the function tool call. Always `function_call`. - - `String name` + - `FUNCTION_CALL("function_call")` - The namespace name used in tool calls (for example, `crm`). + - `Optional id` - - `List tools` + The unique ID of the function tool call. - The function/custom tools available inside this namespace. + - `Optional agent` - - `class Function:` + The agent that produced this item. - - `String name` + - `String agentName` - - `JsonValue; type "function"constant` + The canonical name of the agent that produced this item. - - `FUNCTION("function")` + - `Optional caller` - - `Optional> allowedCallers` + The execution context that produced this tool call. - The tool invocation context(s). + - `JsonValue;` - - `DIRECT("direct")` + - `JsonValue; type "direct"constant` - - `PROGRAMMATIC("programmatic")` + - `DIRECT("direct")` - - `Optional deferLoading` + - `class Program:` - Whether this function should be deferred and discovered via tool search. + - `String callerId` - - `Optional description` + The call ID of the program item that produced this tool call. - - `Optional outputSchema` + - `JsonValue; type "program"constant` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `PROGRAM("program")` - - `Optional parameters` + - `Optional namespace` - - `Optional strict` + The namespace of the function to run. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `Optional status` - - `class BetaCustomTool:` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "namespace"constant` + - `COMPLETED("completed")` - The type of the tool. Always `namespace`. + - `INCOMPLETE("incomplete")` - - `NAMESPACE("namespace")` + - `class BetaResponseFunctionToolCallOutputItem:` - - `class BetaToolSearchTool:` + - `String id` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the function call tool output. - - `JsonValue; type "tool_search"constant` + - `String callId` - The type of the tool. Always `tool_search`. + The unique ID of the function tool call generated by the model. - - `TOOL_SEARCH("tool_search")` + - `Output output` - - `Optional description` + The output from the function call generated by your code. + Can be a string or an list of output content. - Description shown to the model for a client-executed tool search tool. + - `String` - - `Optional execution` + - `List` - Whether tool search is executed by the server or by the client. + - `class BetaResponseInputText:` - - `SERVER("server")` + A text input to the model. - - `CLIENT("client")` + - `String text` - - `Optional parameters` + The text input to the model. - Parameter schema for a client-executed tool search tool. + - `JsonValue; type "input_text"constant` - - `class BetaWebSearchPreviewTool:` + The type of the input item. Always `input_text`. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `INPUT_TEXT("input_text")` - - `Type type` + - `Optional promptCacheBreakpoint` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `JsonValue; mode "explicit"constant` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The breakpoint mode. Always `explicit`. - - `Optional> searchContentTypes` + - `EXPLICIT("explicit")` - - `TEXT("text")` + - `class BetaResponseInputImage:` - - `IMAGE("image")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional searchContextSize` + - `Detail detail` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `LOW("low")` - - `MEDIUM("medium")` - - `HIGH("high")` - - `Optional userLocation` + - `AUTO("auto")` - The user's location. + - `ORIGINAL("original")` - - `JsonValue; type "approximate"constant` + - `JsonValue; type "input_image"constant` - The type of location approximation. Always `approximate`. + The type of the input item. Always `input_image`. - - `APPROXIMATE("approximate")` + - `INPUT_IMAGE("input_image")` - - `Optional city` + - `Optional fileId` - Free text input for the city of the user, e.g. `San Francisco`. + The ID of the file to be sent to the model. - - `Optional country` + - `Optional imageUrl` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `Optional region` + - `Optional promptCacheBreakpoint` - Free text input for the region of the user, e.g. `California`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional timezone` + - `JsonValue; mode "explicit"constant` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The breakpoint mode. Always `explicit`. - - `class BetaApplyPatchTool:` + - `EXPLICIT("explicit")` - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaResponseInputFile:` - - `JsonValue; type "apply_patch"constant` + A file input to the model. - The type of the tool. Always `apply_patch`. + - `JsonValue; type "input_file"constant` - - `APPLY_PATCH("apply_patch")` + The type of the input item. Always `input_file`. - - `Optional> allowedCallers` + - `INPUT_FILE("input_file")` - The tool invocation context(s). + - `Optional detail` - - `DIRECT("direct")` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `PROGRAMMATIC("programmatic")` + - `AUTO("auto")` - - `JsonValue; type "tool_search_output"constant` + - `LOW("low")` - The item type. Always `tool_search_output`. + - `HIGH("high")` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `Optional fileData` - - `Optional id` + The content of the file to be sent to the model. - The unique ID of this tool search output. + - `Optional fileId` - - `Optional agent` + The ID of the file to be sent to the model. - The agent that produced this item. + - `Optional fileUrl` - - `String agentName` + The URL of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `Optional filename` - - `Optional callId` + The name of the file to be sent to the model. - The unique ID of the tool search call generated by the model. + - `Optional promptCacheBreakpoint` - - `Optional execution` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Whether tool search was executed by the server or by the client. + - `JsonValue; mode "explicit"constant` - - `SERVER("server")` + The breakpoint mode. Always `explicit`. - - `CLIENT("client")` + - `EXPLICIT("explicit")` - - `Optional status` + - `Status status` - The status of the tool search output. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -86806,105 +100333,83 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `AdditionalTools` - - - `JsonValue; role "developer"constant` - - The role that provided the additional tools. Only `developer` is supported. - - - `DEVELOPER("developer")` - - - `List tools` - - A list of additional tools made available at this item. - - - `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `class BetaFileSearchTool:` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `JsonValue; type "function_call_output"constant` - - `class BetaComputerTool:` + The type of the function tool call output. Always `function_call_output`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `class BetaComputerUsePreviewTool:` + - `Optional agent` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `class BetaWebSearchTool:` + - `String agentName` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `Mcp` + - `Optional caller` - - `CodeInterpreter` + The execution context that produced this tool call. - `JsonValue;` - - `ImageGeneration` + - `JsonValue; type "direct"constant` - - `JsonValue;` + The caller type. Always `direct`. - - `class BetaFunctionShellTool:` + - `DIRECT("direct")` - A tool that allows the model to execute shell commands. + - `class Program:` - - `class BetaCustomTool:` + - `String callerId` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The call ID of the program item that produced this tool call. - - `class BetaNamespaceTool:` + - `JsonValue; type "program"constant` - Groups function/custom tools under a shared namespace. + The caller type. Always `program`. - - `class BetaToolSearchTool:` + - `PROGRAM("program")` - Hosted or BYOT tool search configuration for deferred tools. + - `Optional createdBy` - - `class BetaWebSearchPreviewTool:` + The identifier of the actor that created the item. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `AgentMessage` - - `class BetaApplyPatchTool:` + - `String id` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the agent message. - - `JsonValue; type "additional_tools"constant` + - `String author` - The item type. Always `additional_tools`. + The sending agent identity. - - `ADDITIONAL_TOOLS("additional_tools")` + - `List content` - - `Optional id` + Encrypted content sent between agents. - The unique ID of this additional tools item. + - `class BetaResponseInputText:` - - `Optional agent` + A text input to the model. - The agent that produced this item. + - `class BetaResponseOutputText:` - - `String agentName` + A text output from the model. - The canonical name of the agent that produced this item. + - `class Text:` - - `class BetaResponseReasoningItem:` + A text content. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `String text` - - `String id` + - `JsonValue; type "text"constant` - The unique identifier of the reasoning content. + - `TEXT("text")` - - `List summary` + - `class SummaryText:` - Reasoning summary content. + A summary text from the model. - `String text` @@ -86916,23 +100421,9 @@ public final class Main { - `SUMMARY_TEXT("summary_text")` - - `JsonValue; type "reasoning"constant` - - The type of the object. Always `reasoning`. - - - `REASONING("reasoning")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional> content` + - `class ReasoningText:` - Reasoning text content. + Reasoning text from the model. - `String text` @@ -86944,75 +100435,81 @@ public final class Main { - `REASONING_TEXT("reasoning_text")` - - `Optional encryptedContent` + - `class BetaResponseOutputRefusal:` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + A refusal from the model. - - `Optional status` + - `class BetaResponseInputImage:` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `IN_PROGRESS("in_progress")` + - `class ComputerScreenshot:` - - `COMPLETED("completed")` + A screenshot of a computer. - - `INCOMPLETE("incomplete")` + - `Detail detail` - - `class BetaResponseCompactionItemParam:` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `LOW("low")` - - `String encryptedContent` + - `HIGH("high")` - The encrypted content of the compaction summary. + - `AUTO("auto")` - - `JsonValue; type "compaction"constant` + - `ORIGINAL("original")` - The type of the item. Always `compaction`. + - `Optional fileId` - - `COMPACTION("compaction")` + The identifier of an uploaded file that contains the screenshot. - - `Optional id` + - `Optional imageUrl` - The ID of the compaction item. + The URL of the screenshot image. - - `Optional agent` + - `JsonValue; type "computer_screenshot"constant` - The agent that produced this item. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `String agentName` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The canonical name of the agent that produced this item. + - `Optional promptCacheBreakpoint` - - `ImageGenerationCall` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String id` + - `JsonValue; mode "explicit"constant` - The unique ID of the image generation call. + The breakpoint mode. Always `explicit`. - - `Optional result` + - `EXPLICIT("explicit")` - The generated image encoded in base64. + - `class BetaResponseInputFile:` - - `Status status` + A file input to the model. - The status of the image generation call. + - `class EncryptedContent:` - - `IN_PROGRESS("in_progress")` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `COMPLETED("completed")` + - `String encryptedContent` - - `GENERATING("generating")` + Opaque encrypted content. - - `FAILED("failed")` + - `JsonValue; type "encrypted_content"constant` - - `JsonValue; type "image_generation_call"constant` + The type of the input item. Always `encrypted_content`. - The type of the image generation call. Always `image_generation_call`. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The type of the item. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` - `Optional agent` @@ -87022,212 +100519,203 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. + - `MultiAgentCall` - `String id` - The unique ID of the code interpreter tool call. - - - `Optional code` - - The code to run, or null if not available. - - - `String containerId` - - The ID of the container used to run the code. + The unique ID of the multi-agent call item. - - `Optional> outputs` + - `Action action` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The multi-agent action to execute. - - `class Logs:` + - `SPAWN_AGENT("spawn_agent")` - The logs output from the code interpreter. + - `INTERRUPT_AGENT("interrupt_agent")` - - `String logs` + - `LIST_AGENTS("list_agents")` - The logs output from the code interpreter. + - `SEND_MESSAGE("send_message")` - - `JsonValue; type "logs"constant` + - `FOLLOWUP_TASK("followup_task")` - The type of the output. Always `logs`. + - `WAIT_AGENT("wait_agent")` - - `LOGS("logs")` + - `String arguments` - - `class Image:` + The JSON string of arguments generated for the action. - The image output from the code interpreter. + - `String callId` - - `JsonValue; type "image"constant` + The unique ID linking this call to its output. - The type of the output. Always `image`. + - `JsonValue; type "multi_agent_call"constant` - - `IMAGE("image")` + The type of the multi-agent call. Always `multi_agent_call`. - - `String url` + - `MULTI_AGENT_CALL("multi_agent_call")` - The URL of the image output from the code interpreter. + - `Optional agent` - - `Status status` + The agent that produced this item. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `String agentName` - - `IN_PROGRESS("in_progress")` + The canonical name of the agent that produced this item. - - `COMPLETED("completed")` + - `MultiAgentCallOutput` - - `INCOMPLETE("incomplete")` + - `String id` - - `INTERPRETING("interpreting")` + The unique ID of the multi-agent call output item. - - `FAILED("failed")` + - `Action action` - - `JsonValue; type "code_interpreter_call"constant` + The multi-agent action that produced this result. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `SPAWN_AGENT("spawn_agent")` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `Optional agent` + - `LIST_AGENTS("list_agents")` - The agent that produced this item. + - `SEND_MESSAGE("send_message")` - - `String agentName` + - `FOLLOWUP_TASK("followup_task")` - The canonical name of the agent that produced this item. + - `WAIT_AGENT("wait_agent")` - - `LocalShellCall` + - `String callId` - - `String id` + The unique ID of the multi-agent call. - The unique ID of the local shell call. + - `List output` - - `Action action` + Text output returned by the multi-agent action. - Execute a shell command on the server. + - `List annotations` - - `List command` + The annotations of the text output. - The command to run. + - `String text` - - `Env env` + The text output from the model. - Environment variables to set for the command. + - `JsonValue; type "output_text"constant` - - `JsonValue; type "exec"constant` + The type of the output text. Always `output_text`. - The type of the local shell action. Always `exec`. + - `Optional> logprobs` - - `EXEC("exec")` + - `JsonValue; type "multi_agent_call_output"constant` - - `Optional timeoutMs` + The type of the multi-agent result. Always `multi_agent_call_output`. - Optional timeout in milliseconds for the command. + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `Optional user` + - `Optional agent` - Optional user to run the command as. + The agent that produced this item. - - `Optional workingDirectory` + - `String agentName` - Optional working directory to run the command in. + The canonical name of the agent that produced this item. - - `String callId` + - `class BetaResponseFunctionWebSearch:` - The unique ID of the local shell tool call generated by the model. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `Status status` + - `String id` - The status of the local shell call. + The unique ID of the web search tool call. - - `IN_PROGRESS("in_progress")` + - `Action action` - - `COMPLETED("completed")` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `INCOMPLETE("incomplete")` + - `class Search:` - - `JsonValue; type "local_shell_call"constant` + Action type "search" - Performs a web search query. - The type of the local shell call. Always `local_shell_call`. + - `JsonValue; type "search"constant` - - `LOCAL_SHELL_CALL("local_shell_call")` + The action type. - - `Optional agent` + - `SEARCH("search")` - The agent that produced this item. + - `Optional> queries` - - `String agentName` + The search queries. - The canonical name of the agent that produced this item. + - `Optional query` - - `LocalShellCallOutput` + The search query. - - `String id` + - `Optional> sources` - The unique ID of the local shell tool call generated by the model. + The sources used in the search. - - `String output` + - `JsonValue; type "url"constant` - A JSON string of the output of the local shell tool call. + The type of source. Always `url`. - - `JsonValue; type "local_shell_call_output"constant` + - `URL("url")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `String url` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The URL of the source. - - `Optional agent` + - `class OpenPage:` - The agent that produced this item. + Action type "open_page" - Opens a specific URL from search results. - - `String agentName` + - `JsonValue; type "open_page"constant` - The canonical name of the agent that produced this item. + The action type. - - `Optional status` + - `OPEN_PAGE("open_page")` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `Optional url` - - `IN_PROGRESS("in_progress")` + The URL opened by the model. - - `COMPLETED("completed")` + - `class FindInPage:` - - `INCOMPLETE("incomplete")` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `ShellCall` + - `String pattern` - - `Action action` + The pattern or text to search for within the page. - The shell commands and limits that describe how to run the tool call. + - `JsonValue; type "find_in_page"constant` - - `List commands` + The action type. - Ordered shell commands for the execution environment to run. + - `FIND_IN_PAGE("find_in_page")` - - `Optional maxOutputLength` + - `String url` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + The URL of the page searched for the pattern. - - `Optional timeoutMs` + - `Status status` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The status of the web search tool call. - - `String callId` + - `IN_PROGRESS("in_progress")` - The unique ID of the shell tool call generated by the model. + - `SEARCHING("searching")` - - `JsonValue; type "shell_call"constant` + - `COMPLETED("completed")` - The type of the item. Always `shell_call`. + - `FAILED("failed")` - - `SHELL_CALL("shell_call")` + - `JsonValue; type "web_search_call"constant` - - `Optional id` + The type of the web search tool call. Always `web_search_call`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `WEB_SEARCH_CALL("web_search_call")` - `Optional agent` @@ -87237,41 +100725,39 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` + - `class BetaResponseComputerToolCall:` - - `JsonValue; type "direct"constant` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The caller type. Always `direct`. + - `String id` - - `DIRECT("direct")` + The unique ID of the computer call. - - `class Program:` + - `String callId` - - `String callerId` + An identifier used when responding to the tool call with output. - The call ID of the program item that produced this tool call. + - `List pendingSafetyChecks` - - `JsonValue; type "program"constant` + The pending safety checks for the computer call. - The caller type. Always `program`. + - `String id` - - `PROGRAM("program")` + The ID of the pending safety check. - - `Optional environment` + - `Optional code` - The environment to execute the shell commands in. + The type of the pending safety check. - - `class BetaLocalEnvironment:` + - `Optional message` - - `class BetaContainerReference:` + Details about the pending safety check. - - `Optional status` + - `Status status` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -87279,311 +100765,327 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `ShellCallOutput` + - `Type type` - - `String callId` + The type of the computer call. Always `computer_call`. - The unique ID of the shell tool call generated by the model. + - `COMPUTER_CALL("computer_call")` - - `List output` + - `Optional action` - Captured chunks of stdout and stderr output, along with their associated outcomes. + A click action. - - `Outcome outcome` + - `Click` - The exit or timeout outcome associated with this shell call. + - `Button button` - - `JsonValue;` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `JsonValue; type "timeout"constant` + - `LEFT("left")` - The outcome type. Always `timeout`. + - `RIGHT("right")` - - `TIMEOUT("timeout")` + - `WHEEL("wheel")` - - `class Exit:` + - `BACK("back")` - Indicates that the shell commands finished and returned an exit code. + - `FORWARD("forward")` - - `long exitCode` + - `JsonValue; type "click"constant` - The exit code returned by the shell process. + Specifies the event type. For a click action, this property is always `click`. - - `JsonValue; type "exit"constant` + - `CLICK("click")` - The outcome type. Always `exit`. + - `long x` - - `EXIT("exit")` + The x-coordinate where the click occurred. - - `String stderr` + - `long y` - Captured stderr output for the shell call. + The y-coordinate where the click occurred. - - `String stdout` + - `Optional> keys` - Captured stdout output for the shell call. + The keys being held while clicking. - - `JsonValue; type "shell_call_output"constant` + - `DoubleClick` - The type of the item. Always `shell_call_output`. + - `Optional> keys` - - `SHELL_CALL_OUTPUT("shell_call_output")` + The keys being held while double-clicking. - - `Optional id` + - `JsonValue; type "double_click"constant` - The unique ID of the shell tool call output. Populated when this item is returned via API. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `Optional agent` + - `DOUBLE_CLICK("double_click")` - The agent that produced this item. + - `long x` - - `String agentName` + The x-coordinate where the double click occurred. - The canonical name of the agent that produced this item. + - `long y` - - `Optional caller` + The y-coordinate where the double click occurred. - The execution context that produced this tool call. + - `Drag` - - `JsonValue;` + - `List path` - - `JsonValue; type "direct"constant` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The caller type. Always `direct`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `DIRECT("direct")` + - `long x` - - `class Program:` + The x-coordinate. - - `String callerId` + - `long y` - The call ID of the program item that produced this tool call. + The y-coordinate. - - `JsonValue; type "program"constant` + - `JsonValue; type "drag"constant` - The caller type. Always `program`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `PROGRAM("program")` + - `DRAG("drag")` - - `Optional maxOutputLength` + - `Optional> keys` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The keys being held while dragging the mouse. - - `Optional status` + - `Keypress` - The status of the shell call output. + - `List keys` - - `IN_PROGRESS("in_progress")` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `COMPLETED("completed")` + - `JsonValue; type "keypress"constant` - - `INCOMPLETE("incomplete")` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `ApplyPatchCall` + - `KEYPRESS("keypress")` - - `String callId` + - `Move` - The unique ID of the apply patch tool call generated by the model. + - `JsonValue; type "move"constant` - - `Operation operation` + Specifies the event type. For a move action, this property is always set to `move`. - The specific create, delete, or update instruction for the apply_patch tool call. + - `MOVE("move")` - - `class CreateFile:` + - `long x` - Instruction for creating a new file via the apply_patch tool. + The x-coordinate to move to. - - `String diff` + - `long y` - Unified diff content to apply when creating the file. + The y-coordinate to move to. - - `String path` + - `Optional> keys` - Path of the file to create relative to the workspace root. + The keys being held while moving the mouse. - - `JsonValue; type "create_file"constant` + - `JsonValue;` - The operation type. Always `create_file`. + - `JsonValue; type "screenshot"constant` - - `CREATE_FILE("create_file")` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `class DeleteFile:` + - `SCREENSHOT("screenshot")` - Instruction for deleting an existing file via the apply_patch tool. + - `Scroll` - - `String path` + - `long scrollX` - Path of the file to delete relative to the workspace root. + The horizontal scroll distance. - - `JsonValue; type "delete_file"constant` + - `long scrollY` - The operation type. Always `delete_file`. + The vertical scroll distance. - - `DELETE_FILE("delete_file")` + - `JsonValue; type "scroll"constant` - - `class UpdateFile:` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Instruction for updating an existing file via the apply_patch tool. + - `SCROLL("scroll")` - - `String diff` + - `long x` - Unified diff content to apply to the existing file. + The x-coordinate where the scroll occurred. - - `String path` + - `long y` - Path of the file to update relative to the workspace root. + The y-coordinate where the scroll occurred. - - `JsonValue; type "update_file"constant` + - `Optional> keys` - The operation type. Always `update_file`. + The keys being held while scrolling. - - `UPDATE_FILE("update_file")` + - `Type` - - `Status status` + - `String text` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The text to type. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "type"constant` - - `COMPLETED("completed")` + Specifies the event type. For a type action, this property is always set to `type`. - - `JsonValue; type "apply_patch_call"constant` + - `TYPE("type")` - The type of the item. Always `apply_patch_call`. + - `JsonValue;` - - `APPLY_PATCH_CALL("apply_patch_call")` + - `JsonValue; type "wait"constant` - - `Optional id` + Specifies the event type. For a wait action, this property is always set to `wait`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `WAIT("wait")` - - `Optional agent` + - `Optional> actions` - The agent that produced this item. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `String agentName` + - `Click` - The canonical name of the agent that produced this item. + - `DoubleClick` - - `Optional caller` + - `Drag` - The execution context that produced this tool call. + - `Keypress` + + - `Move` - `JsonValue;` - - `JsonValue; type "direct"constant` + - `Scroll` - The caller type. Always `direct`. + - `Type` - - `DIRECT("direct")` + - `JsonValue;` - - `class Program:` + - `Optional agent` - - `String callerId` + The agent that produced this item. - The call ID of the program item that produced this tool call. + - `String agentName` - - `JsonValue; type "program"constant` + The canonical name of the agent that produced this item. - The caller type. Always `program`. + - `class BetaResponseComputerToolCallOutputItem:` - - `PROGRAM("program")` + - `String id` - - `ApplyPatchCallOutput` + The unique ID of the computer call tool output. - `String callId` - The unique ID of the apply patch tool call generated by the model. + The ID of the computer tool call that produced the output. - - `Status status` + - `BetaResponseComputerToolCallOutputScreenshot output` - The status of the apply patch tool call output. One of `completed` or `failed`. + A computer screenshot image used with the computer use tool. - - `COMPLETED("completed")` + - `JsonValue; type "computer_screenshot"constant` - - `FAILED("failed")` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `JsonValue; type "apply_patch_call_output"constant` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The type of the item. Always `apply_patch_call_output`. + - `Optional fileId` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The identifier of an uploaded file that contains the screenshot. - - `Optional id` + - `Optional imageUrl` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The URL of the screenshot image. - - `Optional agent` + - `Status status` - The agent that produced this item. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `String agentName` + - `COMPLETED("completed")` - The canonical name of the agent that produced this item. + - `INCOMPLETE("incomplete")` - - `Optional caller` + - `FAILED("failed")` - The execution context that produced this tool call. + - `IN_PROGRESS("in_progress")` - - `JsonValue;` + - `JsonValue; type "computer_call_output"constant` - - `JsonValue; type "direct"constant` + The type of the computer tool call output. Always `computer_call_output`. - The caller type. Always `direct`. + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `DIRECT("direct")` + - `Optional> acknowledgedSafetyChecks` - - `class Program:` + The safety checks reported by the API that have been acknowledged by the + developer. - - `String callerId` + - `String id` - The call ID of the program item that produced this tool call. + The ID of the pending safety check. - - `JsonValue; type "program"constant` + - `Optional code` - The caller type. Always `program`. + The type of the pending safety check. - - `PROGRAM("program")` + - `Optional message` - - `Optional output` + Details about the pending safety check. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `Optional agent` - - `McpListTools` + The agent that produced this item. - - `String id` + - `String agentName` - The unique ID of the list. + The canonical name of the agent that produced this item. - - `String serverLabel` + - `Optional createdBy` - The label of the MCP server. + The identifier of the actor that created the item. - - `List tools` + - `class BetaResponseReasoningItem:` - The tools available on the server. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `JsonValue inputSchema` + - `String id` - The JSON schema describing the tool's input. + The unique identifier of the reasoning content. - - `String name` + - `List summary` - The name of the tool. + Reasoning summary content. - - `Optional annotations` + - `String text` - Additional annotations about the tool. + A summary of the reasoning output from the model so far. - - `Optional description` + - `JsonValue; type "summary_text"constant` - The description of the tool. + The type of the object. Always `summary_text`. - - `JsonValue; type "mcp_list_tools"constant` + - `SUMMARY_TEXT("summary_text")` - The type of the item. Always `mcp_list_tools`. + - `JsonValue; type "reasoning"constant` - - `MCP_LIST_TOOLS("mcp_list_tools")` + The type of the object. Always `reasoning`. + + - `REASONING("reasoning")` - `Optional agent` @@ -87593,61 +101095,59 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional error` - - Error message if the server could not list tools. - - - `McpApprovalRequest` + - `Optional> content` - - `String id` + Reasoning text content. - The unique ID of the approval request. + - `String text` - - `String arguments` + The reasoning text from the model. - A JSON string of arguments for the tool. + - `JsonValue; type "reasoning_text"constant` - - `String name` + The type of the reasoning text. Always `reasoning_text`. - The name of the tool to run. + - `REASONING_TEXT("reasoning_text")` - - `String serverLabel` + - `Optional encryptedContent` - The label of the MCP server making the request. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `JsonValue; type "mcp_approval_request"constant` + - `Optional status` - The type of the item. Always `mcp_approval_request`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `IN_PROGRESS("in_progress")` - - `Optional agent` + - `COMPLETED("completed")` - The agent that produced this item. + - `INCOMPLETE("incomplete")` - - `String agentName` + - `Program` - The canonical name of the agent that produced this item. + - `String id` - - `McpApprovalResponse` + The unique ID of the program item. - - `String approvalRequestId` + - `String callId` - The ID of the approval request being answered. + The stable call ID of the program item. - - `boolean approve` + - `String code` - Whether the request was approved. + The JavaScript source executed by programmatic tool calling. - - `JsonValue; type "mcp_approval_response"constant` + - `String fingerprint` - The type of the item. Always `mcp_approval_response`. + Opaque program replay fingerprint that must be round-tripped. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `JsonValue; type "program"constant` - - `Optional id` + The type of the item. Always `program`. - The unique ID of the approval response + - `PROGRAM("program")` - `Optional agent` @@ -87657,33 +101157,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional reason` + - `ProgramOutput` - Optional reason for the decision. + - `String id` - - `McpCall` + The unique ID of the program output item. - - `String id` + - `String callId` - The unique ID of the tool call. + The call ID of the program item. - - `String arguments` + - `String result` - A JSON string of the arguments passed to the tool. + The result produced by the program item. - - `String name` + - `Status status` - The name of the tool that was run. + The terminal status of the program output item. - - `String serverLabel` + - `COMPLETED("completed")` - The label of the MCP server running the tool. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "mcp_call"constant` + - `JsonValue; type "program_output"constant` - The type of the item. Always `mcp_call`. + The type of the item. Always `program_output`. - - `MCP_CALL("mcp_call")` + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -87693,1116 +101193,1154 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional approvalRequestId` + - `class BetaResponseToolSearchCall:` - 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. + - `String id` - - `Optional error` + The unique ID of the tool search call item. - The error from the tool call, if any. + - `JsonValue arguments` - - `Optional output` + Arguments used for the tool search call. - The output from the tool call. + - `Optional callId` - - `Optional status` + The unique ID of the tool search call generated by the model. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `Execution execution` - - `IN_PROGRESS("in_progress")` + Whether tool search was executed by the server or by the client. - - `COMPLETED("completed")` + - `SERVER("server")` - - `INCOMPLETE("incomplete")` + - `CLIENT("client")` - - `CALLING("calling")` + - `Status status` - - `FAILED("failed")` + The status of the tool search call item that was recorded. - - `class BetaResponseCustomToolCallOutput:` + - `IN_PROGRESS("in_progress")` - The output of a custom tool call from your code, being sent back to the model. + - `COMPLETED("completed")` - - `String callId` + - `INCOMPLETE("incomplete")` - The call ID, used to map this custom tool call output to a custom tool call. + - `JsonValue; type "tool_search_call"constant` - - `Output output` + The type of the item. Always `tool_search_call`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `TOOL_SEARCH_CALL("tool_search_call")` - - `String` + - `Optional agent` - - `List` + The agent that produced this item. - - `class BetaResponseInputText:` + - `String agentName` - A text input to the model. + The canonical name of the agent that produced this item. - - `class BetaResponseInputImage:` + - `Optional createdBy` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The identifier of the actor that created the item. - - `class BetaResponseInputFile:` + - `class BetaResponseToolSearchOutputItem:` - A file input to the model. + - `String id` - - `JsonValue; type "custom_tool_call_output"constant` + The unique ID of the tool search output item. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `Optional callId` - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + The unique ID of the tool search call generated by the model. - - `Optional id` + - `Execution execution` - The unique ID of the custom tool call output in the OpenAI platform. + Whether tool search was executed by the server or by the client. - - `Optional agent` + - `SERVER("server")` - The agent that produced this item. + - `CLIENT("client")` - - `String agentName` + - `Status status` - The canonical name of the agent that produced this item. + The status of the tool search output item that was recorded. - - `Optional caller` + - `IN_PROGRESS("in_progress")` - The execution context that produced this tool call. + - `COMPLETED("completed")` - - `JsonValue;` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "direct"constant` + - `List tools` - The caller type. Always `direct`. + The loaded tool definitions returned by tool search. - - `DIRECT("direct")` + - `class BetaFunctionTool:` - - `class Program:` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String callerId` + - `String name` - The call ID of the program item that produced this tool call. + The name of the function to call. - - `JsonValue; type "program"constant` + - `Optional parameters` - The caller type. Always `program`. + A JSON schema object describing the parameters of the function. - - `PROGRAM("program")` + - `Optional strict` - - `class BetaResponseCustomToolCall:` + Whether strict parameter validation is enforced for this function tool. - A call to a custom tool created by the model. + - `JsonValue; type "function"constant` - - `String callId` + The type of the function tool. Always `function`. - An identifier used to map this custom tool call to a tool call output. + - `FUNCTION("function")` - - `String input` + - `Optional> allowedCallers` - The input for the custom tool call generated by the model. + The tool invocation context(s). - - `String name` + - `DIRECT("direct")` - The name of the custom tool being called. + - `PROGRAMMATIC("programmatic")` - - `JsonValue; type "custom_tool_call"constant` + - `Optional deferLoading` - The type of the custom tool call. Always `custom_tool_call`. + Whether this function is deferred and loaded via tool search. - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `Optional description` - - `Optional id` + A description of the function. Used by the model to determine whether or not to call the function. - The unique ID of the custom tool call in the OpenAI platform. + - `Optional outputSchema` - - `Optional agent` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The agent that produced this item. + - `class BetaFileSearchTool:` - - `String agentName` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The canonical name of the agent that produced this item. + - `JsonValue; type "file_search"constant` - - `Optional caller` + The type of the file search tool. Always `file_search`. - The execution context that produced this tool call. + - `FILE_SEARCH("file_search")` - - `JsonValue;` + - `List vectorStoreIds` - - `JsonValue; type "direct"constant` + The IDs of the vector stores to search. - - `DIRECT("direct")` + - `Optional filters` - - `class Program:` + A filter to apply. - - `String callerId` + - `class ComparisonFilter:` - The call ID of the program item that produced this tool call. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `JsonValue; type "program"constant` + - `String key` - - `PROGRAM("program")` + The key to compare against the value. - - `Optional namespace` + - `Type type` - The namespace of the custom tool being called. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `CompactionTrigger` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `JsonValue; type "compaction_trigger"constant` + - `EQ("eq")` - The type of the item. Always `compaction_trigger`. + - `NE("ne")` - - `COMPACTION_TRIGGER("compaction_trigger")` + - `GT("gt")` - - `Optional agent` + - `GTE("gte")` - The agent that produced this item. + - `LT("lt")` - - `String agentName` + - `LTE("lte")` - The canonical name of the agent that produced this item. + - `IN("in")` - - `ItemReference` + - `NIN("nin")` - - `String id` + - `Value value` - The ID of the item to reference. + The value to compare against the attribute key; supports string, number, or boolean types. - - `Optional agent` + - `String` - The agent that produced this item. + - `double` - - `String agentName` + - `boolean` - The canonical name of the agent that produced this item. + - `List` - - `Optional type` + - `String` - The type of item to reference. Always `item_reference`. + - `double` - - `ITEM_REFERENCE("item_reference")` + - `class CompoundFilter:` - - `Program` + Combine multiple filters using `and` or `or`. - - `String id` + - `List filters` - The unique ID of this program item. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `String callId` + - `class ComparisonFilter:` - The stable call ID of the program item. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `String code` + - `String key` - The JavaScript source executed by programmatic tool calling. + The key to compare against the value. - - `String fingerprint` + - `Type type` - Opaque program replay fingerprint that must be round-tripped. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `JsonValue; type "program"constant` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The item type. Always `program`. + - `EQ("eq")` - - `PROGRAM("program")` + - `NE("ne")` - - `Optional agent` + - `GT("gt")` - The agent that produced this item. + - `GTE("gte")` - - `String agentName` + - `LT("lt")` - The canonical name of the agent that produced this item. + - `LTE("lte")` - - `ProgramOutput` + - `IN("in")` - - `String id` + - `NIN("nin")` - The unique ID of this program output item. + - `Value value` - - `String callId` + The value to compare against the attribute key; supports string, number, or boolean types. - The call ID of the program item. + - `String` - - `String result` + - `double` - The result produced by the program item. + - `boolean` - - `Status status` + - `List` - The terminal status of the program output. + - `String` - - `COMPLETED("completed")` + - `double` - - `INCOMPLETE("incomplete")` + - `JsonValue` - - `JsonValue; type "program_output"constant` + - `Type type` - The item type. Always `program_output`. + Type of operation: `and` or `or`. - - `PROGRAM_OUTPUT("program_output")` + - `AND("and")` - - `Optional agent` + - `OR("or")` - The agent that produced this item. + - `Optional maxNumResults` - - `String agentName` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The canonical name of the agent that produced this item. + - `Optional rankingOptions` - - `Optional metadata` + Ranking options for search. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `Optional hybridSearch` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `Model model` + - `double embeddingWeight` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + The weight of the embedding in the reciprocal ranking fusion. - - `GPT_5_6_SOL("gpt-5.6-sol")` + - `double textWeight` - - `GPT_5_6_TERRA("gpt-5.6-terra")` + The weight of the text in the reciprocal ranking fusion. - - `GPT_5_6_LUNA("gpt-5.6-luna")` + - `Optional ranker` - - `GPT_5_4("gpt-5.4")` + The ranker to use for the file search. - - `GPT_5_4_MINI("gpt-5.4-mini")` + - `AUTO("auto")` - - `GPT_5_4_NANO("gpt-5.4-nano")` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `Optional scoreThreshold` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `class BetaComputerTool:` - - `GPT_5_2("gpt-5.2")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + - `JsonValue; type "computer"constant` - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + The type of the computer tool. Always `computer`. - - `GPT_5_2_PRO("gpt-5.2-pro")` + - `COMPUTER("computer")` - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + - `class BetaComputerUsePreviewTool:` - - `GPT_5_1("gpt-5.1")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `long displayHeight` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + The height of the computer display. - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `long displayWidth` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + The width of the computer display. - - `GPT_5("gpt-5")` + - `Environment environment` - - `GPT_5_MINI("gpt-5-mini")` + The type of computer environment to control. - - `GPT_5_NANO("gpt-5-nano")` + - `WINDOWS("windows")` - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + - `MAC("mac")` - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - `LINUX("linux")` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `UBUNTU("ubuntu")` - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `BROWSER("browser")` - - `GPT_4_1("gpt-4.1")` + - `JsonValue; type "computer_use_preview"constant` - - `GPT_4_1_MINI("gpt-4.1-mini")` + The type of the computer use tool. Always `computer_use_preview`. - - `GPT_4_1_NANO("gpt-4.1-nano")` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `class BetaWebSearchTool:` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + - `Type type` - - `O4_MINI("o4-mini")` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + - `WEB_SEARCH("web_search")` - - `O3("o3")` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `O3_2025_04_16("o3-2025-04-16")` + - `Optional filters` - - `O3_MINI("o3-mini")` + Filters for the search. - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + - `Optional> allowedDomains` - - `O1("o1")` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `O1_2024_12_17("o1-2024-12-17")` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `O1_PREVIEW("o1-preview")` + - `Optional searchContextSize` - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `O1_MINI("o1-mini")` + - `LOW("low")` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + - `MEDIUM("medium")` - - `GPT_4O("gpt-4o")` + - `HIGH("high")` - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + - `Optional userLocation` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + The approximate location of the user. - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + - `Optional city` - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + Free text input for the city of the user, e.g. `San Francisco`. - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + - `Optional country` - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + - `Optional region` - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + Free text input for the region of the user, e.g. `California`. - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + - `Optional timezone` - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + - `Optional type` - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + The type of location approximation. Always `approximate`. - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + - `APPROXIMATE("approximate")` - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `Mcp` - - `CODEX_MINI_LATEST("codex-mini-latest")` + - `String serverLabel` - - `GPT_4O_MINI("gpt-4o-mini")` + A label for this MCP server, used to identify it in tool calls. - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + - `JsonValue; type "mcp"constant` - - `GPT_4_TURBO("gpt-4-turbo")` + The type of the MCP tool. Always `mcp`. - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `MCP("mcp")` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + - `Optional> allowedCallers` - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + The tool invocation context(s). - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `DIRECT("direct")` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + - `PROGRAMMATIC("programmatic")` - - `GPT_4("gpt-4")` + - `Optional allowedTools` - - `GPT_4_0314("gpt-4-0314")` + List of allowed tool names or a filter object. - - `GPT_4_0613("gpt-4-0613")` + - `List` - - `GPT_4_32K("gpt-4-32k")` + - `class McpToolFilter:` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + A filter object to specify which tools are allowed. - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `Optional readOnly` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `Optional> toolNames` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + List of allowed tool names. - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `Optional authorization` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `Optional connectorId` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `O1_PRO("o1-pro")` + Currently supported `connector_id` values are: - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - 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` - - `O3_PRO("o3-pro")` + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `CONNECTOR_GMAIL("connector_gmail")` - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `GPT_5_CODEX("gpt-5-codex")` + - `Optional deferLoading` - - `GPT_5_PRO("gpt-5-pro")` + Whether this MCP tool is deferred and discovered via tool search. - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `Optional headers` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `JsonValue; object_ "response"constant` + - `Optional requireApproval` - The object type of this resource - always set to `response`. + Specify which of the MCP server's tools require approval. - - `RESPONSE("response")` + - `class McpToolApprovalFilter:` - - `List output` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - An array of content items generated by the model. + - `Optional always` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + A filter object to specify which tools are allowed. - - `class BetaResponseOutputMessage:` + - `Optional readOnly` - An output message from the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `class BetaResponseFileSearchToolCall:` + - `Optional> toolNames` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + List of allowed tool names. - - `class BetaResponseFunctionToolCall:` + - `Optional never` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A filter object to specify which tools are allowed. - - `class BetaResponseFunctionToolCallOutputItem:` + - `Optional readOnly` - - `String id` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The unique ID of the function call tool output. + - `Optional> toolNames` - - `String callId` + List of allowed tool names. - The unique ID of the function tool call generated by the model. + - `enum McpToolApprovalSetting:` - - `Output output` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `ALWAYS("always")` - - `String` + - `NEVER("never")` - - `List` + - `Optional serverDescription` - - `class BetaResponseInputText:` + Optional description of the MCP server, used to provide more context. - A text input to the model. + - `Optional serverUrl` - - `class BetaResponseInputImage:` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Optional tunnelId` - - `class BetaResponseInputFile:` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - A file input to the model. + - `CodeInterpreter` - - `Status status` + - `Container container` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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. - - `IN_PROGRESS("in_progress")` + - `String` - - `COMPLETED("completed")` + - `class CodeInterpreterToolAuto:` - - `INCOMPLETE("incomplete")` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `JsonValue; type "function_call_output"constant` + - `JsonValue; type "auto"constant` - The type of the function tool call output. Always `function_call_output`. + Always `auto`. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `AUTO("auto")` - - `Optional agent` + - `Optional> fileIds` - The agent that produced this item. + An optional list of uploaded files to make available to your code. - - `String agentName` + - `Optional memoryLimit` - The canonical name of the agent that produced this item. + The memory limit for the code interpreter container. - - `Optional caller` + - `_1G("1g")` - The execution context that produced this tool call. + - `_4G("4g")` - - `JsonValue;` + - `_16G("16g")` - - `JsonValue; type "direct"constant` + - `_64G("64g")` - The caller type. Always `direct`. + - `Optional networkPolicy` - - `DIRECT("direct")` + Network access policy for the container. - - `class Program:` + - `class BetaContainerNetworkPolicyDisabled:` - - `String callerId` + - `JsonValue; type "disabled"constant` - The call ID of the program item that produced this tool call. + Disable outbound network access. Always `disabled`. - - `JsonValue; type "program"constant` + - `DISABLED("disabled")` - The caller type. Always `program`. + - `class BetaContainerNetworkPolicyAllowlist:` - - `PROGRAM("program")` + - `List allowedDomains` - - `Optional createdBy` + A list of allowed domains when type is `allowlist`. - The identifier of the actor that created the item. + - `JsonValue; type "allowlist"constant` - - `AgentMessage` + Allow outbound network access only to specified domains. Always `allowlist`. - - `String id` + - `ALLOWLIST("allowlist")` - The unique ID of the agent message. + - `Optional> domainSecrets` - - `String author` + Optional domain-scoped secrets for allowlisted domains. - The sending agent identity. + - `String domain` - - `List content` + The domain associated with the secret. - Encrypted content sent between agents. + - `String name` - - `class BetaResponseInputText:` + The name of the secret to inject for the domain. - A text input to the model. + - `String value` - - `class BetaResponseOutputText:` + The secret value to inject for the domain. - A text output from the model. + - `JsonValue; type "code_interpreter"constant` - - `class Text:` + The type of the code interpreter tool. Always `code_interpreter`. - A text content. + - `CODE_INTERPRETER("code_interpreter")` - - `String text` + - `Optional> allowedCallers` - - `JsonValue; type "text"constant` + The tool invocation context(s). - - `TEXT("text")` + - `DIRECT("direct")` - - `class SummaryText:` + - `PROGRAMMATIC("programmatic")` - A summary text from the model. + - `JsonValue;` - - `String text` + - `JsonValue; type "programmatic_tool_calling"constant` - A summary of the reasoning output from the model so far. + The type of the tool. Always `programmatic_tool_calling`. - - `JsonValue; type "summary_text"constant` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - The type of the object. Always `summary_text`. + - `ImageGeneration` - - `SUMMARY_TEXT("summary_text")` + - `JsonValue; type "image_generation"constant` - - `class ReasoningText:` + The type of the image generation tool. Always `image_generation`. - Reasoning text from the model. + - `IMAGE_GENERATION("image_generation")` - - `String text` + - `Optional action` - The reasoning text from the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `JsonValue; type "reasoning_text"constant` + - `GENERATE("generate")` - The type of the reasoning text. Always `reasoning_text`. + - `EDIT("edit")` - - `REASONING_TEXT("reasoning_text")` + - `AUTO("auto")` - - `class BetaResponseOutputRefusal:` + - `Optional background` - A refusal from the model. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `class BetaResponseInputImage:` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `class ComputerScreenshot:` + - `TRANSPARENT("transparent")` - A screenshot of a computer. + - `OPAQUE("opaque")` - - `Detail detail` + - `AUTO("auto")` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Optional inputFidelity` - - `LOW("low")` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - `HIGH("high")` - - `AUTO("auto")` + - `LOW("low")` - - `ORIGINAL("original")` + - `Optional inputImageMask` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - `Optional fileId` - The identifier of an uploaded file that contains the screenshot. + File ID for the mask image. - `Optional imageUrl` - The URL of the screenshot image. + Base64-encoded mask image. - - `JsonValue; type "computer_screenshot"constant` + - `Optional model` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The image generation model to use. Default: `gpt-image-1`. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `GPT_IMAGE_1("gpt-image-1")` - - `Optional promptCacheBreakpoint` + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `GPT_IMAGE_2("gpt-image-2")` - - `JsonValue; mode "explicit"constant` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - The breakpoint mode. Always `explicit`. + - `GPT_IMAGE_1_5("gpt-image-1.5")` - - `EXPLICIT("explicit")` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `class BetaResponseInputFile:` + - `Optional moderation` - A file input to the model. + Moderation level for the generated image. Default: `auto`. - - `class EncryptedContent:` + - `AUTO("auto")` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `LOW("low")` - - `String encryptedContent` + - `Optional outputCompression` - Opaque encrypted content. + Compression level for the output image. Default: 100. - - `JsonValue; type "encrypted_content"constant` + - `Optional outputFormat` - The type of the input item. Always `encrypted_content`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `PNG("png")` - - `String recipient` + - `WEBP("webp")` - The destination agent identity. + - `JPEG("jpeg")` - - `JsonValue; type "agent_message"constant` + - `Optional partialImages` - The type of the item. Always `agent_message`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `AGENT_MESSAGE("agent_message")` + - `Optional quality` - - `Optional agent` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The agent that produced this item. + - `LOW("low")` - - `String agentName` + - `MEDIUM("medium")` - The canonical name of the agent that produced this item. + - `HIGH("high")` - - `MultiAgentCall` + - `AUTO("auto")` - - `String id` + - `Optional size` - The unique ID of the multi-agent call item. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `Action action` + - `_1024X1024("1024x1024")` - The multi-agent action to execute. + - `_1024X1536("1024x1536")` - - `SPAWN_AGENT("spawn_agent")` + - `_1536X1024("1536x1024")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `AUTO("auto")` - - `LIST_AGENTS("list_agents")` + - `JsonValue;` - - `SEND_MESSAGE("send_message")` + - `JsonValue; type "local_shell"constant` - - `FOLLOWUP_TASK("followup_task")` + The type of the local shell tool. Always `local_shell`. - - `WAIT_AGENT("wait_agent")` + - `LOCAL_SHELL("local_shell")` - - `String arguments` + - `class BetaFunctionShellTool:` - The JSON string of arguments generated for the action. + A tool that allows the model to execute shell commands. - - `String callId` + - `JsonValue; type "shell"constant` - The unique ID linking this call to its output. + The type of the shell tool. Always `shell`. - - `JsonValue; type "multi_agent_call"constant` + - `SHELL("shell")` - The type of the multi-agent call. Always `multi_agent_call`. + - `Optional> allowedCallers` - - `MULTI_AGENT_CALL("multi_agent_call")` + The tool invocation context(s). - - `Optional agent` + - `DIRECT("direct")` - The agent that produced this item. + - `PROGRAMMATIC("programmatic")` - - `String agentName` + - `Optional environment` - The canonical name of the agent that produced this item. + - `class BetaContainerAuto:` - - `MultiAgentCallOutput` + - `JsonValue; type "container_auto"constant` - - `String id` + Automatically creates a container for this request - The unique ID of the multi-agent call output item. + - `CONTAINER_AUTO("container_auto")` - - `Action action` + - `Optional> fileIds` - The multi-agent action that produced this result. + An optional list of uploaded files to make available to your code. - - `SPAWN_AGENT("spawn_agent")` + - `Optional memoryLimit` - - `INTERRUPT_AGENT("interrupt_agent")` + The memory limit for the container. - - `LIST_AGENTS("list_agents")` + - `_1G("1g")` - - `SEND_MESSAGE("send_message")` + - `_4G("4g")` - - `FOLLOWUP_TASK("followup_task")` + - `_16G("16g")` - - `WAIT_AGENT("wait_agent")` + - `_64G("64g")` - - `String callId` + - `Optional networkPolicy` - The unique ID of the multi-agent call. + Network access policy for the container. - - `List output` + - `class BetaContainerNetworkPolicyDisabled:` - Text output returned by the multi-agent action. + - `class BetaContainerNetworkPolicyAllowlist:` - - `List annotations` + - `Optional> skills` - The annotations of the text output. + An optional list of skills referenced by id or inline data. - - `String text` + - `class BetaSkillReference:` - The text output from the model. + - `String skillId` - - `JsonValue; type "output_text"constant` + The ID of the referenced skill. - The type of the output text. Always `output_text`. + - `JsonValue; type "skill_reference"constant` - - `Optional> logprobs` + References a skill created with the /v1/skills endpoint. - - `JsonValue; type "multi_agent_call_output"constant` + - `SKILL_REFERENCE("skill_reference")` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `Optional version` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `Optional agent` + - `class BetaInlineSkill:` - The agent that produced this item. + - `String description` - - `String agentName` + The description of the skill. - The canonical name of the agent that produced this item. + - `String name` - - `class BetaResponseFunctionWebSearch:` + The name of the skill. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `BetaInlineSkillSource source` - - `class BetaResponseComputerToolCall:` + Inline skill payload - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `String data` - - `class BetaResponseComputerToolCallOutputItem:` + Base64-encoded skill zip bundle. - - `String id` + - `JsonValue; mediaType "application/zip"constant` - The unique ID of the computer call tool output. + The media type of the inline skill payload. Must be `application/zip`. - - `String callId` + - `APPLICATION_ZIP("application/zip")` - The ID of the computer tool call that produced the output. + - `JsonValue; type "base64"constant` - - `BetaResponseComputerToolCallOutputScreenshot output` + The type of the inline skill source. Must be `base64`. - A computer screenshot image used with the computer use tool. + - `BASE64("base64")` - - `Status status` + - `JsonValue; type "inline"constant` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Defines an inline skill for this request. - - `COMPLETED("completed")` + - `INLINE("inline")` - - `INCOMPLETE("incomplete")` + - `class BetaLocalEnvironment:` - - `FAILED("failed")` + - `JsonValue; type "local"constant` - - `IN_PROGRESS("in_progress")` + Use a local computer environment. - - `JsonValue; type "computer_call_output"constant` + - `LOCAL("local")` - The type of the computer tool call output. Always `computer_call_output`. + - `Optional> skills` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + An optional list of skills. - - `Optional> acknowledgedSafetyChecks` + - `String description` - The safety checks reported by the API that have been acknowledged by the - developer. + The description of the skill. - - `String id` + - `String name` - The ID of the pending safety check. + The name of the skill. - - `Optional code` + - `String path` - The type of the pending safety check. + The path to the directory containing the skill. - - `Optional message` + - `class BetaContainerReference:` - Details about the pending safety check. + - `String containerId` - - `Optional agent` + The ID of the referenced container. - The agent that produced this item. + - `JsonValue; type "container_reference"constant` - - `String agentName` + References a container created with the /v1/containers endpoint - The canonical name of the agent that produced this item. + - `CONTAINER_REFERENCE("container_reference")` - - `Optional createdBy` + - `class BetaCustomTool:` - The identifier of the actor that created the item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class BetaResponseReasoningItem:` + - `String name` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The name of the custom tool, used to identify it in tool calls. - - `Program` + - `JsonValue; type "custom"constant` - - `String id` + The type of the custom tool. Always `custom`. - The unique ID of the program item. + - `CUSTOM("custom")` - - `String callId` + - `Optional> allowedCallers` - The stable call ID of the program item. + The tool invocation context(s). - - `String code` + - `DIRECT("direct")` - The JavaScript source executed by programmatic tool calling. + - `PROGRAMMATIC("programmatic")` - - `String fingerprint` + - `Optional deferLoading` - Opaque program replay fingerprint that must be round-tripped. + Whether this tool should be deferred and discovered via tool search. - - `JsonValue; type "program"constant` + - `Optional description` - The type of the item. Always `program`. + Optional description of the custom tool, used to provide more context. - - `PROGRAM("program")` + - `Optional format` - - `Optional agent` + The input format for the custom tool. Default is unconstrained text. - The agent that produced this item. + - `JsonValue;` - - `String agentName` + - `JsonValue; type "text"constant` - The canonical name of the agent that produced this item. + Unconstrained text format. Always `text`. - - `ProgramOutput` + - `TEXT("text")` - - `String id` + - `class Grammar:` - The unique ID of the program output item. + A grammar defined by the user. - - `String callId` + - `String definition` - The call ID of the program item. + The grammar definition. - - `String result` + - `Syntax syntax` - The result produced by the program item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `Status status` + - `LARK("lark")` - The terminal status of the program output item. + - `REGEX("regex")` - - `COMPLETED("completed")` + - `JsonValue; type "grammar"constant` - - `INCOMPLETE("incomplete")` + Grammar format. Always `grammar`. - - `JsonValue; type "program_output"constant` + - `GRAMMAR("grammar")` - The type of the item. Always `program_output`. + - `class BetaNamespaceTool:` - - `PROGRAM_OUTPUT("program_output")` + Groups function/custom tools under a shared namespace. - - `Optional agent` + - `String description` - The agent that produced this item. + A description of the namespace shown to the model. - - `String agentName` + - `String name` - The canonical name of the agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `class BetaResponseToolSearchCall:` + - `List tools` - - `String id` + The function/custom tools available inside this namespace. - The unique ID of the tool search call item. + - `class Function:` - - `JsonValue arguments` + - `String name` - Arguments used for the tool search call. + - `JsonValue; type "function"constant` - - `Optional callId` + - `FUNCTION("function")` - The unique ID of the tool search call generated by the model. + - `Optional> allowedCallers` - - `Execution execution` + The tool invocation context(s). - Whether tool search was executed by the server or by the client. + - `DIRECT("direct")` - - `SERVER("server")` + - `PROGRAMMATIC("programmatic")` - - `CLIENT("client")` + - `Optional deferLoading` - - `Status status` + Whether this function should be deferred and discovered via tool search. - The status of the tool search call item that was recorded. + - `Optional description` - - `IN_PROGRESS("in_progress")` + - `Optional outputSchema` - - `COMPLETED("completed")` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `INCOMPLETE("incomplete")` + - `Optional parameters` - - `JsonValue; type "tool_search_call"constant` + - `Optional strict` - The type of the item. Always `tool_search_call`. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `TOOL_SEARCH_CALL("tool_search_call")` + - `class BetaCustomTool:` - - `Optional agent` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The agent that produced this item. + - `JsonValue; type "namespace"constant` - - `String agentName` + The type of the tool. Always `namespace`. - The canonical name of the agent that produced this item. + - `NAMESPACE("namespace")` - - `Optional createdBy` + - `class BetaToolSearchTool:` - The identifier of the actor that created the item. + Hosted or BYOT tool search configuration for deferred tools. - - `class BetaResponseToolSearchOutputItem:` + - `JsonValue; type "tool_search"constant` - - `String id` + The type of the tool. Always `tool_search`. - The unique ID of the tool search output item. + - `TOOL_SEARCH("tool_search")` - - `Optional callId` + - `Optional description` - The unique ID of the tool search call generated by the model. + Description shown to the model for a client-executed tool search tool. - - `Execution execution` + - `Optional execution` - Whether tool search was executed by the server or by the client. + Whether tool search is executed by the server or by the client. - `SERVER("server")` - `CLIENT("client")` - - `Status status` + - `Optional parameters` - The status of the tool search output item that was recorded. + Parameter schema for a client-executed tool search tool. - - `IN_PROGRESS("in_progress")` + - `class BetaWebSearchPreviewTool:` - - `COMPLETED("completed")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `INCOMPLETE("incomplete")` + - `Type type` - - `List tools` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The loaded tool definitions returned by tool search. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `class BetaFunctionTool:` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Optional> searchContentTypes` - - `class BetaFileSearchTool:` + - `TEXT("text")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `IMAGE("image")` - - `class BetaComputerTool:` + - `Optional searchContextSize` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `class BetaComputerUsePreviewTool:` + - `LOW("low")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `MEDIUM("medium")` - - `class BetaWebSearchTool:` + - `HIGH("high")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional userLocation` - - `Mcp` + The user's location. - - `CodeInterpreter` + - `JsonValue; type "approximate"constant` - - `JsonValue;` + The type of location approximation. Always `approximate`. - - `ImageGeneration` + - `APPROXIMATE("approximate")` - - `JsonValue;` + - `Optional city` - - `class BetaFunctionShellTool:` + Free text input for the city of the user, e.g. `San Francisco`. - A tool that allows the model to execute shell commands. + - `Optional country` - - `class BetaCustomTool:` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Optional region` - - `class BetaNamespaceTool:` + Free text input for the region of the user, e.g. `California`. - Groups function/custom tools under a shared namespace. + - `Optional timezone` - - `class BetaToolSearchTool:` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Hosted or BYOT tool search configuration for deferred tools. + - `class BetaApplyPatchTool:` - - `class BetaWebSearchPreviewTool:` + Allows the assistant to create, delete, or update files using unified diffs. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "apply_patch"constant` - - `class BetaApplyPatchTool:` + The type of the tool. Always `apply_patch`. - Allows the assistant to create, delete, or update files using unified diffs. + - `APPLY_PATCH("apply_patch")` + + - `Optional> allowedCallers` + + The tool invocation context(s). + + - `DIRECT("direct")` + + - `PROGRAMMATIC("programmatic")` - `JsonValue; type "tool_search_output"constant` @@ -88991,6 +102529,79 @@ public final class Main { A tool call to run code. + - `String id` + + The unique ID of the code interpreter tool call. + + - `Optional code` + + The code to run, or null if not available. + + - `String containerId` + + The ID of the container used to run the code. + + - `Optional> 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")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + - `LocalShellCall` - `String id` @@ -89644,6 +103255,60 @@ public final class Main { 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 id` + + The unique ID of the custom tool call in the OpenAI platform. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` + + - `DIRECT("direct")` + + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + - `PROGRAM("program")` + + - `Optional namespace` + + The namespace of the custom tool being called. + - `class BetaResponseCustomToolCallOutputItem:` The output of a custom tool call from your code, being sent back to the model. @@ -89667,775 +103332,410 @@ public final class Main { The identifier of the actor that created the item. - - `boolean parallelToolCalls` - - Whether to allow the model to run tool calls in parallel. - - - `Optional temperature` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. - - - `ToolChoice toolChoice` - - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. - - - `enum BetaToolChoiceOptions:` - - Controls which (if any) tool is called by the model. - - `none` means the model will not call any tool and instead generates a message. - - `auto` means the model can pick between generating a message or calling one or - more tools. - - `required` means the model must call one or more tools. - - - `NONE("none")` - - - `AUTO("auto")` - - - `REQUIRED("required")` - - - `class BetaToolChoiceAllowed:` - - Constrains the tools available to the model to a pre-defined set. - - - `Mode mode` - - Constrains the tools available to the model to a pre-defined set. - - `auto` allows the model to pick from among the allowed tools and generate a - message. - - `required` requires the model to call one or more of the allowed tools. - - - `AUTO("auto")` - - - `REQUIRED("required")` - - - `List tools` - - A list of tool definitions that the model should be allowed to call. - - For the Responses API, the list of tool definitions might look like: - - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` - - - `JsonValue; type "allowed_tools"constant` - - Allowed tool configuration type. Always `allowed_tools`. - - - `ALLOWED_TOOLS("allowed_tools")` - - - `class BetaToolChoiceTypes:` - - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - - `Type type` - - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - Allowed values are: - - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` - - - `FILE_SEARCH("file_search")` - - - `WEB_SEARCH_PREVIEW("web_search_preview")` - - - `COMPUTER("computer")` - - - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - - `COMPUTER_USE("computer_use")` - - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - - `IMAGE_GENERATION("image_generation")` - - - `CODE_INTERPRETER("code_interpreter")` - - - `class BetaToolChoiceFunction:` - - Use this option to force the model to call a specific function. - - - `String name` - - The name of the function to call. - - - `JsonValue; type "function"constant` - - For function calling, the type is always `function`. - - - `FUNCTION("function")` - - - `class BetaToolChoiceMcp:` - - Use this option to force the model to call a specific tool on a remote MCP server. - - - `String serverLabel` - - The label of the MCP server to use. - - - `JsonValue; type "mcp"constant` - - For MCP tools, the type is always `mcp`. - - - `MCP("mcp")` - - - `Optional name` - - The name of the tool to call on the server. - - - `class BetaToolChoiceCustom:` - - Use this option to force the model to call a specific custom tool. - - - `String name` - - The name of the custom tool to call. - - - `JsonValue; type "custom"constant` - - For custom tool calling, the type is always `custom`. - - - `CUSTOM("custom")` - - - `JsonValue;` - - - `JsonValue; type "programmatic_tool_calling"constant` - - The tool to call. Always `programmatic_tool_calling`. - - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - - `class BetaToolChoiceApplyPatch:` - - Forces the model to call the apply_patch tool when executing a tool call. - - - `JsonValue; type "apply_patch"constant` - - The tool to call. Always `apply_patch`. - - - `APPLY_PATCH("apply_patch")` - - - `class BetaToolChoiceShell:` - - Forces the model to call the shell tool when a tool call is required. - - - `JsonValue; type "shell"constant` - - The tool to call. Always `shell`. - - - `SHELL("shell")` - - - `List tools` - - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. - - We support the following categories of tools: - - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. - - - `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `class BetaFileSearchTool:` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class BetaComputerTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool:` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `Mcp` - - - `CodeInterpreter` - - - `JsonValue;` - - - `ImageGeneration` - - - `JsonValue;` - - - `class BetaFunctionShellTool:` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool:` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class BetaNamespaceTool:` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool:` - - Hosted or BYOT tool search configuration for deferred tools. + - `long outputIndex` - - `class BetaWebSearchPreviewTool:` + The index of the output item that was marked done. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `long sequenceNumber` - - `class BetaApplyPatchTool:` + The sequence number of this event. - Allows the assistant to create, delete, or update files using unified diffs. + - `JsonValue; type "response.output_item.done"constant` - - `Optional topP` + The type of the event. Always `response.output_item.done`. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `RESPONSE_OUTPUT_ITEM_DONE("response.output_item.done")` - We generally recommend altering this or `temperature` but not both. + - `Optional agent` - - `Optional background` + The agent that owns this multi-agent streaming event. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `String agentName` - - `Optional completedAt` + The canonical name of the agent that produced this item. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. +### Beta Response Output Message - - `Optional conversation` +- `class BetaResponseOutputMessage:` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + An output message from the model. - `String id` - The unique ID of the conversation that this response was associated with. - - - `Optional maxOutputTokens` - - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - - `Optional maxToolCalls` - - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - - `Optional moderation` - - Moderation results for the response input and output, if moderated completions were requested. - - - `Input input` - - Moderation for the response input. - - - `class ModerationResult:` - - A moderation result produced for the response input or output. - - - `Categories categories` - - A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - Which modalities of input are reflected by the score for each category. - - - `TEXT("text")` - - - `IMAGE("image")` - - - `CategoryScores categoryScores` - - A dictionary of moderation categories to scores. - - - `boolean flagged` - - A boolean indicating whether the content was flagged by any category. - - - `String model` - - The moderation model that produced this result. - - - `JsonValue; type "moderation_result"constant` - - The object type, which was always `moderation_result` for successful moderation results. - - - `MODERATION_RESULT("moderation_result")` - - - `class Error:` - - An error produced while attempting moderation for the response input or output. - - - `String code` - - The error code. - - - `String message` - - The error message. - - - `JsonValue; type "error"constant` + The unique ID of the output message. - The object type, which was always `error` for moderation failures. + - `List content` - - `ERROR("error")` + The content of the output message. - - `Output output` + - `class BetaResponseOutputText:` - Moderation for the response output. + A text output from the model. - - `class ModerationResult:` + - `List annotations` - A moderation result produced for the response input or output. + The annotations of the text output. - - `Categories categories` + - `class FileCitation:` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + A citation to a file. - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `String fileId` - Which modalities of input are reflected by the score for each category. + The ID of the file. - - `TEXT("text")` + - `String filename` - - `IMAGE("image")` + The filename of the file cited. - - `CategoryScores categoryScores` + - `long index` - A dictionary of moderation categories to scores. + The index of the file in the list of files. - - `boolean flagged` + - `JsonValue; type "file_citation"constant` - A boolean indicating whether the content was flagged by any category. + The type of the file citation. Always `file_citation`. - - `String model` + - `FILE_CITATION("file_citation")` - The moderation model that produced this result. + - `class UrlCitation:` - - `JsonValue; type "moderation_result"constant` + A citation for a web resource used to generate a model response. - The object type, which was always `moderation_result` for successful moderation results. + - `long endIndex` - - `MODERATION_RESULT("moderation_result")` + The index of the last character of the URL citation in the message. - - `class Error:` + - `long startIndex` - An error produced while attempting moderation for the response input or output. + The index of the first character of the URL citation in the message. - - `String code` + - `String title` - The error code. + The title of the web resource. - - `String message` + - `JsonValue; type "url_citation"constant` - The error message. + The type of the URL citation. Always `url_citation`. - - `JsonValue; type "error"constant` + - `URL_CITATION("url_citation")` - The object type, which was always `error` for moderation failures. + - `String url` - - `ERROR("error")` + The URL of the web resource. - - `Optional previousResponseId` + - `class ContainerFileCitation:` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + A citation for a container file used to generate a model response. - - `Optional prompt` + - `String containerId` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The ID of the container file. - - `String id` + - `long endIndex` - The unique identifier of the prompt template to use. + The index of the last character of the container file citation in the message. - - `Optional variables` + - `String fileId` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The ID of the file. - - `String` + - `String filename` - - `class BetaResponseInputText:` + The filename of the container file cited. - A text input to the model. + - `long startIndex` - - `class BetaResponseInputImage:` + The index of the first character of the container file citation in the message. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `JsonValue; type "container_file_citation"constant` - - `class BetaResponseInputFile:` + The type of the container file citation. Always `container_file_citation`. - A file input to the model. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `Optional version` + - `class FilePath:` - Optional version of the prompt template. + A path to a file. - - `Optional promptCacheKey` + - `String fileId` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The ID of the file. - - `Optional promptCacheOptions` + - `long index` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The index of the file in the list of files. - - `Mode mode` + - `JsonValue; type "file_path"constant` - Whether implicit prompt-cache breakpoints were enabled. + The type of the file path. Always `file_path`. - - `IMPLICIT("implicit")` + - `FILE_PATH("file_path")` - - `EXPLICIT("explicit")` + - `String text` - - `Ttl ttl` + The text output from the model. - The minimum lifetime applied to each cache breakpoint. + - `JsonValue; type "output_text"constant` - - `_30M("30m")` + The type of the output text. Always `output_text`. - - `Optional promptCacheRetention` + - `OUTPUT_TEXT("output_text")` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `Optional> logprobs` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `String token` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `List bytes` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `double logprob` - - `IN_MEMORY("in_memory")` + - `List topLogprobs` - - `_24H("24h")` + - `String token` - - `Optional reasoning` + - `List bytes` - **gpt-5 and o-series models only** + - `double logprob` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `class BetaResponseOutputRefusal:` - - `Optional context` + A refusal from the model. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `String refusal` - - `AUTO("auto")` + The refusal explanation from the model. - - `CURRENT_TURN("current_turn")` + - `JsonValue; type "refusal"constant` - - `ALL_TURNS("all_turns")` + The type of the refusal. Always `refusal`. - - `Optional effort` + - `REFUSAL("refusal")` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `JsonValue; role "assistant"constant` - - `NONE("none")` + The role of the output message. Always `assistant`. - - `MINIMAL("minimal")` + - `ASSISTANT("assistant")` - - `LOW("low")` + - `Status status` - - `MEDIUM("medium")` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `HIGH("high")` + - `IN_PROGRESS("in_progress")` - - `XHIGH("xhigh")` + - `COMPLETED("completed")` - - `MAX("max")` + - `INCOMPLETE("incomplete")` - - `Optional generateSummary` + - `JsonValue; type "message"constant` - **Deprecated:** use `summary` instead. + The type of the output message. Always `message`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `MESSAGE("message")` - - `AUTO("auto")` + - `Optional agent` - - `CONCISE("concise")` + The agent that produced this item. - - `DETAILED("detailed")` + - `String agentName` - - `Optional mode` + The canonical name of the agent that produced this item. - Controls the reasoning execution mode for the request. + - `Optional phase` - When returned on a response, this is the effective execution mode. + 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. - - `STANDARD("standard")` + - `COMMENTARY("commentary")` - - `PRO("pro")` + - `FINAL_ANSWER("final_answer")` - - `Optional summary` +### Beta Response Output Refusal - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. +- `class BetaResponseOutputRefusal:` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + A refusal from the model. - - `AUTO("auto")` + - `String refusal` - - `CONCISE("concise")` + The refusal explanation from the model. - - `DETAILED("detailed")` + - `JsonValue; type "refusal"constant` - - `Optional safetyIdentifier` + The type of the refusal. Always `refusal`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `REFUSAL("refusal")` - - `Optional serviceTier` +### Beta Response Output Text - Specifies the processing type used for serving the request. +- `class BetaResponseOutputText:` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + A text output from the model. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `List annotations` - - `AUTO("auto")` + The annotations of the text output. - - `DEFAULT("default")` + - `class FileCitation:` - - `FLEX("flex")` + A citation to a file. - - `SCALE("scale")` + - `String fileId` - - `PRIORITY("priority")` + The ID of the file. - - `Optional status` + - `String filename` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The filename of the file cited. - - `COMPLETED("completed")` + - `long index` - - `FAILED("failed")` + The index of the file in the list of files. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "file_citation"constant` - - `CANCELLED("cancelled")` + The type of the file citation. Always `file_citation`. - - `QUEUED("queued")` + - `FILE_CITATION("file_citation")` - - `INCOMPLETE("incomplete")` + - `class UrlCitation:` - - `Optional text` + A citation for a web resource used to generate a model response. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `long endIndex` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The index of the last character of the URL citation in the message. - - `Optional format` + - `long startIndex` - An object specifying the format that the model must output. + The index of the first character of the URL citation in the message. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `String title` - The default format is `{ "type": "text" }` with no additional options. + The title of the web resource. - **Not recommended for gpt-4o and newer models:** + - `JsonValue; type "url_citation"constant` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The type of the URL citation. Always `url_citation`. - - `JsonValue;` + - `URL_CITATION("url_citation")` - - `JsonValue; type "text"constant` + - `String url` - The type of response format being defined. Always `text`. + The URL of the web resource. - - `TEXT("text")` + - `class ContainerFileCitation:` - - `class BetaResponseFormatTextJsonSchemaConfig:` + A citation for a container file used to generate a model response. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `String containerId` - - `String name` + The ID of the container file. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `long endIndex` - - `Schema schema` + The index of the last character of the container file citation in the message. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `String fileId` - - `JsonValue; type "json_schema"constant` + The ID of the file. - The type of response format being defined. Always `json_schema`. + - `String filename` - - `JSON_SCHEMA("json_schema")` + The filename of the container file cited. - - `Optional description` + - `long startIndex` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The index of the first character of the container file citation in the message. - - `Optional strict` + - `JsonValue; type "container_file_citation"constant` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The type of the container file citation. Always `container_file_citation`. - - `JsonValue;` + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `JsonValue; type "json_object"constant` + - `class FilePath:` - The type of response format being defined. Always `json_object`. + A path to a file. - - `JSON_OBJECT("json_object")` + - `String fileId` - - `Optional verbosity` + The ID of the file. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `long index` - - `LOW("low")` + The index of the file in the list of files. - - `MEDIUM("medium")` + - `JsonValue; type "file_path"constant` - - `HIGH("high")` + The type of the file path. Always `file_path`. - - `Optional topLogprobs` + - `FILE_PATH("file_path")` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `String text` - - `Optional truncation` + The text output from the model. - The truncation strategy to use for the model response. + - `JsonValue; type "output_text"constant` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The type of the output text. Always `output_text`. - - `AUTO("auto")` + - `OUTPUT_TEXT("output_text")` - - `DISABLED("disabled")` + - `Optional> logprobs` - - `Optional usage` + - `String token` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `List bytes` - - `long inputTokens` + - `double logprob` - The number of input tokens. + - `List topLogprobs` - - `InputTokensDetails inputTokensDetails` + - `String token` - A detailed breakdown of the input tokens. + - `List bytes` - - `long cacheWriteTokens` + - `double logprob` - The number of input tokens that were written to the cache. +### Beta Response Output Text Annotation Added Event - - `long cachedTokens` +- `class BetaResponseOutputTextAnnotationAddedEvent:` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + Emitted when an annotation is added to output text content. - - `long outputTokens` + - `JsonValue annotation` - The number of output tokens. + The annotation object being added. (See annotation schema for details.) - - `OutputTokensDetails outputTokensDetails` + - `long annotationIndex` - A detailed breakdown of the output tokens. + The index of the annotation within the content part. - - `long reasoningTokens` + - `long contentIndex` - The number of reasoning tokens. + The index of the content part within the output item. - - `long totalTokens` + - `String itemId` - The total number of tokens used. + The unique identifier of the item to which the annotation is being added. - - `Optional user` + - `long outputIndex` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The index of the output item in the response's output array. - `long sequenceNumber` The sequence number of this event. - - `JsonValue; type "response.incomplete"constant` + - `JsonValue; type "response.output_text.annotation.added"constant` - The type of the event. Always `response.incomplete`. + The type of the event. Always 'response.output_text.annotation.added'. - - `RESPONSE_INCOMPLETE("response.incomplete")` + - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` - `Optional agent` @@ -90445,38 +103745,24 @@ public final class Main { The canonical name of the agent that produced this item. -### Beta Response Input Audio - -- `class BetaResponseInputAudio:` - - An audio input to the model. - - - `InputAudio inputAudio` - - - `String data` - - Base64-encoded audio data. - - - `Format format` - - The format of the audio data. Currently supported formats are `mp3` and - `wav`. - - - `MP3("mp3")` +### Beta Response Prompt - - `WAV("wav")` +- `class BetaResponsePrompt:` - - `JsonValue; type "input_audio"constant` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The type of the input item. Always `input_audio`. + - `String id` - - `INPUT_AUDIO("input_audio")` + The unique identifier of the prompt template to use. -### Beta Response Input Content + - `Optional variables` -- `class BetaResponseInputContent: A class that can be one of several variants.union` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - A text input to the model. + - `String` - `class BetaResponseInputText:` @@ -90588,195 +103874,101 @@ public final class Main { - `EXPLICIT("explicit")` -### Beta Response Input File - -- `class BetaResponseInputFile:` - - 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` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Input File Content - -- `class BetaResponseInputFileContent:` - - 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` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The base64-encoded data of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. + - `Optional version` - - `EXPLICIT("explicit")` + Optional version of the prompt template. -### Beta Response Input Image +### Beta Response Queued Event -- `class BetaResponseInputImage:` +- `class BetaResponseQueuedEvent:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Emitted when a response is queued and waiting to be processed. - - `Detail detail` + - `BetaResponse response` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The full response object that is queued. - - `LOW("low")` + - `String id` - - `HIGH("high")` + Unique identifier for this Response. - - `AUTO("auto")` + - `double createdAt` - - `ORIGINAL("original")` + Unix timestamp (in seconds) of when this Response was created. - - `JsonValue; type "input_image"constant` + - `Optional error` - The type of the input item. Always `input_image`. + An error object returned when the model fails to generate a Response. - - `INPUT_IMAGE("input_image")` + - `Code code` - - `Optional fileId` + The error code for the response. - The ID of the file to be sent to the model. + - `SERVER_ERROR("server_error")` - - `Optional imageUrl` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `INVALID_PROMPT("invalid_prompt")` - - `Optional promptCacheBreakpoint` + - `BIO_POLICY("bio_policy")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - `JsonValue; mode "explicit"constant` + - `INVALID_IMAGE("invalid_image")` - The breakpoint mode. Always `explicit`. + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - - `EXPLICIT("explicit")` + - `INVALID_BASE64_IMAGE("invalid_base64_image")` -### Beta Response Input Image Content + - `INVALID_IMAGE_URL("invalid_image_url")` -- `class BetaResponseInputImageContent:` + - `IMAGE_TOO_LARGE("image_too_large")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `IMAGE_TOO_SMALL("image_too_small")` - - `JsonValue; type "input_image"constant` + - `IMAGE_PARSE_ERROR("image_parse_error")` - The type of the input item. Always `input_image`. + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - - `INPUT_IMAGE("input_image")` + - `INVALID_IMAGE_MODE("invalid_image_mode")` - - `Optional detail` + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - - `LOW("low")` + - `EMPTY_IMAGE_FILE("empty_image_file")` - - `HIGH("high")` + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - - `AUTO("auto")` + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - - `ORIGINAL("original")` + - `String message` - - `Optional fileId` + A human-readable description of the error. - The ID of the file to be sent to the model. + - `Optional incompleteDetails` - - `Optional imageUrl` + Details about why the response is incomplete. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `Optional reason` - - `Optional promptCacheBreakpoint` + The reason why the response is incomplete. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - - `JsonValue; mode "explicit"constant` + - `CONTENT_FILTER("content_filter")` - The breakpoint mode. Always `explicit`. + - `Optional instructions` - - `EXPLICIT("explicit")` + A system (or developer) message inserted into the model's context. -### Beta Response Input Item + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. -- `class BetaResponseInputItem: A class that can be one of several variants.union` + - `String` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `List` - `class BetaEasyInputMessage:` @@ -90926,6 +104118,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -91181,6 +104375,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -92317,7 +105513,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -92374,7 +105574,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -94456,1107 +107660,242 @@ public final class Main { The canonical name of the agent that produced this item. -### Beta Response Input Message Item - -- `class BetaResponseInputMessageItem:` - - - `String id` - - The unique ID of the message input. - - - `List content` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText:` - - 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `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 fileId` - - The ID of the file to be sent to the model. - - - `Optional imageUrl` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - 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` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `Role role` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `USER("user")` - - - `SYSTEM("system")` - - - `DEVELOPER("developer")` - - - `JsonValue; type "message"constant` - - The type of the message input. Always set to `message`. - - - `MESSAGE("message")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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")` - -### Beta Response Input Text - -- `class BetaResponseInputText:` - - 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Input Text Content - -- `class BetaResponseInputTextContent:` - - 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - -### Beta Response Item - -- `class BetaResponseItem: A class that can be one of several variants.union` - - Content item used to generate a response. - - - `class BetaResponseInputMessageItem:` - - - `String id` - - The unique ID of the message input. - - - `List content` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText:` - - 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `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 fileId` - - The ID of the file to be sent to the model. - - - `Optional imageUrl` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - 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` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `AUTO("auto")` - - - `LOW("low")` - - - `HIGH("high")` - - - `Optional fileData` - - The content of the file to be sent to the model. - - - `Optional fileId` - - The ID of the file to be sent to the model. - - - `Optional fileUrl` - - The URL of the file to be sent to the model. - - - `Optional filename` - - The name of the file to be sent to the model. - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `Role role` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `USER("user")` - - - `SYSTEM("system")` - - - `DEVELOPER("developer")` - - - `JsonValue; type "message"constant` - - The type of the message input. Always set to `message`. - - - `MESSAGE("message")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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")` - - - `class BetaResponseOutputMessage:` - - An output message from the model. - - - `String id` - - The unique ID of the output message. - - - `List content` - - The content of the output message. - - - `class BetaResponseOutputText:` - - A text output from the model. - - - `List 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> logprobs` - - - `String token` - - - `List bytes` - - - `double logprob` - - - `List topLogprobs` - - - `String token` - - - `List bytes` - - - `double logprob` - - - `class BetaResponseOutputRefusal:` - - 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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")` - - - `class BetaResponseFileSearchToolCall:` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - - `String id` - - The unique ID of the file search tool call. - - - `List 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional> results` - - The results of the file search tool call. - - - `Optional attributes` + - `Optional 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, booleans, or numbers. - - - `String` - - - `double` - - - `boolean` - - - `Optional fileId` - - The unique ID of the file. - - - `Optional filename` - - The name of the file. - - - `Optional score` - - The relevance score of the file - a value between 0 and 1. - - - `Optional text` - - The text that was retrieved from the file. - - - `class BetaResponseComputerToolCall:` - - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - - `String id` - - The unique ID of the computer call. - - - `String callId` - - An identifier used when responding to the tool call with output. - - - `List pendingSafetyChecks` - - The pending safety checks for the computer call. - - - `String id` - - The ID of the pending safety check. - - - `Optional code` - - The type of the pending safety check. - - - `Optional 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` - - A click action. - - - `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> keys` - - The keys being held while clicking. - - - `DoubleClick` - - - `Optional> 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` - - 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> keys` - - The keys being held while dragging the mouse. - - - `Keypress` - - - `List 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> 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> 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")` - - - `Optional> actions` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `Click` - - - `DoubleClick` + format, and querying for objects via API or the dashboard. - - `Drag` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Keypress` + - `Model model` - - `Move` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `JsonValue;` + - `GPT_5_6_SOL("gpt-5.6-sol")` - - `Scroll` + - `GPT_5_6_TERRA("gpt-5.6-terra")` - - `Type` + - `GPT_5_6_LUNA("gpt-5.6-luna")` - - `JsonValue;` + - `GPT_5_4("gpt-5.4")` - - `Optional agent` + - `GPT_5_4_MINI("gpt-5.4-mini")` - The agent that produced this item. + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `String agentName` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - The canonical name of the agent that produced this item. + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - `class BetaResponseComputerToolCallOutputItem:` + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - `String id` + - `GPT_5_2("gpt-5.2")` - The unique ID of the computer call tool output. + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - - `String callId` + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - The ID of the computer tool call that produced the output. + - `GPT_5_2_PRO("gpt-5.2-pro")` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - A computer screenshot image used with the computer use tool. + - `GPT_5_1("gpt-5.1")` - - `JsonValue; type "computer_screenshot"constant` + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `GPT_5_1_CODEX("gpt-5.1-codex")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `GPT_5_1_MINI("gpt-5.1-mini")` - - `Optional fileId` + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - The identifier of an uploaded file that contains the screenshot. + - `GPT_5("gpt-5")` - - `Optional imageUrl` + - `GPT_5_MINI("gpt-5-mini")` - The URL of the screenshot image. + - `GPT_5_NANO("gpt-5-nano")` - - `Status status` + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `COMPLETED("completed")` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - `INCOMPLETE("incomplete")` + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `FAILED("failed")` + - `GPT_4_1("gpt-4.1")` - - `IN_PROGRESS("in_progress")` + - `GPT_4_1_MINI("gpt-4.1-mini")` - - `JsonValue; type "computer_call_output"constant` + - `GPT_4_1_NANO("gpt-4.1-nano")` - The type of the computer tool call output. Always `computer_call_output`. + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `Optional> acknowledgedSafetyChecks` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - The safety checks reported by the API that have been acknowledged by the - developer. + - `O4_MINI("o4-mini")` - - `String id` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - The ID of the pending safety check. + - `O3("o3")` - - `Optional code` + - `O3_2025_04_16("o3-2025-04-16")` - The type of the pending safety check. + - `O3_MINI("o3-mini")` - - `Optional message` + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - Details about the pending safety check. + - `O1("o1")` - - `Optional agent` + - `O1_2024_12_17("o1-2024-12-17")` - The agent that produced this item. + - `O1_PREVIEW("o1-preview")` - - `String agentName` + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - The canonical name of the agent that produced this item. + - `O1_MINI("o1-mini")` - - `Optional createdBy` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - The identifier of the actor that created the item. + - `GPT_4O("gpt-4o")` - - `class BetaResponseFunctionWebSearch:` + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - `String id` + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - The unique ID of the web search tool call. + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - `Action action` + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - - `class Search:` + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - Action type "search" - Performs a web search query. + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - - `JsonValue; type "search"constant` + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - The action type. + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `SEARCH("search")` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `Optional> queries` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - The search queries. + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - `Optional query` + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - The search query. + - `CODEX_MINI_LATEST("codex-mini-latest")` - - `Optional> sources` + - `GPT_4O_MINI("gpt-4o-mini")` - The sources used in the search. + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - - `JsonValue; type "url"constant` + - `GPT_4_TURBO("gpt-4-turbo")` - The type of source. Always `url`. + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - - `URL("url")` + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `String url` + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - The URL of the source. + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - - `class OpenPage:` + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - Action type "open_page" - Opens a specific URL from search results. + - `GPT_4("gpt-4")` - - `JsonValue; type "open_page"constant` + - `GPT_4_0314("gpt-4-0314")` - The action type. + - `GPT_4_0613("gpt-4-0613")` - - `OPEN_PAGE("open_page")` + - `GPT_4_32K("gpt-4-32k")` - - `Optional url` + - `GPT_4_32K_0314("gpt-4-32k-0314")` - The URL opened by the model. + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `class FindInPage:` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `String pattern` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - The pattern or text to search for within the page. + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `JsonValue; type "find_in_page"constant` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - The action type. + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - `FIND_IN_PAGE("find_in_page")` + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - - `String url` + - `O1_PRO("o1-pro")` - The URL of the page searched for the pattern. + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - - `Status status` + - `O3_PRO("o3-pro")` - The status of the web search tool call. + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - - `IN_PROGRESS("in_progress")` + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `SEARCHING("searching")` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - - `COMPLETED("completed")` + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - - `FAILED("failed")` + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - - `JsonValue; type "web_search_call"constant` + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - The type of the web search tool call. Always `web_search_call`. + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - - `WEB_SEARCH_CALL("web_search_call")` + - `GPT_5_CODEX("gpt-5-codex")` - - `Optional agent` + - `GPT_5_PRO("gpt-5-pro")` - The agent that produced this item. + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - - `String agentName` + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - The canonical name of the agent that produced this item. + - `JsonValue; object_ "response"constant` - - `class BetaResponseFunctionToolCallItem:` + The object type of this resource - always set to `response`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `RESPONSE("response")` - - `String id` + - `List output` - The unique ID of the function tool call. + An array of content items generated by the model. - - `Status status` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaResponseOutputMessage:` - - `IN_PROGRESS("in_progress")` + An output message from the model. - - `COMPLETED("completed")` + - `class BetaResponseFileSearchToolCall:` - - `INCOMPLETE("incomplete")` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `Optional createdBy` + - `class BetaResponseFunctionToolCall:` - The identifier of the actor that created the item. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `class BetaResponseFunctionToolCallOutputItem:` @@ -95888,6 +108227,153 @@ public final class Main { The canonical name of the agent that produced this item. + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `class BetaResponseComputerToolCallOutputItem:` + + - `String id` + + The unique ID of the computer call tool output. + + - `String callId` + + The ID of the computer tool call that produced the output. + + - `BetaResponseComputerToolCallOutputScreenshot output` + + A computer screenshot image used with the computer use tool. + + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + + - `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> 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 code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseReasoningItem:` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `Program` + + - `String id` + + The unique ID of the program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The type of the item. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of the program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output item. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The type of the item. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + - `class BetaResponseToolSearchCall:` - `String id` @@ -95974,1513 +108460,1730 @@ public final class Main { Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String name` + - `class BetaFileSearchTool:` - The name of the function to call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional parameters` + - `class BetaComputerTool:` - A JSON schema object describing the parameters of the function. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional strict` + - `class BetaComputerUsePreviewTool:` - Whether strict parameter validation is enforced for this function tool. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; type "function"constant` + - `class BetaWebSearchTool:` - The type of the function tool. Always `function`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `FUNCTION("function")` + - `Mcp` - - `Optional> allowedCallers` + - `CodeInterpreter` - The tool invocation context(s). + - `JsonValue;` - - `DIRECT("direct")` + - `ImageGeneration` - - `PROGRAMMATIC("programmatic")` + - `JsonValue;` - - `Optional deferLoading` + - `class BetaFunctionShellTool:` - Whether this function is deferred and loaded via tool search. + A tool that allows the model to execute shell commands. - - `Optional description` + - `class BetaCustomTool:` - A description of the function. Used by the model to determine whether or not to call the function. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional outputSchema` + - `class BetaNamespaceTool:` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `JsonValue; type "tool_search_output"constant` + + The type of the item. Always `tool_search_output`. + + - `TOOL_SEARCH_OUTPUT("tool_search_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `AdditionalTools` + + - `String id` + + The unique ID of the additional tools item. + + - `Role role` + + The role that provided the additional tools. + + - `UNKNOWN("unknown")` + + - `USER("user")` + + - `ASSISTANT("assistant")` + + - `SYSTEM("system")` + + - `CRITIC("critic")` + + - `DISCRIMINATOR("discriminator")` + + - `DEVELOPER("developer")` + + - `TOOL("tool")` + + - `List tools` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `class BetaFileSearchTool:` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `JsonValue; type "file_search"constant` + - `class BetaComputerTool:` - The type of the file search tool. Always `file_search`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `FILE_SEARCH("file_search")` + - `class BetaComputerUsePreviewTool:` - - `List vectorStoreIds` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The IDs of the vector stores to search. + - `class BetaWebSearchTool:` - - `Optional filters` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - A filter to apply. + - `Mcp` - - `class ComparisonFilter:` + - `CodeInterpreter` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `JsonValue;` - - `String key` + - `ImageGeneration` - The key to compare against the value. + - `JsonValue;` - - `Type type` + - `class BetaFunctionShellTool:` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A tool that allows the model to execute shell commands. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `class BetaCustomTool:` - - `EQ("eq")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `NE("ne")` + - `class BetaNamespaceTool:` - - `GT("gt")` + Groups function/custom tools under a shared namespace. - - `GTE("gte")` + - `class BetaToolSearchTool:` - - `LT("lt")` + Hosted or BYOT tool search configuration for deferred tools. - - `LTE("lte")` + - `class BetaWebSearchPreviewTool:` - - `IN("in")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `NIN("nin")` + - `class BetaApplyPatchTool:` - - `Value value` + Allows the assistant to create, delete, or update files using unified diffs. - The value to compare against the attribute key; supports string, number, or boolean types. + - `JsonValue; type "additional_tools"constant` - - `String` + The type of the item. Always `additional_tools`. - - `double` + - `ADDITIONAL_TOOLS("additional_tools")` - - `boolean` + - `Optional agent` - - `List` + The agent that produced this item. - - `class CompoundFilter:` + - `String agentName` - Combine multiple filters using `and` or `or`. + The canonical name of the agent that produced this item. - - `List filters` + - `class BetaResponseCompactionItem:` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `class ComparisonFilter:` + - `String id` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The unique ID of the compaction item. - - `String key` + - `String encryptedContent` - The key to compare against the value. + The encrypted content that was produced by compaction. - - `Type type` + - `JsonValue; type "compaction"constant` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the item. Always `compaction`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `COMPACTION("compaction")` - - `EQ("eq")` + - `Optional agent` - - `NE("ne")` + The agent that produced this item. - - `GT("gt")` + - `String agentName` - - `GTE("gte")` + The canonical name of the agent that produced this item. - - `LT("lt")` + - `Optional createdBy` - - `LTE("lte")` + The identifier of the actor that created the item. - - `IN("in")` + - `ImageGenerationCall` - - `NIN("nin")` + - `String id` - - `Value value` + The unique ID of the image generation call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `Optional result` - - `String` + The generated image encoded in base64. - - `double` + - `Status status` - - `boolean` + The status of the image generation call. - - `List` + - `IN_PROGRESS("in_progress")` - - `JsonValue` + - `COMPLETED("completed")` - - `Type type` + - `GENERATING("generating")` - Type of operation: `and` or `or`. + - `FAILED("failed")` - - `AND("and")` + - `JsonValue; type "image_generation_call"constant` - - `OR("or")` + The type of the image generation call. Always `image_generation_call`. - - `Optional maxNumResults` + - `IMAGE_GENERATION_CALL("image_generation_call")` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `Optional agent` - - `Optional rankingOptions` + The agent that produced this item. - Ranking options for search. + - `String agentName` - - `Optional hybridSearch` + The canonical name of the agent that produced this item. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `class BetaResponseCodeInterpreterToolCall:` - - `double embeddingWeight` + A tool call to run code. - The weight of the embedding in the reciprocal ranking fusion. + - `LocalShellCall` - - `double textWeight` + - `String id` - The weight of the text in the reciprocal ranking fusion. + The unique ID of the local shell call. - - `Optional ranker` + - `Action action` - The ranker to use for the file search. + Execute a shell command on the server. - - `AUTO("auto")` + - `List command` - - `DEFAULT_2024_11_15("default-2024-11-15")` + The command to run. - - `Optional scoreThreshold` + - `Env env` - 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. + Environment variables to set for the command. - - `class BetaComputerTool:` + - `JsonValue; type "exec"constant` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the local shell action. Always `exec`. - - `JsonValue; type "computer"constant` + - `EXEC("exec")` - The type of the computer tool. Always `computer`. + - `Optional timeoutMs` - - `COMPUTER("computer")` + Optional timeout in milliseconds for the command. - - `class BetaComputerUsePreviewTool:` + - `Optional user` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Optional user to run the command as. - - `long displayHeight` + - `Optional workingDirectory` - The height of the computer display. + Optional working directory to run the command in. - - `long displayWidth` + - `String callId` - The width of the computer display. + The unique ID of the local shell tool call generated by the model. - - `Environment environment` + - `Status status` - The type of computer environment to control. + The status of the local shell call. - - `WINDOWS("windows")` + - `IN_PROGRESS("in_progress")` - - `MAC("mac")` + - `COMPLETED("completed")` - - `LINUX("linux")` + - `INCOMPLETE("incomplete")` - - `UBUNTU("ubuntu")` + - `JsonValue; type "local_shell_call"constant` - - `BROWSER("browser")` + The type of the local shell call. Always `local_shell_call`. - - `JsonValue; type "computer_use_preview"constant` + - `LOCAL_SHELL_CALL("local_shell_call")` - The type of the computer use tool. Always `computer_use_preview`. + - `Optional agent` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The agent that produced this item. - - `class BetaWebSearchTool:` + - `String agentName` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `Type type` + - `LocalShellCallOutput` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `String id` - - `WEB_SEARCH("web_search")` + The unique ID of the local shell tool call generated by the model. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `String output` - - `Optional filters` + A JSON string of the output of the local shell tool call. - Filters for the search. + - `JsonValue; type "local_shell_call_output"constant` - - `Optional> allowedDomains` + The type of the local shell tool call output. Always `local_shell_call_output`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `Optional agent` - - `Optional searchContextSize` + The agent that produced this item. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `String agentName` - - `LOW("low")` + The canonical name of the agent that produced this item. - - `MEDIUM("medium")` + - `Optional status` - - `HIGH("high")` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `Optional userLocation` + - `IN_PROGRESS("in_progress")` - The approximate location of the user. + - `COMPLETED("completed")` - - `Optional city` + - `INCOMPLETE("incomplete")` - Free text input for the city of the user, e.g. `San Francisco`. + - `class BetaResponseFunctionShellToolCall:` - - `Optional country` + A tool call that executes one or more shell commands in a managed environment. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `String id` - - `Optional region` + The unique ID of the shell tool call. Populated when this item is returned via API. - Free text input for the region of the user, e.g. `California`. + - `Action action` - - `Optional timezone` + The shell commands and limits that describe how to run the tool call. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `List commands` - - `Optional type` + - `Optional maxOutputLength` - The type of location approximation. Always `approximate`. + Optional maximum number of characters to return from each command. - - `APPROXIMATE("approximate")` + - `Optional timeoutMs` - - `Mcp` + Optional timeout in milliseconds for the commands. - - `String serverLabel` + - `String callId` - A label for this MCP server, used to identify it in tool calls. + The unique ID of the shell tool call generated by the model. - - `JsonValue; type "mcp"constant` + - `Optional environment` - The type of the MCP tool. Always `mcp`. + Represents the use of a local environment to perform shell actions. - - `MCP("mcp")` + - `class BetaResponseLocalEnvironment:` - - `Optional> allowedCallers` + Represents the use of a local environment to perform shell actions. - The tool invocation context(s). + - `JsonValue; type "local"constant` + + The environment type. Always `local`. + + - `LOCAL("local")` + + - `class BetaResponseContainerReference:` + + Represents a container created with /v1/containers. + + - `String containerId` + + - `JsonValue; type "container_reference"constant` + + The environment type. Always `container_reference`. + + - `CONTAINER_REFERENCE("container_reference")` + + - `Status status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call"constant` + + The type of the item. Always `shell_call`. + + - `SHELL_CALL("shell_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` + + - `JsonValue; type "direct"constant` - `DIRECT("direct")` - - `PROGRAMMATIC("programmatic")` + - `class Program:` - - `Optional allowedTools` + - `String callerId` - List of allowed tool names or a filter object. + The call ID of the program item that produced this tool call. - - `List` + - `JsonValue; type "program"constant` - - `class McpToolFilter:` + - `PROGRAM("program")` - A filter object to specify which tools are allowed. + - `Optional createdBy` - - `Optional readOnly` + The ID of the entity that created this tool call. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class BetaResponseFunctionShellToolCallOutput:` - - `Optional> toolNames` + The output of a shell tool call that was emitted. - List of allowed tool names. + - `String id` - - `Optional authorization` + The unique ID of the shell call output. Populated when this item is returned via API. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `String callId` - - `Optional connectorId` + The unique ID of the shell tool call generated by the model. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `Optional maxOutputLength` - Currently supported `connector_id` values are: + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `List output` - - `CONNECTOR_DROPBOX("connector_dropbox")` + An array of shell call output contents - - `CONNECTOR_GMAIL("connector_gmail")` + - `Outcome outcome` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `JsonValue;` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `JsonValue; type "timeout"constant` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + The outcome type. Always `timeout`. - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `TIMEOUT("timeout")` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `class Exit:` - - `Optional deferLoading` + Indicates that the shell commands finished and returned an exit code. - Whether this MCP tool is deferred and discovered via tool search. + - `long exitCode` - - `Optional headers` + Exit code from the shell process. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `JsonValue; type "exit"constant` - - `Optional requireApproval` + The outcome type. Always `exit`. - Specify which of the MCP server's tools require approval. + - `EXIT("exit")` - - `class McpToolApprovalFilter:` + - `String stderr` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The standard error output that was captured. - - `Optional always` + - `String stdout` - A filter object to specify which tools are allowed. + The standard output that was captured. - - `Optional readOnly` + - `Optional createdBy` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The identifier of the actor that created the item. - - `Optional> toolNames` + - `Status status` - List of allowed tool names. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `Optional never` + - `IN_PROGRESS("in_progress")` - A filter object to specify which tools are allowed. + - `COMPLETED("completed")` - - `Optional readOnly` + - `INCOMPLETE("incomplete")` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `JsonValue; type "shell_call_output"constant` - - `Optional> toolNames` + The type of the shell call output. Always `shell_call_output`. - List of allowed tool names. + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `enum McpToolApprovalSetting:` + - `Optional agent` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The agent that produced this item. - - `ALWAYS("always")` + - `String agentName` - - `NEVER("never")` + The canonical name of the agent that produced this item. - - `Optional serverDescription` + - `Optional caller` - Optional description of the MCP server, used to provide more context. + The execution context that produced this tool call. - - `Optional serverUrl` + - `JsonValue;` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `JsonValue; type "direct"constant` - - `Optional tunnelId` + - `DIRECT("direct")` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `class Program:` - - `CodeInterpreter` + - `String callerId` - - `Container container` + The call ID of the program item that produced this tool call. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `JsonValue; type "program"constant` - - `String` + - `PROGRAM("program")` - - `class CodeInterpreterToolAuto:` + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseApplyPatchToolCall:` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `String id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `String callId` + + The unique ID of the apply patch tool call generated by the model. + + - `Operation operation` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `class CreateFile:` + + Instruction describing how to create a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to create. + + - `JsonValue; type "create_file"constant` + + Create a new file with the provided diff. + + - `CREATE_FILE("create_file")` + + - `class DeleteFile:` + + Instruction describing how to delete a file via the apply_patch tool. + + - `String path` + + Path of the file to delete. + + - `JsonValue; type "delete_file"constant` + + Delete the specified file. + + - `DELETE_FILE("delete_file")` + + - `class UpdateFile:` + + Instruction describing how to update a file via the apply_patch tool. + + - `String diff` + + Diff to apply. + + - `String path` + + Path of the file to update. + + - `JsonValue; type "update_file"constant` + + Update an existing file with the provided diff. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `UPDATE_FILE("update_file")` - - `JsonValue; type "auto"constant` + - `Status status` - Always `auto`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `AUTO("auto")` + - `IN_PROGRESS("in_progress")` - - `Optional> fileIds` + - `COMPLETED("completed")` - An optional list of uploaded files to make available to your code. + - `JsonValue; type "apply_patch_call"constant` - - `Optional memoryLimit` + The type of the item. Always `apply_patch_call`. - The memory limit for the code interpreter container. + - `APPLY_PATCH_CALL("apply_patch_call")` - - `_1G("1g")` + - `Optional agent` - - `_4G("4g")` + The agent that produced this item. - - `_16G("16g")` + - `String agentName` - - `_64G("64g")` + The canonical name of the agent that produced this item. - - `Optional networkPolicy` + - `Optional caller` - Network access policy for the container. + The execution context that produced this tool call. - - `class BetaContainerNetworkPolicyDisabled:` + - `JsonValue;` - - `JsonValue; type "disabled"constant` + - `JsonValue; type "direct"constant` - Disable outbound network access. Always `disabled`. + - `DIRECT("direct")` - - `DISABLED("disabled")` + - `class Program:` - - `class BetaContainerNetworkPolicyAllowlist:` + - `String callerId` - - `List allowedDomains` + The call ID of the program item that produced this tool call. - A list of allowed domains when type is `allowlist`. + - `JsonValue; type "program"constant` - - `JsonValue; type "allowlist"constant` + - `PROGRAM("program")` - Allow outbound network access only to specified domains. Always `allowlist`. + - `Optional createdBy` - - `ALLOWLIST("allowlist")` + The ID of the entity that created this tool call. - - `Optional> domainSecrets` + - `class BetaResponseApplyPatchToolCallOutput:` - Optional domain-scoped secrets for allowlisted domains. + The output emitted by an apply patch tool call. - - `String domain` + - `String id` - The domain associated with the secret. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `String name` + - `String callId` - The name of the secret to inject for the domain. + The unique ID of the apply patch tool call generated by the model. - - `String value` + - `Status status` - The secret value to inject for the domain. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `JsonValue; type "code_interpreter"constant` + - `COMPLETED("completed")` - The type of the code interpreter tool. Always `code_interpreter`. + - `FAILED("failed")` - - `CODE_INTERPRETER("code_interpreter")` + - `JsonValue; type "apply_patch_call_output"constant` - - `Optional> allowedCallers` + The type of the item. Always `apply_patch_call_output`. - The tool invocation context(s). + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `DIRECT("direct")` + - `Optional agent` - - `PROGRAMMATIC("programmatic")` + The agent that produced this item. - - `JsonValue;` + - `String agentName` - - `JsonValue; type "programmatic_tool_calling"constant` + The canonical name of the agent that produced this item. - The type of the tool. Always `programmatic_tool_calling`. + - `Optional caller` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + The execution context that produced this tool call. - - `ImageGeneration` + - `JsonValue;` - - `JsonValue; type "image_generation"constant` + - `JsonValue; type "direct"constant` - The type of the image generation tool. Always `image_generation`. + - `DIRECT("direct")` - - `IMAGE_GENERATION("image_generation")` + - `class Program:` - - `Optional action` + - `String callerId` - Whether to generate a new image or edit an existing image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `GENERATE("generate")` + - `JsonValue; type "program"constant` - - `EDIT("edit")` + - `PROGRAM("program")` - - `AUTO("auto")` + - `Optional createdBy` - - `Optional background` + The ID of the entity that created this tool call output. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `Optional output` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + Optional textual output returned by the apply patch tool. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `McpCall` - - `TRANSPARENT("transparent")` + - `String id` - - `OPAQUE("opaque")` + The unique ID of the tool call. - - `AUTO("auto")` + - `String arguments` - - `Optional inputFidelity` + A JSON string of the arguments passed to the tool. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `String name` - - `HIGH("high")` + The name of the tool that was run. - - `LOW("low")` + - `String serverLabel` - - `Optional inputImageMask` + The label of the MCP server running the tool. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `JsonValue; type "mcp_call"constant` - - `Optional fileId` + The type of the item. Always `mcp_call`. - File ID for the mask image. + - `MCP_CALL("mcp_call")` - - `Optional imageUrl` + - `Optional agent` - Base64-encoded mask image. + The agent that produced this item. - - `Optional model` + - `String agentName` - The image generation model to use. Default: `gpt-image-1`. + The canonical name of the agent that produced this item. - - `GPT_IMAGE_1("gpt-image-1")` + - `Optional approvalRequestId` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `GPT_IMAGE_2("gpt-image-2")` + - `Optional error` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The error from the tool call, if any. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `Optional output` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + The output from the tool call. - - `Optional moderation` + - `Optional status` - Moderation level for the generated image. Default: `auto`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `AUTO("auto")` + - `IN_PROGRESS("in_progress")` - - `LOW("low")` + - `COMPLETED("completed")` - - `Optional outputCompression` + - `INCOMPLETE("incomplete")` - Compression level for the output image. Default: 100. + - `CALLING("calling")` - - `Optional outputFormat` + - `FAILED("failed")` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `McpListTools` - - `PNG("png")` + - `String id` - - `WEBP("webp")` + The unique ID of the list. - - `JPEG("jpeg")` + - `String serverLabel` - - `Optional partialImages` + The label of the MCP server. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `List tools` - - `Optional quality` + The tools available on the server. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `JsonValue inputSchema` - - `LOW("low")` + The JSON schema describing the tool's input. - - `MEDIUM("medium")` + - `String name` - - `HIGH("high")` + The name of the tool. - - `AUTO("auto")` + - `Optional annotations` - - `Optional size` + Additional annotations about the tool. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `Optional description` - - `_1024X1024("1024x1024")` + The description of the tool. - - `_1024X1536("1024x1536")` + - `JsonValue; type "mcp_list_tools"constant` - - `_1536X1024("1536x1024")` + The type of the item. Always `mcp_list_tools`. - - `AUTO("auto")` + - `MCP_LIST_TOOLS("mcp_list_tools")` - - `JsonValue;` + - `Optional agent` - - `JsonValue; type "local_shell"constant` + The agent that produced this item. - The type of the local shell tool. Always `local_shell`. + - `String agentName` - - `LOCAL_SHELL("local_shell")` + The canonical name of the agent that produced this item. - - `class BetaFunctionShellTool:` + - `Optional error` - A tool that allows the model to execute shell commands. + Error message if the server could not list tools. - - `JsonValue; type "shell"constant` + - `McpApprovalRequest` - The type of the shell tool. Always `shell`. + - `String id` - - `SHELL("shell")` + The unique ID of the approval request. - - `Optional> allowedCallers` + - `String arguments` - The tool invocation context(s). + A JSON string of arguments for the tool. - - `DIRECT("direct")` + - `String name` - - `PROGRAMMATIC("programmatic")` + The name of the tool to run. - - `Optional environment` + - `String serverLabel` - - `class BetaContainerAuto:` + The label of the MCP server making the request. - - `JsonValue; type "container_auto"constant` + - `JsonValue; type "mcp_approval_request"constant` - Automatically creates a container for this request + The type of the item. Always `mcp_approval_request`. - - `CONTAINER_AUTO("container_auto")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `Optional> fileIds` + - `Optional agent` - An optional list of uploaded files to make available to your code. + The agent that produced this item. - - `Optional memoryLimit` + - `String agentName` - The memory limit for the container. + The canonical name of the agent that produced this item. - - `_1G("1g")` + - `McpApprovalResponse` - - `_4G("4g")` + - `String id` - - `_16G("16g")` + The unique ID of the approval response - - `_64G("64g")` + - `String approvalRequestId` - - `Optional networkPolicy` + The ID of the approval request being answered. - Network access policy for the container. + - `boolean approve` - - `class BetaContainerNetworkPolicyDisabled:` + Whether the request was approved. - - `class BetaContainerNetworkPolicyAllowlist:` + - `JsonValue; type "mcp_approval_response"constant` - - `Optional> skills` + The type of the item. Always `mcp_approval_response`. - An optional list of skills referenced by id or inline data. + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `class BetaSkillReference:` + - `Optional agent` - - `String skillId` + The agent that produced this item. - The ID of the referenced skill. + - `String agentName` - - `JsonValue; type "skill_reference"constant` + The canonical name of the agent that produced this item. - References a skill created with the /v1/skills endpoint. + - `Optional reason` - - `SKILL_REFERENCE("skill_reference")` + Optional reason for the decision. - - `Optional version` + - `class BetaResponseCustomToolCall:` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + A call to a custom tool created by the model. - - `class BetaInlineSkill:` + - `class BetaResponseCustomToolCallOutputItem:` - - `String description` + The output of a custom tool call from your code, being sent back to the model. - The description of the skill. + - `String id` - - `String name` + The unique ID of the custom tool call output item. - The name of the skill. + - `Status status` - - `BetaInlineSkillSource source` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Inline skill payload + - `IN_PROGRESS("in_progress")` - - `String data` + - `COMPLETED("completed")` - Base64-encoded skill zip bundle. + - `INCOMPLETE("incomplete")` - - `JsonValue; mediaType "application/zip"constant` + - `Optional createdBy` - The media type of the inline skill payload. Must be `application/zip`. + The identifier of the actor that created the item. - - `APPLICATION_ZIP("application/zip")` + - `boolean parallelToolCalls` - - `JsonValue; type "base64"constant` + Whether to allow the model to run tool calls in parallel. - The type of the inline skill source. Must be `base64`. + - `Optional temperature` - - `BASE64("base64")` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `JsonValue; type "inline"constant` + - `ToolChoice toolChoice` - Defines an inline skill for this request. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `INLINE("inline")` + - `enum BetaToolChoiceOptions:` - - `class BetaLocalEnvironment:` + Controls which (if any) tool is called by the model. - - `JsonValue; type "local"constant` + `none` means the model will not call any tool and instead generates a message. - Use a local computer environment. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `LOCAL("local")` + `required` means the model must call one or more tools. - - `Optional> skills` + - `NONE("none")` - An optional list of skills. + - `AUTO("auto")` - - `String description` + - `REQUIRED("required")` - The description of the skill. + - `class BetaToolChoiceAllowed:` - - `String name` + Constrains the tools available to the model to a pre-defined set. - The name of the skill. + - `Mode mode` - - `String path` + Constrains the tools available to the model to a pre-defined set. - The path to the directory containing the skill. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `class BetaContainerReference:` + `required` requires the model to call one or more of the allowed tools. - - `String containerId` + - `AUTO("auto")` - The ID of the referenced container. + - `REQUIRED("required")` - - `JsonValue; type "container_reference"constant` + - `List tools` - References a container created with the /v1/containers endpoint + A list of tool definitions that the model should be allowed to call. - - `CONTAINER_REFERENCE("container_reference")` + For the Responses API, the list of tool definitions might look like: - - `class BetaCustomTool:` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `JsonValue; type "allowed_tools"constant` - - `String name` + Allowed tool configuration type. Always `allowed_tools`. - The name of the custom tool, used to identify it in tool calls. + - `ALLOWED_TOOLS("allowed_tools")` - - `JsonValue; type "custom"constant` + - `class BetaToolChoiceTypes:` - The type of the custom tool. Always `custom`. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `CUSTOM("custom")` + - `Type type` - - `Optional> allowedCallers` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The tool invocation context(s). + Allowed values are: - - `DIRECT("direct")` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `PROGRAMMATIC("programmatic")` + - `FILE_SEARCH("file_search")` - - `Optional deferLoading` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - Whether this tool should be deferred and discovered via tool search. + - `COMPUTER("computer")` - - `Optional description` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - Optional description of the custom tool, used to provide more context. + - `COMPUTER_USE("computer_use")` - - `Optional format` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - The input format for the custom tool. Default is unconstrained text. + - `IMAGE_GENERATION("image_generation")` - - `JsonValue;` + - `CODE_INTERPRETER("code_interpreter")` - - `JsonValue; type "text"constant` + - `class BetaToolChoiceFunction:` - Unconstrained text format. Always `text`. + Use this option to force the model to call a specific function. - - `TEXT("text")` + - `String name` - - `class Grammar:` + The name of the function to call. - A grammar defined by the user. + - `JsonValue; type "function"constant` - - `String definition` + For function calling, the type is always `function`. - The grammar definition. + - `FUNCTION("function")` - - `Syntax syntax` + - `class BetaToolChoiceMcp:` - The syntax of the grammar definition. One of `lark` or `regex`. + Use this option to force the model to call a specific tool on a remote MCP server. - - `LARK("lark")` + - `String serverLabel` - - `REGEX("regex")` + The label of the MCP server to use. - - `JsonValue; type "grammar"constant` + - `JsonValue; type "mcp"constant` - Grammar format. Always `grammar`. + For MCP tools, the type is always `mcp`. - - `GRAMMAR("grammar")` + - `MCP("mcp")` - - `class BetaNamespaceTool:` + - `Optional name` - Groups function/custom tools under a shared namespace. + The name of the tool to call on the server. - - `String description` + - `class BetaToolChoiceCustom:` - A description of the namespace shown to the model. + Use this option to force the model to call a specific custom tool. - `String name` - The namespace name used in tool calls (for example, `crm`). + The name of the custom tool to call. - - `List tools` + - `JsonValue; type "custom"constant` - The function/custom tools available inside this namespace. + For custom tool calling, the type is always `custom`. - - `class Function:` + - `CUSTOM("custom")` - - `String name` + - `JsonValue;` - - `JsonValue; type "function"constant` + - `JsonValue; type "programmatic_tool_calling"constant` - - `FUNCTION("function")` + The tool to call. Always `programmatic_tool_calling`. - - `Optional> allowedCallers` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - The tool invocation context(s). + - `class BetaToolChoiceApplyPatch:` - - `DIRECT("direct")` + Forces the model to call the apply_patch tool when executing a tool call. - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "apply_patch"constant` - - `Optional deferLoading` + The tool to call. Always `apply_patch`. - Whether this function should be deferred and discovered via tool search. + - `APPLY_PATCH("apply_patch")` - - `Optional description` + - `class BetaToolChoiceShell:` - - `Optional outputSchema` + Forces the model to call the shell tool when a tool call is required. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `JsonValue; type "shell"constant` - - `Optional parameters` + The tool to call. Always `shell`. - - `Optional strict` + - `SHELL("shell")` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `List tools` - - `class BetaCustomTool:` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + We support the following categories of tools: - - `JsonValue; type "namespace"constant` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - The type of the tool. Always `namespace`. + - `class BetaFunctionTool:` - - `NAMESPACE("namespace")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class BetaToolSearchTool:` + - `class BetaFileSearchTool:` - Hosted or BYOT tool search configuration for deferred tools. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `JsonValue; type "tool_search"constant` + - `class BetaComputerTool:` - The type of the tool. Always `tool_search`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `TOOL_SEARCH("tool_search")` + - `class BetaComputerUsePreviewTool:` - - `Optional description` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Description shown to the model for a client-executed tool search tool. + - `class BetaWebSearchTool:` - - `Optional execution` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Whether tool search is executed by the server or by the client. + - `Mcp` - - `SERVER("server")` + - `CodeInterpreter` - - `CLIENT("client")` + - `JsonValue;` - - `Optional parameters` + - `ImageGeneration` - Parameter schema for a client-executed tool search tool. + - `JsonValue;` - - `class BetaWebSearchPreviewTool:` + - `class BetaFunctionShellTool:` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A tool that allows the model to execute shell commands. - - `Type type` + - `class BetaCustomTool:` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `class BetaNamespaceTool:` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + Groups function/custom tools under a shared namespace. - - `Optional> searchContentTypes` + - `class BetaToolSearchTool:` - - `TEXT("text")` + Hosted or BYOT tool search configuration for deferred tools. - - `IMAGE("image")` + - `class BetaWebSearchPreviewTool:` - - `Optional searchContextSize` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `class BetaApplyPatchTool:` - - `LOW("low")` + Allows the assistant to create, delete, or update files using unified diffs. - - `MEDIUM("medium")` + - `Optional topP` - - `HIGH("high")` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `Optional userLocation` + We generally recommend altering this or `temperature` but not both. - The user's location. + - `Optional background` - - `JsonValue; type "approximate"constant` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The type of location approximation. Always `approximate`. + - `Optional completedAt` - - `APPROXIMATE("approximate")` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Optional city` + - `Optional conversation` - Free text input for the city of the user, e.g. `San Francisco`. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `Optional country` + - `String id` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The unique ID of the conversation that this response was associated with. - - `Optional region` + - `Optional maxOutputTokens` - Free text input for the region of the user, e.g. `California`. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `Optional timezone` + - `Optional maxToolCalls` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `class BetaApplyPatchTool:` + - `Optional moderation` - Allows the assistant to create, delete, or update files using unified diffs. + Moderation results for the response input and output, if moderated completions were requested. - - `JsonValue; type "apply_patch"constant` + - `Input input` - The type of the tool. Always `apply_patch`. + Moderation for the response input. - - `APPLY_PATCH("apply_patch")` + - `class ModerationResult:` - - `Optional> allowedCallers` + A moderation result produced for the response input or output. - The tool invocation context(s). + - `Categories categories` - - `DIRECT("direct")` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `PROGRAMMATIC("programmatic")` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `JsonValue; type "tool_search_output"constant` + Which modalities of input are reflected by the score for each category. - The type of the item. Always `tool_search_output`. + - `TEXT("text")` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `IMAGE("image")` - - `Optional agent` + - `CategoryScores categoryScores` - The agent that produced this item. + A dictionary of moderation categories to scores. - - `String agentName` + - `boolean flagged` - The canonical name of the agent that produced this item. + A boolean indicating whether the content was flagged by any category. - - `Optional createdBy` + - `String model` - The identifier of the actor that created the item. + The moderation model that produced this result. - - `AdditionalTools` + - `JsonValue; type "moderation_result"constant` - - `String id` + The object type, which was always `moderation_result` for successful moderation results. - The unique ID of the additional tools item. + - `MODERATION_RESULT("moderation_result")` - - `Role role` + - `class Error:` - The role that provided the additional tools. + An error produced while attempting moderation for the response input or output. - - `UNKNOWN("unknown")` + - `String code` - - `USER("user")` + The error code. - - `ASSISTANT("assistant")` + - `String message` - - `SYSTEM("system")` + The error message. - - `CRITIC("critic")` + - `JsonValue; type "error"constant` - - `DISCRIMINATOR("discriminator")` + The object type, which was always `error` for moderation failures. - - `DEVELOPER("developer")` + - `ERROR("error")` - - `TOOL("tool")` + - `Output output` - - `List tools` + Moderation for the response output. - The additional tool definitions made available at this item. + - `class ModerationResult:` - - `class BetaFunctionTool:` + A moderation result produced for the response input or output. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Categories categories` - - `class BetaFileSearchTool:` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `class BetaComputerTool:` + Which modalities of input are reflected by the score for each category. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `TEXT("text")` - - `class BetaComputerUsePreviewTool:` + - `IMAGE("image")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `CategoryScores categoryScores` - - `class BetaWebSearchTool:` + A dictionary of moderation categories to scores. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `boolean flagged` - - `Mcp` + A boolean indicating whether the content was flagged by any category. - - `CodeInterpreter` + - `String model` - - `JsonValue;` + The moderation model that produced this result. - - `ImageGeneration` + - `JsonValue; type "moderation_result"constant` - - `JsonValue;` + The object type, which was always `moderation_result` for successful moderation results. - - `class BetaFunctionShellTool:` + - `MODERATION_RESULT("moderation_result")` - A tool that allows the model to execute shell commands. + - `class Error:` - - `class BetaCustomTool:` + An error produced while attempting moderation for the response input or output. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `String code` - - `class BetaNamespaceTool:` + The error code. - Groups function/custom tools under a shared namespace. + - `String message` - - `class BetaToolSearchTool:` + The error message. - Hosted or BYOT tool search configuration for deferred tools. + - `JsonValue; type "error"constant` - - `class BetaWebSearchPreviewTool:` + The object type, which was always `error` for moderation failures. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `ERROR("error")` - - `class BetaApplyPatchTool:` + - `Optional previousResponseId` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `JsonValue; type "additional_tools"constant` + - `Optional prompt` - The type of the item. Always `additional_tools`. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `ADDITIONAL_TOOLS("additional_tools")` + - `String id` - - `Optional agent` + The unique identifier of the prompt template to use. - The agent that produced this item. + - `Optional variables` - - `String agentName` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The canonical name of the agent that produced this item. + - `String` - - `class BetaResponseReasoningItem:` + - `class BetaResponseInputText:` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + A text input to the model. - - `String id` + - `class BetaResponseInputImage:` - The unique identifier of the reasoning content. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `List summary` + - `class BetaResponseInputFile:` - Reasoning summary content. + A file input to the model. - - `String text` + - `Optional version` - A summary of the reasoning output from the model so far. + Optional version of the prompt template. - - `JsonValue; type "summary_text"constant` + - `Optional promptCacheKey` - The type of the object. Always `summary_text`. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `SUMMARY_TEXT("summary_text")` + - `Optional promptCacheOptions` - - `JsonValue; type "reasoning"constant` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The type of the object. Always `reasoning`. + - `Mode mode` - - `REASONING("reasoning")` + Whether implicit prompt-cache breakpoints were enabled. - - `Optional agent` + - `IMPLICIT("implicit")` - The agent that produced this item. + - `EXPLICIT("explicit")` - - `String agentName` + - `Ttl ttl` - The canonical name of the agent that produced this item. + The minimum lifetime applied to each cache breakpoint. - - `Optional> content` + - `_30M("30m")` - Reasoning text content. + - `Optional promptCacheRetention` - - `String text` + Deprecated. Use `prompt_cache_options.ttl` instead. - The reasoning text from the model. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `JsonValue; type "reasoning_text"constant` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The type of the reasoning text. Always `reasoning_text`. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `REASONING_TEXT("reasoning_text")` + - `IN_MEMORY("in_memory")` - - `Optional encryptedContent` + - `_24H("24h")` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `Optional reasoning` - - `Optional status` + **gpt-5 and o-series models only** - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `IN_PROGRESS("in_progress")` + - `Optional context` - - `COMPLETED("completed")` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `INCOMPLETE("incomplete")` + - `AUTO("auto")` - - `Program` + - `CURRENT_TURN("current_turn")` - - `String id` + - `ALL_TURNS("all_turns")` - The unique ID of the program item. + - `Optional effort` - - `String callId` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The stable call ID of the program item. + - `NONE("none")` - - `String code` + - `MINIMAL("minimal")` - The JavaScript source executed by programmatic tool calling. + - `LOW("low")` - - `String fingerprint` + - `MEDIUM("medium")` - Opaque program replay fingerprint that must be round-tripped. + - `HIGH("high")` - - `JsonValue; type "program"constant` + - `XHIGH("xhigh")` - The type of the item. Always `program`. + - `MAX("max")` - - `PROGRAM("program")` + - `Optional generateSummary` - - `Optional agent` + **Deprecated:** use `summary` instead. - The agent that produced this item. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `String agentName` + - `AUTO("auto")` - The canonical name of the agent that produced this item. + - `CONCISE("concise")` - - `ProgramOutput` + - `DETAILED("detailed")` - - `String id` + - `Optional mode` - The unique ID of the program output item. + Controls the reasoning execution mode for the request. - - `String callId` + When returned on a response, this is the effective execution mode. - The call ID of the program item. + - `STANDARD("standard")` - - `String result` + - `PRO("pro")` - The result produced by the program item. + - `Optional summary` - - `Status status` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The terminal status of the program output item. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `COMPLETED("completed")` + - `AUTO("auto")` - - `INCOMPLETE("incomplete")` + - `CONCISE("concise")` - - `JsonValue; type "program_output"constant` + - `DETAILED("detailed")` - The type of the item. Always `program_output`. + - `Optional safetyIdentifier` - - `PROGRAM_OUTPUT("program_output")` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `Optional agent` + - `Optional serviceTier` - The agent that produced this item. + Specifies the processing type used for serving the request. - - `String agentName` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The canonical name of the agent that produced this item. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `class BetaResponseCompactionItem:` + - `AUTO("auto")` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `DEFAULT("default")` - - `String id` + - `FLEX("flex")` - The unique ID of the compaction item. + - `SCALE("scale")` - - `String encryptedContent` + - `PRIORITY("priority")` - The encrypted content that was produced by compaction. + - `Optional status` - - `JsonValue; type "compaction"constant` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The type of the item. Always `compaction`. + - `COMPLETED("completed")` - - `COMPACTION("compaction")` + - `FAILED("failed")` - - `Optional agent` + - `IN_PROGRESS("in_progress")` - The agent that produced this item. + - `CANCELLED("cancelled")` - - `String agentName` + - `QUEUED("queued")` - The canonical name of the agent that produced this item. + - `INCOMPLETE("incomplete")` - - `Optional createdBy` + - `Optional text` - The identifier of the actor that created the item. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `ImageGenerationCall` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `String id` + - `Optional format` - The unique ID of the image generation call. + An object specifying the format that the model must output. - - `Optional result` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The generated image encoded in base64. + The default format is `{ "type": "text" }` with no additional options. - - `Status status` + **Not recommended for gpt-4o and newer models:** - The status of the image generation call. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `IN_PROGRESS("in_progress")` + - `JsonValue;` - - `COMPLETED("completed")` + - `JsonValue; type "text"constant` - - `GENERATING("generating")` + The type of response format being defined. Always `text`. - - `FAILED("failed")` + - `TEXT("text")` - - `JsonValue; type "image_generation_call"constant` + - `class BetaResponseFormatTextJsonSchemaConfig:` - The type of the image generation call. Always `image_generation_call`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `String name` - - `Optional agent` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The agent that produced this item. + - `Schema schema` - - `String agentName` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The canonical name of the agent that produced this item. + - `JsonValue; type "json_schema"constant` - - `class BetaResponseCodeInterpreterToolCall:` + The type of response format being defined. Always `json_schema`. - A tool call to run code. + - `JSON_SCHEMA("json_schema")` - - `String id` + - `Optional description` - The unique ID of the code interpreter tool call. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `Optional code` + - `Optional strict` - The code to run, or null if not available. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `String containerId` + - `JsonValue;` - The ID of the container used to run the code. + - `JsonValue; type "json_object"constant` - - `Optional> outputs` + The type of response format being defined. Always `json_object`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `JSON_OBJECT("json_object")` - - `class Logs:` + - `Optional verbosity` - The logs output from the code interpreter. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `String logs` + - `LOW("low")` - The logs output from the code interpreter. + - `MEDIUM("medium")` - - `JsonValue; type "logs"constant` + - `HIGH("high")` - The type of the output. Always `logs`. + - `Optional topLogprobs` - - `LOGS("logs")` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `class Image:` + - `Optional truncation` - The image output from the code interpreter. + The truncation strategy to use for the model response. - - `JsonValue; type "image"constant` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The type of the output. Always `image`. + - `AUTO("auto")` - - `IMAGE("image")` + - `DISABLED("disabled")` - - `String url` + - `Optional usage` - The URL of the image output from the code interpreter. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `Status status` + - `long inputTokens` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The number of input tokens. - - `IN_PROGRESS("in_progress")` + - `InputTokensDetails inputTokensDetails` - - `COMPLETED("completed")` + A detailed breakdown of the input tokens. - - `INCOMPLETE("incomplete")` + - `long cacheWriteTokens` - - `INTERPRETING("interpreting")` + The number of input tokens that were written to the cache. - - `FAILED("failed")` + - `long cachedTokens` - - `JsonValue; type "code_interpreter_call"constant` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `long outputTokens` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + The number of output tokens. - - `Optional agent` + - `OutputTokensDetails outputTokensDetails` - The agent that produced this item. + A detailed breakdown of the output tokens. - - `String agentName` + - `long reasoningTokens` - The canonical name of the agent that produced this item. + The number of reasoning tokens. - - `LocalShellCall` + - `long totalTokens` - - `String id` + The total number of tokens used. - The unique ID of the local shell call. + - `Optional user` - - `Action action` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - Execute a shell command on the server. + - `long sequenceNumber` - - `List command` + The sequence number for this event. - The command to run. + - `JsonValue; type "response.queued"constant` - - `Env env` + The type of the event. Always 'response.queued'. - Environment variables to set for the command. + - `RESPONSE_QUEUED("response.queued")` - - `JsonValue; type "exec"constant` + - `Optional agent` - The type of the local shell action. Always `exec`. + The agent that owns this multi-agent streaming event. - - `EXEC("exec")` + - `String agentName` - - `Optional timeoutMs` + The canonical name of the agent that produced this item. - Optional timeout in milliseconds for the command. +### Beta Response Reasoning Item - - `Optional user` +- `class BetaResponseReasoningItem:` - Optional user to run the command as. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `Optional workingDirectory` + - `String id` - Optional working directory to run the command in. + The unique identifier of the reasoning content. - - `String callId` + - `List summary` - The unique ID of the local shell tool call generated by the model. + Reasoning summary content. - - `Status status` + - `String text` - The status of the local shell call. + A summary of the reasoning output from the model so far. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "summary_text"constant` - - `COMPLETED("completed")` + The type of the object. Always `summary_text`. - - `INCOMPLETE("incomplete")` + - `SUMMARY_TEXT("summary_text")` - - `JsonValue; type "local_shell_call"constant` + - `JsonValue; type "reasoning"constant` - The type of the local shell call. Always `local_shell_call`. + The type of the object. Always `reasoning`. - - `LOCAL_SHELL_CALL("local_shell_call")` + - `REASONING("reasoning")` - `Optional agent` @@ -97490,33 +110193,29 @@ public final class Main { The canonical name of the agent that produced this item. - - `LocalShellCallOutput` - - - `String id` - - The unique ID of the local shell tool call generated by the model. - - - `String output` + - `Optional> content` - A JSON string of the output of the local shell tool call. + Reasoning text content. - - `JsonValue; type "local_shell_call_output"constant` + - `String text` - The type of the local shell tool call output. Always `local_shell_call_output`. + The reasoning text from the model. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `JsonValue; type "reasoning_text"constant` - - `Optional agent` + The type of the reasoning text. Always `reasoning_text`. - The agent that produced this item. + - `REASONING_TEXT("reasoning_text")` - - `String agentName` + - `Optional encryptedContent` - The canonical name of the agent that produced this item. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `Optional status` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -97524,904 +110223,931 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionShellToolCall:` +### Beta Response Reasoning Summary Part Added Event - A tool call that executes one or more shell commands in a managed environment. +- `class BetaResponseReasoningSummaryPartAddedEvent:` - - `String id` + Emitted when a new reasoning summary part is added. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `String itemId` - - `Action action` + The ID of the item this summary part is associated with. - The shell commands and limits that describe how to run the tool call. + - `long outputIndex` - - `List commands` + The index of the output item this summary part is associated with. - - `Optional maxOutputLength` + - `Part part` - Optional maximum number of characters to return from each command. + The summary part that was added. - - `Optional timeoutMs` + - `String text` - Optional timeout in milliseconds for the commands. + The text of the summary part. - - `String callId` + - `JsonValue; type "summary_text"constant` - The unique ID of the shell tool call generated by the model. + The type of the summary part. Always `summary_text`. - - `Optional environment` + - `SUMMARY_TEXT("summary_text")` - Represents the use of a local environment to perform shell actions. + - `long sequenceNumber` - - `class BetaResponseLocalEnvironment:` + The sequence number of this event. - Represents the use of a local environment to perform shell actions. + - `long summaryIndex` - - `JsonValue; type "local"constant` + The index of the summary part within the reasoning summary. - The environment type. Always `local`. + - `JsonValue; type "response.reasoning_summary_part.added"constant` - - `LOCAL("local")` + The type of the event. Always `response.reasoning_summary_part.added`. - - `class BetaResponseContainerReference:` + - `RESPONSE_REASONING_SUMMARY_PART_ADDED("response.reasoning_summary_part.added")` - Represents a container created with /v1/containers. + - `Optional agent` - - `String containerId` + The agent that owns this multi-agent streaming event. - - `JsonValue; type "container_reference"constant` + - `String agentName` - The environment type. Always `container_reference`. + The canonical name of the agent that produced this item. - - `CONTAINER_REFERENCE("container_reference")` +### Beta Response Reasoning Summary Part Done Event - - `Status status` +- `class BetaResponseReasoningSummaryPartDoneEvent:` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Emitted when a reasoning summary part is completed. - - `IN_PROGRESS("in_progress")` + - `String itemId` - - `COMPLETED("completed")` + The ID of the item this summary part is associated with. - - `INCOMPLETE("incomplete")` + - `long outputIndex` - - `JsonValue; type "shell_call"constant` + The index of the output item this summary part is associated with. - The type of the item. Always `shell_call`. + - `Part part` - - `SHELL_CALL("shell_call")` + The completed summary part. - - `Optional agent` + - `String text` - The agent that produced this item. + The text of the summary part. - - `String agentName` + - `JsonValue; type "summary_text"constant` - The canonical name of the agent that produced this item. + The type of the summary part. Always `summary_text`. - - `Optional caller` + - `SUMMARY_TEXT("summary_text")` - The execution context that produced this tool call. + - `long sequenceNumber` - - `JsonValue;` + The sequence number of this event. - - `JsonValue; type "direct"constant` + - `long summaryIndex` - - `DIRECT("direct")` + The index of the summary part within the reasoning summary. - - `class Program:` + - `JsonValue; type "response.reasoning_summary_part.done"constant` - - `String callerId` + The type of the event. Always `response.reasoning_summary_part.done`. - The call ID of the program item that produced this tool call. + - `RESPONSE_REASONING_SUMMARY_PART_DONE("response.reasoning_summary_part.done")` - - `JsonValue; type "program"constant` + - `Optional agent` - - `PROGRAM("program")` + The agent that owns this multi-agent streaming event. - - `Optional createdBy` + - `String agentName` - The ID of the entity that created this tool call. + The canonical name of the agent that produced this item. - - `class BetaResponseFunctionShellToolCallOutput:` + - `Optional status` - The output of a shell tool call that was emitted. + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `String id` + - `INCOMPLETE("incomplete")` - The unique ID of the shell call output. Populated when this item is returned via API. +### Beta Response Reasoning Summary Text Delta Event - - `String callId` +- `class BetaResponseReasoningSummaryTextDeltaEvent:` - The unique ID of the shell tool call generated by the model. + Emitted when a delta is added to a reasoning summary text. - - `Optional maxOutputLength` + - `String delta` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The text delta that was added to the summary. - - `List output` + - `String itemId` - An array of shell call output contents + The ID of the item this summary text delta is associated with. - - `Outcome outcome` + - `long outputIndex` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The index of the output item this summary text delta is associated with. - - `JsonValue;` + - `long sequenceNumber` - - `JsonValue; type "timeout"constant` + The sequence number of this event. - The outcome type. Always `timeout`. + - `long summaryIndex` - - `TIMEOUT("timeout")` + The index of the summary part within the reasoning summary. - - `class Exit:` + - `JsonValue; type "response.reasoning_summary_text.delta"constant` - Indicates that the shell commands finished and returned an exit code. + The type of the event. Always `response.reasoning_summary_text.delta`. - - `long exitCode` + - `RESPONSE_REASONING_SUMMARY_TEXT_DELTA("response.reasoning_summary_text.delta")` - Exit code from the shell process. + - `Optional agent` - - `JsonValue; type "exit"constant` + The agent that owns this multi-agent streaming event. - The outcome type. Always `exit`. + - `String agentName` - - `EXIT("exit")` + The canonical name of the agent that produced this item. - - `String stderr` +### Beta Response Reasoning Summary Text Done Event - The standard error output that was captured. +- `class BetaResponseReasoningSummaryTextDoneEvent:` - - `String stdout` + Emitted when a reasoning summary text is completed. - The standard output that was captured. + - `String itemId` - - `Optional createdBy` + The ID of the item this summary text is associated with. - The identifier of the actor that created the item. + - `long outputIndex` - - `Status status` + The index of the output item this summary text is associated with. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `long sequenceNumber` - - `IN_PROGRESS("in_progress")` + The sequence number of this event. - - `COMPLETED("completed")` + - `long summaryIndex` - - `INCOMPLETE("incomplete")` + The index of the summary part within the reasoning summary. - - `JsonValue; type "shell_call_output"constant` + - `String text` - The type of the shell call output. Always `shell_call_output`. + The full text of the completed reasoning summary. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `JsonValue; type "response.reasoning_summary_text.done"constant` + + The type of the event. Always `response.reasoning_summary_text.done`. + + - `RESPONSE_REASONING_SUMMARY_TEXT_DONE("response.reasoning_summary_text.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` +### Beta Response Reasoning Text Delta Event - - `String callerId` +- `class BetaResponseReasoningTextDeltaEvent:` - The call ID of the program item that produced this tool call. + Emitted when a delta is added to a reasoning text. - - `JsonValue; type "program"constant` + - `long contentIndex` - - `PROGRAM("program")` + The index of the reasoning content part this delta is associated with. - - `Optional createdBy` + - `String delta` - The identifier of the actor that created the item. + The text delta that was added to the reasoning content. - - `class BetaResponseApplyPatchToolCall:` + - `String itemId` - A tool call that applies file diffs by creating, deleting, or updating files. + The ID of the item this reasoning text delta is associated with. - - `String id` + - `long outputIndex` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The index of the output item this reasoning text delta is associated with. - - `String callId` + - `long sequenceNumber` - The unique ID of the apply patch tool call generated by the model. + The sequence number of this event. - - `Operation operation` + - `JsonValue; type "response.reasoning_text.delta"constant` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of the event. Always `response.reasoning_text.delta`. - - `class CreateFile:` + - `RESPONSE_REASONING_TEXT_DELTA("response.reasoning_text.delta")` - Instruction describing how to create a file via the apply_patch tool. + - `Optional agent` - - `String diff` + The agent that owns this multi-agent streaming event. - Diff to apply. + - `String agentName` - - `String path` + The canonical name of the agent that produced this item. - Path of the file to create. +### Beta Response Reasoning Text Done Event - - `JsonValue; type "create_file"constant` +- `class BetaResponseReasoningTextDoneEvent:` - Create a new file with the provided diff. + Emitted when a reasoning text is completed. - - `CREATE_FILE("create_file")` + - `long contentIndex` - - `class DeleteFile:` + The index of the reasoning content part. - Instruction describing how to delete a file via the apply_patch tool. + - `String itemId` - - `String path` + The ID of the item this reasoning text is associated with. - Path of the file to delete. + - `long outputIndex` - - `JsonValue; type "delete_file"constant` + The index of the output item this reasoning text is associated with. - Delete the specified file. + - `long sequenceNumber` - - `DELETE_FILE("delete_file")` + The sequence number of this event. - - `class UpdateFile:` + - `String text` - Instruction describing how to update a file via the apply_patch tool. + The full text of the completed reasoning content. - - `String diff` + - `JsonValue; type "response.reasoning_text.done"constant` - Diff to apply. + The type of the event. Always `response.reasoning_text.done`. - - `String path` + - `RESPONSE_REASONING_TEXT_DONE("response.reasoning_text.done")` - Path of the file to update. + - `Optional agent` - - `JsonValue; type "update_file"constant` + The agent that owns this multi-agent streaming event. - Update an existing file with the provided diff. + - `String agentName` - - `UPDATE_FILE("update_file")` + The canonical name of the agent that produced this item. - - `Status status` +### Beta Response Refusal Delta Event - The status of the apply patch tool call. One of `in_progress` or `completed`. +- `class BetaResponseRefusalDeltaEvent:` - - `IN_PROGRESS("in_progress")` + Emitted when there is a partial refusal text. - - `COMPLETED("completed")` + - `long contentIndex` - - `JsonValue; type "apply_patch_call"constant` + The index of the content part that the refusal text is added to. - The type of the item. Always `apply_patch_call`. + - `String delta` - - `APPLY_PATCH_CALL("apply_patch_call")` + The refusal text that is added. - - `Optional agent` + - `String itemId` - The agent that produced this item. + The ID of the output item that the refusal text is added to. - - `String agentName` + - `long outputIndex` - The canonical name of the agent that produced this item. + The index of the output item that the refusal text is added to. - - `Optional caller` + - `long sequenceNumber` - The execution context that produced this tool call. + The sequence number of this event. - - `JsonValue;` + - `JsonValue; type "response.refusal.delta"constant` - - `JsonValue; type "direct"constant` + The type of the event. Always `response.refusal.delta`. - - `DIRECT("direct")` + - `RESPONSE_REFUSAL_DELTA("response.refusal.delta")` - - `class Program:` + - `Optional agent` - - `String callerId` + The agent that owns this multi-agent streaming event. - The call ID of the program item that produced this tool call. + - `String agentName` - - `JsonValue; type "program"constant` + The canonical name of the agent that produced this item. - - `PROGRAM("program")` +### Beta Response Refusal Done Event - - `Optional createdBy` +- `class BetaResponseRefusalDoneEvent:` - The ID of the entity that created this tool call. + Emitted when refusal text is finalized. - - `class BetaResponseApplyPatchToolCallOutput:` + - `long contentIndex` - The output emitted by an apply patch tool call. + The index of the content part that the refusal text is finalized. - - `String id` + - `String itemId` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The ID of the output item that the refusal text is finalized. - - `String callId` + - `long outputIndex` - The unique ID of the apply patch tool call generated by the model. + The index of the output item that the refusal text is finalized. - - `Status status` + - `String refusal` - The status of the apply patch tool call output. One of `completed` or `failed`. + The refusal text that is finalized. - - `COMPLETED("completed")` + - `long sequenceNumber` - - `FAILED("failed")` + The sequence number of this event. - - `JsonValue; type "apply_patch_call_output"constant` + - `JsonValue; type "response.refusal.done"constant` - The type of the item. Always `apply_patch_call_output`. + The type of the event. Always `response.refusal.done`. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `RESPONSE_REFUSAL_DONE("response.refusal.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` +### Beta Response Status - The execution context that produced this tool call. +- `enum BetaResponseStatus:` - - `JsonValue;` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `JsonValue; type "direct"constant` + - `COMPLETED("completed")` - - `DIRECT("direct")` + - `FAILED("failed")` - - `class Program:` + - `IN_PROGRESS("in_progress")` - - `String callerId` + - `CANCELLED("cancelled")` - The call ID of the program item that produced this tool call. + - `QUEUED("queued")` - - `JsonValue; type "program"constant` + - `INCOMPLETE("incomplete")` - - `PROGRAM("program")` +### Beta Response Stream Event - - `Optional createdBy` +- `class BetaResponseStreamEvent: A class that can be one of several variants.union` - The ID of the entity that created this tool call output. + Emitted when there is a partial audio response. - - `Optional output` + - `class BetaResponseAudioDeltaEvent:` - Optional textual output returned by the apply patch tool. + Emitted when there is a partial audio response. - - `McpListTools` + - `String delta` - - `String id` + A chunk of Base64 encoded response audio bytes. - The unique ID of the list. + - `long sequenceNumber` - - `String serverLabel` + A sequence number for this chunk of the stream response. - The label of the MCP server. + - `JsonValue; type "response.audio.delta"constant` - - `List tools` + The type of the event. Always `response.audio.delta`. - The tools available on the server. + - `RESPONSE_AUDIO_DELTA("response.audio.delta")` - - `JsonValue inputSchema` + - `Optional agent` - The JSON schema describing the tool's input. + The agent that owns this multi-agent streaming event. - - `String name` + - `String agentName` - The name of the tool. + The canonical name of the agent that produced this item. - - `Optional annotations` + - `class BetaResponseAudioDoneEvent:` - Additional annotations about the tool. + Emitted when the audio response is complete. - - `Optional description` + - `long sequenceNumber` - The description of the tool. + The sequence number of the delta. - - `JsonValue; type "mcp_list_tools"constant` + - `JsonValue; type "response.audio.done"constant` - The type of the item. Always `mcp_list_tools`. + The type of the event. Always `response.audio.done`. - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `RESPONSE_AUDIO_DONE("response.audio.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional error` + - `class BetaResponseAudioTranscriptDeltaEvent:` - Error message if the server could not list tools. + Emitted when there is a partial transcript of audio. - - `McpApprovalRequest` + - `String delta` - - `String id` + The partial transcript of the audio response. - The unique ID of the approval request. + - `long sequenceNumber` - - `String arguments` + The sequence number of this event. - A JSON string of arguments for the tool. + - `JsonValue; type "response.audio.transcript.delta"constant` - - `String name` + The type of the event. Always `response.audio.transcript.delta`. - The name of the tool to run. + - `RESPONSE_AUDIO_TRANSCRIPT_DELTA("response.audio.transcript.delta")` - - `String serverLabel` + - `Optional agent` - The label of the MCP server making the request. + The agent that owns this multi-agent streaming event. - - `JsonValue; type "mcp_approval_request"constant` + - `String agentName` - The type of the item. Always `mcp_approval_request`. + The canonical name of the agent that produced this item. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `class BetaResponseAudioTranscriptDoneEvent:` + + Emitted when the full audio transcript is completed. + + - `long sequenceNumber` + + The sequence number of this event. + + - `JsonValue; type "response.audio.transcript.done"constant` + + The type of the event. Always `response.audio.transcript.done`. + + - `RESPONSE_AUDIO_TRANSCRIPT_DONE("response.audio.transcript.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `McpApprovalResponse` + - `class BetaResponseCodeInterpreterCallCodeDeltaEvent:` - - `String id` + Emitted when a partial code snippet is streamed by the code interpreter. - The unique ID of the approval response + - `String delta` - - `String approvalRequestId` + The partial code snippet being streamed by the code interpreter. - The ID of the approval request being answered. + - `String itemId` - - `boolean approve` + The unique identifier of the code interpreter tool call item. - Whether the request was approved. + - `long outputIndex` - - `JsonValue; type "mcp_approval_response"constant` + The index of the output item in the response for which the code is being streamed. - The type of the item. Always `mcp_approval_response`. + - `long sequenceNumber` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + The sequence number of this event, used to order streaming events. + + - `JsonValue; type "response.code_interpreter_call_code.delta"constant` + + The type of the event. Always `response.code_interpreter_call_code.delta`. + + - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DELTA("response.code_interpreter_call_code.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional reason` - - Optional reason for the decision. + - `class BetaResponseCodeInterpreterCallCodeDoneEvent:` - - `McpCall` + Emitted when the code snippet is finalized by the code interpreter. - - `String id` + - `String code` - The unique ID of the tool call. + The final code snippet output by the code interpreter. - - `String arguments` + - `String itemId` - A JSON string of the arguments passed to the tool. + The unique identifier of the code interpreter tool call item. - - `String name` + - `long outputIndex` - The name of the tool that was run. + The index of the output item in the response for which the code is finalized. - - `String serverLabel` + - `long sequenceNumber` - The label of the MCP server running the tool. + The sequence number of this event, used to order streaming events. - - `JsonValue; type "mcp_call"constant` + - `JsonValue; type "response.code_interpreter_call_code.done"constant` - The type of the item. Always `mcp_call`. + The type of the event. Always `response.code_interpreter_call_code.done`. - - `MCP_CALL("mcp_call")` + - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DONE("response.code_interpreter_call_code.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional approvalRequestId` + - `class BetaResponseCodeInterpreterCallCompletedEvent:` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + Emitted when the code interpreter call is completed. - - `Optional error` + - `String itemId` - The error from the tool call, if any. + The unique identifier of the code interpreter tool call item. - - `Optional output` + - `long outputIndex` - The output from the tool call. + The index of the output item in the response for which the code interpreter call is completed. - - `Optional status` + - `long sequenceNumber` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The sequence number of this event, used to order streaming events. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "response.code_interpreter_call.completed"constant` - - `COMPLETED("completed")` + The type of the event. Always `response.code_interpreter_call.completed`. - - `INCOMPLETE("incomplete")` + - `RESPONSE_CODE_INTERPRETER_CALL_COMPLETED("response.code_interpreter_call.completed")` - - `CALLING("calling")` + - `Optional agent` - - `FAILED("failed")` + The agent that owns this multi-agent streaming event. - - `class BetaResponseCustomToolCallItem:` + - `String agentName` - A call to a custom tool created by the model. + The canonical name of the agent that produced this item. - - `String id` + - `class BetaResponseCodeInterpreterCallInProgressEvent:` - The unique ID of the custom tool call item. + Emitted when a code interpreter call is in progress. - - `Status status` + - `String itemId` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique identifier of the code interpreter tool call item. - - `IN_PROGRESS("in_progress")` + - `long outputIndex` - - `COMPLETED("completed")` + The index of the output item in the response for which the code interpreter call is in progress. - - `INCOMPLETE("incomplete")` + - `long sequenceNumber` - - `Optional createdBy` + The sequence number of this event, used to order streaming events. - The identifier of the actor that created the item. + - `JsonValue; type "response.code_interpreter_call.in_progress"constant` - - `class BetaResponseCustomToolCallOutputItem:` + The type of the event. Always `response.code_interpreter_call.in_progress`. - The output of a custom tool call from your code, being sent back to the model. + - `RESPONSE_CODE_INTERPRETER_CALL_IN_PROGRESS("response.code_interpreter_call.in_progress")` - - `String id` + - `Optional agent` - The unique ID of the custom tool call output item. + The agent that owns this multi-agent streaming event. - - `Status status` + - `String agentName` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The canonical name of the agent that produced this item. - - `IN_PROGRESS("in_progress")` + - `class BetaResponseCodeInterpreterCallInterpretingEvent:` - - `COMPLETED("completed")` + Emitted when the code interpreter is actively interpreting the code snippet. - - `INCOMPLETE("incomplete")` + - `String itemId` - - `Optional createdBy` + The unique identifier of the code interpreter tool call item. - The identifier of the actor that created the item. + - `long outputIndex` -### Beta Response Local Environment + The index of the output item in the response for which the code interpreter is interpreting code. -- `class BetaResponseLocalEnvironment:` + - `long sequenceNumber` - Represents the use of a local environment to perform shell actions. + The sequence number of this event, used to order streaming events. - - `JsonValue; type "local"constant` + - `JsonValue; type "response.code_interpreter_call.interpreting"constant` - The environment type. Always `local`. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `LOCAL("local")` + - `RESPONSE_CODE_INTERPRETER_CALL_INTERPRETING("response.code_interpreter_call.interpreting")` -### Beta Response Mcp Call Arguments Delta Event + - `Optional agent` -- `class BetaResponseMcpCallArgumentsDeltaEvent:` + The agent that owns this multi-agent streaming event. - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `String agentName` - - `String delta` + The canonical name of the agent that produced this item. - A JSON string containing the partial update to the arguments for the MCP tool call. + - `class BetaResponseCompletedEvent:` - - `String itemId` + Emitted when the model response is complete. - The unique identifier of the MCP tool call item being processed. + - `BetaResponse response` - - `long outputIndex` + Properties of the completed response. - The index of the output item in the response's output array. + - `String id` - - `long sequenceNumber` + Unique identifier for this Response. - The sequence number of this event. + - `double createdAt` - - `JsonValue; type "response.mcp_call_arguments.delta"constant` + Unix timestamp (in seconds) of when this Response was created. - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `Optional error` - - `RESPONSE_MCP_CALL_ARGUMENTS_DELTA("response.mcp_call_arguments.delta")` + An error object returned when the model fails to generate a Response. - - `Optional agent` + - `Code code` - The agent that owns this multi-agent streaming event. + The error code for the response. - - `String agentName` + - `SERVER_ERROR("server_error")` - The canonical name of the agent that produced this item. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` -### Beta Response Mcp Call Arguments Done Event + - `INVALID_PROMPT("invalid_prompt")` -- `class BetaResponseMcpCallArgumentsDoneEvent:` + - `BIO_POLICY("bio_policy")` - Emitted when the arguments for an MCP tool call are finalized. + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - - `String arguments` + - `INVALID_IMAGE("invalid_image")` - A JSON string containing the finalized arguments for the MCP tool call. + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - - `String itemId` + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - The unique identifier of the MCP tool call item being processed. + - `INVALID_IMAGE_URL("invalid_image_url")` - - `long outputIndex` + - `IMAGE_TOO_LARGE("image_too_large")` - The index of the output item in the response's output array. + - `IMAGE_TOO_SMALL("image_too_small")` - - `long sequenceNumber` + - `IMAGE_PARSE_ERROR("image_parse_error")` - The sequence number of this event. + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - - `JsonValue; type "response.mcp_call_arguments.done"constant` + - `INVALID_IMAGE_MODE("invalid_image_mode")` - The type of the event. Always 'response.mcp_call_arguments.done'. + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `RESPONSE_MCP_CALL_ARGUMENTS_DONE("response.mcp_call_arguments.done")` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - - `Optional agent` + - `EMPTY_IMAGE_FILE("empty_image_file")` - The agent that owns this multi-agent streaming event. + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - - `String agentName` + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - The canonical name of the agent that produced this item. + - `String message` -### Beta Response Mcp Call Completed Event + A human-readable description of the error. -- `class BetaResponseMcpCallCompletedEvent:` + - `Optional incompleteDetails` - Emitted when an MCP tool call has completed successfully. + Details about why the response is incomplete. - - `String itemId` + - `Optional reason` - The ID of the MCP tool call item that completed. + The reason why the response is incomplete. - - `long outputIndex` + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - The index of the output item that completed. + - `CONTENT_FILTER("content_filter")` - - `long sequenceNumber` + - `Optional instructions` - The sequence number of this event. + A system (or developer) message inserted into the model's context. - - `JsonValue; type "response.mcp_call.completed"constant` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - The type of the event. Always 'response.mcp_call.completed'. + - `String` - - `RESPONSE_MCP_CALL_COMPLETED("response.mcp_call.completed")` + - `List` - - `Optional agent` + - `class BetaEasyInputMessage:` - The agent that owns this multi-agent streaming event. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `String agentName` + - `Content content` - The canonical name of the agent that produced this item. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. -### Beta Response Mcp Call Failed Event + - `String` -- `class BetaResponseMcpCallFailedEvent:` + - `List` - Emitted when an MCP tool call has failed. + - `class BetaResponseInputText:` - - `String itemId` + A text input to the model. - The ID of the MCP tool call item that failed. + - `String text` - - `long outputIndex` + The text input to the model. - The index of the output item that failed. + - `JsonValue; type "input_text"constant` - - `long sequenceNumber` + The type of the input item. Always `input_text`. - The sequence number of this event. + - `INPUT_TEXT("input_text")` - - `JsonValue; type "response.mcp_call.failed"constant` + - `Optional promptCacheBreakpoint` - The type of the event. Always 'response.mcp_call.failed'. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `RESPONSE_MCP_CALL_FAILED("response.mcp_call.failed")` + - `JsonValue; mode "explicit"constant` - - `Optional agent` + The breakpoint mode. Always `explicit`. - The agent that owns this multi-agent streaming event. + - `EXPLICIT("explicit")` - - `String agentName` + - `class BetaResponseInputImage:` - The canonical name of the agent that produced this item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -### Beta Response Mcp Call In Progress Event + - `Detail detail` -- `class BetaResponseMcpCallInProgressEvent:` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Emitted when an MCP tool call is in progress. + - `LOW("low")` - - `String itemId` + - `HIGH("high")` - The unique identifier of the MCP tool call item being processed. + - `AUTO("auto")` - - `long outputIndex` + - `ORIGINAL("original")` - The index of the output item in the response's output array. + - `JsonValue; type "input_image"constant` - - `long sequenceNumber` + The type of the input item. Always `input_image`. - The sequence number of this event. + - `INPUT_IMAGE("input_image")` - - `JsonValue; type "response.mcp_call.in_progress"constant` + - `Optional fileId` - The type of the event. Always 'response.mcp_call.in_progress'. + The ID of the file to be sent to the model. - - `RESPONSE_MCP_CALL_IN_PROGRESS("response.mcp_call.in_progress")` + - `Optional imageUrl` - - `Optional agent` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The agent that owns this multi-agent streaming event. + - `Optional promptCacheBreakpoint` - - `String agentName` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The canonical name of the agent that produced this item. + - `JsonValue; mode "explicit"constant` -### Beta Response Mcp List Tools Completed Event + The breakpoint mode. Always `explicit`. -- `class BetaResponseMcpListToolsCompletedEvent:` + - `EXPLICIT("explicit")` - Emitted when the list of available MCP tools has been successfully retrieved. + - `class BetaResponseInputFile:` - - `String itemId` + A file input to the model. - The ID of the MCP tool call item that produced this output. + - `JsonValue; type "input_file"constant` - - `long outputIndex` + The type of the input item. Always `input_file`. - The index of the output item that was processed. + - `INPUT_FILE("input_file")` - - `long sequenceNumber` + - `Optional detail` - The sequence number of this event. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `JsonValue; type "response.mcp_list_tools.completed"constant` + - `AUTO("auto")` - The type of the event. Always 'response.mcp_list_tools.completed'. + - `LOW("low")` - - `RESPONSE_MCP_LIST_TOOLS_COMPLETED("response.mcp_list_tools.completed")` + - `HIGH("high")` - - `Optional agent` + - `Optional fileData` - The agent that owns this multi-agent streaming event. + The content of the file to be sent to the model. - - `String agentName` + - `Optional fileId` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. -### Beta Response Mcp List Tools Failed Event + - `Optional fileUrl` -- `class BetaResponseMcpListToolsFailedEvent:` + The URL of the file to be sent to the model. - Emitted when the attempt to list available MCP tools has failed. + - `Optional filename` - - `String itemId` + The name of the file to be sent to the model. - The ID of the MCP tool call item that failed. + - `Optional promptCacheBreakpoint` - - `long outputIndex` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The index of the output item that failed. + - `JsonValue; mode "explicit"constant` - - `long sequenceNumber` + The breakpoint mode. Always `explicit`. - The sequence number of this event. + - `EXPLICIT("explicit")` - - `JsonValue; type "response.mcp_list_tools.failed"constant` + - `Role role` - The type of the event. Always 'response.mcp_list_tools.failed'. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `RESPONSE_MCP_LIST_TOOLS_FAILED("response.mcp_list_tools.failed")` + - `USER("user")` - - `Optional agent` + - `ASSISTANT("assistant")` - The agent that owns this multi-agent streaming event. + - `SYSTEM("system")` - - `String agentName` + - `DEVELOPER("developer")` - The canonical name of the agent that produced this item. + - `Optional phase` -### Beta Response Mcp List Tools In Progress Event + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. -- `class BetaResponseMcpListToolsInProgressEvent:` + - `COMMENTARY("commentary")` - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `FINAL_ANSWER("final_answer")` - - `String itemId` + - `Optional type` - The ID of the MCP tool call item that is being processed. + The type of the message input. Always `message`. - - `long outputIndex` + - `MESSAGE("message")` - The index of the output item that is being processed. + - `Message` - - `long sequenceNumber` + - `List content` - The sequence number of this event. + A list of one or many input items to the model, containing different content + types. - - `JsonValue; type "response.mcp_list_tools.in_progress"constant` + - `class BetaResponseInputText:` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + A text input to the model. - - `RESPONSE_MCP_LIST_TOOLS_IN_PROGRESS("response.mcp_list_tools.in_progress")` + - `class BetaResponseInputImage:` - - `Optional agent` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The agent that owns this multi-agent streaming event. + - `class BetaResponseInputFile:` - - `String agentName` + A file input to the model. - The canonical name of the agent that produced this item. + - `Role role` -### Beta Response Output Audio + The role of the message input. One of `user`, `system`, or `developer`. -- `class BetaResponseOutputAudio:` + - `USER("user")` - An audio output from the model. + - `SYSTEM("system")` - - `String data` + - `DEVELOPER("developer")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` - Base64-encoded audio data from the model. + The canonical name of the agent that produced this item. - - `String transcript` + - `Optional status` - The transcript of the audio data from the model. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue; type "output_audio"constant` + - `IN_PROGRESS("in_progress")` - The type of the output audio. Always `output_audio`. + - `COMPLETED("completed")` - - `OUTPUT_AUDIO("output_audio")` + - `INCOMPLETE("incomplete")` -### Beta Response Output Item + - `Optional type` -- `class BetaResponseOutputItem: A class that can be one of several variants.union` + The type of the message input. Always set to `message`. - An output message from the model. + - `MESSAGE("message")` - `class BetaResponseOutputMessage:` @@ -98618,6 +111344,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -98694,66 +111422,36 @@ public final class Main { The text that was retrieved from the file. - - `class BetaResponseFunctionToolCall:` + - `class BetaResponseComputerToolCall:` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `String arguments` + - `String id` - A JSON string of the arguments to pass to the function. + The unique ID of the computer call. - `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 id` - - The unique ID of the function tool call. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` + An identifier used when responding to the tool call with output. - - `DIRECT("direct")` + - `List pendingSafetyChecks` - - `class Program:` + The pending safety checks for the computer call. - - `String callerId` + - `String id` - The call ID of the program item that produced this tool call. + The ID of the pending safety check. - - `JsonValue; type "program"constant` + - `Optional code` - - `PROGRAM("program")` + The type of the pending safety check. - - `Optional namespace` + - `Optional message` - The namespace of the function to run. + Details about the pending safety check. - - `Optional status` + - `Status status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -98764,271 +111462,236 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionToolCallOutputItem:` - - - `String id` - - The unique ID of the function call tool output. - - - `String callId` - - The unique ID of the function tool call generated by the model. - - - `Output output` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `String` - - - `List` - - - `class BetaResponseInputText:` - - 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Type type` - - `JsonValue; mode "explicit"constant` + The type of the computer call. Always `computer_call`. - The breakpoint mode. Always `explicit`. + - `COMPUTER_CALL("computer_call")` - - `EXPLICIT("explicit")` + - `Optional action` - - `class BetaResponseInputImage:` + A click action. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Click` - - `Detail detail` + - `Button button` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `LOW("low")` + - `LEFT("left")` - - `HIGH("high")` + - `RIGHT("right")` - - `AUTO("auto")` + - `WHEEL("wheel")` - - `ORIGINAL("original")` + - `BACK("back")` - - `JsonValue; type "input_image"constant` + - `FORWARD("forward")` - The type of the input item. Always `input_image`. + - `JsonValue; type "click"constant` - - `INPUT_IMAGE("input_image")` + Specifies the event type. For a click action, this property is always `click`. - - `Optional fileId` + - `CLICK("click")` - The ID of the file to be sent to the model. + - `long x` - - `Optional imageUrl` + The x-coordinate where the click occurred. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `long y` - - `Optional promptCacheBreakpoint` + The y-coordinate where the click occurred. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional> keys` - - `JsonValue; mode "explicit"constant` + The keys being held while clicking. - The breakpoint mode. Always `explicit`. + - `DoubleClick` - - `EXPLICIT("explicit")` + - `Optional> keys` - - `class BetaResponseInputFile:` + The keys being held while double-clicking. - A file input to the model. + - `JsonValue; type "double_click"constant` - - `JsonValue; type "input_file"constant` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The type of the input item. Always `input_file`. + - `DOUBLE_CLICK("double_click")` - - `INPUT_FILE("input_file")` + - `long x` - - `Optional detail` + The x-coordinate where the double click occurred. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `long y` - - `AUTO("auto")` + The y-coordinate where the double click occurred. - - `LOW("low")` + - `Drag` - - `HIGH("high")` + - `List path` - - `Optional fileData` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The content of the file to be sent to the model. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `Optional fileId` + - `long x` - The ID of the file to be sent to the model. + The x-coordinate. - - `Optional fileUrl` + - `long y` - The URL of the file to be sent to the model. + The y-coordinate. - - `Optional filename` + - `JsonValue; type "drag"constant` - The name of the file to be sent to the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `Optional promptCacheBreakpoint` + - `DRAG("drag")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional> keys` - - `JsonValue; mode "explicit"constant` + The keys being held while dragging the mouse. - The breakpoint mode. Always `explicit`. + - `Keypress` - - `EXPLICIT("explicit")` + - `List keys` - - `Status status` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `JsonValue; type "keypress"constant` - - `IN_PROGRESS("in_progress")` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `COMPLETED("completed")` + - `KEYPRESS("keypress")` - - `INCOMPLETE("incomplete")` + - `Move` - - `JsonValue; type "function_call_output"constant` + - `JsonValue; type "move"constant` - The type of the function tool call output. Always `function_call_output`. + Specifies the event type. For a move action, this property is always set to `move`. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `MOVE("move")` - - `Optional agent` + - `long x` - The agent that produced this item. + The x-coordinate to move to. - - `String agentName` + - `long y` - The canonical name of the agent that produced this item. + The y-coordinate to move to. - - `Optional caller` + - `Optional> keys` - The execution context that produced this tool call. + The keys being held while moving the mouse. - `JsonValue;` - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` + - `JsonValue; type "screenshot"constant` - - `String callerId` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The call ID of the program item that produced this tool call. + - `SCREENSHOT("screenshot")` - - `JsonValue; type "program"constant` + - `Scroll` - The caller type. Always `program`. + - `long scrollX` - - `PROGRAM("program")` + The horizontal scroll distance. - - `Optional createdBy` + - `long scrollY` - The identifier of the actor that created the item. + The vertical scroll distance. - - `AgentMessage` + - `JsonValue; type "scroll"constant` - - `String id` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The unique ID of the agent message. + - `SCROLL("scroll")` - - `String author` + - `long x` - The sending agent identity. + The x-coordinate where the scroll occurred. - - `List content` + - `long y` - Encrypted content sent between agents. + The y-coordinate where the scroll occurred. - - `class BetaResponseInputText:` + - `Optional> keys` - A text input to the model. + The keys being held while scrolling. - - `class BetaResponseOutputText:` + - `Type` - A text output from the model. + - `String text` - - `class Text:` + The text to type. - A text content. + - `JsonValue; type "type"constant` - - `String text` + Specifies the event type. For a type action, this property is always set to `type`. - - `JsonValue; type "text"constant` + - `TYPE("type")` - - `TEXT("text")` + - `JsonValue;` - - `class SummaryText:` + - `JsonValue; type "wait"constant` - A summary text from the model. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `String text` + - `WAIT("wait")` - A summary of the reasoning output from the model so far. + - `Optional> actions` - - `JsonValue; type "summary_text"constant` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the object. Always `summary_text`. + - `Click` - - `SUMMARY_TEXT("summary_text")` + - `DoubleClick` - - `class ReasoningText:` + - `Drag` - Reasoning text from the model. + - `Keypress` - - `String text` + - `Move` - The reasoning text from the model. + - `JsonValue;` - - `JsonValue; type "reasoning_text"constant` + - `Scroll` - The type of the reasoning text. Always `reasoning_text`. + - `Type` - - `REASONING_TEXT("reasoning_text")` + - `JsonValue;` - - `class BetaResponseOutputRefusal:` + - `Optional agent` - A refusal from the model. + The agent that produced this item. - - `class BetaResponseInputImage:` + - `String agentName` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `class ComputerScreenshot:` + - `ComputerCallOutput` - A screenshot of a computer. + - `String callId` - - `Detail detail` + The ID of the computer tool call that produced the output. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `BetaResponseComputerToolCallOutputScreenshot output` - - `LOW("low")` + A computer screenshot image used with the computer use tool. - - `HIGH("high")` + - `JsonValue; type "computer_screenshot"constant` - - `AUTO("auto")` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `ORIGINAL("original")` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - `Optional fileId` @@ -99038,93 +111701,31 @@ public final class Main { 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `class EncryptedContent:` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `String encryptedContent` - - Opaque encrypted content. - - - `JsonValue; type "encrypted_content"constant` - - The type of the input item. Always `encrypted_content`. - - - `ENCRYPTED_CONTENT("encrypted_content")` - - - `String recipient` - - The destination agent identity. - - - `JsonValue; type "agent_message"constant` - - The type of the item. Always `agent_message`. + - `JsonValue; type "computer_call_output"constant` - - `AGENT_MESSAGE("agent_message")` + The type of the computer tool call output. Always `computer_call_output`. - - `Optional agent` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - The agent that produced this item. + - `Optional id` - - `String agentName` + The ID of the computer tool call output. - The canonical name of the agent that produced this item. + - `Optional> acknowledgedSafetyChecks` - - `MultiAgentCall` + The safety checks reported by the API that have been acknowledged by the developer. - `String id` - The unique ID of the multi-agent call item. - - - `Action action` - - The multi-agent action to execute. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` - - - `SEND_MESSAGE("send_message")` - - - `FOLLOWUP_TASK("followup_task")` - - - `WAIT_AGENT("wait_agent")` - - - `String arguments` - - The JSON string of arguments generated for the action. - - - `String callId` + The ID of the pending safety check. - The unique ID linking this call to its output. + - `Optional code` - - `JsonValue; type "multi_agent_call"constant` + The type of the pending safety check. - The type of the multi-agent call. Always `multi_agent_call`. + - `Optional message` - - `MULTI_AGENT_CALL("multi_agent_call")` + Details about the pending safety check. - `Optional agent` @@ -99134,63 +111735,15 @@ public final class Main { The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `String id` - - The unique ID of the multi-agent call output item. - - - `Action action` - - The multi-agent action that produced this result. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` - - - `SEND_MESSAGE("send_message")` - - - `FOLLOWUP_TASK("followup_task")` - - - `WAIT_AGENT("wait_agent")` - - - `String callId` - - The unique ID of the multi-agent call. - - - `List output` - - Text output returned by the multi-agent action. - - - `List annotations` - - The annotations of the text output. - - - `String text` - - The text output from the model. - - - `JsonValue; type "output_text"constant` - - The type of the output text. Always `output_text`. - - - `Optional> logprobs` - - - `JsonValue; type "multi_agent_call_output"constant` - - The type of the multi-agent result. Always `multi_agent_call_output`. - - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `Optional status` - - `Optional agent` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The agent that produced this item. + - `IN_PROGRESS("in_progress")` - - `String agentName` + - `COMPLETED("completed")` - The canonical name of the agent that produced this item. + - `INCOMPLETE("incomplete")` - `class BetaResponseFunctionWebSearch:` @@ -99296,324 +111849,297 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall:` + - `class BetaResponseFunctionToolCall:` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `String id` + - `String arguments` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `String callId` - An identifier used when responding to the tool call with output. - - - `List pendingSafetyChecks` - - The pending safety checks for the computer call. - - - `String id` - - The ID of the pending safety check. - - - `Optional code` - - The type of the pending safety check. - - - `Optional message` - - Details about the pending safety check. + The unique ID of the function tool call generated by the model. - - `Status status` + - `String name` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the function to run. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "function_call"constant` - - `COMPLETED("completed")` + The type of the function tool call. Always `function_call`. - - `INCOMPLETE("incomplete")` + - `FUNCTION_CALL("function_call")` - - `Type type` + - `Optional id` - The type of the computer call. Always `computer_call`. + The unique ID of the function tool call. - - `COMPUTER_CALL("computer_call")` + - `Optional agent` - - `Optional action` + The agent that produced this item. - A click action. + - `String agentName` - - `Click` + The canonical name of the agent that produced this item. - - `Button button` + - `Optional caller` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The execution context that produced this tool call. - - `LEFT("left")` + - `JsonValue;` - - `RIGHT("right")` + - `JsonValue; type "direct"constant` - - `WHEEL("wheel")` + - `DIRECT("direct")` - - `BACK("back")` + - `class Program:` - - `FORWARD("forward")` + - `String callerId` - - `JsonValue; type "click"constant` + The call ID of the program item that produced this tool call. - Specifies the event type. For a click action, this property is always `click`. + - `JsonValue; type "program"constant` - - `CLICK("click")` + - `PROGRAM("program")` - - `long x` + - `Optional namespace` - The x-coordinate where the click occurred. + The namespace of the function to run. - - `long y` + - `Optional status` - The y-coordinate where the click occurred. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional> keys` + - `IN_PROGRESS("in_progress")` - The keys being held while clicking. + - `COMPLETED("completed")` - - `DoubleClick` + - `INCOMPLETE("incomplete")` - - `Optional> keys` + - `FunctionCallOutput` - The keys being held while double-clicking. + - `String callId` - - `JsonValue; type "double_click"constant` + The unique ID of the function tool call generated by the model. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `Output output` - - `DOUBLE_CLICK("double_click")` + Text, image, or file output of the function tool call. - - `long x` + - `String` - The x-coordinate where the double click occurred. + - `List` - - `long y` + - `class BetaResponseInputTextContent:` - The y-coordinate where the double click occurred. + A text input to the model. - - `Drag` + - `String text` - - `List path` + The text input to the model. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `JsonValue; type "input_text"constant` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The type of the input item. Always `input_text`. - - `long x` + - `INPUT_TEXT("input_text")` - The x-coordinate. + - `Optional promptCacheBreakpoint` - - `long y` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The y-coordinate. + - `JsonValue; mode "explicit"constant` - - `JsonValue; type "drag"constant` + The breakpoint mode. Always `explicit`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `EXPLICIT("explicit")` - - `DRAG("drag")` + - `class BetaResponseInputImageContent:` - - `Optional> keys` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The keys being held while dragging the mouse. + - `JsonValue; type "input_image"constant` - - `Keypress` + The type of the input item. Always `input_image`. - - `List keys` + - `INPUT_IMAGE("input_image")` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `Optional detail` - - `JsonValue; type "keypress"constant` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `LOW("low")` - - `KEYPRESS("keypress")` + - `HIGH("high")` - - `Move` + - `AUTO("auto")` - - `JsonValue; type "move"constant` + - `ORIGINAL("original")` - Specifies the event type. For a move action, this property is always set to `move`. + - `Optional fileId` - - `MOVE("move")` + The ID of the file to be sent to the model. - - `long x` + - `Optional imageUrl` - The x-coordinate to move to. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `long y` + - `Optional promptCacheBreakpoint` - The y-coordinate to move to. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional> keys` + - `JsonValue; mode "explicit"constant` - The keys being held while moving the mouse. + The breakpoint mode. Always `explicit`. - - `JsonValue;` + - `EXPLICIT("explicit")` - - `JsonValue; type "screenshot"constant` + - `class BetaResponseInputFileContent:` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + A file input to the model. - - `SCREENSHOT("screenshot")` + - `JsonValue; type "input_file"constant` - - `Scroll` + The type of the input item. Always `input_file`. - - `long scrollX` + - `INPUT_FILE("input_file")` - The horizontal scroll distance. + - `Optional detail` - - `long scrollY` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The vertical scroll distance. + - `AUTO("auto")` - - `JsonValue; type "scroll"constant` + - `LOW("low")` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `HIGH("high")` - - `SCROLL("scroll")` + - `Optional fileData` - - `long x` + The base64-encoded data of the file to be sent to the model. - The x-coordinate where the scroll occurred. + - `Optional fileId` - - `long y` + The ID of the file to be sent to the model. - The y-coordinate where the scroll occurred. + - `Optional fileUrl` - - `Optional> keys` + The URL of the file to be sent to the model. - The keys being held while scrolling. + - `Optional filename` - - `Type` + The name of the file to be sent to the model. - - `String text` + - `Optional promptCacheBreakpoint` - The text to type. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `JsonValue; type "type"constant` + - `JsonValue; mode "explicit"constant` - Specifies the event type. For a type action, this property is always set to `type`. + The breakpoint mode. Always `explicit`. - - `TYPE("type")` + - `EXPLICIT("explicit")` - - `JsonValue;` + - `JsonValue; type "function_call_output"constant` - - `JsonValue; type "wait"constant` + The type of the function tool call output. Always `function_call_output`. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `WAIT("wait")` + - `Optional id` - - `Optional> actions` + The unique ID of the function tool call output. Populated when this item is returned via API. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `Optional agent` - - `Click` + The agent that produced this item. - - `DoubleClick` + - `String agentName` - - `Drag` + The canonical name of the agent that produced this item. - - `Keypress` + - `Optional caller` - - `Move` + The execution context that produced this tool call. - `JsonValue;` - - `Scroll` - - - `Type` + - `JsonValue; type "direct"constant` - - `JsonValue;` + The caller type. Always `direct`. - - `Optional agent` + - `DIRECT("direct")` - The agent that produced this item. + - `class Program:` - - `String agentName` + - `String callerId` - The canonical name of the agent that produced this item. + The call ID of the program item that produced this tool call. - - `class BetaResponseComputerToolCallOutputItem:` + - `JsonValue; type "program"constant` - - `String id` + The caller type. Always `program`. - The unique ID of the computer call tool output. + - `PROGRAM("program")` - - `String callId` + - `Optional status` - The ID of the computer tool call that produced the output. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `IN_PROGRESS("in_progress")` - A computer screenshot image used with the computer use tool. + - `COMPLETED("completed")` - - `JsonValue; type "computer_screenshot"constant` + - `INCOMPLETE("incomplete")` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `AgentMessage` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `String author` - - `Optional fileId` + The sending agent identity. - The identifier of an uploaded file that contains the screenshot. + - `List content` - - `Optional imageUrl` + Plaintext, image, or encrypted content sent between agents. - The URL of the screenshot image. + - `class BetaResponseInputTextContent:` - - `Status status` + A text input to the model. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaResponseInputImageContent:` - - `COMPLETED("completed")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `INCOMPLETE("incomplete")` + - `class EncryptedContent:` - - `FAILED("failed")` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `IN_PROGRESS("in_progress")` + - `String encryptedContent` - - `JsonValue; type "computer_call_output"constant` + Opaque encrypted content. - The type of the computer tool call output. Always `computer_call_output`. + - `JsonValue; type "encrypted_content"constant` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The type of the input item. Always `encrypted_content`. - - `Optional> acknowledgedSafetyChecks` + - `ENCRYPTED_CONTENT("encrypted_content")` - The safety checks reported by the API that have been acknowledged by the - developer. + - `String recipient` - - `String id` + The destination agent identity. - The ID of the pending safety check. + - `JsonValue; type "agent_message"constant` - - `Optional code` + The item type. Always `agent_message`. - The type of the pending safety check. + - `AGENT_MESSAGE("agent_message")` - - `Optional message` + - `Optional id` - Details about the pending safety check. + The unique ID of this agent message item. - `Optional agent` @@ -99623,40 +112149,41 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `MultiAgentCall` - The identifier of the actor that created the item. + - `Action action` - - `class BetaResponseReasoningItem:` + The multi-agent action that was executed. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `SPAWN_AGENT("spawn_agent")` - - `String id` + - `INTERRUPT_AGENT("interrupt_agent")` - The unique identifier of the reasoning content. + - `LIST_AGENTS("list_agents")` - - `List summary` + - `SEND_MESSAGE("send_message")` - Reasoning summary content. + - `FOLLOWUP_TASK("followup_task")` - - `String text` + - `WAIT_AGENT("wait_agent")` - A summary of the reasoning output from the model so far. + - `String arguments` - - `JsonValue; type "summary_text"constant` + The action arguments as a JSON string. - The type of the object. Always `summary_text`. + - `String callId` - - `SUMMARY_TEXT("summary_text")` + The unique ID linking this call to its output. - - `JsonValue; type "reasoning"constant` + - `JsonValue; type "multi_agent_call"constant` - The type of the object. Always `reasoning`. + The item type. Always `multi_agent_call`. - - `REASONING("reasoning")` + - `MULTI_AGENT_CALL("multi_agent_call")` + + - `Optional id` + + The unique ID of this multi-agent call. - `Optional agent` @@ -99666,142 +112193,152 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional> content` + - `MultiAgentCallOutput` - Reasoning text content. + - `Action action` - - `String text` + The multi-agent action that produced this result. - The reasoning text from the model. + - `SPAWN_AGENT("spawn_agent")` - - `JsonValue; type "reasoning_text"constant` + - `INTERRUPT_AGENT("interrupt_agent")` - The type of the reasoning text. Always `reasoning_text`. + - `LIST_AGENTS("list_agents")` - - `REASONING_TEXT("reasoning_text")` + - `SEND_MESSAGE("send_message")` - - `Optional encryptedContent` + - `FOLLOWUP_TASK("followup_task")` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `WAIT_AGENT("wait_agent")` - - `Optional status` + - `String callId` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique ID of the multi-agent call. - - `IN_PROGRESS("in_progress")` + - `List output` - - `COMPLETED("completed")` + Text output returned by the multi-agent action. - - `INCOMPLETE("incomplete")` + - `String text` - - `Program` + The text content. - - `String id` + - `JsonValue; type "output_text"constant` - The unique ID of the program item. + The content type. Always `output_text`. - - `String callId` + - `OUTPUT_TEXT("output_text")` - The stable call ID of the program item. + - `Optional annotations` - - `String code` + Citations associated with the text content. - The JavaScript source executed by programmatic tool calling. + - `List` - - `String fingerprint` + - `String fileId` - Opaque program replay fingerprint that must be round-tripped. + The ID of the file. - - `JsonValue; type "program"constant` + - `String filename` - The type of the item. Always `program`. + The filename of the file cited. - - `PROGRAM("program")` + - `long index` - - `Optional agent` + The index of the file in the list of files. - The agent that produced this item. + - `JsonValue; type "file_citation"constant` - - `String agentName` + The citation type. Always `file_citation`. - The canonical name of the agent that produced this item. + - `FILE_CITATION("file_citation")` - - `ProgramOutput` + - `List` - - `String id` + - `long endIndex` - The unique ID of the program output item. + The index of the last character of the citation in the message. - - `String callId` + - `long startIndex` - The call ID of the program item. + The index of the first character of the citation in the message. - - `String result` + - `String title` - The result produced by the program item. + The title of the cited resource. - - `Status status` + - `JsonValue; type "url_citation"constant` - The terminal status of the program output item. + The citation type. Always `url_citation`. - - `COMPLETED("completed")` + - `URL_CITATION("url_citation")` - - `INCOMPLETE("incomplete")` + - `String url` - - `JsonValue; type "program_output"constant` + The URL of the cited resource. - The type of the item. Always `program_output`. + - `List` - - `PROGRAM_OUTPUT("program_output")` + - `String containerId` - - `Optional agent` + The ID of the container. - The agent that produced this item. + - `long endIndex` - - `String agentName` + The index of the last character of the citation in the message. - The canonical name of the agent that produced this item. + - `String fileId` - - `class BetaResponseToolSearchCall:` + The ID of the container file. - - `String id` + - `String filename` - The unique ID of the tool search call item. + The filename of the container file cited. - - `JsonValue arguments` + - `long startIndex` - Arguments used for the tool search call. + The index of the first character of the citation in the message. - - `Optional callId` + - `JsonValue; type "container_file_citation"constant` - The unique ID of the tool search call generated by the model. + The citation type. Always `container_file_citation`. - - `Execution execution` + - `CONTAINER_FILE_CITATION("container_file_citation")` - Whether tool search was executed by the server or by the client. + - `JsonValue; type "multi_agent_call_output"constant` - - `SERVER("server")` + The item type. Always `multi_agent_call_output`. - - `CLIENT("client")` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - - `Status status` + - `Optional id` - The status of the tool search call item that was recorded. + The unique ID of this multi-agent call output. - - `IN_PROGRESS("in_progress")` + - `Optional agent` - - `COMPLETED("completed")` + The agent that produced this item. - - `INCOMPLETE("incomplete")` + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ToolSearchCall` + + - `JsonValue arguments` + + The arguments supplied to the tool search call. - `JsonValue; type "tool_search_call"constant` - The type of the item. Always `tool_search_call`. + The item type. Always `tool_search_call`. - `TOOL_SEARCH_CALL("tool_search_call")` + - `Optional id` + + The unique ID of this tool search call. + - `Optional agent` The agent that produced this item. @@ -99810,21 +112347,11 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `class BetaResponseToolSearchOutputItem:` - - - `String id` - - The unique ID of the tool search output item. - - `Optional callId` The unique ID of the tool search call generated by the model. - - `Execution execution` + - `Optional execution` Whether tool search was executed by the server or by the client. @@ -99832,9 +112359,9 @@ public final class Main { - `CLIENT("client")` - - `Status status` + - `Optional status` - The status of the tool search output item that was recorded. + The status of the tool search call. - `IN_PROGRESS("in_progress")` @@ -99842,9 +112369,11 @@ public final class Main { - `INCOMPLETE("incomplete")` + - `class BetaResponseToolSearchOutputItemParam:` + - `List tools` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool:` @@ -99953,7 +112482,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -100010,7 +112543,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -100907,10 +113444,14 @@ public final class Main { - `JsonValue; type "tool_search_output"constant` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `Optional id` + + The unique ID of this tool search output. + - `Optional agent` The agent that produced this item. @@ -100919,39 +113460,39 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional callId` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `AdditionalTools` + - `Optional execution` - - `String id` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `SERVER("server")` - - `Role role` + - `CLIENT("client")` - The role that provided the additional tools. + - `Optional status` - - `UNKNOWN("unknown")` + The status of the tool search output. - - `USER("user")` + - `IN_PROGRESS("in_progress")` - - `ASSISTANT("assistant")` + - `COMPLETED("completed")` - - `SYSTEM("system")` + - `INCOMPLETE("incomplete")` - - `CRITIC("critic")` + - `AdditionalTools` - - `DISCRIMINATOR("discriminator")` + - `JsonValue; role "developer"constant` - - `DEVELOPER("developer")` + The role that provided the additional tools. Only `developer` is supported. - - `TOOL("tool")` + - `DEVELOPER("developer")` - `List tools` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool:` @@ -101010,10 +113551,14 @@ public final class Main { - `JsonValue; type "additional_tools"constant` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `ADDITIONAL_TOOLS("additional_tools")` + - `Optional id` + + The unique ID of this additional tools item. + - `Optional agent` The agent that produced this item. @@ -101022,17 +113567,82 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` + - `class BetaResponseReasoningItem:` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `String id` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `List 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 agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional> 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 encryptedContent` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `Optional 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 BetaResponseCompactionItemParam:` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `String encryptedContent` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `JsonValue; type "compaction"constant` @@ -101040,6 +113650,10 @@ public final class Main { - `COMPACTION("compaction")` + - `Optional id` + + The ID of the compaction item. + - `Optional agent` The agent that produced this item. @@ -101048,10 +113662,6 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - `ImageGenerationCall` - `String id` @@ -101263,13 +113873,7 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseFunctionShellToolCall:` - - A tool call that executes one or more shell commands in a managed environment. - - - `String id` - - The unique ID of the shell tool call. Populated when this item is returned via API. + - `ShellCall` - `Action action` @@ -101277,60 +113881,30 @@ public final class Main { - `List commands` + Ordered shell commands for the execution environment to run. + - `Optional maxOutputLength` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `Optional timeoutMs` - Optional timeout in milliseconds for the commands. + 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. - - `Optional environment` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment:` - - Represents the use of a local environment to perform shell actions. - - - `JsonValue; type "local"constant` - - The environment type. Always `local`. - - - `LOCAL("local")` - - - `class BetaResponseContainerReference:` - - Represents a container created with /v1/containers. - - - `String containerId` - - - `JsonValue; type "container_reference"constant` - - The environment type. Always `container_reference`. - - - `CONTAINER_REFERENCE("container_reference")` - - - `Status status` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - `JsonValue; type "shell_call"constant` The type of the item. Always `shell_call`. - `SHELL_CALL("shell_call")` + - `Optional id` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -101347,6 +113921,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -101357,35 +113933,41 @@ public final class Main { - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - - `Optional createdBy` + - `Optional environment` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput:` + - `class BetaLocalEnvironment:` - The output of a shell tool call that was emitted. + - `class BetaContainerReference:` - - `String id` + - `Optional status` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String callId` + - `IN_PROGRESS("in_progress")` - The unique ID of the shell tool call generated by the model. + - `COMPLETED("completed")` - - `Optional maxOutputLength` + - `INCOMPLETE("incomplete")` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `ShellCallOutput` - - `List output` + - `String callId` - An array of shell call output contents + The unique ID of the shell tool call generated by the model. + + - `List output` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `Outcome outcome` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `JsonValue;` @@ -101401,7 +113983,7 @@ public final class Main { - `long exitCode` - Exit code from the shell process. + The exit code returned by the shell process. - `JsonValue; type "exit"constant` @@ -101411,32 +113993,22 @@ public final class Main { - `String stderr` - The standard error output that was captured. + Captured stderr output for the shell call. - `String stdout` - The standard output that was captured. - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `Status status` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` + Captured stdout output for the shell call. - `JsonValue; type "shell_call_output"constant` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -101453,6 +114025,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -101463,19 +114037,25 @@ public final class Main { - `JsonValue; type "program"constant` + The caller type. Always `program`. + - `PROGRAM("program")` - - `Optional createdBy` + - `Optional maxOutputLength` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall:` + - `Optional status` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `String id` + - `IN_PROGRESS("in_progress")` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `ApplyPatchCall` - `String callId` @@ -101483,55 +114063,55 @@ public final class Main { - `Operation operation` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `class CreateFile:` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `String diff` - Diff to apply. + Unified diff content to apply when creating the file. - `String path` - Path of the file to create. + Path of the file to create relative to the workspace root. - `JsonValue; type "create_file"constant` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `CREATE_FILE("create_file")` - `class DeleteFile:` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `String path` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `JsonValue; type "delete_file"constant` - Delete the specified file. + The operation type. Always `delete_file`. - `DELETE_FILE("delete_file")` - `class UpdateFile:` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `String diff` - Diff to apply. + Unified diff content to apply to the existing file. - `String path` - Path of the file to update. + Path of the file to update relative to the workspace root. - `JsonValue; type "update_file"constant` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `UPDATE_FILE("update_file")` @@ -101549,6 +114129,10 @@ public final class Main { - `APPLY_PATCH_CALL("apply_patch_call")` + - `Optional id` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -101565,6 +114149,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -101575,19 +114161,11 @@ public final class Main { - `JsonValue; type "program"constant` - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput:` - - The output emitted by an apply patch tool call. + The caller type. Always `program`. - - `String id` + - `PROGRAM("program")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `ApplyPatchCallOutput` - `String callId` @@ -101607,6 +114185,10 @@ public final class Main { - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `Optional id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `Optional agent` The agent that produced this item. @@ -101623,6 +114205,8 @@ public final class Main { - `JsonValue; type "direct"constant` + The caller type. Always `direct`. + - `DIRECT("direct")` - `class Program:` @@ -101633,74 +114217,13 @@ public final class Main { - `JsonValue; type "program"constant` - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call output. - - - `Optional output` - - Optional textual output returned by the apply patch tool. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional 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 error` + The caller type. Always `program`. - The error from the tool call, if any. + - `PROGRAM("program")` - `Optional output` - The output from the tool call. - - - `Optional 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")` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `McpListTools` @@ -101784,10 +114307,6 @@ public final class Main { - `McpApprovalResponse` - - `String id` - - The unique ID of the approval response - - `String approvalRequestId` The ID of the approval request being answered. @@ -101802,6 +114321,10 @@ public final class Main { - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `Optional id` + + The unique ID of the approval response + - `Optional agent` The agent that produced this item. @@ -101814,31 +114337,29 @@ public final class Main { Optional reason for the decision. - - `class BetaResponseCustomToolCall:` - - A call to a custom tool created by the model. + - `McpCall` - - `String callId` + - `String id` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the tool call. - - `String input` + - `String arguments` - The input for the custom tool call generated by the model. + A JSON string of the arguments passed to the tool. - `String name` - The name of the custom tool being called. + The name of the tool that was run. - - `JsonValue; type "custom_tool_call"constant` + - `String serverLabel` - The type of the custom tool call. Always `custom_tool_call`. + The label of the MCP server running the tool. - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `JsonValue; type "mcp_call"constant` - - `Optional id` + The type of the item. Always `mcp_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `MCP_CALL("mcp_call")` - `Optional agent` @@ -101848,42 +114369,22 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional namespace` + - `Optional approvalRequestId` - The namespace of the custom tool being called. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `class BetaResponseCustomToolCallOutputItem:` + - `Optional error` - The output of a custom tool call from your code, being sent back to the model. + The error from the tool call, if any. - - `String id` + - `Optional output` - The unique ID of the custom tool call output item. + The output from the tool call. - - `Status status` + - `Optional status` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `IN_PROGRESS("in_progress")` @@ -101891,198 +114392,198 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `Optional createdBy` + - `CALLING("calling")` - The identifier of the actor that created the item. + - `FAILED("failed")` -### Beta Response Output Item Added Event + - `class BetaResponseCustomToolCallOutput:` -- `class BetaResponseOutputItemAddedEvent:` + The output of a custom tool call from your code, being sent back to the model. - Emitted when a new output item is added. + - `String callId` - - `BetaResponseOutputItem item` + The call ID, used to map this custom tool call output to a custom tool call. - The output item that was added. + - `Output output` - - `class BetaResponseOutputMessage:` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - An output message from the model. + - `String` - - `String id` + - `List` - The unique ID of the output message. + - `class BetaResponseInputText:` - - `List content` + A text input to the model. - The content of the output message. + - `class BetaResponseInputImage:` - - `class BetaResponseOutputText:` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A text output from the model. + - `class BetaResponseInputFile:` - - `List annotations` + A file input to the model. - The annotations of the text output. + - `JsonValue; type "custom_tool_call_output"constant` - - `class FileCitation:` + The type of the custom tool call output. Always `custom_tool_call_output`. - A citation to a file. + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - - `String fileId` + - `Optional id` - The ID of the file. + The unique ID of the custom tool call output in the OpenAI platform. - - `String filename` + - `Optional agent` - The filename of the file cited. + The agent that produced this item. - - `long index` + - `String agentName` - The index of the file in the list of files. + The canonical name of the agent that produced this item. - - `JsonValue; type "file_citation"constant` + - `Optional caller` - The type of the file citation. Always `file_citation`. + The execution context that produced this tool call. - - `FILE_CITATION("file_citation")` + - `JsonValue;` - - `class UrlCitation:` + - `JsonValue; type "direct"constant` - A citation for a web resource used to generate a model response. + The caller type. Always `direct`. - - `long endIndex` + - `DIRECT("direct")` - The index of the last character of the URL citation in the message. + - `class Program:` - - `long startIndex` + - `String callerId` - The index of the first character of the URL citation in the message. + The call ID of the program item that produced this tool call. - - `String title` + - `JsonValue; type "program"constant` - The title of the web resource. + The caller type. Always `program`. - - `JsonValue; type "url_citation"constant` + - `PROGRAM("program")` - The type of the URL citation. Always `url_citation`. + - `class BetaResponseCustomToolCall:` - - `URL_CITATION("url_citation")` + A call to a custom tool created by the model. - - `String url` + - `String callId` - The URL of the web resource. + An identifier used to map this custom tool call to a tool call output. - - `class ContainerFileCitation:` + - `String input` - A citation for a container file used to generate a model response. + The input for the custom tool call generated by the model. - - `String containerId` + - `String name` - The ID of the container file. + The name of the custom tool being called. - - `long endIndex` + - `JsonValue; type "custom_tool_call"constant` - The index of the last character of the container file citation in the message. + The type of the custom tool call. Always `custom_tool_call`. - - `String fileId` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - The ID of the file. + - `Optional id` - - `String filename` + The unique ID of the custom tool call in the OpenAI platform. - The filename of the container file cited. + - `Optional agent` - - `long startIndex` + The agent that produced this item. - The index of the first character of the container file citation in the message. + - `String agentName` - - `JsonValue; type "container_file_citation"constant` + The canonical name of the agent that produced this item. - The type of the container file citation. Always `container_file_citation`. + - `Optional caller` - - `CONTAINER_FILE_CITATION("container_file_citation")` + The execution context that produced this tool call. - - `class FilePath:` + - `JsonValue;` - A path to a file. + - `JsonValue; type "direct"constant` - - `String fileId` + - `DIRECT("direct")` - The ID of the file. + - `class Program:` - - `long index` + - `String callerId` - The index of the file in the list of files. + The call ID of the program item that produced this tool call. - - `JsonValue; type "file_path"constant` + - `JsonValue; type "program"constant` - The type of the file path. Always `file_path`. + - `PROGRAM("program")` - - `FILE_PATH("file_path")` + - `Optional namespace` - - `String text` + The namespace of the custom tool being called. - The text output from the model. + - `CompactionTrigger` - - `JsonValue; type "output_text"constant` + - `JsonValue; type "compaction_trigger"constant` - The type of the output text. Always `output_text`. + The type of the item. Always `compaction_trigger`. - - `OUTPUT_TEXT("output_text")` + - `COMPACTION_TRIGGER("compaction_trigger")` - - `Optional> logprobs` + - `Optional agent` - - `String token` + The agent that produced this item. - - `List bytes` + - `String agentName` - - `double logprob` + The canonical name of the agent that produced this item. - - `List topLogprobs` + - `ItemReference` - - `String token` + - `String id` - - `List bytes` + The ID of the item to reference. - - `double logprob` + - `Optional agent` - - `class BetaResponseOutputRefusal:` + The agent that produced this item. - A refusal from the model. + - `String agentName` - - `String refusal` + The canonical name of the agent that produced this item. - The refusal explanation from the model. + - `Optional type` - - `JsonValue; type "refusal"constant` + The type of item to reference. Always `item_reference`. - The type of the refusal. Always `refusal`. + - `ITEM_REFERENCE("item_reference")` - - `REFUSAL("refusal")` + - `Program` - - `JsonValue; role "assistant"constant` + - `String id` - The role of the output message. Always `assistant`. + The unique ID of this program item. - - `ASSISTANT("assistant")` + - `String callId` - - `Status status` + The stable call ID of the program item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `String code` - - `IN_PROGRESS("in_progress")` + The JavaScript source executed by programmatic tool calling. - - `COMPLETED("completed")` + - `String fingerprint` - - `INCOMPLETE("incomplete")` + Opaque program replay fingerprint that must be round-tripped. - - `JsonValue; type "message"constant` + - `JsonValue; type "program"constant` - The type of the output message. Always `message`. + The item type. Always `program`. - - `MESSAGE("message")` + - `PROGRAM("program")` - `Optional agent` @@ -102092,47 +114593,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional 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")` - - - `class BetaResponseFileSearchToolCall:` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `ProgramOutput` - `String id` - The unique ID of the file search tool call. + The unique ID of this program output item. - - `List queries` + - `String callId` - The queries used to search for files. + The call ID of the program item. - - `Status status` + - `String result` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The result produced by the program item. - - `IN_PROGRESS("in_progress")` + - `Status status` - - `SEARCHING("searching")` + The terminal status of the program output. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `FAILED("failed")` - - - `JsonValue; type "file_search_call"constant` + - `JsonValue; type "program_output"constant` - The type of the file search tool call. Always `file_search_call`. + The item type. Always `program_output`. - - `FILE_SEARCH_CALL("file_search_call")` + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -102142,238 +114629,273 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional> results` - - The results of the file search tool call. - - - `Optional attributes` + - `Optional 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, booleans, or numbers. + format, and querying for objects via API or the dashboard. - - `String` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `double` + - `Model model` - - `boolean` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - - `Optional fileId` + - `GPT_5_6_SOL("gpt-5.6-sol")` - The unique ID of the file. + - `GPT_5_6_TERRA("gpt-5.6-terra")` - - `Optional filename` + - `GPT_5_6_LUNA("gpt-5.6-luna")` - The name of the file. + - `GPT_5_4("gpt-5.4")` - - `Optional score` + - `GPT_5_4_MINI("gpt-5.4-mini")` - The relevance score of the file - a value between 0 and 1. + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `Optional text` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - The text that was retrieved from the file. + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - `class BetaResponseFunctionToolCall:` + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `GPT_5_2("gpt-5.2")` - - `String arguments` + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - A JSON string of the arguments to pass to the function. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - `String callId` + - `GPT_5_2_PRO("gpt-5.2-pro")` - The unique ID of the function tool call generated by the model. + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `String name` + - `GPT_5_1("gpt-5.1")` - The name of the function to run. + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - `JsonValue; type "function_call"constant` + - `GPT_5_1_CODEX("gpt-5.1-codex")` - The type of the function tool call. Always `function_call`. + - `GPT_5_1_MINI("gpt-5.1-mini")` - - `FUNCTION_CALL("function_call")` + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - `Optional id` + - `GPT_5("gpt-5")` - The unique ID of the function tool call. + - `GPT_5_MINI("gpt-5-mini")` - - `Optional agent` + - `GPT_5_NANO("gpt-5-nano")` - The agent that produced this item. + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - `String agentName` + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - The canonical name of the agent that produced this item. + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - `Optional caller` + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - The execution context that produced this tool call. + - `GPT_4_1("gpt-4.1")` - - `JsonValue;` + - `GPT_4_1_MINI("gpt-4.1-mini")` - - `JsonValue; type "direct"constant` + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `DIRECT("direct")` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - `class Program:` + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `String callerId` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - The call ID of the program item that produced this tool call. + - `O4_MINI("o4-mini")` - - `JsonValue; type "program"constant` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - - `PROGRAM("program")` + - `O3("o3")` - - `Optional namespace` + - `O3_2025_04_16("o3-2025-04-16")` - The namespace of the function to run. + - `O3_MINI("o3-mini")` - - `Optional status` + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + + - `O1("o1")` + + - `O1_2024_12_17("o1-2024-12-17")` + + - `O1_PREVIEW("o1-preview")` + + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + + - `O1_MINI("o1-mini")` + + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + + - `GPT_4O("gpt-4o")` + + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - `IN_PROGRESS("in_progress")` + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `COMPLETED("completed")` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - - `INCOMPLETE("incomplete")` + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - `class BetaResponseFunctionToolCallOutputItem:` + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - `String id` + - `CODEX_MINI_LATEST("codex-mini-latest")` - The unique ID of the function call tool output. + - `GPT_4O_MINI("gpt-4o-mini")` - - `String callId` + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - The unique ID of the function tool call generated by the model. + - `GPT_4_TURBO("gpt-4-turbo")` - - `Output output` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - - `String` + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `List` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - - `class BetaResponseInputText:` + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - A text input to the model. + - `GPT_4("gpt-4")` - - `String text` + - `GPT_4_0314("gpt-4-0314")` - The text input to the model. + - `GPT_4_0613("gpt-4-0613")` - - `JsonValue; type "input_text"constant` + - `GPT_4_32K("gpt-4-32k")` - The type of the input item. Always `input_text`. + - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `INPUT_TEXT("input_text")` + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `Optional promptCacheBreakpoint` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `JsonValue; mode "explicit"constant` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - The breakpoint mode. Always `explicit`. + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `EXPLICIT("explicit")` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - - `class BetaResponseInputImage:` + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - - `Detail detail` + - `O1_PRO("o1-pro")` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - - `LOW("low")` + - `O3_PRO("o3-pro")` - - `HIGH("high")` + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - - `AUTO("auto")` + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `ORIGINAL("original")` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - - `JsonValue; type "input_image"constant` + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - The type of the input item. Always `input_image`. + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - - `INPUT_IMAGE("input_image")` + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - `Optional fileId` + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - The ID of the file to be sent to the model. + - `GPT_5_CODEX("gpt-5-codex")` - - `Optional imageUrl` + - `GPT_5_PRO("gpt-5-pro")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - - `Optional promptCacheBreakpoint` + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; object_ "response"constant` - - `JsonValue; mode "explicit"constant` + The object type of this resource - always set to `response`. - The breakpoint mode. Always `explicit`. + - `RESPONSE("response")` - - `EXPLICIT("explicit")` + - `List output` - - `class BetaResponseInputFile:` + An array of content items generated by the model. - A file input to the model. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `JsonValue; type "input_file"constant` + - `class BetaResponseOutputMessage:` - The type of the input item. Always `input_file`. + An output message from the model. - - `INPUT_FILE("input_file")` + - `class BetaResponseFileSearchToolCall:` - - `Optional detail` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `class BetaResponseFunctionToolCall:` - - `AUTO("auto")` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `LOW("low")` + - `class BetaResponseFunctionToolCallOutputItem:` - - `HIGH("high")` + - `String id` - - `Optional fileData` + The unique ID of the function call tool output. - The content of the file to be sent to the model. + - `String callId` - - `Optional fileId` + The unique ID of the function tool call generated by the model. - The ID of the file to be sent to the model. + - `Output output` - - `Optional fileUrl` + The output from the function call generated by your code. + Can be a string or an list of output content. - The URL of the file to be sent to the model. + - `String` - - `Optional filename` + - `List` - The name of the file to be sent to the model. + - `class BetaResponseInputText:` - - `Optional promptCacheBreakpoint` + A text input to the model. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class BetaResponseInputImage:` - - `JsonValue; mode "explicit"constant` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The breakpoint mode. Always `explicit`. + - `class BetaResponseInputFile:` - - `EXPLICIT("explicit")` + A file input to the model. - `Status status` @@ -102679,359 +115201,11 @@ public final class Main { The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `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. - - - `JsonValue; type "search"constant` - - The action type. - - - `SEARCH("search")` - - - `Optional> queries` - - The search queries. - - - `Optional query` - - The search query. - - - `Optional> 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 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCall:` A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `String id` - - The unique ID of the computer call. - - - `String callId` - - An identifier used when responding to the tool call with output. - - - `List pendingSafetyChecks` - - The pending safety checks for the computer call. - - - `String id` - - The ID of the pending safety check. - - - `Optional code` - - The type of the pending safety check. - - - `Optional 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` - - A click action. - - - `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> keys` - - The keys being held while clicking. - - - `DoubleClick` - - - `Optional> 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` - - 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> keys` - - The keys being held while dragging the mouse. - - - `Keypress` - - - `List 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> 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> 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")` - - - `Optional> actions` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `Click` - - - `DoubleClick` - - - `Drag` - - - `Keypress` - - - `Move` - - - `JsonValue;` - - - `Scroll` - - - `Type` - - - `JsonValue;` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem:` - `String id` @@ -103046,21 +115220,6 @@ public final class Main { 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 fileId` - - The identifier of an uploaded file that contains the screenshot. - - - `Optional imageUrl` - - The URL of the screenshot image. - - `Status status` The status of the message input. One of `in_progress`, `completed`, or @@ -103116,68 +115275,6 @@ public final class Main { for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `String id` - - The unique identifier of the reasoning content. - - - `List 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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional> 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 encryptedContent` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `Optional 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")` - - `Program` - `String id` @@ -103332,1108 +115429,1118 @@ public final class Main { Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String name` + - `class BetaFileSearchTool:` - The name of the function to call. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional parameters` + - `class BetaComputerTool:` - A JSON schema object describing the parameters of the function. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Optional strict` + - `class BetaComputerUsePreviewTool:` - Whether strict parameter validation is enforced for this function tool. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; type "function"constant` + - `class BetaWebSearchTool:` - The type of the function tool. Always `function`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `FUNCTION("function")` + - `Mcp` - - `Optional> allowedCallers` + - `CodeInterpreter` - The tool invocation context(s). + - `JsonValue;` - - `DIRECT("direct")` + - `ImageGeneration` - - `PROGRAMMATIC("programmatic")` + - `JsonValue;` - - `Optional deferLoading` + - `class BetaFunctionShellTool:` - Whether this function is deferred and loaded via tool search. + A tool that allows the model to execute shell commands. - - `Optional description` + - `class BetaCustomTool:` - A description of the function. Used by the model to determine whether or not to call the function. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional outputSchema` + - `class BetaNamespaceTool:` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Groups function/custom tools under a shared namespace. - - `class BetaFileSearchTool:` + - `class BetaToolSearchTool:` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Hosted or BYOT tool search configuration for deferred tools. - - `JsonValue; type "file_search"constant` + - `class BetaWebSearchPreviewTool:` - The type of the file search tool. Always `file_search`. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `FILE_SEARCH("file_search")` + - `class BetaApplyPatchTool:` - - `List vectorStoreIds` + Allows the assistant to create, delete, or update files using unified diffs. - The IDs of the vector stores to search. + - `JsonValue; type "tool_search_output"constant` - - `Optional filters` + The type of the item. Always `tool_search_output`. - A filter to apply. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `class ComparisonFilter:` + - `Optional agent` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The agent that produced this item. - - `String key` + - `String agentName` - The key to compare against the value. + The canonical name of the agent that produced this item. - - `Type type` + - `Optional createdBy` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The identifier of the actor that created the item. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `AdditionalTools` - - `EQ("eq")` + - `String id` - - `NE("ne")` + The unique ID of the additional tools item. - - `GT("gt")` + - `Role role` - - `GTE("gte")` + The role that provided the additional tools. - - `LT("lt")` + - `UNKNOWN("unknown")` - - `LTE("lte")` + - `USER("user")` - - `IN("in")` + - `ASSISTANT("assistant")` - - `NIN("nin")` + - `SYSTEM("system")` - - `Value value` + - `CRITIC("critic")` - The value to compare against the attribute key; supports string, number, or boolean types. + - `DISCRIMINATOR("discriminator")` - - `String` + - `DEVELOPER("developer")` - - `double` + - `TOOL("tool")` - - `boolean` + - `List tools` - - `List` + The additional tool definitions made available at this item. - - `class CompoundFilter:` + - `class BetaFunctionTool:` - Combine multiple filters using `and` or `or`. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `List filters` + - `class BetaFileSearchTool:` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `class ComparisonFilter:` + - `class BetaComputerTool:` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String key` + - `class BetaComputerUsePreviewTool:` - The key to compare against the value. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Type type` + - `class BetaWebSearchTool:` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `Mcp` - - `EQ("eq")` + - `CodeInterpreter` - - `NE("ne")` + - `JsonValue;` - - `GT("gt")` + - `ImageGeneration` - - `GTE("gte")` + - `JsonValue;` - - `LT("lt")` + - `class BetaFunctionShellTool:` - - `LTE("lte")` + A tool that allows the model to execute shell commands. - - `IN("in")` + - `class BetaCustomTool:` - - `NIN("nin")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Value value` + - `class BetaNamespaceTool:` - The value to compare against the attribute key; supports string, number, or boolean types. + Groups function/custom tools under a shared namespace. - - `String` + - `class BetaToolSearchTool:` - - `double` + Hosted or BYOT tool search configuration for deferred tools. - - `boolean` + - `class BetaWebSearchPreviewTool:` - - `List` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue` + - `class BetaApplyPatchTool:` - - `Type type` + Allows the assistant to create, delete, or update files using unified diffs. - Type of operation: `and` or `or`. + - `JsonValue; type "additional_tools"constant` - - `AND("and")` + The type of the item. Always `additional_tools`. - - `OR("or")` + - `ADDITIONAL_TOOLS("additional_tools")` - - `Optional maxNumResults` + - `Optional agent` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The agent that produced this item. - - `Optional rankingOptions` + - `String agentName` - Ranking options for search. + The canonical name of the agent that produced this item. - - `Optional hybridSearch` + - `class BetaResponseCompactionItem:` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `double embeddingWeight` + - `String id` - The weight of the embedding in the reciprocal ranking fusion. + The unique ID of the compaction item. - - `double textWeight` + - `String encryptedContent` - The weight of the text in the reciprocal ranking fusion. + The encrypted content that was produced by compaction. - - `Optional ranker` + - `JsonValue; type "compaction"constant` - The ranker to use for the file search. + The type of the item. Always `compaction`. - - `AUTO("auto")` + - `COMPACTION("compaction")` - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `Optional agent` - - `Optional scoreThreshold` + The agent that produced this item. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `String agentName` - - `class BetaComputerTool:` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional createdBy` - - `JsonValue; type "computer"constant` + The identifier of the actor that created the item. - The type of the computer tool. Always `computer`. + - `ImageGenerationCall` - - `COMPUTER("computer")` + - `String id` - - `class BetaComputerUsePreviewTool:` + The unique ID of the image generation call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional result` - - `long displayHeight` + The generated image encoded in base64. - The height of the computer display. + - `Status status` - - `long displayWidth` + The status of the image generation call. - The width of the computer display. + - `IN_PROGRESS("in_progress")` - - `Environment environment` + - `COMPLETED("completed")` - The type of computer environment to control. + - `GENERATING("generating")` - - `WINDOWS("windows")` + - `FAILED("failed")` - - `MAC("mac")` + - `JsonValue; type "image_generation_call"constant` - - `LINUX("linux")` + The type of the image generation call. Always `image_generation_call`. - - `UBUNTU("ubuntu")` + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `BROWSER("browser")` + - `Optional agent` - - `JsonValue; type "computer_use_preview"constant` + The agent that produced this item. - The type of the computer use tool. Always `computer_use_preview`. + - `String agentName` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The canonical name of the agent that produced this item. - - `class BetaWebSearchTool:` + - `class BetaResponseCodeInterpreterToolCall:` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A tool call to run code. - - `Type type` + - `LocalShellCall` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `String id` - - `WEB_SEARCH("web_search")` + The unique ID of the local shell call. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `Action action` - - `Optional filters` + Execute a shell command on the server. - Filters for the search. + - `List command` - - `Optional> allowedDomains` + The command to run. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Env env` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Environment variables to set for the command. - - `Optional searchContextSize` + - `JsonValue; type "exec"constant` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the local shell action. Always `exec`. - - `LOW("low")` + - `EXEC("exec")` - - `MEDIUM("medium")` + - `Optional timeoutMs` - - `HIGH("high")` + Optional timeout in milliseconds for the command. - - `Optional userLocation` + - `Optional user` - The approximate location of the user. + Optional user to run the command as. - - `Optional city` + - `Optional workingDirectory` - Free text input for the city of the user, e.g. `San Francisco`. + Optional working directory to run the command in. - - `Optional country` + - `String callId` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The unique ID of the local shell tool call generated by the model. - - `Optional region` + - `Status status` - Free text input for the region of the user, e.g. `California`. + The status of the local shell call. - - `Optional timezone` + - `IN_PROGRESS("in_progress")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `COMPLETED("completed")` - - `Optional type` + - `INCOMPLETE("incomplete")` - The type of location approximation. Always `approximate`. + - `JsonValue; type "local_shell_call"constant` - - `APPROXIMATE("approximate")` + The type of the local shell call. Always `local_shell_call`. - - `Mcp` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `String serverLabel` + - `Optional agent` - A label for this MCP server, used to identify it in tool calls. + The agent that produced this item. - - `JsonValue; type "mcp"constant` + - `String agentName` - The type of the MCP tool. Always `mcp`. + The canonical name of the agent that produced this item. - - `MCP("mcp")` + - `LocalShellCallOutput` - - `Optional> allowedCallers` + - `String id` - The tool invocation context(s). + The unique ID of the local shell tool call generated by the model. - - `DIRECT("direct")` + - `String output` - - `PROGRAMMATIC("programmatic")` + A JSON string of the output of the local shell tool call. - - `Optional allowedTools` + - `JsonValue; type "local_shell_call_output"constant` - List of allowed tool names or a filter object. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `List` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `class McpToolFilter:` + - `Optional agent` - A filter object to specify which tools are allowed. + The agent that produced this item. - - `Optional readOnly` + - `String agentName` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The canonical name of the agent that produced this item. - - `Optional> toolNames` + - `Optional status` - List of allowed tool names. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `Optional authorization` + - `IN_PROGRESS("in_progress")` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `COMPLETED("completed")` - - `Optional connectorId` + - `INCOMPLETE("incomplete")` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `class BetaResponseFunctionShellToolCall:` - Currently supported `connector_id` values are: + A tool call that executes one or more shell commands in a managed environment. - - 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` + - `String id` - - `CONNECTOR_DROPBOX("connector_dropbox")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `CONNECTOR_GMAIL("connector_gmail")` + - `Action action` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + The shell commands and limits that describe how to run the tool call. - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `List commands` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `Optional maxOutputLength` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + Optional maximum number of characters to return from each command. - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `Optional timeoutMs` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + Optional timeout in milliseconds for the commands. - - `Optional deferLoading` + - `String callId` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the shell tool call generated by the model. - - `Optional headers` + - `Optional environment` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Represents the use of a local environment to perform shell actions. - - `Optional requireApproval` + - `class BetaResponseLocalEnvironment:` - Specify which of the MCP server's tools require approval. + Represents the use of a local environment to perform shell actions. - - `class McpToolApprovalFilter:` + - `JsonValue; type "local"constant` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The environment type. Always `local`. - - `Optional always` + - `LOCAL("local")` - A filter object to specify which tools are allowed. + - `class BetaResponseContainerReference:` - - `Optional readOnly` + Represents a container created with /v1/containers. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `String containerId` - - `Optional> toolNames` + - `JsonValue; type "container_reference"constant` - List of allowed tool names. + The environment type. Always `container_reference`. - - `Optional never` + - `CONTAINER_REFERENCE("container_reference")` - A filter object to specify which tools are allowed. + - `Status status` - - `Optional readOnly` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call"constant` + + The type of the item. Always `shell_call`. + + - `SHELL_CALL("shell_call")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `Optional caller` + + The execution context that produced this tool call. + + - `JsonValue;` - - `Optional> toolNames` + - `JsonValue; type "direct"constant` - List of allowed tool names. + - `DIRECT("direct")` - - `enum McpToolApprovalSetting:` + - `class Program:` - 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. + - `String callerId` - - `ALWAYS("always")` + The call ID of the program item that produced this tool call. - - `NEVER("never")` + - `JsonValue; type "program"constant` - - `Optional serverDescription` + - `PROGRAM("program")` - Optional description of the MCP server, used to provide more context. + - `Optional createdBy` - - `Optional serverUrl` + The ID of the entity that created this tool call. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `class BetaResponseFunctionShellToolCallOutput:` - - `Optional tunnelId` + The output of a shell tool call that was emitted. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `String id` - - `CodeInterpreter` + The unique ID of the shell call output. Populated when this item is returned via API. - - `Container container` + - `String callId` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The unique ID of the shell tool call generated by the model. - - `String` + - `Optional maxOutputLength` - - `class CodeInterpreterToolAuto:` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `List output` - - `JsonValue; type "auto"constant` + An array of shell call output contents - Always `auto`. + - `Outcome outcome` - - `AUTO("auto")` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `Optional> fileIds` + - `JsonValue;` - An optional list of uploaded files to make available to your code. + - `JsonValue; type "timeout"constant` - - `Optional memoryLimit` + The outcome type. Always `timeout`. - The memory limit for the code interpreter container. + - `TIMEOUT("timeout")` - - `_1G("1g")` + - `class Exit:` - - `_4G("4g")` + Indicates that the shell commands finished and returned an exit code. - - `_16G("16g")` + - `long exitCode` - - `_64G("64g")` + Exit code from the shell process. - - `Optional networkPolicy` + - `JsonValue; type "exit"constant` - Network access policy for the container. + The outcome type. Always `exit`. - - `class BetaContainerNetworkPolicyDisabled:` + - `EXIT("exit")` - - `JsonValue; type "disabled"constant` + - `String stderr` - Disable outbound network access. Always `disabled`. + The standard error output that was captured. - - `DISABLED("disabled")` + - `String stdout` - - `class BetaContainerNetworkPolicyAllowlist:` + The standard output that was captured. - - `List allowedDomains` + - `Optional createdBy` - A list of allowed domains when type is `allowlist`. + The identifier of the actor that created the item. - - `JsonValue; type "allowlist"constant` + - `Status status` - Allow outbound network access only to specified domains. Always `allowlist`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `ALLOWLIST("allowlist")` + - `IN_PROGRESS("in_progress")` - - `Optional> domainSecrets` + - `COMPLETED("completed")` - Optional domain-scoped secrets for allowlisted domains. + - `INCOMPLETE("incomplete")` - - `String domain` + - `JsonValue; type "shell_call_output"constant` - The domain associated with the secret. + The type of the shell call output. Always `shell_call_output`. - - `String name` + - `SHELL_CALL_OUTPUT("shell_call_output")` - The name of the secret to inject for the domain. + - `Optional agent` - - `String value` + The agent that produced this item. - The secret value to inject for the domain. + - `String agentName` - - `JsonValue; type "code_interpreter"constant` + The canonical name of the agent that produced this item. - The type of the code interpreter tool. Always `code_interpreter`. + - `Optional caller` - - `CODE_INTERPRETER("code_interpreter")` + The execution context that produced this tool call. - - `Optional> allowedCallers` + - `JsonValue;` - The tool invocation context(s). + - `JsonValue; type "direct"constant` - `DIRECT("direct")` - - `PROGRAMMATIC("programmatic")` + - `class Program:` - - `JsonValue;` + - `String callerId` - - `JsonValue; type "programmatic_tool_calling"constant` + The call ID of the program item that produced this tool call. - The type of the tool. Always `programmatic_tool_calling`. + - `JsonValue; type "program"constant` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `PROGRAM("program")` - - `ImageGeneration` + - `Optional createdBy` - - `JsonValue; type "image_generation"constant` + The identifier of the actor that created the item. - The type of the image generation tool. Always `image_generation`. + - `class BetaResponseApplyPatchToolCall:` - - `IMAGE_GENERATION("image_generation")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `Optional action` + - `String id` - Whether to generate a new image or edit an existing image. Default: `auto`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `GENERATE("generate")` + - `String callId` - - `EDIT("edit")` + The unique ID of the apply patch tool call generated by the model. - - `AUTO("auto")` + - `Operation operation` - - `Optional background` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `class CreateFile:` - `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. + Instruction describing how to create a file via the apply_patch tool. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `String diff` - - `TRANSPARENT("transparent")` + Diff to apply. - - `OPAQUE("opaque")` + - `String path` - - `AUTO("auto")` + Path of the file to create. - - `Optional inputFidelity` + - `JsonValue; type "create_file"constant` - 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`. + Create a new file with the provided diff. - - `HIGH("high")` + - `CREATE_FILE("create_file")` - - `LOW("low")` + - `class DeleteFile:` - - `Optional inputImageMask` + Instruction describing how to delete a file via the apply_patch tool. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `String path` - - `Optional fileId` + Path of the file to delete. - File ID for the mask image. + - `JsonValue; type "delete_file"constant` - - `Optional imageUrl` + Delete the specified file. - Base64-encoded mask image. + - `DELETE_FILE("delete_file")` - - `Optional model` + - `class UpdateFile:` - The image generation model to use. Default: `gpt-image-1`. + Instruction describing how to update a file via the apply_patch tool. - - `GPT_IMAGE_1("gpt-image-1")` + - `String diff` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + Diff to apply. - - `GPT_IMAGE_2("gpt-image-2")` + - `String path` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + Path of the file to update. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `JsonValue; type "update_file"constant` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + Update an existing file with the provided diff. - - `Optional moderation` + - `UPDATE_FILE("update_file")` - Moderation level for the generated image. Default: `auto`. + - `Status status` - - `AUTO("auto")` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `LOW("low")` + - `IN_PROGRESS("in_progress")` - - `Optional outputCompression` + - `COMPLETED("completed")` - Compression level for the output image. Default: 100. + - `JsonValue; type "apply_patch_call"constant` - - `Optional outputFormat` + The type of the item. Always `apply_patch_call`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `APPLY_PATCH_CALL("apply_patch_call")` - - `PNG("png")` + - `Optional agent` - - `WEBP("webp")` + The agent that produced this item. - - `JPEG("jpeg")` + - `String agentName` - - `Optional partialImages` + The canonical name of the agent that produced this item. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `Optional caller` - - `Optional quality` + The execution context that produced this tool call. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `JsonValue;` - - `LOW("low")` + - `JsonValue; type "direct"constant` - - `MEDIUM("medium")` + - `DIRECT("direct")` - - `HIGH("high")` + - `class Program:` - - `AUTO("auto")` + - `String callerId` - - `Optional size` + The call ID of the program item that produced this tool call. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `JsonValue; type "program"constant` - - `_1024X1024("1024x1024")` + - `PROGRAM("program")` - - `_1024X1536("1024x1536")` + - `Optional createdBy` - - `_1536X1024("1536x1024")` + The ID of the entity that created this tool call. - - `AUTO("auto")` + - `class BetaResponseApplyPatchToolCallOutput:` - - `JsonValue;` + The output emitted by an apply patch tool call. - - `JsonValue; type "local_shell"constant` + - `String id` - The type of the local shell tool. Always `local_shell`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `LOCAL_SHELL("local_shell")` + - `String callId` - - `class BetaFunctionShellTool:` + The unique ID of the apply patch tool call generated by the model. - A tool that allows the model to execute shell commands. + - `Status status` - - `JsonValue; type "shell"constant` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the shell tool. Always `shell`. + - `COMPLETED("completed")` - - `SHELL("shell")` + - `FAILED("failed")` - - `Optional> allowedCallers` + - `JsonValue; type "apply_patch_call_output"constant` - The tool invocation context(s). + The type of the item. Always `apply_patch_call_output`. - - `DIRECT("direct")` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `PROGRAMMATIC("programmatic")` + - `Optional agent` - - `Optional environment` + The agent that produced this item. - - `class BetaContainerAuto:` + - `String agentName` - - `JsonValue; type "container_auto"constant` + The canonical name of the agent that produced this item. - Automatically creates a container for this request + - `Optional caller` - - `CONTAINER_AUTO("container_auto")` + The execution context that produced this tool call. - - `Optional> fileIds` + - `JsonValue;` - An optional list of uploaded files to make available to your code. + - `JsonValue; type "direct"constant` - - `Optional memoryLimit` + - `DIRECT("direct")` - The memory limit for the container. + - `class Program:` - - `_1G("1g")` + - `String callerId` - - `_4G("4g")` + The call ID of the program item that produced this tool call. - - `_16G("16g")` + - `JsonValue; type "program"constant` - - `_64G("64g")` + - `PROGRAM("program")` - - `Optional networkPolicy` + - `Optional createdBy` - Network access policy for the container. + The ID of the entity that created this tool call output. - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional output` - - `class BetaContainerNetworkPolicyAllowlist:` + Optional textual output returned by the apply patch tool. - - `Optional> skills` + - `McpCall` - An optional list of skills referenced by id or inline data. + - `String id` - - `class BetaSkillReference:` + The unique ID of the tool call. - - `String skillId` + - `String arguments` - The ID of the referenced skill. + A JSON string of the arguments passed to the tool. - - `JsonValue; type "skill_reference"constant` + - `String name` - References a skill created with the /v1/skills endpoint. + The name of the tool that was run. - - `SKILL_REFERENCE("skill_reference")` + - `String serverLabel` - - `Optional version` + The label of the MCP server running the tool. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `JsonValue; type "mcp_call"constant` - - `class BetaInlineSkill:` + The type of the item. Always `mcp_call`. - - `String description` + - `MCP_CALL("mcp_call")` - The description of the skill. + - `Optional agent` - - `String name` + The agent that produced this item. - The name of the skill. + - `String agentName` - - `BetaInlineSkillSource source` + The canonical name of the agent that produced this item. - Inline skill payload + - `Optional approvalRequestId` - - `String data` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - Base64-encoded skill zip bundle. + - `Optional error` - - `JsonValue; mediaType "application/zip"constant` + The error from the tool call, if any. - The media type of the inline skill payload. Must be `application/zip`. + - `Optional output` - - `APPLICATION_ZIP("application/zip")` + The output from the tool call. - - `JsonValue; type "base64"constant` + - `Optional status` - The type of the inline skill source. Must be `base64`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `BASE64("base64")` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "inline"constant` + - `COMPLETED("completed")` - Defines an inline skill for this request. + - `INCOMPLETE("incomplete")` - - `INLINE("inline")` + - `CALLING("calling")` - - `class BetaLocalEnvironment:` + - `FAILED("failed")` - - `JsonValue; type "local"constant` + - `McpListTools` - Use a local computer environment. + - `String id` - - `LOCAL("local")` + The unique ID of the list. - - `Optional> skills` + - `String serverLabel` - An optional list of skills. + The label of the MCP server. - - `String description` + - `List tools` - The description of the skill. + The tools available on the server. - - `String name` + - `JsonValue inputSchema` - The name of the skill. + The JSON schema describing the tool's input. - - `String path` + - `String name` - The path to the directory containing the skill. + The name of the tool. - - `class BetaContainerReference:` + - `Optional annotations` - - `String containerId` + Additional annotations about the tool. - The ID of the referenced container. + - `Optional description` - - `JsonValue; type "container_reference"constant` + The description of the tool. - References a container created with the /v1/containers endpoint + - `JsonValue; type "mcp_list_tools"constant` - - `CONTAINER_REFERENCE("container_reference")` + The type of the item. Always `mcp_list_tools`. - - `class BetaCustomTool:` + - `MCP_LIST_TOOLS("mcp_list_tools")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Optional agent` - - `String name` + The agent that produced this item. - The name of the custom tool, used to identify it in tool calls. + - `String agentName` - - `JsonValue; type "custom"constant` + The canonical name of the agent that produced this item. - The type of the custom tool. Always `custom`. + - `Optional error` - - `CUSTOM("custom")` + Error message if the server could not list tools. - - `Optional> allowedCallers` + - `McpApprovalRequest` - The tool invocation context(s). + - `String id` - - `DIRECT("direct")` + The unique ID of the approval request. - - `PROGRAMMATIC("programmatic")` + - `String arguments` - - `Optional deferLoading` + A JSON string of arguments for the tool. - Whether this tool should be deferred and discovered via tool search. + - `String name` - - `Optional description` + The name of the tool to run. - Optional description of the custom tool, used to provide more context. + - `String serverLabel` - - `Optional format` + The label of the MCP server making the request. - The input format for the custom tool. Default is unconstrained text. + - `JsonValue; type "mcp_approval_request"constant` - - `JsonValue;` + The type of the item. Always `mcp_approval_request`. - - `JsonValue; type "text"constant` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - Unconstrained text format. Always `text`. + - `Optional agent` - - `TEXT("text")` + The agent that produced this item. - - `class Grammar:` + - `String agentName` - A grammar defined by the user. + The canonical name of the agent that produced this item. - - `String definition` + - `McpApprovalResponse` - The grammar definition. + - `String id` - - `Syntax syntax` + The unique ID of the approval response - The syntax of the grammar definition. One of `lark` or `regex`. + - `String approvalRequestId` - - `LARK("lark")` + The ID of the approval request being answered. - - `REGEX("regex")` + - `boolean approve` - - `JsonValue; type "grammar"constant` + Whether the request was approved. - Grammar format. Always `grammar`. + - `JsonValue; type "mcp_approval_response"constant` - - `GRAMMAR("grammar")` + The type of the item. Always `mcp_approval_response`. - - `class BetaNamespaceTool:` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - Groups function/custom tools under a shared namespace. + - `Optional agent` - - `String description` + The agent that produced this item. - A description of the namespace shown to the model. + - `String agentName` - - `String name` + The canonical name of the agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `Optional reason` - - `List tools` + Optional reason for the decision. - The function/custom tools available inside this namespace. + - `class BetaResponseCustomToolCall:` - - `class Function:` + A call to a custom tool created by the model. - - `String name` + - `class BetaResponseCustomToolCallOutputItem:` - - `JsonValue; type "function"constant` + The output of a custom tool call from your code, being sent back to the model. - - `FUNCTION("function")` + - `String id` - - `Optional> allowedCallers` + The unique ID of the custom tool call output item. - The tool invocation context(s). + - `Status status` - - `DIRECT("direct")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `PROGRAMMATIC("programmatic")` + - `IN_PROGRESS("in_progress")` - - `Optional deferLoading` + - `COMPLETED("completed")` - Whether this function should be deferred and discovered via tool search. + - `INCOMPLETE("incomplete")` - - `Optional description` + - `Optional createdBy` - - `Optional outputSchema` + The identifier of the actor that created the item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `boolean parallelToolCalls` - - `Optional parameters` + Whether to allow the model to run tool calls in parallel. - - `Optional strict` + - `Optional temperature` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `class BetaCustomTool:` + - `ToolChoice toolChoice` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `JsonValue; type "namespace"constant` + - `enum BetaToolChoiceOptions:` - The type of the tool. Always `namespace`. + Controls which (if any) tool is called by the model. - - `NAMESPACE("namespace")` + `none` means the model will not call any tool and instead generates a message. - - `class BetaToolSearchTool:` + `auto` means the model can pick between generating a message or calling one or + more tools. - Hosted or BYOT tool search configuration for deferred tools. + `required` means the model must call one or more tools. - - `JsonValue; type "tool_search"constant` + - `NONE("none")` - The type of the tool. Always `tool_search`. + - `AUTO("auto")` - - `TOOL_SEARCH("tool_search")` + - `REQUIRED("required")` - - `Optional description` + - `class BetaToolChoiceAllowed:` - Description shown to the model for a client-executed tool search tool. + Constrains the tools available to the model to a pre-defined set. - - `Optional execution` + - `Mode mode` - Whether tool search is executed by the server or by the client. + Constrains the tools available to the model to a pre-defined set. - - `SERVER("server")` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `CLIENT("client")` + `required` requires the model to call one or more of the allowed tools. - - `Optional parameters` + - `AUTO("auto")` - Parameter schema for a client-executed tool search tool. + - `REQUIRED("required")` - - `class BetaWebSearchPreviewTool:` + - `List tools` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A list of tool definitions that the model should be allowed to call. - - `Type type` + For the Responses API, the list of tool definitions might look like: - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `JsonValue; type "allowed_tools"constant` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + Allowed tool configuration type. Always `allowed_tools`. - - `Optional> searchContentTypes` + - `ALLOWED_TOOLS("allowed_tools")` - - `TEXT("text")` + - `class BetaToolChoiceTypes:` - - `IMAGE("image")` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `Optional searchContextSize` + - `Type type` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `LOW("low")` + Allowed values are: - - `MEDIUM("medium")` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `HIGH("high")` + - `FILE_SEARCH("file_search")` - - `Optional userLocation` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - The user's location. + - `COMPUTER("computer")` - - `JsonValue; type "approximate"constant` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - The type of location approximation. Always `approximate`. + - `COMPUTER_USE("computer_use")` - - `APPROXIMATE("approximate")` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `Optional city` + - `IMAGE_GENERATION("image_generation")` - Free text input for the city of the user, e.g. `San Francisco`. + - `CODE_INTERPRETER("code_interpreter")` - - `Optional country` + - `class BetaToolChoiceFunction:` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Use this option to force the model to call a specific function. - - `Optional region` + - `String name` - Free text input for the region of the user, e.g. `California`. + The name of the function to call. - - `Optional timezone` + - `JsonValue; type "function"constant` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + For function calling, the type is always `function`. - - `class BetaApplyPatchTool:` + - `FUNCTION("function")` - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaToolChoiceMcp:` - - `JsonValue; type "apply_patch"constant` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the tool. Always `apply_patch`. + - `String serverLabel` - - `APPLY_PATCH("apply_patch")` + The label of the MCP server to use. - - `Optional> allowedCallers` + - `JsonValue; type "mcp"constant` - The tool invocation context(s). + For MCP tools, the type is always `mcp`. - - `DIRECT("direct")` + - `MCP("mcp")` - - `PROGRAMMATIC("programmatic")` + - `Optional name` - - `JsonValue; type "tool_search_output"constant` + The name of the tool to call on the server. - The type of the item. Always `tool_search_output`. + - `class BetaToolChoiceCustom:` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + Use this option to force the model to call a specific custom tool. - - `Optional agent` + - `String name` - The agent that produced this item. + The name of the custom tool to call. - - `String agentName` + - `JsonValue; type "custom"constant` - The canonical name of the agent that produced this item. + For custom tool calling, the type is always `custom`. - - `Optional createdBy` + - `CUSTOM("custom")` - The identifier of the actor that created the item. + - `JsonValue;` - - `AdditionalTools` + - `JsonValue; type "programmatic_tool_calling"constant` - - `String id` + The tool to call. Always `programmatic_tool_calling`. - The unique ID of the additional tools item. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `Role role` + - `class BetaToolChoiceApplyPatch:` - The role that provided the additional tools. + Forces the model to call the apply_patch tool when executing a tool call. - - `UNKNOWN("unknown")` + - `JsonValue; type "apply_patch"constant` - - `USER("user")` + The tool to call. Always `apply_patch`. - - `ASSISTANT("assistant")` + - `APPLY_PATCH("apply_patch")` - - `SYSTEM("system")` + - `class BetaToolChoiceShell:` - - `CRITIC("critic")` + Forces the model to call the shell tool when a tool call is required. - - `DISCRIMINATOR("discriminator")` + - `JsonValue; type "shell"constant` - - `DEVELOPER("developer")` + The tool to call. Always `shell`. - - `TOOL("tool")` + - `SHELL("shell")` - `List tools` - The additional tool definitions made available at this item. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - `class BetaFunctionTool:` @@ -104490,892 +116597,1052 @@ public final class Main { Allows the assistant to create, delete, or update files using unified diffs. - - `JsonValue; type "additional_tools"constant` + - `Optional topP` - The type of the item. Always `additional_tools`. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `ADDITIONAL_TOOLS("additional_tools")` + We generally recommend altering this or `temperature` but not both. - - `Optional agent` + - `Optional background` - The agent that produced this item. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `String agentName` + - `Optional completedAt` - The canonical name of the agent that produced this item. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `class BetaResponseCompactionItem:` + - `Optional conversation` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - `String id` - The unique ID of the compaction item. + The unique ID of the conversation that this response was associated with. - - `String encryptedContent` + - `Optional maxOutputTokens` - The encrypted content that was produced by compaction. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `JsonValue; type "compaction"constant` + - `Optional maxToolCalls` - The type of the item. Always `compaction`. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `COMPACTION("compaction")` + - `Optional moderation` - - `Optional agent` + Moderation results for the response input and output, if moderated completions were requested. - The agent that produced this item. + - `Input input` - - `String agentName` + Moderation for the response input. - The canonical name of the agent that produced this item. + - `class ModerationResult:` - - `Optional createdBy` + A moderation result produced for the response input or output. - The identifier of the actor that created the item. + - `Categories categories` - - `ImageGenerationCall` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `String id` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - The unique ID of the image generation call. + Which modalities of input are reflected by the score for each category. - - `Optional result` + - `TEXT("text")` - The generated image encoded in base64. + - `IMAGE("image")` - - `Status status` + - `CategoryScores categoryScores` - The status of the image generation call. + A dictionary of moderation categories to scores. - - `IN_PROGRESS("in_progress")` + - `boolean flagged` - - `COMPLETED("completed")` + A boolean indicating whether the content was flagged by any category. - - `GENERATING("generating")` + - `String model` - - `FAILED("failed")` + The moderation model that produced this result. - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "moderation_result"constant` - The type of the image generation call. Always `image_generation_call`. + The object type, which was always `moderation_result` for successful moderation results. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `MODERATION_RESULT("moderation_result")` - - `Optional agent` + - `class Error:` - The agent that produced this item. + An error produced while attempting moderation for the response input or output. - - `String agentName` + - `String code` - The canonical name of the agent that produced this item. + The error code. - - `class BetaResponseCodeInterpreterToolCall:` + - `String message` - A tool call to run code. + The error message. + + - `JsonValue; type "error"constant` + + The object type, which was always `error` for moderation failures. + + - `ERROR("error")` + + - `Output output` + + Moderation for the response output. + + - `class ModerationResult:` + + A moderation result produced for the response input or output. + + - `Categories categories` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `CategoryAppliedInputTypes categoryAppliedInputTypes` + + Which modalities of input are reflected by the score for each category. + + - `TEXT("text")` + + - `IMAGE("image")` + + - `CategoryScores categoryScores` + + A dictionary of moderation categories to scores. + + - `boolean flagged` + + A boolean indicating whether the content was flagged by any category. + + - `String model` + + The moderation model that produced this result. + + - `JsonValue; type "moderation_result"constant` + + The object type, which was always `moderation_result` for successful moderation results. + + - `MODERATION_RESULT("moderation_result")` + + - `class Error:` + + An error produced while attempting moderation for the response input or output. + + - `String code` + + The error code. + + - `String message` + + The error message. + + - `JsonValue; type "error"constant` + + The object type, which was always `error` for moderation failures. + + - `ERROR("error")` + + - `Optional previousResponseId` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `Optional prompt` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - `String id` - The unique ID of the code interpreter tool call. + The unique identifier of the prompt template to use. - - `Optional code` + - `Optional variables` - The code to run, or null if not available. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `String containerId` + - `String` - The ID of the container used to run the code. + - `class BetaResponseInputText:` - - `Optional> outputs` + A text input to the model. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `class BetaResponseInputImage:` - - `class Logs:` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The logs output from the code interpreter. + - `class BetaResponseInputFile:` - - `String logs` + A file input to the model. - The logs output from the code interpreter. + - `Optional version` - - `JsonValue; type "logs"constant` + Optional version of the prompt template. - The type of the output. Always `logs`. + - `Optional promptCacheKey` - - `LOGS("logs")` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `class Image:` + - `Optional promptCacheOptions` - The image output from the code interpreter. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `JsonValue; type "image"constant` + - `Mode mode` - The type of the output. Always `image`. + Whether implicit prompt-cache breakpoints were enabled. - - `IMAGE("image")` + - `IMPLICIT("implicit")` - - `String url` + - `EXPLICIT("explicit")` - The URL of the image output from the code interpreter. + - `Ttl ttl` - - `Status status` + The minimum lifetime applied to each cache breakpoint. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `_30M("30m")` - - `IN_PROGRESS("in_progress")` + - `Optional promptCacheRetention` - - `COMPLETED("completed")` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `INCOMPLETE("incomplete")` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `INTERPRETING("interpreting")` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `FAILED("failed")` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `JsonValue; type "code_interpreter_call"constant` + - `IN_MEMORY("in_memory")` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `_24H("24h")` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `Optional reasoning` - - `Optional agent` + **gpt-5 and o-series models only** - The agent that produced this item. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `String agentName` + - `Optional context` - The canonical name of the agent that produced this item. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `LocalShellCall` + - `AUTO("auto")` - - `String id` + - `CURRENT_TURN("current_turn")` - The unique ID of the local shell call. + - `ALL_TURNS("all_turns")` - - `Action action` + - `Optional effort` - Execute a shell command on the server. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `List command` + - `NONE("none")` - The command to run. + - `MINIMAL("minimal")` - - `Env env` + - `LOW("low")` - Environment variables to set for the command. + - `MEDIUM("medium")` - - `JsonValue; type "exec"constant` + - `HIGH("high")` - The type of the local shell action. Always `exec`. + - `XHIGH("xhigh")` - - `EXEC("exec")` + - `MAX("max")` - - `Optional timeoutMs` + - `Optional generateSummary` - Optional timeout in milliseconds for the command. + **Deprecated:** use `summary` instead. - - `Optional user` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - Optional user to run the command as. + - `AUTO("auto")` - - `Optional workingDirectory` + - `CONCISE("concise")` - Optional working directory to run the command in. + - `DETAILED("detailed")` - - `String callId` + - `Optional mode` - The unique ID of the local shell tool call generated by the model. + Controls the reasoning execution mode for the request. - - `Status status` + When returned on a response, this is the effective execution mode. - The status of the local shell call. + - `STANDARD("standard")` - - `IN_PROGRESS("in_progress")` + - `PRO("pro")` + + - `Optional summary` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `AUTO("auto")` + + - `CONCISE("concise")` + + - `DETAILED("detailed")` + + - `Optional safetyIdentifier` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `Optional serviceTier` - - `COMPLETED("completed")` + Specifies the processing type used for serving the request. - - `INCOMPLETE("incomplete")` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `JsonValue; type "local_shell_call"constant` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The type of the local shell call. Always `local_shell_call`. + - `AUTO("auto")` - - `LOCAL_SHELL_CALL("local_shell_call")` + - `DEFAULT("default")` - - `Optional agent` + - `FLEX("flex")` - The agent that produced this item. + - `SCALE("scale")` - - `String agentName` + - `PRIORITY("priority")` - The canonical name of the agent that produced this item. + - `Optional status` - - `LocalShellCallOutput` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `String id` + - `COMPLETED("completed")` - The unique ID of the local shell tool call generated by the model. + - `FAILED("failed")` - - `String output` + - `IN_PROGRESS("in_progress")` - A JSON string of the output of the local shell tool call. + - `CANCELLED("cancelled")` - - `JsonValue; type "local_shell_call_output"constant` + - `QUEUED("queued")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `INCOMPLETE("incomplete")` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `Optional text` - - `Optional agent` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The agent that produced this item. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `String agentName` + - `Optional format` - The canonical name of the agent that produced this item. + An object specifying the format that the model must output. - - `Optional status` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The default format is `{ "type": "text" }` with no additional options. - - `IN_PROGRESS("in_progress")` + **Not recommended for gpt-4o and newer models:** - - `COMPLETED("completed")` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `INCOMPLETE("incomplete")` + - `JsonValue;` - - `class BetaResponseFunctionShellToolCall:` + - `JsonValue; type "text"constant` - A tool call that executes one or more shell commands in a managed environment. + The type of response format being defined. Always `text`. - - `String id` + - `TEXT("text")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `class BetaResponseFormatTextJsonSchemaConfig:` - - `Action action` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The shell commands and limits that describe how to run the tool call. + - `String name` - - `List commands` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `Optional maxOutputLength` + - `Schema schema` - Optional maximum number of characters to return from each command. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `Optional timeoutMs` + - `JsonValue; type "json_schema"constant` - Optional timeout in milliseconds for the commands. + The type of response format being defined. Always `json_schema`. - - `String callId` + - `JSON_SCHEMA("json_schema")` - The unique ID of the shell tool call generated by the model. + - `Optional description` - - `Optional environment` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Represents the use of a local environment to perform shell actions. + - `Optional strict` - - `class BetaResponseLocalEnvironment:` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - Represents the use of a local environment to perform shell actions. + - `JsonValue;` - - `JsonValue; type "local"constant` + - `JsonValue; type "json_object"constant` - The environment type. Always `local`. + The type of response format being defined. Always `json_object`. - - `LOCAL("local")` + - `JSON_OBJECT("json_object")` - - `class BetaResponseContainerReference:` + - `Optional verbosity` - Represents a container created with /v1/containers. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `String containerId` + - `LOW("low")` - - `JsonValue; type "container_reference"constant` + - `MEDIUM("medium")` - The environment type. Always `container_reference`. + - `HIGH("high")` - - `CONTAINER_REFERENCE("container_reference")` + - `Optional topLogprobs` - - `Status status` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `Optional truncation` - - `IN_PROGRESS("in_progress")` + The truncation strategy to use for the model response. - - `COMPLETED("completed")` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `INCOMPLETE("incomplete")` + - `AUTO("auto")` - - `JsonValue; type "shell_call"constant` + - `DISABLED("disabled")` - The type of the item. Always `shell_call`. + - `Optional usage` - - `SHELL_CALL("shell_call")` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `Optional agent` + - `long inputTokens` - The agent that produced this item. + The number of input tokens. - - `String agentName` + - `InputTokensDetails inputTokensDetails` - The canonical name of the agent that produced this item. + A detailed breakdown of the input tokens. - - `Optional caller` + - `long cacheWriteTokens` - The execution context that produced this tool call. + The number of input tokens that were written to the cache. - - `JsonValue;` + - `long cachedTokens` - - `JsonValue; type "direct"constant` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `DIRECT("direct")` + - `long outputTokens` - - `class Program:` + The number of output tokens. - - `String callerId` + - `OutputTokensDetails outputTokensDetails` - The call ID of the program item that produced this tool call. + A detailed breakdown of the output tokens. - - `JsonValue; type "program"constant` + - `long reasoningTokens` - - `PROGRAM("program")` + The number of reasoning tokens. - - `Optional createdBy` + - `long totalTokens` - The ID of the entity that created this tool call. + The total number of tokens used. - - `class BetaResponseFunctionShellToolCallOutput:` + - `Optional user` - The output of a shell tool call that was emitted. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `String id` + - `long sequenceNumber` - The unique ID of the shell call output. Populated when this item is returned via API. + The sequence number for this event. - - `String callId` + - `JsonValue; type "response.completed"constant` - The unique ID of the shell tool call generated by the model. + The type of the event. Always `response.completed`. - - `Optional maxOutputLength` + - `RESPONSE_COMPLETED("response.completed")` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `Optional agent` - - `List output` + The agent that owns this multi-agent streaming event. - An array of shell call output contents + - `String agentName` - - `Outcome outcome` + The canonical name of the agent that produced this item. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `class BetaResponseContentPartAddedEvent:` - - `JsonValue;` + Emitted when a new content part is added. - - `JsonValue; type "timeout"constant` + - `long contentIndex` - The outcome type. Always `timeout`. + The index of the content part that was added. - - `TIMEOUT("timeout")` + - `String itemId` - - `class Exit:` + The ID of the output item that the content part was added to. - Indicates that the shell commands finished and returned an exit code. + - `long outputIndex` - - `long exitCode` + The index of the output item that the content part was added to. - Exit code from the shell process. + - `Part part` - - `JsonValue; type "exit"constant` + The content part that was added. - The outcome type. Always `exit`. + - `class BetaResponseOutputText:` - - `EXIT("exit")` + A text output from the model. - - `String stderr` + - `class BetaResponseOutputRefusal:` - The standard error output that was captured. + A refusal from the model. - - `String stdout` + - `class ReasoningText:` - The standard output that was captured. + Reasoning text from the model. - - `Optional createdBy` + - `String text` - The identifier of the actor that created the item. + The reasoning text from the model. - - `Status status` + - `JsonValue; type "reasoning_text"constant` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The type of the reasoning text. Always `reasoning_text`. - - `IN_PROGRESS("in_progress")` + - `REASONING_TEXT("reasoning_text")` - - `COMPLETED("completed")` + - `long sequenceNumber` - - `INCOMPLETE("incomplete")` + The sequence number of this event. - - `JsonValue; type "shell_call_output"constant` + - `JsonValue; type "response.content_part.added"constant` - The type of the shell call output. Always `shell_call_output`. + The type of the event. Always `response.content_part.added`. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `RESPONSE_CONTENT_PART_ADDED("response.content_part.added")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` + - `class BetaResponseContentPartDoneEvent:` - The execution context that produced this tool call. + Emitted when a content part is done. - - `JsonValue;` + - `long contentIndex` - - `JsonValue; type "direct"constant` + The index of the content part that is done. - - `DIRECT("direct")` + - `String itemId` - - `class Program:` + The ID of the output item that the content part was added to. - - `String callerId` + - `long outputIndex` - The call ID of the program item that produced this tool call. + The index of the output item that the content part was added to. - - `JsonValue; type "program"constant` + - `Part part` - - `PROGRAM("program")` + The content part that is done. - - `Optional createdBy` + - `class BetaResponseOutputText:` - The identifier of the actor that created the item. + A text output from the model. - - `class BetaResponseApplyPatchToolCall:` + - `class BetaResponseOutputRefusal:` - A tool call that applies file diffs by creating, deleting, or updating files. + A refusal from the model. - - `String id` + - `class ReasoningText:` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Reasoning text from the model. - - `String callId` + - `String text` - The unique ID of the apply patch tool call generated by the model. + The reasoning text from the model. - - `Operation operation` + - `JsonValue; type "reasoning_text"constant` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of the reasoning text. Always `reasoning_text`. - - `class CreateFile:` + - `REASONING_TEXT("reasoning_text")` - Instruction describing how to create a file via the apply_patch tool. + - `long sequenceNumber` - - `String diff` + The sequence number of this event. - Diff to apply. + - `JsonValue; type "response.content_part.done"constant` - - `String path` + The type of the event. Always `response.content_part.done`. - Path of the file to create. + - `RESPONSE_CONTENT_PART_DONE("response.content_part.done")` - - `JsonValue; type "create_file"constant` + - `Optional agent` - Create a new file with the provided diff. + The agent that owns this multi-agent streaming event. - - `CREATE_FILE("create_file")` + - `String agentName` - - `class DeleteFile:` + The canonical name of the agent that produced this item. - Instruction describing how to delete a file via the apply_patch tool. + - `class BetaResponseCreatedEvent:` - - `String path` + An event that is emitted when a response is created. - Path of the file to delete. + - `BetaResponse response` - - `JsonValue; type "delete_file"constant` + The response that was created. - Delete the specified file. + - `long sequenceNumber` - - `DELETE_FILE("delete_file")` + The sequence number for this event. - - `class UpdateFile:` + - `JsonValue; type "response.created"constant` - Instruction describing how to update a file via the apply_patch tool. + The type of the event. Always `response.created`. - - `String diff` + - `RESPONSE_CREATED("response.created")` - Diff to apply. + - `Optional agent` - - `String path` + The agent that owns this multi-agent streaming event. - Path of the file to update. + - `String agentName` - - `JsonValue; type "update_file"constant` + The canonical name of the agent that produced this item. - Update an existing file with the provided diff. + - `class BetaResponseErrorEvent:` - - `UPDATE_FILE("update_file")` + Emitted when an error occurs. - - `Status status` + - `Optional code` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The error code. - - `IN_PROGRESS("in_progress")` + - `String message` - - `COMPLETED("completed")` + The error message. - - `JsonValue; type "apply_patch_call"constant` + - `Optional param` - The type of the item. Always `apply_patch_call`. + The error parameter. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `long sequenceNumber` + + The sequence number of this event. + + - `JsonValue; type "error"constant` + + The type of the event. Always `error`. + + - `ERROR("error")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` + - `class BetaResponseFileSearchCallCompletedEvent:` - The execution context that produced this tool call. + Emitted when a file search call is completed (results found). - - `JsonValue;` + - `String itemId` - - `JsonValue; type "direct"constant` + The ID of the output item that the file search call is initiated. - - `DIRECT("direct")` + - `long outputIndex` - - `class Program:` + The index of the output item that the file search call is initiated. - - `String callerId` + - `long sequenceNumber` - The call ID of the program item that produced this tool call. + The sequence number of this event. - - `JsonValue; type "program"constant` + - `JsonValue; type "response.file_search_call.completed"constant` - - `PROGRAM("program")` + The type of the event. Always `response.file_search_call.completed`. - - `Optional createdBy` + - `RESPONSE_FILE_SEARCH_CALL_COMPLETED("response.file_search_call.completed")` - The ID of the entity that created this tool call. + - `Optional agent` - - `class BetaResponseApplyPatchToolCallOutput:` + The agent that owns this multi-agent streaming event. - The output emitted by an apply patch tool call. + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `class BetaResponseFileSearchCallInProgressEvent:` - - `String callId` + Emitted when a file search call is initiated. - The unique ID of the apply patch tool call generated by the model. + - `String itemId` - - `Status status` + The ID of the output item that the file search call is initiated. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `long outputIndex` - - `COMPLETED("completed")` + The index of the output item that the file search call is initiated. - - `FAILED("failed")` + - `long sequenceNumber` - - `JsonValue; type "apply_patch_call_output"constant` + The sequence number of this event. - The type of the item. Always `apply_patch_call_output`. + - `JsonValue; type "response.file_search_call.in_progress"constant` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The type of the event. Always `response.file_search_call.in_progress`. + + - `RESPONSE_FILE_SEARCH_CALL_IN_PROGRESS("response.file_search_call.in_progress")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` + - `class BetaResponseFileSearchCallSearchingEvent:` - The execution context that produced this tool call. + Emitted when a file search is currently searching. - - `JsonValue;` + - `String itemId` - - `JsonValue; type "direct"constant` + The ID of the output item that the file search call is initiated. - - `DIRECT("direct")` + - `long outputIndex` - - `class Program:` + The index of the output item that the file search call is searching. - - `String callerId` + - `long sequenceNumber` - The call ID of the program item that produced this tool call. + The sequence number of this event. - - `JsonValue; type "program"constant` + - `JsonValue; type "response.file_search_call.searching"constant` - - `PROGRAM("program")` + The type of the event. Always `response.file_search_call.searching`. - - `Optional createdBy` + - `RESPONSE_FILE_SEARCH_CALL_SEARCHING("response.file_search_call.searching")` - The ID of the entity that created this tool call output. + - `Optional agent` - - `Optional output` + The agent that owns this multi-agent streaming event. - Optional textual output returned by the apply patch tool. + - `String agentName` - - `McpCall` + The canonical name of the agent that produced this item. - - `String id` + - `class BetaResponseFunctionCallArgumentsDeltaEvent:` - The unique ID of the tool call. + Emitted when there is a partial function-call arguments delta. - - `String arguments` + - `String delta` - A JSON string of the arguments passed to the tool. + The function-call arguments delta that is added. - - `String name` + - `String itemId` - The name of the tool that was run. + The ID of the output item that the function-call arguments delta is added to. - - `String serverLabel` + - `long outputIndex` - The label of the MCP server running the tool. + The index of the output item that the function-call arguments delta is added to. - - `JsonValue; type "mcp_call"constant` + - `long sequenceNumber` - The type of the item. Always `mcp_call`. + The sequence number of this event. - - `MCP_CALL("mcp_call")` + - `JsonValue; type "response.function_call_arguments.delta"constant` + + The type of the event. Always `response.function_call_arguments.delta`. + + - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DELTA("response.function_call_arguments.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional 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 error` - - The error from the tool call, if any. - - - `Optional output` + - `class BetaResponseFunctionCallArgumentsDoneEvent:` - The output from the tool call. + Emitted when function-call arguments are finalized. - - `Optional status` + - `String arguments` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The function-call arguments. - - `IN_PROGRESS("in_progress")` + - `String itemId` - - `COMPLETED("completed")` + The ID of the item. - - `INCOMPLETE("incomplete")` + - `String name` - - `CALLING("calling")` + The name of the function that was called. - - `FAILED("failed")` + - `long outputIndex` - - `McpListTools` + The index of the output item. - - `String id` + - `long sequenceNumber` - The unique ID of the list. + The sequence number of this event. - - `String serverLabel` + - `JsonValue; type "response.function_call_arguments.done"constant` - The label of the MCP server. + - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DONE("response.function_call_arguments.done")` - - `List tools` + - `Optional agent` - The tools available on the server. + The agent that owns this multi-agent streaming event. - - `JsonValue inputSchema` + - `String agentName` - The JSON schema describing the tool's input. + The canonical name of the agent that produced this item. - - `String name` + - `class BetaResponseInProgressEvent:` - The name of the tool. + Emitted when the response is in progress. - - `Optional annotations` + - `BetaResponse response` - Additional annotations about the tool. + The response that is in progress. - - `Optional description` + - `long sequenceNumber` - The description of the tool. + The sequence number of this event. - - `JsonValue; type "mcp_list_tools"constant` + - `JsonValue; type "response.in_progress"constant` - The type of the item. Always `mcp_list_tools`. + The type of the event. Always `response.in_progress`. - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `RESPONSE_IN_PROGRESS("response.in_progress")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional error` - - Error message if the server could not list tools. - - - `McpApprovalRequest` - - - `String id` - - The unique ID of the approval request. - - - `String arguments` + - `class BetaResponseFailedEvent:` - A JSON string of arguments for the tool. + An event that is emitted when a response fails. - - `String name` + - `BetaResponse response` - The name of the tool to run. + The response that failed. - - `String serverLabel` + - `long sequenceNumber` - The label of the MCP server making the request. + The sequence number of this event. - - `JsonValue; type "mcp_approval_request"constant` + - `JsonValue; type "response.failed"constant` - The type of the item. Always `mcp_approval_request`. + The type of the event. Always `response.failed`. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `RESPONSE_FAILED("response.failed")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `McpApprovalResponse` - - - `String id` + - `class BetaResponseIncompleteEvent:` - The unique ID of the approval response + An event that is emitted when a response finishes as incomplete. - - `String approvalRequestId` + - `BetaResponse response` - The ID of the approval request being answered. + The response that was incomplete. - - `boolean approve` + - `long sequenceNumber` - Whether the request was approved. + The sequence number of this event. - - `JsonValue; type "mcp_approval_response"constant` + - `JsonValue; type "response.incomplete"constant` - The type of the item. Always `mcp_approval_response`. + The type of the event. Always `response.incomplete`. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `RESPONSE_INCOMPLETE("response.incomplete")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional reason` + - `class BetaResponseOutputItemAddedEvent:` - Optional reason for the decision. + Emitted when a new output item is added. - - `class BetaResponseCustomToolCall:` + - `BetaResponseOutputItem item` - A call to a custom tool created by the model. + The output item that was added. - - `String callId` + - `class BetaResponseOutputMessage:` - An identifier used to map this custom tool call to a tool call output. + An output message from the model. - - `String input` + - `class BetaResponseFileSearchToolCall:` - The input for the custom tool call generated by the model. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `String name` + - `class BetaResponseFunctionToolCall:` - The name of the custom tool being called. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `JsonValue; type "custom_tool_call"constant` + - `class BetaResponseFunctionToolCallOutputItem:` - The type of the custom tool call. Always `custom_tool_call`. + - `AgentMessage` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `MultiAgentCall` - - `Optional id` + - `MultiAgentCallOutput` - The unique ID of the custom tool call in the OpenAI platform. + - `class BetaResponseFunctionWebSearch:` - - `Optional agent` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The agent that produced this item. + - `class BetaResponseComputerToolCall:` - - `String agentName` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The canonical name of the agent that produced this item. + - `class BetaResponseComputerToolCallOutputItem:` - - `Optional caller` + - `class BetaResponseReasoningItem:` - The execution context that produced this tool call. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `JsonValue;` + - `Program` - - `JsonValue; type "direct"constant` + - `ProgramOutput` - - `DIRECT("direct")` + - `class BetaResponseToolSearchCall:` - - `class Program:` + - `class BetaResponseToolSearchOutputItem:` - - `String callerId` + - `AdditionalTools` - The call ID of the program item that produced this tool call. + - `class BetaResponseCompactionItem:` - - `JsonValue; type "program"constant` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `PROGRAM("program")` + - `ImageGenerationCall` - - `Optional namespace` + - `class BetaResponseCodeInterpreterToolCall:` - The namespace of the custom tool being called. + A tool call to run code. - - `class BetaResponseCustomToolCallOutputItem:` + - `LocalShellCall` - The output of a custom tool call from your code, being sent back to the model. + - `LocalShellCallOutput` - - `String id` + - `class BetaResponseFunctionShellToolCall:` - The unique ID of the custom tool call output item. + A tool call that executes one or more shell commands in a managed environment. - - `Status status` + - `class BetaResponseFunctionShellToolCallOutput:` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The output of a shell tool call that was emitted. - - `IN_PROGRESS("in_progress")` + - `class BetaResponseApplyPatchToolCall:` - - `COMPLETED("completed")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `INCOMPLETE("incomplete")` + - `class BetaResponseApplyPatchToolCallOutput:` - - `Optional createdBy` + The output emitted by an apply patch tool call. - The identifier of the actor that created the item. + - `McpCall` + + - `McpListTools` + + - `McpApprovalRequest` + + - `McpApprovalResponse` + + - `class BetaResponseCustomToolCall:` + + A call to a custom tool created by the model. + + - `class BetaResponseCustomToolCallOutputItem:` + + The output of a custom tool call from your code, being sent back to the model. - `long outputIndex` @@ -105399,9 +117666,7 @@ public final class Main { The canonical name of the agent that produced this item. -### Beta Response Output Item Done Event - -- `class BetaResponseOutputItemDoneEvent:` + - `class BetaResponseOutputItemDoneEvent:` Emitted when an output item is marked done. @@ -105409,1348 +117674,1304 @@ public final class Main { The output item that was marked done. - - `class BetaResponseOutputMessage:` - - An output message from the model. - - - `String id` - - The unique ID of the output message. - - - `List content` - - The content of the output message. - - - `class BetaResponseOutputText:` - - A text output from the model. - - - `List annotations` - - The annotations of the text output. - - - `class FileCitation:` - - A citation to a file. - - - `String fileId` + - `long outputIndex` - The ID of the file. + The index of the output item that was marked done. - - `String filename` + - `long sequenceNumber` - The filename of the file cited. + The sequence number of this event. - - `long index` + - `JsonValue; type "response.output_item.done"constant` - The index of the file in the list of files. + The type of the event. Always `response.output_item.done`. - - `JsonValue; type "file_citation"constant` + - `RESPONSE_OUTPUT_ITEM_DONE("response.output_item.done")` - The type of the file citation. Always `file_citation`. + - `Optional agent` - - `FILE_CITATION("file_citation")` + The agent that owns this multi-agent streaming event. - - `class UrlCitation:` + - `String agentName` - A citation for a web resource used to generate a model response. + The canonical name of the agent that produced this item. - - `long endIndex` + - `class BetaResponseReasoningSummaryPartAddedEvent:` - The index of the last character of the URL citation in the message. + Emitted when a new reasoning summary part is added. - - `long startIndex` + - `String itemId` - The index of the first character of the URL citation in the message. + The ID of the item this summary part is associated with. - - `String title` + - `long outputIndex` - The title of the web resource. + The index of the output item this summary part is associated with. - - `JsonValue; type "url_citation"constant` + - `Part part` - The type of the URL citation. Always `url_citation`. + The summary part that was added. - - `URL_CITATION("url_citation")` + - `String text` - - `String url` + The text of the summary part. - The URL of the web resource. + - `JsonValue; type "summary_text"constant` - - `class ContainerFileCitation:` + The type of the summary part. Always `summary_text`. - A citation for a container file used to generate a model response. + - `SUMMARY_TEXT("summary_text")` - - `String containerId` + - `long sequenceNumber` - The ID of the container file. + The sequence number of this event. - - `long endIndex` + - `long summaryIndex` - The index of the last character of the container file citation in the message. + The index of the summary part within the reasoning summary. - - `String fileId` + - `JsonValue; type "response.reasoning_summary_part.added"constant` - The ID of the file. + The type of the event. Always `response.reasoning_summary_part.added`. - - `String filename` + - `RESPONSE_REASONING_SUMMARY_PART_ADDED("response.reasoning_summary_part.added")` - The filename of the container file cited. + - `Optional agent` - - `long startIndex` + The agent that owns this multi-agent streaming event. - The index of the first character of the container file citation in the message. + - `String agentName` - - `JsonValue; type "container_file_citation"constant` + The canonical name of the agent that produced this item. - The type of the container file citation. Always `container_file_citation`. + - `class BetaResponseReasoningSummaryPartDoneEvent:` - - `CONTAINER_FILE_CITATION("container_file_citation")` + Emitted when a reasoning summary part is completed. - - `class FilePath:` + - `String itemId` - A path to a file. + The ID of the item this summary part is associated with. - - `String fileId` + - `long outputIndex` - The ID of the file. + The index of the output item this summary part is associated with. - - `long index` + - `Part part` - The index of the file in the list of files. + The completed summary part. - - `JsonValue; type "file_path"constant` + - `String text` - The type of the file path. Always `file_path`. + The text of the summary part. - - `FILE_PATH("file_path")` + - `JsonValue; type "summary_text"constant` - - `String text` + The type of the summary part. Always `summary_text`. - The text output from the model. + - `SUMMARY_TEXT("summary_text")` - - `JsonValue; type "output_text"constant` + - `long sequenceNumber` - The type of the output text. Always `output_text`. + The sequence number of this event. - - `OUTPUT_TEXT("output_text")` + - `long summaryIndex` - - `Optional> logprobs` + The index of the summary part within the reasoning summary. - - `String token` + - `JsonValue; type "response.reasoning_summary_part.done"constant` - - `List bytes` + The type of the event. Always `response.reasoning_summary_part.done`. - - `double logprob` + - `RESPONSE_REASONING_SUMMARY_PART_DONE("response.reasoning_summary_part.done")` - - `List topLogprobs` + - `Optional agent` - - `String token` + The agent that owns this multi-agent streaming event. - - `List bytes` + - `String agentName` - - `double logprob` + The canonical name of the agent that produced this item. - - `class BetaResponseOutputRefusal:` + - `Optional status` - A refusal from the model. + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `String refusal` + - `INCOMPLETE("incomplete")` - The refusal explanation from the model. + - `class BetaResponseReasoningSummaryTextDeltaEvent:` - - `JsonValue; type "refusal"constant` + Emitted when a delta is added to a reasoning summary text. - The type of the refusal. Always `refusal`. + - `String delta` - - `REFUSAL("refusal")` + The text delta that was added to the summary. - - `JsonValue; role "assistant"constant` + - `String itemId` - The role of the output message. Always `assistant`. + The ID of the item this summary text delta is associated with. - - `ASSISTANT("assistant")` + - `long outputIndex` - - `Status status` + The index of the output item this summary text delta is associated with. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `long sequenceNumber` - - `IN_PROGRESS("in_progress")` + The sequence number of this event. - - `COMPLETED("completed")` + - `long summaryIndex` - - `INCOMPLETE("incomplete")` + The index of the summary part within the reasoning summary. - - `JsonValue; type "message"constant` + - `JsonValue; type "response.reasoning_summary_text.delta"constant` - The type of the output message. Always `message`. + The type of the event. Always `response.reasoning_summary_text.delta`. - - `MESSAGE("message")` + - `RESPONSE_REASONING_SUMMARY_TEXT_DELTA("response.reasoning_summary_text.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional 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")` - - - `class BetaResponseFileSearchToolCall:` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class BetaResponseReasoningSummaryTextDoneEvent:` - - `String id` + Emitted when a reasoning summary text is completed. - The unique ID of the file search tool call. + - `String itemId` - - `List queries` + The ID of the item this summary text is associated with. - The queries used to search for files. + - `long outputIndex` - - `Status status` + The index of the output item this summary text is associated with. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `long sequenceNumber` - - `IN_PROGRESS("in_progress")` + The sequence number of this event. - - `SEARCHING("searching")` + - `long summaryIndex` - - `COMPLETED("completed")` + The index of the summary part within the reasoning summary. - - `INCOMPLETE("incomplete")` + - `String text` - - `FAILED("failed")` + The full text of the completed reasoning summary. - - `JsonValue; type "file_search_call"constant` + - `JsonValue; type "response.reasoning_summary_text.done"constant` - The type of the file search tool call. Always `file_search_call`. + The type of the event. Always `response.reasoning_summary_text.done`. - - `FILE_SEARCH_CALL("file_search_call")` + - `RESPONSE_REASONING_SUMMARY_TEXT_DONE("response.reasoning_summary_text.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional> results` + - `class BetaResponseReasoningTextDeltaEvent:` - The results of the file search tool call. + Emitted when a delta is added to a reasoning text. - - `Optional attributes` + - `long contentIndex` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The index of the reasoning content part this delta is associated with. - - `String` + - `String delta` - - `double` + The text delta that was added to the reasoning content. - - `boolean` + - `String itemId` - - `Optional fileId` + The ID of the item this reasoning text delta is associated with. - The unique ID of the file. + - `long outputIndex` - - `Optional filename` + The index of the output item this reasoning text delta is associated with. - The name of the file. + - `long sequenceNumber` - - `Optional score` + The sequence number of this event. - The relevance score of the file - a value between 0 and 1. + - `JsonValue; type "response.reasoning_text.delta"constant` - - `Optional text` + The type of the event. Always `response.reasoning_text.delta`. - The text that was retrieved from the file. + - `RESPONSE_REASONING_TEXT_DELTA("response.reasoning_text.delta")` - - `class BetaResponseFunctionToolCall:` + - `Optional agent` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The agent that owns this multi-agent streaming event. - - `String arguments` + - `String agentName` - A JSON string of the arguments to pass to the function. + The canonical name of the agent that produced this item. - - `String callId` + - `class BetaResponseReasoningTextDoneEvent:` - The unique ID of the function tool call generated by the model. + Emitted when a reasoning text is completed. - - `String name` + - `long contentIndex` - The name of the function to run. + The index of the reasoning content part. - - `JsonValue; type "function_call"constant` + - `String itemId` - The type of the function tool call. Always `function_call`. + The ID of the item this reasoning text is associated with. - - `FUNCTION_CALL("function_call")` + - `long outputIndex` - - `Optional id` + The index of the output item this reasoning text is associated with. - The unique ID of the function tool call. + - `long sequenceNumber` - - `Optional agent` + The sequence number of this event. - The agent that produced this item. + - `String text` - - `String agentName` + The full text of the completed reasoning content. - The canonical name of the agent that produced this item. + - `JsonValue; type "response.reasoning_text.done"constant` - - `Optional caller` + The type of the event. Always `response.reasoning_text.done`. - The execution context that produced this tool call. + - `RESPONSE_REASONING_TEXT_DONE("response.reasoning_text.done")` - - `JsonValue;` + - `Optional agent` - - `JsonValue; type "direct"constant` + The agent that owns this multi-agent streaming event. - - `DIRECT("direct")` + - `String agentName` - - `class Program:` + The canonical name of the agent that produced this item. - - `String callerId` + - `class BetaResponseRefusalDeltaEvent:` + + Emitted when there is a partial refusal text. + + - `long contentIndex` - The call ID of the program item that produced this tool call. + The index of the content part that the refusal text is added to. - - `JsonValue; type "program"constant` + - `String delta` - - `PROGRAM("program")` + The refusal text that is added. - - `Optional namespace` + - `String itemId` - The namespace of the function to run. + The ID of the output item that the refusal text is added to. - - `Optional status` + - `long outputIndex` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The index of the output item that the refusal text is added to. - - `IN_PROGRESS("in_progress")` + - `long sequenceNumber` - - `COMPLETED("completed")` + The sequence number of this event. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "response.refusal.delta"constant` - - `class BetaResponseFunctionToolCallOutputItem:` + The type of the event. Always `response.refusal.delta`. - - `String id` + - `RESPONSE_REFUSAL_DELTA("response.refusal.delta")` - The unique ID of the function call tool output. + - `Optional agent` - - `String callId` + The agent that owns this multi-agent streaming event. - The unique ID of the function tool call generated by the model. + - `String agentName` - - `Output output` + The canonical name of the agent that produced this item. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `class BetaResponseRefusalDoneEvent:` - - `String` + Emitted when refusal text is finalized. - - `List` + - `long contentIndex` - - `class BetaResponseInputText:` + The index of the content part that the refusal text is finalized. - A text input to the model. + - `String itemId` - - `String text` + The ID of the output item that the refusal text is finalized. - The text input to the model. + - `long outputIndex` - - `JsonValue; type "input_text"constant` + The index of the output item that the refusal text is finalized. - The type of the input item. Always `input_text`. + - `String refusal` - - `INPUT_TEXT("input_text")` + The refusal text that is finalized. - - `Optional promptCacheBreakpoint` + - `long sequenceNumber` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The sequence number of this event. - - `JsonValue; mode "explicit"constant` + - `JsonValue; type "response.refusal.done"constant` - The breakpoint mode. Always `explicit`. + The type of the event. Always `response.refusal.done`. - - `EXPLICIT("explicit")` + - `RESPONSE_REFUSAL_DONE("response.refusal.done")` - - `class BetaResponseInputImage:` + - `Optional agent` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The agent that owns this multi-agent streaming event. - - `Detail detail` + - `String agentName` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The canonical name of the agent that produced this item. - - `LOW("low")` + - `class BetaResponseTextDeltaEvent:` - - `HIGH("high")` + Emitted when there is an additional text delta. - - `AUTO("auto")` + - `long contentIndex` - - `ORIGINAL("original")` + The index of the content part that the text delta was added to. - - `JsonValue; type "input_image"constant` + - `String delta` - The type of the input item. Always `input_image`. + The text delta that was added. - - `INPUT_IMAGE("input_image")` + - `String itemId` - - `Optional fileId` + The ID of the output item that the text delta was added to. - The ID of the file to be sent to the model. + - `List logprobs` - - `Optional imageUrl` + The log probabilities of the tokens in the delta. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `String token` - - `Optional promptCacheBreakpoint` + A possible text token. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `double logprob` - - `JsonValue; mode "explicit"constant` + The log probability of this token. - The breakpoint mode. Always `explicit`. + - `Optional> topLogprobs` - - `EXPLICIT("explicit")` + The log probabilities of up to 20 of the most likely tokens. - - `class BetaResponseInputFile:` + - `Optional token` - A file input to the model. + A possible text token. - - `JsonValue; type "input_file"constant` + - `Optional logprob` - The type of the input item. Always `input_file`. + The log probability of this token. - - `INPUT_FILE("input_file")` + - `long outputIndex` - - `Optional detail` + The index of the output item that the text delta was added to. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `long sequenceNumber` - - `AUTO("auto")` + The sequence number for this event. - - `LOW("low")` + - `JsonValue; type "response.output_text.delta"constant` - - `HIGH("high")` + The type of the event. Always `response.output_text.delta`. - - `Optional fileData` + - `RESPONSE_OUTPUT_TEXT_DELTA("response.output_text.delta")` - The content of the file to be sent to the model. + - `Optional agent` - - `Optional fileId` + The agent that owns this multi-agent streaming event. - The ID of the file to be sent to the model. + - `String agentName` - - `Optional fileUrl` + The canonical name of the agent that produced this item. - The URL of the file to be sent to the model. + - `class BetaResponseTextDoneEvent:` - - `Optional filename` + Emitted when text content is finalized. - The name of the file to be sent to the model. + - `long contentIndex` - - `Optional promptCacheBreakpoint` + The index of the content part that the text content is finalized. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String itemId` - - `JsonValue; mode "explicit"constant` + The ID of the output item that the text content is finalized. - The breakpoint mode. Always `explicit`. + - `List logprobs` - - `EXPLICIT("explicit")` + The log probabilities of the tokens in the delta. - - `Status status` + - `String token` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A possible text token. - - `IN_PROGRESS("in_progress")` + - `double logprob` - - `COMPLETED("completed")` + The log probability of this token. - - `INCOMPLETE("incomplete")` + - `Optional> topLogprobs` - - `JsonValue; type "function_call_output"constant` + The log probabilities of up to 20 of the most likely tokens. - The type of the function tool call output. Always `function_call_output`. + - `Optional token` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + A possible text token. - - `Optional agent` + - `Optional logprob` - The agent that produced this item. + The log probability of this token. - - `String agentName` + - `long outputIndex` - The canonical name of the agent that produced this item. + The index of the output item that the text content is finalized. - - `Optional caller` + - `long sequenceNumber` - The execution context that produced this tool call. + The sequence number for this event. - - `JsonValue;` + - `String text` - - `JsonValue; type "direct"constant` + The text content that is finalized. - The caller type. Always `direct`. + - `JsonValue; type "response.output_text.done"constant` - - `DIRECT("direct")` + The type of the event. Always `response.output_text.done`. - - `class Program:` + - `RESPONSE_OUTPUT_TEXT_DONE("response.output_text.done")` - - `String callerId` + - `Optional agent` - The call ID of the program item that produced this tool call. + The agent that owns this multi-agent streaming event. - - `JsonValue; type "program"constant` + - `String agentName` - The caller type. Always `program`. + The canonical name of the agent that produced this item. - - `PROGRAM("program")` + - `class BetaResponseWebSearchCallCompletedEvent:` - - `Optional createdBy` + Emitted when a web search call is completed. - The identifier of the actor that created the item. + - `String itemId` - - `AgentMessage` + Unique ID for the output item associated with the web search call. - - `String id` + - `long outputIndex` - The unique ID of the agent message. + The index of the output item that the web search call is associated with. - - `String author` + - `long sequenceNumber` - The sending agent identity. + The sequence number of the web search call being processed. - - `List content` + - `JsonValue; type "response.web_search_call.completed"constant` - Encrypted content sent between agents. + The type of the event. Always `response.web_search_call.completed`. - - `class BetaResponseInputText:` + - `RESPONSE_WEB_SEARCH_CALL_COMPLETED("response.web_search_call.completed")` - A text input to the model. + - `Optional agent` - - `class BetaResponseOutputText:` + The agent that owns this multi-agent streaming event. - A text output from the model. + - `String agentName` - - `class Text:` + The canonical name of the agent that produced this item. - A text content. + - `class BetaResponseWebSearchCallInProgressEvent:` - - `String text` + Emitted when a web search call is initiated. - - `JsonValue; type "text"constant` + - `String itemId` - - `TEXT("text")` + Unique ID for the output item associated with the web search call. - - `class SummaryText:` + - `long outputIndex` - A summary text from the model. + The index of the output item that the web search call is associated with. - - `String text` + - `long sequenceNumber` - A summary of the reasoning output from the model so far. + The sequence number of the web search call being processed. - - `JsonValue; type "summary_text"constant` + - `JsonValue; type "response.web_search_call.in_progress"constant` - The type of the object. Always `summary_text`. + The type of the event. Always `response.web_search_call.in_progress`. - - `SUMMARY_TEXT("summary_text")` + - `RESPONSE_WEB_SEARCH_CALL_IN_PROGRESS("response.web_search_call.in_progress")` - - `class ReasoningText:` + - `Optional agent` - Reasoning text from the model. + The agent that owns this multi-agent streaming event. - - `String text` + - `String agentName` - The reasoning text from the model. + The canonical name of the agent that produced this item. - - `JsonValue; type "reasoning_text"constant` + - `class BetaResponseWebSearchCallSearchingEvent:` - The type of the reasoning text. Always `reasoning_text`. + Emitted when a web search call is executing. - - `REASONING_TEXT("reasoning_text")` + - `String itemId` - - `class BetaResponseOutputRefusal:` + Unique ID for the output item associated with the web search call. - A refusal from the model. + - `long outputIndex` - - `class BetaResponseInputImage:` + The index of the output item that the web search call is associated with. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `long sequenceNumber` - - `class ComputerScreenshot:` + The sequence number of the web search call being processed. - A screenshot of a computer. + - `JsonValue; type "response.web_search_call.searching"constant` - - `Detail detail` + The type of the event. Always `response.web_search_call.searching`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `RESPONSE_WEB_SEARCH_CALL_SEARCHING("response.web_search_call.searching")` - - `LOW("low")` + - `Optional agent` - - `HIGH("high")` + The agent that owns this multi-agent streaming event. - - `AUTO("auto")` + - `String agentName` - - `ORIGINAL("original")` + The canonical name of the agent that produced this item. - - `Optional fileId` + - `class BetaResponseImageGenCallCompletedEvent:` - The identifier of an uploaded file that contains the screenshot. + Emitted when an image generation tool call has completed and the final image is available. - - `Optional imageUrl` + - `String itemId` - The URL of the screenshot image. + The unique identifier of the image generation item being processed. - - `JsonValue; type "computer_screenshot"constant` + - `long outputIndex` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The index of the output item in the response's output array. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `long sequenceNumber` - - `Optional promptCacheBreakpoint` + The sequence number of this event. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; type "response.image_generation_call.completed"constant` - - `JsonValue; mode "explicit"constant` + The type of the event. Always 'response.image_generation_call.completed'. - The breakpoint mode. Always `explicit`. + - `RESPONSE_IMAGE_GENERATION_CALL_COMPLETED("response.image_generation_call.completed")` - - `EXPLICIT("explicit")` + - `Optional agent` - - `class BetaResponseInputFile:` + The agent that owns this multi-agent streaming event. - A file input to the model. + - `String agentName` - - `class EncryptedContent:` + The canonical name of the agent that produced this item. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `class BetaResponseImageGenCallGeneratingEvent:` - - `String encryptedContent` + Emitted when an image generation tool call is actively generating an image (intermediate state). - Opaque encrypted content. + - `String itemId` - - `JsonValue; type "encrypted_content"constant` + The unique identifier of the image generation item being processed. - The type of the input item. Always `encrypted_content`. + - `long outputIndex` - - `ENCRYPTED_CONTENT("encrypted_content")` + The index of the output item in the response's output array. - - `String recipient` + - `long sequenceNumber` - The destination agent identity. + The sequence number of the image generation item being processed. - - `JsonValue; type "agent_message"constant` + - `JsonValue; type "response.image_generation_call.generating"constant` - The type of the item. Always `agent_message`. + The type of the event. Always 'response.image_generation_call.generating'. - - `AGENT_MESSAGE("agent_message")` + - `RESPONSE_IMAGE_GENERATION_CALL_GENERATING("response.image_generation_call.generating")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `MultiAgentCall` + - `class BetaResponseImageGenCallInProgressEvent:` - - `String id` + Emitted when an image generation tool call is in progress. - The unique ID of the multi-agent call item. + - `String itemId` - - `Action action` + The unique identifier of the image generation item being processed. - The multi-agent action to execute. + - `long outputIndex` - - `SPAWN_AGENT("spawn_agent")` + The index of the output item in the response's output array. - - `INTERRUPT_AGENT("interrupt_agent")` + - `long sequenceNumber` - - `LIST_AGENTS("list_agents")` + The sequence number of the image generation item being processed. - - `SEND_MESSAGE("send_message")` + - `JsonValue; type "response.image_generation_call.in_progress"constant` - - `FOLLOWUP_TASK("followup_task")` + The type of the event. Always 'response.image_generation_call.in_progress'. - - `WAIT_AGENT("wait_agent")` + - `RESPONSE_IMAGE_GENERATION_CALL_IN_PROGRESS("response.image_generation_call.in_progress")` - - `String arguments` + - `Optional agent` - The JSON string of arguments generated for the action. + The agent that owns this multi-agent streaming event. - - `String callId` + - `String agentName` - The unique ID linking this call to its output. + The canonical name of the agent that produced this item. - - `JsonValue; type "multi_agent_call"constant` + - `class BetaResponseImageGenCallPartialImageEvent:` - The type of the multi-agent call. Always `multi_agent_call`. + Emitted when a partial image is available during image generation streaming. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `String itemId` - - `Optional agent` + The unique identifier of the image generation item being processed. - The agent that produced this item. + - `long outputIndex` - - `String agentName` + The index of the output item in the response's output array. - The canonical name of the agent that produced this item. + - `String partialImageB64` - - `MultiAgentCallOutput` + Base64-encoded partial image data, suitable for rendering as an image. - - `String id` + - `long partialImageIndex` - The unique ID of the multi-agent call output item. + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `Action action` + - `long sequenceNumber` - The multi-agent action that produced this result. + The sequence number of the image generation item being processed. - - `SPAWN_AGENT("spawn_agent")` + - `JsonValue; type "response.image_generation_call.partial_image"constant` - - `INTERRUPT_AGENT("interrupt_agent")` + The type of the event. Always 'response.image_generation_call.partial_image'. - - `LIST_AGENTS("list_agents")` + - `RESPONSE_IMAGE_GENERATION_CALL_PARTIAL_IMAGE("response.image_generation_call.partial_image")` - - `SEND_MESSAGE("send_message")` + - `Optional agent` - - `FOLLOWUP_TASK("followup_task")` + The agent that owns this multi-agent streaming event. - - `WAIT_AGENT("wait_agent")` + - `String agentName` - - `String callId` + The canonical name of the agent that produced this item. - The unique ID of the multi-agent call. + - `class BetaResponseMcpCallArgumentsDeltaEvent:` - - `List output` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - Text output returned by the multi-agent action. + - `String delta` - - `List annotations` + A JSON string containing the partial update to the arguments for the MCP tool call. - The annotations of the text output. + - `String itemId` - - `String text` + The unique identifier of the MCP tool call item being processed. - The text output from the model. + - `long outputIndex` - - `JsonValue; type "output_text"constant` + The index of the output item in the response's output array. - The type of the output text. Always `output_text`. + - `long sequenceNumber` - - `Optional> logprobs` + The sequence number of this event. - - `JsonValue; type "multi_agent_call_output"constant` + - `JsonValue; type "response.mcp_call_arguments.delta"constant` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `RESPONSE_MCP_CALL_ARGUMENTS_DELTA("response.mcp_call_arguments.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseFunctionWebSearch:` + - `class BetaResponseMcpCallArgumentsDoneEvent:` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Emitted when the arguments for an MCP tool call are finalized. - - `String id` + - `String arguments` - The unique ID of the web search tool call. + A JSON string containing the finalized arguments for the MCP tool call. - - `Action action` + - `String itemId` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The unique identifier of the MCP tool call item being processed. - - `class Search:` + - `long outputIndex` - Action type "search" - Performs a web search query. + The index of the output item in the response's output array. - - `JsonValue; type "search"constant` + - `long sequenceNumber` - The action type. + The sequence number of this event. - - `SEARCH("search")` + - `JsonValue; type "response.mcp_call_arguments.done"constant` - - `Optional> queries` + The type of the event. Always 'response.mcp_call_arguments.done'. - The search queries. + - `RESPONSE_MCP_CALL_ARGUMENTS_DONE("response.mcp_call_arguments.done")` - - `Optional query` + - `Optional agent` - The search query. + The agent that owns this multi-agent streaming event. - - `Optional> sources` + - `String agentName` - The sources used in the search. + The canonical name of the agent that produced this item. - - `JsonValue; type "url"constant` + - `class BetaResponseMcpCallCompletedEvent:` - The type of source. Always `url`. + Emitted when an MCP tool call has completed successfully. - - `URL("url")` + - `String itemId` - - `String url` + The ID of the MCP tool call item that completed. - The URL of the source. + - `long outputIndex` - - `class OpenPage:` + The index of the output item that completed. - Action type "open_page" - Opens a specific URL from search results. + - `long sequenceNumber` - - `JsonValue; type "open_page"constant` + The sequence number of this event. - The action type. + - `JsonValue; type "response.mcp_call.completed"constant` - - `OPEN_PAGE("open_page")` + The type of the event. Always 'response.mcp_call.completed'. - - `Optional url` + - `RESPONSE_MCP_CALL_COMPLETED("response.mcp_call.completed")` - The URL opened by the model. + - `Optional agent` - - `class FindInPage:` + The agent that owns this multi-agent streaming event. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `String agentName` - - `String pattern` + The canonical name of the agent that produced this item. - The pattern or text to search for within the page. + - `class BetaResponseMcpCallFailedEvent:` - - `JsonValue; type "find_in_page"constant` + Emitted when an MCP tool call has failed. - The action type. + - `String itemId` - - `FIND_IN_PAGE("find_in_page")` + The ID of the MCP tool call item that failed. - - `String url` + - `long outputIndex` - The URL of the page searched for the pattern. + The index of the output item that failed. - - `Status status` + - `long sequenceNumber` - The status of the web search tool call. + The sequence number of this event. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "response.mcp_call.failed"constant` - - `SEARCHING("searching")` + The type of the event. Always 'response.mcp_call.failed'. - - `COMPLETED("completed")` + - `RESPONSE_MCP_CALL_FAILED("response.mcp_call.failed")` - - `FAILED("failed")` + - `Optional agent` - - `JsonValue; type "web_search_call"constant` + The agent that owns this multi-agent streaming event. - The type of the web search tool call. Always `web_search_call`. + - `String agentName` - - `WEB_SEARCH_CALL("web_search_call")` + The canonical name of the agent that produced this item. - - `Optional agent` + - `class BetaResponseMcpCallInProgressEvent:` - The agent that produced this item. + Emitted when an MCP tool call is in progress. - - `String agentName` + - `String itemId` - The canonical name of the agent that produced this item. + The unique identifier of the MCP tool call item being processed. - - `class BetaResponseComputerToolCall:` + - `long outputIndex` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The index of the output item in the response's output array. - - `String id` + - `long sequenceNumber` - The unique ID of the computer call. + The sequence number of this event. - - `String callId` + - `JsonValue; type "response.mcp_call.in_progress"constant` - An identifier used when responding to the tool call with output. + The type of the event. Always 'response.mcp_call.in_progress'. - - `List pendingSafetyChecks` + - `RESPONSE_MCP_CALL_IN_PROGRESS("response.mcp_call.in_progress")` - The pending safety checks for the computer call. + - `Optional agent` - - `String id` + The agent that owns this multi-agent streaming event. - The ID of the pending safety check. + - `String agentName` - - `Optional code` + The canonical name of the agent that produced this item. - The type of the pending safety check. + - `class BetaResponseMcpListToolsCompletedEvent:` - - `Optional message` + Emitted when the list of available MCP tools has been successfully retrieved. - Details about the pending safety check. + - `String itemId` - - `Status status` + The ID of the MCP tool call item that produced this output. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `long outputIndex` - - `IN_PROGRESS("in_progress")` + The index of the output item that was processed. - - `COMPLETED("completed")` + - `long sequenceNumber` - - `INCOMPLETE("incomplete")` + The sequence number of this event. - - `Type type` + - `JsonValue; type "response.mcp_list_tools.completed"constant` - The type of the computer call. Always `computer_call`. + The type of the event. Always 'response.mcp_list_tools.completed'. - - `COMPUTER_CALL("computer_call")` + - `RESPONSE_MCP_LIST_TOOLS_COMPLETED("response.mcp_list_tools.completed")` - - `Optional action` + - `Optional agent` - A click action. + The agent that owns this multi-agent streaming event. - - `Click` + - `String agentName` - - `Button button` + The canonical name of the agent that produced this item. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class BetaResponseMcpListToolsFailedEvent:` - - `LEFT("left")` + Emitted when the attempt to list available MCP tools has failed. - - `RIGHT("right")` + - `String itemId` - - `WHEEL("wheel")` + The ID of the MCP tool call item that failed. - - `BACK("back")` + - `long outputIndex` - - `FORWARD("forward")` + The index of the output item that failed. - - `JsonValue; type "click"constant` + - `long sequenceNumber` - Specifies the event type. For a click action, this property is always `click`. + The sequence number of this event. - - `CLICK("click")` + - `JsonValue; type "response.mcp_list_tools.failed"constant` - - `long x` + The type of the event. Always 'response.mcp_list_tools.failed'. - The x-coordinate where the click occurred. + - `RESPONSE_MCP_LIST_TOOLS_FAILED("response.mcp_list_tools.failed")` - - `long y` + - `Optional agent` - The y-coordinate where the click occurred. + The agent that owns this multi-agent streaming event. - - `Optional> keys` + - `String agentName` - The keys being held while clicking. + The canonical name of the agent that produced this item. - - `DoubleClick` + - `class BetaResponseMcpListToolsInProgressEvent:` - - `Optional> keys` + Emitted when the system is in the process of retrieving the list of available MCP tools. - The keys being held while double-clicking. + - `String itemId` - - `JsonValue; type "double_click"constant` + The ID of the MCP tool call item that is being processed. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `long outputIndex` - - `DOUBLE_CLICK("double_click")` + The index of the output item that is being processed. - - `long x` + - `long sequenceNumber` - The x-coordinate where the double click occurred. + The sequence number of this event. - - `long y` + - `JsonValue; type "response.mcp_list_tools.in_progress"constant` - The y-coordinate where the double click occurred. + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `Drag` + - `RESPONSE_MCP_LIST_TOOLS_IN_PROGRESS("response.mcp_list_tools.in_progress")` - - `List path` + - `Optional agent` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The agent that owns this multi-agent streaming event. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `String agentName` - - `long x` + The canonical name of the agent that produced this item. - The x-coordinate. + - `class BetaResponseOutputTextAnnotationAddedEvent:` - - `long y` + Emitted when an annotation is added to output text content. - The y-coordinate. + - `JsonValue annotation` - - `JsonValue; type "drag"constant` + The annotation object being added. (See annotation schema for details.) - Specifies the event type. For a drag action, this property is always set to `drag`. + - `long annotationIndex` - - `DRAG("drag")` + The index of the annotation within the content part. - - `Optional> keys` + - `long contentIndex` - The keys being held while dragging the mouse. + The index of the content part within the output item. - - `Keypress` + - `String itemId` - - `List keys` + The unique identifier of the item to which the annotation is being added. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `long outputIndex` - - `JsonValue; type "keypress"constant` + The index of the output item in the response's output array. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `long sequenceNumber` - - `KEYPRESS("keypress")` + The sequence number of this event. - - `Move` + - `JsonValue; type "response.output_text.annotation.added"constant` - - `JsonValue; type "move"constant` + The type of the event. Always 'response.output_text.annotation.added'. - Specifies the event type. For a move action, this property is always set to `move`. + - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` - - `MOVE("move")` + - `Optional agent` - - `long x` + The agent that owns this multi-agent streaming event. - The x-coordinate to move to. + - `String agentName` - - `long y` + The canonical name of the agent that produced this item. - The y-coordinate to move to. + - `class BetaResponseQueuedEvent:` - - `Optional> keys` + Emitted when a response is queued and waiting to be processed. - The keys being held while moving the mouse. + - `BetaResponse response` - - `JsonValue;` + The full response object that is queued. - - `JsonValue; type "screenshot"constant` + - `long sequenceNumber` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The sequence number for this event. - - `SCREENSHOT("screenshot")` + - `JsonValue; type "response.queued"constant` - - `Scroll` + The type of the event. Always 'response.queued'. - - `long scrollX` + - `RESPONSE_QUEUED("response.queued")` - The horizontal scroll distance. + - `Optional agent` - - `long scrollY` + The agent that owns this multi-agent streaming event. - The vertical scroll distance. + - `String agentName` - - `JsonValue; type "scroll"constant` + The canonical name of the agent that produced this item. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `class BetaResponseCustomToolCallInputDeltaEvent:` - - `SCROLL("scroll")` + Event representing a delta (partial update) to the input of a custom tool call. - - `long x` + - `String delta` - The x-coordinate where the scroll occurred. + The incremental input data (delta) for the custom tool call. - - `long y` + - `String itemId` - The y-coordinate where the scroll occurred. + Unique identifier for the API item associated with this event. - - `Optional> keys` + - `long outputIndex` - The keys being held while scrolling. + The index of the output this delta applies to. - - `Type` + - `long sequenceNumber` - - `String text` + The sequence number of this event. - The text to type. + - `JsonValue; type "response.custom_tool_call_input.delta"constant` - - `JsonValue; type "type"constant` + The event type identifier. - Specifies the event type. For a type action, this property is always set to `type`. + - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DELTA("response.custom_tool_call_input.delta")` - - `TYPE("type")` + - `Optional agent` - - `JsonValue;` + The agent that owns this multi-agent streaming event. - - `JsonValue; type "wait"constant` + - `String agentName` - Specifies the event type. For a wait action, this property is always set to `wait`. + The canonical name of the agent that produced this item. - - `WAIT("wait")` + - `class BetaResponseCustomToolCallInputDoneEvent:` - - `Optional> actions` + Event indicating that input for a custom tool call is complete. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `String input` - - `Click` + The complete input data for the custom tool call. - - `DoubleClick` + - `String itemId` - - `Drag` + Unique identifier for the API item associated with this event. - - `Keypress` + - `long outputIndex` - - `Move` + The index of the output this event applies to. - - `JsonValue;` + - `long sequenceNumber` - - `Scroll` + The sequence number of this event. - - `Type` + - `JsonValue; type "response.custom_tool_call_input.done"constant` - - `JsonValue;` + The event type identifier. + + - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DONE("response.custom_tool_call_input.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem:` - - - `String id` - - The unique ID of the computer call tool output. - - - `String callId` +### Beta Response Text Config - The ID of the computer tool call that produced the output. +- `class BetaResponseTextConfig:` - - `BetaResponseComputerToolCallOutputScreenshot output` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - A computer screenshot image used with the computer use tool. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `JsonValue; type "computer_screenshot"constant` + - `Optional format` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + An object specifying the format that the model must output. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional fileId` + The default format is `{ "type": "text" }` with no additional options. - The identifier of an uploaded file that contains the screenshot. + **Not recommended for gpt-4o and newer models:** - - `Optional imageUrl` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The URL of the screenshot image. + - `JsonValue;` - - `Status status` + - `JsonValue; type "text"constant` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The type of response format being defined. Always `text`. - - `COMPLETED("completed")` + - `TEXT("text")` - - `INCOMPLETE("incomplete")` + - `class BetaResponseFormatTextJsonSchemaConfig:` - - `FAILED("failed")` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `IN_PROGRESS("in_progress")` + - `String name` - - `JsonValue; type "computer_call_output"constant` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The type of the computer tool call output. Always `computer_call_output`. + - `Schema schema` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `Optional> acknowledgedSafetyChecks` + - `JsonValue; type "json_schema"constant` - The safety checks reported by the API that have been acknowledged by the - developer. + The type of response format being defined. Always `json_schema`. - - `String id` + - `JSON_SCHEMA("json_schema")` - The ID of the pending safety check. + - `Optional description` - - `Optional code` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The type of the pending safety check. + - `Optional strict` - - `Optional message` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - Details about the pending safety check. + - `JsonValue;` - - `Optional agent` + - `JsonValue; type "json_object"constant` - The agent that produced this item. + The type of response format being defined. Always `json_object`. - - `String agentName` + - `JSON_OBJECT("json_object")` - The canonical name of the agent that produced this item. + - `Optional verbosity` - - `Optional createdBy` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The identifier of the actor that created the item. + - `LOW("low")` - - `class BetaResponseReasoningItem:` + - `MEDIUM("medium")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `HIGH("high")` - - `String id` +### Beta Response Text Delta Event - The unique identifier of the reasoning content. +- `class BetaResponseTextDeltaEvent:` - - `List summary` + Emitted when there is an additional text delta. - Reasoning summary content. + - `long contentIndex` - - `String text` + The index of the content part that the text delta was added to. - A summary of the reasoning output from the model so far. + - `String delta` - - `JsonValue; type "summary_text"constant` + The text delta that was added. - The type of the object. Always `summary_text`. + - `String itemId` - - `SUMMARY_TEXT("summary_text")` + The ID of the output item that the text delta was added to. - - `JsonValue; type "reasoning"constant` + - `List logprobs` - The type of the object. Always `reasoning`. + The log probabilities of the tokens in the delta. - - `REASONING("reasoning")` + - `String token` - - `Optional agent` + A possible text token. - The agent that produced this item. + - `double logprob` - - `String agentName` + The log probability of this token. - The canonical name of the agent that produced this item. + - `Optional> topLogprobs` - - `Optional> content` + The log probabilities of up to 20 of the most likely tokens. - Reasoning text content. + - `Optional token` - - `String text` + A possible text token. - The reasoning text from the model. + - `Optional logprob` - - `JsonValue; type "reasoning_text"constant` + The log probability of this token. - The type of the reasoning text. Always `reasoning_text`. + - `long outputIndex` - - `REASONING_TEXT("reasoning_text")` + The index of the output item that the text delta was added to. - - `Optional encryptedContent` + - `long sequenceNumber` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The sequence number for this event. - - `Optional status` + - `JsonValue; type "response.output_text.delta"constant` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the event. Always `response.output_text.delta`. - - `IN_PROGRESS("in_progress")` + - `RESPONSE_OUTPUT_TEXT_DELTA("response.output_text.delta")` - - `COMPLETED("completed")` + - `Optional agent` - - `INCOMPLETE("incomplete")` + The agent that owns this multi-agent streaming event. - - `Program` + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - The unique ID of the program item. +### Beta Response Text Done Event - - `String callId` +- `class BetaResponseTextDoneEvent:` - The stable call ID of the program item. + Emitted when text content is finalized. - - `String code` + - `long contentIndex` - The JavaScript source executed by programmatic tool calling. + The index of the content part that the text content is finalized. - - `String fingerprint` + - `String itemId` - Opaque program replay fingerprint that must be round-tripped. + The ID of the output item that the text content is finalized. - - `JsonValue; type "program"constant` + - `List logprobs` - The type of the item. Always `program`. + The log probabilities of the tokens in the delta. - - `PROGRAM("program")` + - `String token` - - `Optional agent` + A possible text token. - The agent that produced this item. + - `double logprob` - - `String agentName` + The log probability of this token. - The canonical name of the agent that produced this item. + - `Optional> topLogprobs` - - `ProgramOutput` + The log probabilities of up to 20 of the most likely tokens. - - `String id` + - `Optional token` - The unique ID of the program output item. + A possible text token. - - `String callId` + - `Optional logprob` - The call ID of the program item. + The log probability of this token. - - `String result` + - `long outputIndex` - The result produced by the program item. + The index of the output item that the text content is finalized. - - `Status status` + - `long sequenceNumber` - The terminal status of the program output item. + The sequence number for this event. - - `COMPLETED("completed")` + - `String text` - - `INCOMPLETE("incomplete")` + The text content that is finalized. - - `JsonValue; type "program_output"constant` + - `JsonValue; type "response.output_text.done"constant` - The type of the item. Always `program_output`. + The type of the event. Always `response.output_text.done`. - - `PROGRAM_OUTPUT("program_output")` + - `RESPONSE_OUTPUT_TEXT_DONE("response.output_text.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall:` +### Beta Response Tool Search Call + +- `class BetaResponseToolSearchCall:` - `String id` @@ -106800,7 +119021,9 @@ public final class Main { The identifier of the actor that created the item. - - `class BetaResponseToolSearchOutputItem:` +### Beta Response Tool Search Output Item + +- `class BetaResponseToolSearchOutputItem:` - `String id` @@ -106939,7 +119162,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -106996,7 +119223,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -107909,1609 +120140,1342 @@ public final class Main { The identifier of the actor that created the item. - - `AdditionalTools` - - - `String id` - - The unique ID of the additional tools item. - - - `Role role` - - The role that provided the additional tools. - - - `UNKNOWN("unknown")` - - - `USER("user")` - - - `ASSISTANT("assistant")` - - - `SYSTEM("system")` - - - `CRITIC("critic")` - - - `DISCRIMINATOR("discriminator")` - - - `DEVELOPER("developer")` +### Beta Response Tool Search Output Item Param - - `TOOL("tool")` +- `class BetaResponseToolSearchOutputItemParam:` - `List tools` - The additional tool definitions made available at this item. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool:` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class BetaFileSearchTool:` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class BetaComputerTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaComputerUsePreviewTool:` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class BetaWebSearchTool:` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `Mcp` - - - `CodeInterpreter` - - - `JsonValue;` - - - `ImageGeneration` - - - `JsonValue;` - - - `class BetaFunctionShellTool:` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool:` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class BetaNamespaceTool:` - - Groups function/custom tools under a shared namespace. - - - `class BetaToolSearchTool:` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class BetaWebSearchPreviewTool:` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class BetaApplyPatchTool:` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `JsonValue; type "additional_tools"constant` - - The type of the item. Always `additional_tools`. - - - `ADDITIONAL_TOOLS("additional_tools")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCompactionItem:` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `String id` - - The unique ID of the compaction item. - - - `String encryptedContent` - - The encrypted content that was produced by compaction. - - - `JsonValue; type "compaction"constant` - - The type of the item. Always `compaction`. - - - `COMPACTION("compaction")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `ImageGenerationCall` - - - `String id` - - The unique ID of the image generation call. - - - `Optional 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. - - - `String id` - - The unique ID of the code interpreter tool call. - - - `Optional code` - - The code to run, or null if not available. - - - `String containerId` - - The ID of the container used to run the code. - - - `Optional> 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `LocalShellCall` - - - `String id` - - The unique ID of the local shell call. - - - `Action action` - - Execute a shell command on the server. - - - `List 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 timeoutMs` - - Optional timeout in milliseconds for the command. - - - `Optional user` - - Optional user to run the command as. - - - `Optional 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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `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 agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional status` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `IN_PROGRESS("in_progress")` - - - `COMPLETED("completed")` + - `String name` - - `INCOMPLETE("incomplete")` + The name of the function to call. - - `class BetaResponseFunctionShellToolCall:` + - `Optional parameters` - A tool call that executes one or more shell commands in a managed environment. + A JSON schema object describing the parameters of the function. - - `String id` + - `Optional strict` - The unique ID of the shell tool call. Populated when this item is returned via API. + Whether strict parameter validation is enforced for this function tool. - - `Action action` + - `JsonValue; type "function"constant` - The shell commands and limits that describe how to run the tool call. + The type of the function tool. Always `function`. - - `List commands` + - `FUNCTION("function")` - - `Optional maxOutputLength` + - `Optional> allowedCallers` - Optional maximum number of characters to return from each command. + The tool invocation context(s). - - `Optional timeoutMs` + - `DIRECT("direct")` - Optional timeout in milliseconds for the commands. + - `PROGRAMMATIC("programmatic")` - - `String callId` + - `Optional deferLoading` - The unique ID of the shell tool call generated by the model. + Whether this function is deferred and loaded via tool search. - - `Optional environment` + - `Optional description` - Represents the use of a local environment to perform shell actions. + A description of the function. Used by the model to determine whether or not to call the function. - - `class BetaResponseLocalEnvironment:` + - `Optional outputSchema` - Represents the use of a local environment to perform shell actions. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `JsonValue; type "local"constant` + - `class BetaFileSearchTool:` - The environment type. Always `local`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `LOCAL("local")` + - `JsonValue; type "file_search"constant` - - `class BetaResponseContainerReference:` + The type of the file search tool. Always `file_search`. - Represents a container created with /v1/containers. + - `FILE_SEARCH("file_search")` - - `String containerId` + - `List vectorStoreIds` - - `JsonValue; type "container_reference"constant` + The IDs of the vector stores to search. - The environment type. Always `container_reference`. + - `Optional filters` - - `CONTAINER_REFERENCE("container_reference")` + A filter to apply. - - `Status status` + - `class ComparisonFilter:` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `IN_PROGRESS("in_progress")` + - `String key` - - `COMPLETED("completed")` + The key to compare against the value. - - `INCOMPLETE("incomplete")` + - `Type type` - - `JsonValue; type "shell_call"constant` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The type of the item. Always `shell_call`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `SHELL_CALL("shell_call")` + - `EQ("eq")` - - `Optional agent` + - `NE("ne")` - The agent that produced this item. + - `GT("gt")` - - `String agentName` + - `GTE("gte")` - The canonical name of the agent that produced this item. + - `LT("lt")` - - `Optional caller` + - `LTE("lte")` - The execution context that produced this tool call. + - `IN("in")` - - `JsonValue;` + - `NIN("nin")` - - `JsonValue; type "direct"constant` + - `Value value` - - `DIRECT("direct")` + The value to compare against the attribute key; supports string, number, or boolean types. - - `class Program:` + - `String` - - `String callerId` + - `double` - The call ID of the program item that produced this tool call. + - `boolean` - - `JsonValue; type "program"constant` + - `List` - - `PROGRAM("program")` + - `String` - - `Optional createdBy` + - `double` - The ID of the entity that created this tool call. + - `class CompoundFilter:` - - `class BetaResponseFunctionShellToolCallOutput:` + Combine multiple filters using `and` or `or`. - The output of a shell tool call that was emitted. + - `List filters` - - `String id` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The unique ID of the shell call output. Populated when this item is returned via API. + - `class ComparisonFilter:` - - `String callId` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique ID of the shell tool call generated by the model. + - `String key` - - `Optional maxOutputLength` + The key to compare against the value. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `Type type` - - `List output` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - An array of shell call output contents + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Outcome outcome` + - `EQ("eq")` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `NE("ne")` - - `JsonValue;` + - `GT("gt")` - - `JsonValue; type "timeout"constant` + - `GTE("gte")` - The outcome type. Always `timeout`. + - `LT("lt")` - - `TIMEOUT("timeout")` + - `LTE("lte")` - - `class Exit:` + - `IN("in")` - Indicates that the shell commands finished and returned an exit code. + - `NIN("nin")` - - `long exitCode` + - `Value value` - Exit code from the shell process. + The value to compare against the attribute key; supports string, number, or boolean types. - - `JsonValue; type "exit"constant` + - `String` - The outcome type. Always `exit`. + - `double` - - `EXIT("exit")` + - `boolean` - - `String stderr` + - `List` - The standard error output that was captured. + - `String` - - `String stdout` + - `double` - The standard output that was captured. + - `JsonValue` - - `Optional createdBy` + - `Type type` - The identifier of the actor that created the item. + Type of operation: `and` or `or`. - - `Status status` + - `AND("and")` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `OR("or")` - - `IN_PROGRESS("in_progress")` + - `Optional maxNumResults` - - `COMPLETED("completed")` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `INCOMPLETE("incomplete")` + - `Optional rankingOptions` - - `JsonValue; type "shell_call_output"constant` + Ranking options for search. - The type of the shell call output. Always `shell_call_output`. + - `Optional hybridSearch` - - `SHELL_CALL_OUTPUT("shell_call_output")` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `Optional agent` + - `double embeddingWeight` - The agent that produced this item. + The weight of the embedding in the reciprocal ranking fusion. - - `String agentName` + - `double textWeight` - The canonical name of the agent that produced this item. + The weight of the text in the reciprocal ranking fusion. - - `Optional caller` + - `Optional ranker` - The execution context that produced this tool call. + The ranker to use for the file search. - - `JsonValue;` + - `AUTO("auto")` - - `JsonValue; type "direct"constant` + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `DIRECT("direct")` + - `Optional scoreThreshold` - - `class Program:` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `String callerId` + - `class BetaComputerTool:` - The call ID of the program item that produced this tool call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; type "program"constant` + - `JsonValue; type "computer"constant` - - `PROGRAM("program")` + The type of the computer tool. Always `computer`. - - `Optional createdBy` + - `COMPUTER("computer")` - The identifier of the actor that created the item. + - `class BetaComputerUsePreviewTool:` - - `class BetaResponseApplyPatchToolCall:` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A tool call that applies file diffs by creating, deleting, or updating files. + - `long displayHeight` - - `String id` + The height of the computer display. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `long displayWidth` - - `String callId` + The width of the computer display. - The unique ID of the apply patch tool call generated by the model. + - `Environment environment` - - `Operation operation` + The type of computer environment to control. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `WINDOWS("windows")` - - `class CreateFile:` + - `MAC("mac")` - Instruction describing how to create a file via the apply_patch tool. + - `LINUX("linux")` - - `String diff` + - `UBUNTU("ubuntu")` - Diff to apply. + - `BROWSER("browser")` - - `String path` + - `JsonValue; type "computer_use_preview"constant` - Path of the file to create. + The type of the computer use tool. Always `computer_use_preview`. - - `JsonValue; type "create_file"constant` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - Create a new file with the provided diff. + - `class BetaWebSearchTool:` - - `CREATE_FILE("create_file")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class DeleteFile:` + - `Type type` - Instruction describing how to delete a file via the apply_patch tool. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `String path` + - `WEB_SEARCH("web_search")` - Path of the file to delete. + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `JsonValue; type "delete_file"constant` + - `Optional filters` - Delete the specified file. + Filters for the search. - - `DELETE_FILE("delete_file")` + - `Optional> allowedDomains` - - `class UpdateFile:` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Instruction describing how to update a file via the apply_patch tool. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `String diff` + - `Optional searchContextSize` - Diff to apply. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `String path` + - `LOW("low")` - Path of the file to update. + - `MEDIUM("medium")` - - `JsonValue; type "update_file"constant` + - `HIGH("high")` - Update an existing file with the provided diff. + - `Optional userLocation` - - `UPDATE_FILE("update_file")` + The approximate location of the user. - - `Status status` + - `Optional city` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Free text input for the city of the user, e.g. `San Francisco`. - - `IN_PROGRESS("in_progress")` + - `Optional country` - - `COMPLETED("completed")` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `JsonValue; type "apply_patch_call"constant` + - `Optional region` - The type of the item. Always `apply_patch_call`. + Free text input for the region of the user, e.g. `California`. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `Optional timezone` - - `Optional agent` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The agent that produced this item. + - `Optional type` - - `String agentName` + The type of location approximation. Always `approximate`. - The canonical name of the agent that produced this item. + - `APPROXIMATE("approximate")` - - `Optional caller` + - `Mcp` - The execution context that produced this tool call. + - `String serverLabel` - - `JsonValue;` + A label for this MCP server, used to identify it in tool calls. - - `JsonValue; type "direct"constant` + - `JsonValue; type "mcp"constant` - - `DIRECT("direct")` + The type of the MCP tool. Always `mcp`. - - `class Program:` + - `MCP("mcp")` - - `String callerId` + - `Optional> allowedCallers` - The call ID of the program item that produced this tool call. + The tool invocation context(s). - - `JsonValue; type "program"constant` + - `DIRECT("direct")` - - `PROGRAM("program")` + - `PROGRAMMATIC("programmatic")` - - `Optional createdBy` + - `Optional allowedTools` - The ID of the entity that created this tool call. + List of allowed tool names or a filter object. - - `class BetaResponseApplyPatchToolCallOutput:` + - `List` - The output emitted by an apply patch tool call. + - `class McpToolFilter:` - - `String id` + A filter object to specify which tools are allowed. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `Optional readOnly` - - `String callId` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The unique ID of the apply patch tool call generated by the model. + - `Optional> toolNames` - - `Status status` + List of allowed tool names. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `Optional authorization` - - `COMPLETED("completed")` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `FAILED("failed")` + - `Optional connectorId` - - `JsonValue; type "apply_patch_call_output"constant` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The type of the item. Always `apply_patch_call_output`. + Currently supported `connector_id` values are: - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `Optional agent` + - `CONNECTOR_DROPBOX("connector_dropbox")` - The agent that produced this item. + - `CONNECTOR_GMAIL("connector_gmail")` - - `String agentName` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - The canonical name of the agent that produced this item. + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `Optional caller` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - The execution context that produced this tool call. + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `JsonValue;` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `JsonValue; type "direct"constant` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `DIRECT("direct")` + - `Optional deferLoading` - - `class Program:` + Whether this MCP tool is deferred and discovered via tool search. - - `String callerId` + - `Optional headers` - The call ID of the program item that produced this tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `JsonValue; type "program"constant` + - `Optional requireApproval` - - `PROGRAM("program")` + Specify which of the MCP server's tools require approval. - - `Optional createdBy` + - `class McpToolApprovalFilter:` - The ID of the entity that created this tool call output. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `Optional output` + - `Optional always` - Optional textual output returned by the apply patch tool. + A filter object to specify which tools are allowed. - - `McpCall` + - `Optional readOnly` - - `String id` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The unique ID of the tool call. + - `Optional> toolNames` - - `String arguments` + List of allowed tool names. - A JSON string of the arguments passed to the tool. + - `Optional never` - - `String name` + A filter object to specify which tools are allowed. - The name of the tool that was run. + - `Optional readOnly` - - `String serverLabel` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The label of the MCP server running the tool. + - `Optional> toolNames` - - `JsonValue; type "mcp_call"constant` + List of allowed tool names. - The type of the item. Always `mcp_call`. + - `enum McpToolApprovalSetting:` - - `MCP_CALL("mcp_call")` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `Optional agent` + - `ALWAYS("always")` - The agent that produced this item. + - `NEVER("never")` - - `String agentName` + - `Optional serverDescription` - The canonical name of the agent that produced this item. + Optional description of the MCP server, used to provide more context. - - `Optional approvalRequestId` + - `Optional serverUrl` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `Optional error` + - `Optional tunnelId` - The error from the tool call, if any. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `Optional output` + - `CodeInterpreter` - The output from the tool call. + - `Container container` - - `Optional status` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `String` - - `IN_PROGRESS("in_progress")` + - `class CodeInterpreterToolAuto:` - - `COMPLETED("completed")` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "auto"constant` - - `CALLING("calling")` + Always `auto`. - - `FAILED("failed")` + - `AUTO("auto")` - - `McpListTools` + - `Optional> fileIds` - - `String id` + An optional list of uploaded files to make available to your code. - The unique ID of the list. + - `Optional memoryLimit` - - `String serverLabel` + The memory limit for the code interpreter container. - The label of the MCP server. + - `_1G("1g")` - - `List tools` + - `_4G("4g")` - The tools available on the server. + - `_16G("16g")` - - `JsonValue inputSchema` + - `_64G("64g")` - The JSON schema describing the tool's input. + - `Optional networkPolicy` - - `String name` + Network access policy for the container. - The name of the tool. + - `class BetaContainerNetworkPolicyDisabled:` - - `Optional annotations` + - `JsonValue; type "disabled"constant` - Additional annotations about the tool. + Disable outbound network access. Always `disabled`. - - `Optional description` + - `DISABLED("disabled")` - The description of the tool. + - `class BetaContainerNetworkPolicyAllowlist:` - - `JsonValue; type "mcp_list_tools"constant` + - `List allowedDomains` - The type of the item. Always `mcp_list_tools`. + A list of allowed domains when type is `allowlist`. - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `JsonValue; type "allowlist"constant` - - `Optional agent` + Allow outbound network access only to specified domains. Always `allowlist`. - The agent that produced this item. + - `ALLOWLIST("allowlist")` - - `String agentName` + - `Optional> domainSecrets` - The canonical name of the agent that produced this item. + Optional domain-scoped secrets for allowlisted domains. - - `Optional error` + - `String domain` - Error message if the server could not list tools. + The domain associated with the secret. - - `McpApprovalRequest` + - `String name` - - `String id` + The name of the secret to inject for the domain. - The unique ID of the approval request. + - `String value` - - `String arguments` + The secret value to inject for the domain. - A JSON string of arguments for the tool. + - `JsonValue; type "code_interpreter"constant` - - `String name` + The type of the code interpreter tool. Always `code_interpreter`. - The name of the tool to run. + - `CODE_INTERPRETER("code_interpreter")` - - `String serverLabel` + - `Optional> allowedCallers` - The label of the MCP server making the request. + The tool invocation context(s). - - `JsonValue; type "mcp_approval_request"constant` + - `DIRECT("direct")` - The type of the item. Always `mcp_approval_request`. + - `PROGRAMMATIC("programmatic")` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `JsonValue;` - - `Optional agent` + - `JsonValue; type "programmatic_tool_calling"constant` - The agent that produced this item. + The type of the tool. Always `programmatic_tool_calling`. - - `String agentName` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - The canonical name of the agent that produced this item. + - `ImageGeneration` - - `McpApprovalResponse` + - `JsonValue; type "image_generation"constant` - - `String id` + The type of the image generation tool. Always `image_generation`. - The unique ID of the approval response + - `IMAGE_GENERATION("image_generation")` - - `String approvalRequestId` + - `Optional action` - The ID of the approval request being answered. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `boolean approve` + - `GENERATE("generate")` - Whether the request was approved. + - `EDIT("edit")` - - `JsonValue; type "mcp_approval_response"constant` + - `AUTO("auto")` - The type of the item. Always `mcp_approval_response`. + - `Optional background` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + 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. - - `Optional agent` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - The agent that produced this item. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `String agentName` + - `TRANSPARENT("transparent")` - The canonical name of the agent that produced this item. + - `OPAQUE("opaque")` - - `Optional reason` + - `AUTO("auto")` - Optional reason for the decision. + - `Optional inputFidelity` - - `class BetaResponseCustomToolCall:` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - A call to a custom tool created by the model. + - `HIGH("high")` - - `String callId` + - `LOW("low")` - An identifier used to map this custom tool call to a tool call output. + - `Optional inputImageMask` - - `String input` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The input for the custom tool call generated by the model. + - `Optional fileId` - - `String name` + File ID for the mask image. - The name of the custom tool being called. + - `Optional imageUrl` - - `JsonValue; type "custom_tool_call"constant` + Base64-encoded mask image. - The type of the custom tool call. Always `custom_tool_call`. + - `Optional model` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + The image generation model to use. Default: `gpt-image-1`. - - `Optional id` + - `GPT_IMAGE_1("gpt-image-1")` - The unique ID of the custom tool call in the OpenAI platform. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `Optional agent` + - `GPT_IMAGE_2("gpt-image-2")` - The agent that produced this item. + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `String agentName` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - The canonical name of the agent that produced this item. + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `Optional caller` + - `Optional moderation` - The execution context that produced this tool call. + Moderation level for the generated image. Default: `auto`. - - `JsonValue;` + - `AUTO("auto")` - - `JsonValue; type "direct"constant` + - `LOW("low")` - - `DIRECT("direct")` + - `Optional outputCompression` - - `class Program:` + Compression level for the output image. Default: 100. - - `String callerId` + - `Optional outputFormat` - The call ID of the program item that produced this tool call. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `JsonValue; type "program"constant` + - `PNG("png")` - - `PROGRAM("program")` + - `WEBP("webp")` - - `Optional namespace` + - `JPEG("jpeg")` - The namespace of the custom tool being called. + - `Optional partialImages` - - `class BetaResponseCustomToolCallOutputItem:` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The output of a custom tool call from your code, being sent back to the model. + - `Optional quality` - - `String id` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The unique ID of the custom tool call output item. + - `LOW("low")` - - `Status status` + - `MEDIUM("medium")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `HIGH("high")` - - `IN_PROGRESS("in_progress")` + - `AUTO("auto")` - - `COMPLETED("completed")` + - `Optional size` - - `INCOMPLETE("incomplete")` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `Optional createdBy` + - `_1024X1024("1024x1024")` - The identifier of the actor that created the item. + - `_1024X1536("1024x1536")` - - `long outputIndex` + - `_1536X1024("1536x1024")` - The index of the output item that was marked done. + - `AUTO("auto")` - - `long sequenceNumber` + - `JsonValue;` - The sequence number of this event. + - `JsonValue; type "local_shell"constant` - - `JsonValue; type "response.output_item.done"constant` + The type of the local shell tool. Always `local_shell`. - The type of the event. Always `response.output_item.done`. + - `LOCAL_SHELL("local_shell")` - - `RESPONSE_OUTPUT_ITEM_DONE("response.output_item.done")` + - `class BetaFunctionShellTool:` - - `Optional agent` + A tool that allows the model to execute shell commands. - The agent that owns this multi-agent streaming event. + - `JsonValue; type "shell"constant` - - `String agentName` + The type of the shell tool. Always `shell`. - The canonical name of the agent that produced this item. + - `SHELL("shell")` -### Beta Response Output Message + - `Optional> allowedCallers` -- `class BetaResponseOutputMessage:` + The tool invocation context(s). - An output message from the model. + - `DIRECT("direct")` - - `String id` + - `PROGRAMMATIC("programmatic")` - The unique ID of the output message. + - `Optional environment` - - `List content` + - `class BetaContainerAuto:` - The content of the output message. + - `JsonValue; type "container_auto"constant` - - `class BetaResponseOutputText:` + Automatically creates a container for this request - A text output from the model. + - `CONTAINER_AUTO("container_auto")` - - `List annotations` + - `Optional> fileIds` - The annotations of the text output. + An optional list of uploaded files to make available to your code. - - `class FileCitation:` + - `Optional memoryLimit` - A citation to a file. + The memory limit for the container. - - `String fileId` + - `_1G("1g")` - The ID of the file. + - `_4G("4g")` - - `String filename` + - `_16G("16g")` - The filename of the file cited. + - `_64G("64g")` - - `long index` + - `Optional networkPolicy` - The index of the file in the list of files. + Network access policy for the container. - - `JsonValue; type "file_citation"constant` + - `class BetaContainerNetworkPolicyDisabled:` - The type of the file citation. Always `file_citation`. + - `class BetaContainerNetworkPolicyAllowlist:` - - `FILE_CITATION("file_citation")` + - `Optional> skills` - - `class UrlCitation:` + An optional list of skills referenced by id or inline data. - A citation for a web resource used to generate a model response. + - `class BetaSkillReference:` - - `long endIndex` + - `String skillId` - The index of the last character of the URL citation in the message. + The ID of the referenced skill. - - `long startIndex` + - `JsonValue; type "skill_reference"constant` - The index of the first character of the URL citation in the message. + References a skill created with the /v1/skills endpoint. - - `String title` + - `SKILL_REFERENCE("skill_reference")` - The title of the web resource. + - `Optional version` - - `JsonValue; type "url_citation"constant` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The type of the URL citation. Always `url_citation`. + - `class BetaInlineSkill:` - - `URL_CITATION("url_citation")` + - `String description` - - `String url` + The description of the skill. - The URL of the web resource. + - `String name` - - `class ContainerFileCitation:` + The name of the skill. - A citation for a container file used to generate a model response. + - `BetaInlineSkillSource source` - - `String containerId` + Inline skill payload - The ID of the container file. + - `String data` - - `long endIndex` + Base64-encoded skill zip bundle. - The index of the last character of the container file citation in the message. + - `JsonValue; mediaType "application/zip"constant` - - `String fileId` + The media type of the inline skill payload. Must be `application/zip`. - The ID of the file. + - `APPLICATION_ZIP("application/zip")` - - `String filename` + - `JsonValue; type "base64"constant` - The filename of the container file cited. + The type of the inline skill source. Must be `base64`. - - `long startIndex` + - `BASE64("base64")` - The index of the first character of the container file citation in the message. + - `JsonValue; type "inline"constant` - - `JsonValue; type "container_file_citation"constant` + Defines an inline skill for this request. - The type of the container file citation. Always `container_file_citation`. + - `INLINE("inline")` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `class BetaLocalEnvironment:` - - `class FilePath:` + - `JsonValue; type "local"constant` - A path to a file. + Use a local computer environment. - - `String fileId` + - `LOCAL("local")` - The ID of the file. + - `Optional> skills` - - `long index` + An optional list of skills. - The index of the file in the list of files. + - `String description` - - `JsonValue; type "file_path"constant` + The description of the skill. - The type of the file path. Always `file_path`. + - `String name` - - `FILE_PATH("file_path")` + The name of the skill. - - `String text` + - `String path` - The text output from the model. + The path to the directory containing the skill. - - `JsonValue; type "output_text"constant` + - `class BetaContainerReference:` - The type of the output text. Always `output_text`. + - `String containerId` - - `OUTPUT_TEXT("output_text")` + The ID of the referenced container. - - `Optional> logprobs` + - `JsonValue; type "container_reference"constant` - - `String token` + References a container created with the /v1/containers endpoint - - `List bytes` + - `CONTAINER_REFERENCE("container_reference")` - - `double logprob` + - `class BetaCustomTool:` - - `List topLogprobs` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `String token` + - `String name` - - `List bytes` + The name of the custom tool, used to identify it in tool calls. - - `double logprob` + - `JsonValue; type "custom"constant` - - `class BetaResponseOutputRefusal:` + The type of the custom tool. Always `custom`. - A refusal from the model. + - `CUSTOM("custom")` - - `String refusal` + - `Optional> allowedCallers` - The refusal explanation from the model. + The tool invocation context(s). - - `JsonValue; type "refusal"constant` + - `DIRECT("direct")` - The type of the refusal. Always `refusal`. + - `PROGRAMMATIC("programmatic")` - - `REFUSAL("refusal")` + - `Optional deferLoading` - - `JsonValue; role "assistant"constant` + Whether this tool should be deferred and discovered via tool search. - The role of the output message. Always `assistant`. + - `Optional description` - - `ASSISTANT("assistant")` + Optional description of the custom tool, used to provide more context. - - `Status status` + - `Optional format` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The input format for the custom tool. Default is unconstrained text. - - `IN_PROGRESS("in_progress")` + - `JsonValue;` - - `COMPLETED("completed")` + - `JsonValue; type "text"constant` - - `INCOMPLETE("incomplete")` + Unconstrained text format. Always `text`. - - `JsonValue; type "message"constant` + - `TEXT("text")` - The type of the output message. Always `message`. + - `class Grammar:` - - `MESSAGE("message")` + A grammar defined by the user. - - `Optional agent` + - `String definition` - The agent that produced this item. + The grammar definition. - - `String agentName` + - `Syntax syntax` - The canonical name of the agent that produced this item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `Optional phase` + - `LARK("lark")` - 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. + - `REGEX("regex")` - - `COMMENTARY("commentary")` + - `JsonValue; type "grammar"constant` -### Beta Response Output Refusal + Grammar format. Always `grammar`. -- `class BetaResponseOutputRefusal:` + - `GRAMMAR("grammar")` - A refusal from the model. + - `class BetaNamespaceTool:` - - `String refusal` + Groups function/custom tools under a shared namespace. - The refusal explanation from the model. + - `String description` - - `JsonValue; type "refusal"constant` + A description of the namespace shown to the model. - The type of the refusal. Always `refusal`. + - `String name` - - `REFUSAL("refusal")` + The namespace name used in tool calls (for example, `crm`). -### Beta Response Output Text + - `List tools` -- `class BetaResponseOutputText:` + The function/custom tools available inside this namespace. - A text output from the model. + - `class Function:` - - `List annotations` + - `String name` - The annotations of the text output. + - `JsonValue; type "function"constant` - - `class FileCitation:` + - `FUNCTION("function")` - A citation to a file. + - `Optional> allowedCallers` - - `String fileId` + The tool invocation context(s). - The ID of the file. + - `DIRECT("direct")` - - `String filename` + - `PROGRAMMATIC("programmatic")` - The filename of the file cited. + - `Optional deferLoading` - - `long index` + Whether this function should be deferred and discovered via tool search. - The index of the file in the list of files. + - `Optional description` - - `JsonValue; type "file_citation"constant` + - `Optional outputSchema` - The type of the file citation. Always `file_citation`. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `FILE_CITATION("file_citation")` + - `Optional parameters` - - `class UrlCitation:` + - `Optional strict` - A citation for a web resource used to generate a model response. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `long endIndex` + - `class BetaCustomTool:` - The index of the last character of the URL citation in the message. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `long startIndex` + - `JsonValue; type "namespace"constant` - The index of the first character of the URL citation in the message. + The type of the tool. Always `namespace`. - - `String title` + - `NAMESPACE("namespace")` - The title of the web resource. + - `class BetaToolSearchTool:` - - `JsonValue; type "url_citation"constant` + Hosted or BYOT tool search configuration for deferred tools. - The type of the URL citation. Always `url_citation`. + - `JsonValue; type "tool_search"constant` - - `URL_CITATION("url_citation")` + The type of the tool. Always `tool_search`. - - `String url` + - `TOOL_SEARCH("tool_search")` - The URL of the web resource. + - `Optional description` - - `class ContainerFileCitation:` + Description shown to the model for a client-executed tool search tool. - A citation for a container file used to generate a model response. + - `Optional execution` - - `String containerId` + Whether tool search is executed by the server or by the client. - The ID of the container file. + - `SERVER("server")` - - `long endIndex` + - `CLIENT("client")` - The index of the last character of the container file citation in the message. + - `Optional parameters` - - `String fileId` + Parameter schema for a client-executed tool search tool. - The ID of the file. + - `class BetaWebSearchPreviewTool:` - - `String filename` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The filename of the container file cited. + - `Type type` - - `long startIndex` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The index of the first character of the container file citation in the message. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `JsonValue; type "container_file_citation"constant` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - The type of the container file citation. Always `container_file_citation`. + - `Optional> searchContentTypes` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `TEXT("text")` - - `class FilePath:` + - `IMAGE("image")` - A path to a file. + - `Optional searchContextSize` - - `String fileId` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The ID of the file. + - `LOW("low")` - - `long index` + - `MEDIUM("medium")` - The index of the file in the list of files. + - `HIGH("high")` - - `JsonValue; type "file_path"constant` + - `Optional userLocation` - The type of the file path. Always `file_path`. + The user's location. - - `FILE_PATH("file_path")` + - `JsonValue; type "approximate"constant` - - `String text` + The type of location approximation. Always `approximate`. - The text output from the model. + - `APPROXIMATE("approximate")` - - `JsonValue; type "output_text"constant` + - `Optional city` - The type of the output text. Always `output_text`. + Free text input for the city of the user, e.g. `San Francisco`. - - `OUTPUT_TEXT("output_text")` + - `Optional country` - - `Optional> logprobs` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `String token` + - `Optional region` - - `List bytes` + Free text input for the region of the user, e.g. `California`. - - `double logprob` + - `Optional timezone` - - `List topLogprobs` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `String token` + - `class BetaApplyPatchTool:` - - `List bytes` + Allows the assistant to create, delete, or update files using unified diffs. - - `double logprob` + - `JsonValue; type "apply_patch"constant` -### Beta Response Output Text Annotation Added Event + The type of the tool. Always `apply_patch`. -- `class BetaResponseOutputTextAnnotationAddedEvent:` + - `APPLY_PATCH("apply_patch")` - Emitted when an annotation is added to output text content. + - `Optional> allowedCallers` - - `JsonValue annotation` + The tool invocation context(s). - The annotation object being added. (See annotation schema for details.) + - `DIRECT("direct")` - - `long annotationIndex` + - `PROGRAMMATIC("programmatic")` - The index of the annotation within the content part. + - `JsonValue; type "tool_search_output"constant` - - `long contentIndex` + The item type. Always `tool_search_output`. - The index of the content part within the output item. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `String itemId` + - `Optional id` - The unique identifier of the item to which the annotation is being added. + The unique ID of this tool search output. - - `long outputIndex` + - `Optional agent` - The index of the output item in the response's output array. + The agent that produced this item. - - `long sequenceNumber` + - `String agentName` - The sequence number of this event. + The canonical name of the agent that produced this item. - - `JsonValue; type "response.output_text.annotation.added"constant` + - `Optional callId` - The type of the event. Always 'response.output_text.annotation.added'. + The unique ID of the tool search call generated by the model. - - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` + - `Optional execution` - - `Optional agent` + Whether tool search was executed by the server or by the client. - The agent that owns this multi-agent streaming event. + - `SERVER("server")` - - `String agentName` + - `CLIENT("client")` - The canonical name of the agent that produced this item. + - `Optional status` -### Beta Response Prompt + The status of the tool search output. -- `class BetaResponsePrompt:` + - `IN_PROGRESS("in_progress")` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `COMPLETED("completed")` - - `String id` + - `INCOMPLETE("incomplete")` - The unique identifier of the prompt template to use. +### Beta Response Usage - - `Optional variables` +- `class BetaResponseUsage:` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `String` + - `long inputTokens` - - `class BetaResponseInputText:` + The number of input tokens. - A text input to the model. + - `InputTokensDetails inputTokensDetails` - - `String text` + A detailed breakdown of the input tokens. - The text input to the model. + - `long cacheWriteTokens` - - `JsonValue; type "input_text"constant` + The number of input tokens that were written to the cache. - The type of the input item. Always `input_text`. + - `long cachedTokens` - - `INPUT_TEXT("input_text")` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `Optional promptCacheBreakpoint` + - `long outputTokens` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The number of output tokens. - - `JsonValue; mode "explicit"constant` + - `OutputTokensDetails outputTokensDetails` - The breakpoint mode. Always `explicit`. + A detailed breakdown of the output tokens. - - `EXPLICIT("explicit")` + - `long reasoningTokens` - - `class BetaResponseInputImage:` + The number of reasoning tokens. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `long totalTokens` - - `Detail detail` + The total number of tokens used. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +### Beta Response Web Search Call Completed Event - - `LOW("low")` +- `class BetaResponseWebSearchCallCompletedEvent:` - - `HIGH("high")` + Emitted when a web search call is completed. - - `AUTO("auto")` + - `String itemId` - - `ORIGINAL("original")` + Unique ID for the output item associated with the web search call. - - `JsonValue; type "input_image"constant` + - `long outputIndex` - The type of the input item. Always `input_image`. + The index of the output item that the web search call is associated with. - - `INPUT_IMAGE("input_image")` + - `long sequenceNumber` - - `Optional fileId` + The sequence number of the web search call being processed. - The ID of the file to be sent to the model. + - `JsonValue; type "response.web_search_call.completed"constant` - - `Optional imageUrl` + The type of the event. Always `response.web_search_call.completed`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `RESPONSE_WEB_SEARCH_CALL_COMPLETED("response.web_search_call.completed")` - - `Optional promptCacheBreakpoint` + - `Optional agent` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The agent that owns this multi-agent streaming event. - - `JsonValue; mode "explicit"constant` + - `String agentName` - The breakpoint mode. Always `explicit`. + The canonical name of the agent that produced this item. - - `EXPLICIT("explicit")` +### Beta Response Web Search Call In Progress Event - - `class BetaResponseInputFile:` +- `class BetaResponseWebSearchCallInProgressEvent:` - A file input to the model. + Emitted when a web search call is initiated. - - `JsonValue; type "input_file"constant` + - `String itemId` - The type of the input item. Always `input_file`. + Unique ID for the output item associated with the web search call. - - `INPUT_FILE("input_file")` + - `long outputIndex` - - `Optional detail` + The index of the output item that the web search call is associated with. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `long sequenceNumber` - - `AUTO("auto")` + The sequence number of the web search call being processed. - - `LOW("low")` + - `JsonValue; type "response.web_search_call.in_progress"constant` - - `HIGH("high")` + The type of the event. Always `response.web_search_call.in_progress`. - - `Optional fileData` + - `RESPONSE_WEB_SEARCH_CALL_IN_PROGRESS("response.web_search_call.in_progress")` - The content of the file to be sent to the model. + - `Optional agent` - - `Optional fileId` + The agent that owns this multi-agent streaming event. - The ID of the file to be sent to the model. + - `String agentName` - - `Optional fileUrl` + The canonical name of the agent that produced this item. - The URL of the file to be sent to the model. +### Beta Response Web Search Call Searching Event - - `Optional filename` +- `class BetaResponseWebSearchCallSearchingEvent:` - The name of the file to be sent to the model. + Emitted when a web search call is executing. - - `Optional promptCacheBreakpoint` + - `String itemId` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Unique ID for the output item associated with the web search call. - - `JsonValue; mode "explicit"constant` + - `long outputIndex` - The breakpoint mode. Always `explicit`. + The index of the output item that the web search call is associated with. - - `EXPLICIT("explicit")` + - `long sequenceNumber` - - `Optional version` + The sequence number of the web search call being processed. - Optional version of the prompt template. + - `JsonValue; type "response.web_search_call.searching"constant` -### Beta Response Queued Event + The type of the event. Always `response.web_search_call.searching`. -- `class BetaResponseQueuedEvent:` + - `RESPONSE_WEB_SEARCH_CALL_SEARCHING("response.web_search_call.searching")` - Emitted when a response is queued and waiting to be processed. + - `Optional agent` - - `BetaResponse response` + The agent that owns this multi-agent streaming event. - The full response object that is queued. + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - Unique identifier for this Response. +### Beta Responses Client Event - - `double createdAt` +- `class BetaResponsesClientEvent: A class that can be one of several variants.union` - Unix timestamp (in seconds) of when this Response was created. + Client events accepted by the Responses WebSocket server. - - `Optional error` + - `ResponseCreate` - An error object returned when the model fails to generate a Response. + - `JsonValue; type "response.create"constant` - - `Code code` + The type of the client event. Always `response.create`. - The error code for the response. + - `RESPONSE_CREATE("response.create")` - - `SERVER_ERROR("server_error")` + - `Optional background` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `INVALID_PROMPT("invalid_prompt")` + - `Optional> contextManagement` - - `BIO_POLICY("bio_policy")` + Context management configuration for this request. - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + - `String type` - - `INVALID_IMAGE("invalid_image")` + The context management entry type. Currently only 'compaction' is supported. - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + - `Optional compactThreshold` - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + Token threshold at which compaction should be triggered for this entry. - - `INVALID_IMAGE_URL("invalid_image_url")` + - `Optional conversation` - - `IMAGE_TOO_LARGE("image_too_large")` + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - - `IMAGE_TOO_SMALL("image_too_small")` + - `String` - - `IMAGE_PARSE_ERROR("image_parse_error")` + - `class BetaResponseConversationParam:` - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + The conversation that this response belongs to. - - `INVALID_IMAGE_MODE("invalid_image_mode")` + - `String id` - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + The unique ID of the conversation. - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + - `Optional> include` - - `EMPTY_IMAGE_FILE("empty_image_file")` + Specify additional output data to include in the model response. Currently supported values are: - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` - - `String message` + - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` - A human-readable description of the error. + - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` - - `Optional incompleteDetails` + - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` - Details about why the response is incomplete. + - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` - - `Optional reason` + - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` - The reason why the response is incomplete. + - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` - - `CONTENT_FILTER("content_filter")` + - `Optional input` - - `Optional instructions` + Text, image, or file inputs to the model, used to generate a response. - A system (or developer) message inserted into the model's context. + Learn more: - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) - `String` @@ -109665,6 +121629,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `Optional type` The type of the message input. Always `message`. @@ -109920,6 +121886,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -111056,7 +123024,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -111113,7 +123085,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -113195,6 +125171,22 @@ public final class Main { The canonical name of the agent that produced this item. + - `Optional instructions` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `Optional maxOutputTokens` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `Optional maxToolCalls` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `Optional metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -113204,7 +125196,7 @@ public final class Main { Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `Model model` + - `Optional model` Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance @@ -113357,629 +125349,1354 @@ public final class Main { - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `GPT_4_32K_0613("gpt-4-32k-0613")` + + - `GPT_3_5_TURBO("gpt-3.5-turbo")` + + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + + - `O1_PRO("o1-pro")` + + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + + - `O3_PRO("o3-pro")` + + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + + - `O3_DEEP_RESEARCH("o3-deep-research")` + + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + + - `COMPUTER_USE_PREVIEW("computer-use-preview")` + + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + + - `GPT_5_CODEX("gpt-5-codex")` + + - `GPT_5_PRO("gpt-5-pro")` + + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + + - `Optional moderation` + + Configuration for running moderation on the input and output of this response. + + - `String model` + + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + + - `Optional policy` + + The policy to apply to moderated response input and output. + + - `Optional input` + + The moderation policy for the response input. + + - `Mode mode` + + - `SCORE("score")` + + - `BLOCK("block")` + + - `Optional output` + + The moderation policy for the response output. + + - `Mode mode` + + - `SCORE("score")` + + - `BLOCK("block")` + + - `Optional multiAgent` + + Configuration for server-hosted multi-agent execution. + + - `boolean enabled` + + Whether to enable server-hosted multi-agent execution for this response. + + - `Optional maxConcurrentSubagents` + + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + + - `Optional parallelToolCalls` + + Whether to allow the model to run tool calls in parallel. + + - `Optional previousResponseId` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `Optional prompt` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `String id` + + The unique identifier of the prompt template to use. + + - `Optional variables` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `String` + + - `class BetaResponseInputText:` + + A text input to the model. + + - `class BetaResponseInputImage:` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile:` + + A file input to the model. + + - `Optional version` + + Optional version of the prompt template. + + - `Optional promptCacheKey` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `Optional promptCacheOptions` + + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + + - `Optional mode` + + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + + - `IMPLICIT("implicit")` + + - `EXPLICIT("explicit")` + + - `Optional ttl` + + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + + - `_30M("30m")` + + - `Optional promptCacheRetention` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `IN_MEMORY("in_memory")` + + - `_24H("24h")` + + - `Optional reasoning` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `Optional context` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `AUTO("auto")` + + - `CURRENT_TURN("current_turn")` + + - `ALL_TURNS("all_turns")` + + - `Optional effort` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `NONE("none")` + + - `MINIMAL("minimal")` + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `XHIGH("xhigh")` + + - `MAX("max")` + + - `Optional generateSummary` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `AUTO("auto")` + + - `CONCISE("concise")` + + - `DETAILED("detailed")` + + - `Optional mode` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `STANDARD("standard")` + + - `PRO("pro")` + + - `Optional summary` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `AUTO("auto")` + + - `CONCISE("concise")` + + - `DETAILED("detailed")` + + - `Optional safetyIdentifier` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `Optional serviceTier` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `AUTO("auto")` + + - `DEFAULT("default")` + + - `FLEX("flex")` + + - `SCALE("scale")` + + - `PRIORITY("priority")` + + - `Optional store` + + Whether to store the generated model response for later retrieval via + API. + + - `Optional stream` + + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. + + - `Optional streamOptions` + + Options for streaming responses. Only set this when you set `stream: true`. + + - `Optional includeObfuscation` + + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. + + - `Optional temperature` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + + - `Optional text` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `Optional format` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `JsonValue;` + + - `JsonValue; type "text"constant` + + The type of response format being defined. Always `text`. + + - `TEXT("text")` + + - `class BetaResponseFormatTextJsonSchemaConfig:` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `String name` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `Schema schema` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `JsonValue; type "json_schema"constant` + + The type of response format being defined. Always `json_schema`. + + - `JSON_SCHEMA("json_schema")` + + - `Optional description` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `Optional strict` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). + + - `JsonValue;` + + - `JsonValue; type "json_object"constant` + + The type of response format being defined. Always `json_object`. + + - `JSON_OBJECT("json_object")` + + - `Optional verbosity` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `LOW("low")` + + - `MEDIUM("medium")` + + - `HIGH("high")` + + - `Optional toolChoice` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `enum BetaToolChoiceOptions:` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `NONE("none")` + + - `AUTO("auto")` + + - `REQUIRED("required")` + + - `class BetaToolChoiceAllowed:` + + Constrains the tools available to the model to a pre-defined set. + + - `Mode mode` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `AUTO("auto")` + + - `REQUIRED("required")` + + - `List tools` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `JsonValue; type "allowed_tools"constant` + + Allowed tool configuration type. Always `allowed_tools`. + + - `ALLOWED_TOOLS("allowed_tools")` + + - `class BetaToolChoiceTypes:` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `Type type` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `FILE_SEARCH("file_search")` + + - `WEB_SEARCH_PREVIEW("web_search_preview")` + + - `COMPUTER("computer")` + + - `COMPUTER_USE_PREVIEW("computer_use_preview")` + + - `COMPUTER_USE("computer_use")` + + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + + - `IMAGE_GENERATION("image_generation")` + + - `CODE_INTERPRETER("code_interpreter")` + + - `class BetaToolChoiceFunction:` + + Use this option to force the model to call a specific function. + + - `String name` + + The name of the function to call. + + - `JsonValue; type "function"constant` + + For function calling, the type is always `function`. + + - `FUNCTION("function")` + + - `class BetaToolChoiceMcp:` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `String serverLabel` + + The label of the MCP server to use. + + - `JsonValue; type "mcp"constant` + + For MCP tools, the type is always `mcp`. + + - `MCP("mcp")` + + - `Optional name` + + The name of the tool to call on the server. + + - `class BetaToolChoiceCustom:` + + Use this option to force the model to call a specific custom tool. + + - `String name` + + The name of the custom tool to call. + + - `JsonValue; type "custom"constant` + + For custom tool calling, the type is always `custom`. + + - `CUSTOM("custom")` + + - `JsonValue;` + + - `JsonValue; type "programmatic_tool_calling"constant` + + The tool to call. Always `programmatic_tool_calling`. + + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + + - `class BetaToolChoiceApplyPatch:` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `JsonValue; type "apply_patch"constant` + + The tool to call. Always `apply_patch`. + + - `APPLY_PATCH("apply_patch")` + + - `class BetaToolChoiceShell:` + + Forces the model to call the shell tool when a tool call is required. + + - `JsonValue; type "shell"constant` + + The tool to call. Always `shell`. + + - `SHELL("shell")` + + - `Optional> tools` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool:` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` + + - `CodeInterpreter` + + - `JsonValue;` + + - `ImageGeneration` + + - `JsonValue;` + + - `class BetaFunctionShellTool:` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool:` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool:` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool:` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool:` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool:` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `Optional topLogprobs` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `Optional topP` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `Optional truncation` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `AUTO("auto")` + + - `DISABLED("disabled")` + + - `Optional user` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `class BetaResponseInjectEvent:` + + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. + + - `List input` + + Input items to inject into the active response. + + - `class BetaEasyInputMessage:` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `Message` + + - `class BetaResponseOutputMessage:` + + An output message from the model. + + - `class BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `class BetaResponseComputerToolCall:` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `ComputerCallOutput` + + - `class BetaResponseFunctionWebSearch:` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `class BetaResponseFunctionToolCall:` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `FunctionCallOutput` + + - `AgentMessage` + + - `MultiAgentCall` + + - `MultiAgentCallOutput` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `ToolSearchCall` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `class BetaResponseToolSearchOutputItemParam:` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `AdditionalTools` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `class BetaResponseReasoningItem:` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `class BetaResponseCompactionItemParam:` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `O1_PRO("o1-pro")` + - `ImageGenerationCall` - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - `class BetaResponseCodeInterpreterToolCall:` - - `O3_PRO("o3-pro")` + A tool call to run code. - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `LocalShellCall` - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `LocalShellCallOutput` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + - `ShellCall` - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + - `ShellCallOutput` - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `ApplyPatchCall` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + - `ApplyPatchCallOutput` - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `McpListTools` - - `GPT_5_CODEX("gpt-5-codex")` + - `McpApprovalRequest` - - `GPT_5_PRO("gpt-5-pro")` + - `McpApprovalResponse` - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `McpCall` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + - `class BetaResponseCustomToolCallOutput:` - - `JsonValue; object_ "response"constant` + The output of a custom tool call from your code, being sent back to the model. - The object type of this resource - always set to `response`. + - `class BetaResponseCustomToolCall:` - - `RESPONSE("response")` + A call to a custom tool created by the model. - - `List output` + - `CompactionTrigger` - An array of content items generated by the model. + - `ItemReference` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `Program` - - `class BetaResponseOutputMessage:` + - `ProgramOutput` - An output message from the model. + - `String responseId` - - `class BetaResponseFileSearchToolCall:` + The ID of the active response that should receive the input. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `JsonValue; type "response.inject"constant` - - `class BetaResponseFunctionToolCall:` + The event discriminator. Always `response.inject`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `RESPONSE_INJECT("response.inject")` - - `class BetaResponseFunctionToolCallOutputItem:` +### Beta Responses Server Event - - `String id` +- `class BetaResponsesServerEvent: A class that can be one of several variants.union` - The unique ID of the function call tool output. + Server events emitted by the Responses WebSocket server. - - `String callId` + - `class BetaResponseAudioDeltaEvent:` - The unique ID of the function tool call generated by the model. + Emitted when there is a partial audio response. - - `Output output` + - `String delta` - The output from the function call generated by your code. - Can be a string or an list of output content. + A chunk of Base64 encoded response audio bytes. - - `String` + - `long sequenceNumber` - - `List` + A sequence number for this chunk of the stream response. - - `class BetaResponseInputText:` + - `JsonValue; type "response.audio.delta"constant` - A text input to the model. + The type of the event. Always `response.audio.delta`. - - `class BetaResponseInputImage:` + - `RESPONSE_AUDIO_DELTA("response.audio.delta")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Optional agent` - - `class BetaResponseInputFile:` + The agent that owns this multi-agent streaming event. - A file input to the model. + - `String agentName` - - `Status status` + The canonical name of the agent that produced this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class BetaResponseAudioDoneEvent:` - - `IN_PROGRESS("in_progress")` + Emitted when the audio response is complete. - - `COMPLETED("completed")` + - `long sequenceNumber` - - `INCOMPLETE("incomplete")` + The sequence number of the delta. - - `JsonValue; type "function_call_output"constant` + - `JsonValue; type "response.audio.done"constant` - The type of the function tool call output. Always `function_call_output`. + The type of the event. Always `response.audio.done`. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `RESPONSE_AUDIO_DONE("response.audio.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` + - `class BetaResponseAudioTranscriptDeltaEvent:` - The execution context that produced this tool call. + Emitted when there is a partial transcript of audio. - - `JsonValue;` + - `String delta` - - `JsonValue; type "direct"constant` + The partial transcript of the audio response. - The caller type. Always `direct`. + - `long sequenceNumber` - - `DIRECT("direct")` + The sequence number of this event. - - `class Program:` + - `JsonValue; type "response.audio.transcript.delta"constant` - - `String callerId` + The type of the event. Always `response.audio.transcript.delta`. - The call ID of the program item that produced this tool call. + - `RESPONSE_AUDIO_TRANSCRIPT_DELTA("response.audio.transcript.delta")` - - `JsonValue; type "program"constant` + - `Optional agent` - The caller type. Always `program`. + The agent that owns this multi-agent streaming event. - - `PROGRAM("program")` + - `String agentName` - - `Optional createdBy` + The canonical name of the agent that produced this item. - The identifier of the actor that created the item. + - `class BetaResponseAudioTranscriptDoneEvent:` - - `AgentMessage` + Emitted when the full audio transcript is completed. - - `String id` + - `long sequenceNumber` - The unique ID of the agent message. + The sequence number of this event. - - `String author` + - `JsonValue; type "response.audio.transcript.done"constant` - The sending agent identity. + The type of the event. Always `response.audio.transcript.done`. - - `List content` + - `RESPONSE_AUDIO_TRANSCRIPT_DONE("response.audio.transcript.done")` - Encrypted content sent between agents. + - `Optional agent` - - `class BetaResponseInputText:` + The agent that owns this multi-agent streaming event. - A text input to the model. + - `String agentName` - - `class BetaResponseOutputText:` + The canonical name of the agent that produced this item. - A text output from the model. + - `class BetaResponseCodeInterpreterCallCodeDeltaEvent:` - - `class Text:` + Emitted when a partial code snippet is streamed by the code interpreter. - A text content. + - `String delta` - - `String text` + The partial code snippet being streamed by the code interpreter. - - `JsonValue; type "text"constant` + - `String itemId` - - `TEXT("text")` + The unique identifier of the code interpreter tool call item. - - `class SummaryText:` + - `long outputIndex` - A summary text from the model. + The index of the output item in the response for which the code is being streamed. - - `String text` + - `long sequenceNumber` - A summary of the reasoning output from the model so far. + The sequence number of this event, used to order streaming events. - - `JsonValue; type "summary_text"constant` + - `JsonValue; type "response.code_interpreter_call_code.delta"constant` - The type of the object. Always `summary_text`. + The type of the event. Always `response.code_interpreter_call_code.delta`. - - `SUMMARY_TEXT("summary_text")` + - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DELTA("response.code_interpreter_call_code.delta")` - - `class ReasoningText:` + - `Optional agent` - Reasoning text from the model. + The agent that owns this multi-agent streaming event. - - `String text` + - `String agentName` - The reasoning text from the model. + The canonical name of the agent that produced this item. - - `JsonValue; type "reasoning_text"constant` + - `class BetaResponseCodeInterpreterCallCodeDoneEvent:` - The type of the reasoning text. Always `reasoning_text`. + Emitted when the code snippet is finalized by the code interpreter. - - `REASONING_TEXT("reasoning_text")` + - `String code` - - `class BetaResponseOutputRefusal:` + The final code snippet output by the code interpreter. - A refusal from the model. + - `String itemId` - - `class BetaResponseInputImage:` + The unique identifier of the code interpreter tool call item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `long outputIndex` - - `class ComputerScreenshot:` + The index of the output item in the response for which the code is finalized. - A screenshot of a computer. + - `long sequenceNumber` - - `Detail detail` + The sequence number of this event, used to order streaming events. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `JsonValue; type "response.code_interpreter_call_code.done"constant` - - `LOW("low")` + The type of the event. Always `response.code_interpreter_call_code.done`. - - `HIGH("high")` + - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DONE("response.code_interpreter_call_code.done")` - - `AUTO("auto")` + - `Optional agent` - - `ORIGINAL("original")` + The agent that owns this multi-agent streaming event. - - `Optional fileId` + - `String agentName` - The identifier of an uploaded file that contains the screenshot. + The canonical name of the agent that produced this item. - - `Optional imageUrl` + - `class BetaResponseCodeInterpreterCallCompletedEvent:` - The URL of the screenshot image. + Emitted when the code interpreter call is completed. - - `JsonValue; type "computer_screenshot"constant` + - `String itemId` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The unique identifier of the code interpreter tool call item. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `long outputIndex` - - `Optional promptCacheBreakpoint` + The index of the output item in the response for which the code interpreter call is completed. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `long sequenceNumber` - - `JsonValue; mode "explicit"constant` + The sequence number of this event, used to order streaming events. - The breakpoint mode. Always `explicit`. + - `JsonValue; type "response.code_interpreter_call.completed"constant` - - `EXPLICIT("explicit")` + The type of the event. Always `response.code_interpreter_call.completed`. - - `class BetaResponseInputFile:` + - `RESPONSE_CODE_INTERPRETER_CALL_COMPLETED("response.code_interpreter_call.completed")` - A file input to the model. + - `Optional agent` - - `class EncryptedContent:` + The agent that owns this multi-agent streaming event. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `String agentName` - - `String encryptedContent` + The canonical name of the agent that produced this item. - Opaque encrypted content. + - `class BetaResponseCodeInterpreterCallInProgressEvent:` - - `JsonValue; type "encrypted_content"constant` + Emitted when a code interpreter call is in progress. - The type of the input item. Always `encrypted_content`. + - `String itemId` - - `ENCRYPTED_CONTENT("encrypted_content")` + The unique identifier of the code interpreter tool call item. - - `String recipient` + - `long outputIndex` - The destination agent identity. + The index of the output item in the response for which the code interpreter call is in progress. - - `JsonValue; type "agent_message"constant` + - `long sequenceNumber` - The type of the item. Always `agent_message`. + The sequence number of this event, used to order streaming events. - - `AGENT_MESSAGE("agent_message")` + - `JsonValue; type "response.code_interpreter_call.in_progress"constant` + + The type of the event. Always `response.code_interpreter_call.in_progress`. + + - `RESPONSE_CODE_INTERPRETER_CALL_IN_PROGRESS("response.code_interpreter_call.in_progress")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `MultiAgentCall` - - - `String id` - - The unique ID of the multi-agent call item. - - - `Action action` - - The multi-agent action to execute. - - - `SPAWN_AGENT("spawn_agent")` - - - `INTERRUPT_AGENT("interrupt_agent")` - - - `LIST_AGENTS("list_agents")` + - `class BetaResponseCodeInterpreterCallInterpretingEvent:` - - `SEND_MESSAGE("send_message")` + Emitted when the code interpreter is actively interpreting the code snippet. - - `FOLLOWUP_TASK("followup_task")` + - `String itemId` - - `WAIT_AGENT("wait_agent")` + The unique identifier of the code interpreter tool call item. - - `String arguments` + - `long outputIndex` - The JSON string of arguments generated for the action. + The index of the output item in the response for which the code interpreter is interpreting code. - - `String callId` + - `long sequenceNumber` - The unique ID linking this call to its output. + The sequence number of this event, used to order streaming events. - - `JsonValue; type "multi_agent_call"constant` + - `JsonValue; type "response.code_interpreter_call.interpreting"constant` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `RESPONSE_CODE_INTERPRETER_CALL_INTERPRETING("response.code_interpreter_call.interpreting")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` + - `class BetaResponseCompletedEvent:` + + Emitted when the model response is complete. + + - `BetaResponse response` + + Properties of the completed response. - `String id` - The unique ID of the multi-agent call output item. + Unique identifier for this Response. - - `Action action` + - `double createdAt` - The multi-agent action that produced this result. + Unix timestamp (in seconds) of when this Response was created. - - `SPAWN_AGENT("spawn_agent")` + - `Optional error` - - `INTERRUPT_AGENT("interrupt_agent")` + An error object returned when the model fails to generate a Response. - - `LIST_AGENTS("list_agents")` + - `Code code` - - `SEND_MESSAGE("send_message")` + The error code for the response. - - `FOLLOWUP_TASK("followup_task")` + - `SERVER_ERROR("server_error")` - - `WAIT_AGENT("wait_agent")` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `String callId` + - `INVALID_PROMPT("invalid_prompt")` - The unique ID of the multi-agent call. + - `BIO_POLICY("bio_policy")` - - `List output` + - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` - Text output returned by the multi-agent action. + - `INVALID_IMAGE("invalid_image")` - - `List annotations` + - `INVALID_IMAGE_FORMAT("invalid_image_format")` - The annotations of the text output. + - `INVALID_BASE64_IMAGE("invalid_base64_image")` - - `String text` + - `INVALID_IMAGE_URL("invalid_image_url")` - The text output from the model. + - `IMAGE_TOO_LARGE("image_too_large")` - - `JsonValue; type "output_text"constant` + - `IMAGE_TOO_SMALL("image_too_small")` - The type of the output text. Always `output_text`. + - `IMAGE_PARSE_ERROR("image_parse_error")` - - `Optional> logprobs` + - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` - - `JsonValue; type "multi_agent_call_output"constant` + - `INVALID_IMAGE_MODE("invalid_image_mode")` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` - - `Optional agent` + - `EMPTY_IMAGE_FILE("empty_image_file")` - The agent that produced this item. + - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` - - `String agentName` + - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` - The canonical name of the agent that produced this item. + - `String message` - - `class BetaResponseFunctionWebSearch:` + A human-readable description of the error. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Optional incompleteDetails` - - `class BetaResponseComputerToolCall:` + Details about why the response is incomplete. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `Optional reason` - - `class BetaResponseComputerToolCallOutputItem:` + The reason why the response is incomplete. - - `String id` + - `MAX_OUTPUT_TOKENS("max_output_tokens")` - The unique ID of the computer call tool output. + - `CONTENT_FILTER("content_filter")` - - `String callId` + - `Optional instructions` - The ID of the computer tool call that produced the output. + A system (or developer) message inserted into the model's context. - - `BetaResponseComputerToolCallOutputScreenshot output` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - A computer screenshot image used with the computer use tool. + - `String` - - `Status status` + - `List` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `class BetaEasyInputMessage:` - - `COMPLETED("completed")` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `INCOMPLETE("incomplete")` + - `Content content` - - `FAILED("failed")` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `IN_PROGRESS("in_progress")` + - `String` - - `JsonValue; type "computer_call_output"constant` + - `List` - The type of the computer tool call output. Always `computer_call_output`. + - `class BetaResponseInputText:` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + A text input to the model. - - `Optional> acknowledgedSafetyChecks` + - `String text` - The safety checks reported by the API that have been acknowledged by the - developer. + The text input to the model. - - `String id` + - `JsonValue; type "input_text"constant` - The ID of the pending safety check. + The type of the input item. Always `input_text`. - - `Optional code` + - `INPUT_TEXT("input_text")` - The type of the pending safety check. + - `Optional promptCacheBreakpoint` - - `Optional message` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Details about the pending safety check. + - `JsonValue; mode "explicit"constant` - - `Optional agent` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `EXPLICIT("explicit")` - - `String agentName` + - `class BetaResponseInputImage:` - The canonical name of the agent that produced this item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional createdBy` + - `Detail detail` - The identifier of the actor that created the item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `class BetaResponseReasoningItem:` + - `LOW("low")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `HIGH("high")` - - `Program` + - `AUTO("auto")` - - `String id` + - `ORIGINAL("original")` - The unique ID of the program item. + - `JsonValue; type "input_image"constant` - - `String callId` + The type of the input item. Always `input_image`. - The stable call ID of the program item. + - `INPUT_IMAGE("input_image")` - - `String code` + - `Optional fileId` - The JavaScript source executed by programmatic tool calling. + The ID of the file to be sent to the model. - - `String fingerprint` + - `Optional imageUrl` - Opaque program replay fingerprint that must be round-tripped. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `JsonValue; type "program"constant` + - `Optional promptCacheBreakpoint` - The type of the item. Always `program`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `PROGRAM("program")` + - `JsonValue; mode "explicit"constant` - - `Optional agent` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `EXPLICIT("explicit")` - - `String agentName` + - `class BetaResponseInputFile:` - The canonical name of the agent that produced this item. + A file input to the model. - - `ProgramOutput` + - `JsonValue; type "input_file"constant` - - `String id` + The type of the input item. Always `input_file`. - The unique ID of the program output item. + - `INPUT_FILE("input_file")` - - `String callId` + - `Optional detail` - The call ID of the program item. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `String result` + - `AUTO("auto")` - The result produced by the program item. + - `LOW("low")` - - `Status status` + - `HIGH("high")` - The terminal status of the program output item. + - `Optional fileData` - - `COMPLETED("completed")` + The content of the file to be sent to the model. - - `INCOMPLETE("incomplete")` + - `Optional fileId` - - `JsonValue; type "program_output"constant` + The ID of the file to be sent to the model. - The type of the item. Always `program_output`. + - `Optional fileUrl` - - `PROGRAM_OUTPUT("program_output")` + The URL of the file to be sent to the model. - - `Optional agent` + - `Optional filename` - The agent that produced this item. + The name of the file to be sent to the model. - - `String agentName` + - `Optional promptCacheBreakpoint` - The canonical name of the agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseToolSearchCall:` + - `JsonValue; mode "explicit"constant` - - `String id` + The breakpoint mode. Always `explicit`. - The unique ID of the tool search call item. + - `EXPLICIT("explicit")` - - `JsonValue arguments` + - `Role role` - Arguments used for the tool search call. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `Optional callId` + - `USER("user")` - The unique ID of the tool search call generated by the model. + - `ASSISTANT("assistant")` - - `Execution execution` + - `SYSTEM("system")` - Whether tool search was executed by the server or by the client. + - `DEVELOPER("developer")` - - `SERVER("server")` + - `Optional phase` - - `CLIENT("client")` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `Status status` + - `COMMENTARY("commentary")` - The status of the tool search call item that was recorded. + - `FINAL_ANSWER("final_answer")` - - `IN_PROGRESS("in_progress")` + - `Optional type` - - `COMPLETED("completed")` + The type of the message input. Always `message`. - - `INCOMPLETE("incomplete")` + - `MESSAGE("message")` - - `JsonValue; type "tool_search_call"constant` + - `Message` - The type of the item. Always `tool_search_call`. + - `List content` - - `TOOL_SEARCH_CALL("tool_search_call")` + A list of one or many input items to the model, containing different content + types. - - `Optional agent` + - `class BetaResponseInputText:` - The agent that produced this item. + A text input to the model. - - `String agentName` + - `class BetaResponseInputImage:` - The canonical name of the agent that produced this item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional createdBy` + - `class BetaResponseInputFile:` - The identifier of the actor that created the item. + A file input to the model. - - `class BetaResponseToolSearchOutputItem:` + - `Role role` - - `String id` + The role of the message input. One of `user`, `system`, or `developer`. - The unique ID of the tool search output item. + - `USER("user")` - - `Optional callId` + - `SYSTEM("system")` - The unique ID of the tool search call generated by the model. + - `DEVELOPER("developer")` - - `Execution execution` + - `Optional agent` - Whether tool search was executed by the server or by the client. + The agent that produced this item. - - `SERVER("server")` + - `String agentName` - - `CLIENT("client")` + The canonical name of the agent that produced this item. - - `Status status` + - `Optional status` - The status of the tool search output item that was recorded. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -113987,199 +126704,190 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `List tools` - - The loaded tool definitions returned by tool search. - - - `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `class BetaFileSearchTool:` + - `Optional type` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The type of the message input. Always set to `message`. - - `class BetaComputerTool:` + - `MESSAGE("message")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `class BetaResponseOutputMessage:` - - `class BetaComputerUsePreviewTool:` + An output message from the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String id` - - `class BetaWebSearchTool:` + The unique ID of the output message. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `List content` - - `Mcp` + The content of the output message. - - `CodeInterpreter` + - `class BetaResponseOutputText:` - - `JsonValue;` + A text output from the model. - - `ImageGeneration` + - `List annotations` - - `JsonValue;` + The annotations of the text output. - - `class BetaFunctionShellTool:` + - `class FileCitation:` - A tool that allows the model to execute shell commands. + A citation to a file. - - `class BetaCustomTool:` + - `String fileId` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The ID of the file. - - `class BetaNamespaceTool:` + - `String filename` - Groups function/custom tools under a shared namespace. + The filename of the file cited. - - `class BetaToolSearchTool:` + - `long index` - Hosted or BYOT tool search configuration for deferred tools. + The index of the file in the list of files. - - `class BetaWebSearchPreviewTool:` + - `JsonValue; type "file_citation"constant` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The type of the file citation. Always `file_citation`. - - `class BetaApplyPatchTool:` + - `FILE_CITATION("file_citation")` - Allows the assistant to create, delete, or update files using unified diffs. + - `class UrlCitation:` - - `JsonValue; type "tool_search_output"constant` + A citation for a web resource used to generate a model response. - The type of the item. Always `tool_search_output`. + - `long endIndex` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + The index of the last character of the URL citation in the message. - - `Optional agent` + - `long startIndex` - The agent that produced this item. + The index of the first character of the URL citation in the message. - - `String agentName` + - `String title` - The canonical name of the agent that produced this item. + The title of the web resource. - - `Optional createdBy` + - `JsonValue; type "url_citation"constant` - The identifier of the actor that created the item. + The type of the URL citation. Always `url_citation`. - - `AdditionalTools` + - `URL_CITATION("url_citation")` - - `String id` + - `String url` - The unique ID of the additional tools item. + The URL of the web resource. - - `Role role` + - `class ContainerFileCitation:` - The role that provided the additional tools. + A citation for a container file used to generate a model response. - - `UNKNOWN("unknown")` + - `String containerId` - - `USER("user")` + The ID of the container file. - - `ASSISTANT("assistant")` + - `long endIndex` - - `SYSTEM("system")` + The index of the last character of the container file citation in the message. - - `CRITIC("critic")` + - `String fileId` - - `DISCRIMINATOR("discriminator")` + The ID of the file. - - `DEVELOPER("developer")` + - `String filename` - - `TOOL("tool")` + The filename of the container file cited. - - `List tools` + - `long startIndex` - The additional tool definitions made available at this item. + The index of the first character of the container file citation in the message. - - `class BetaFunctionTool:` + - `JsonValue; type "container_file_citation"constant` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The type of the container file citation. Always `container_file_citation`. - - `class BetaFileSearchTool:` + - `CONTAINER_FILE_CITATION("container_file_citation")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class FilePath:` - - `class BetaComputerTool:` + A path to a file. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String fileId` - - `class BetaComputerUsePreviewTool:` + The ID of the file. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `long index` - - `class BetaWebSearchTool:` + The index of the file in the list of files. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "file_path"constant` - - `Mcp` + The type of the file path. Always `file_path`. - - `CodeInterpreter` + - `FILE_PATH("file_path")` - - `JsonValue;` + - `String text` - - `ImageGeneration` + The text output from the model. - - `JsonValue;` + - `JsonValue; type "output_text"constant` - - `class BetaFunctionShellTool:` + The type of the output text. Always `output_text`. - A tool that allows the model to execute shell commands. + - `OUTPUT_TEXT("output_text")` - - `class BetaCustomTool:` + - `Optional> logprobs` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `String token` - - `class BetaNamespaceTool:` + - `List bytes` - Groups function/custom tools under a shared namespace. + - `double logprob` - - `class BetaToolSearchTool:` + - `List topLogprobs` - Hosted or BYOT tool search configuration for deferred tools. + - `String token` - - `class BetaWebSearchPreviewTool:` + - `List bytes` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `double logprob` - - `class BetaApplyPatchTool:` + - `class BetaResponseOutputRefusal:` - Allows the assistant to create, delete, or update files using unified diffs. + A refusal from the model. - - `JsonValue; type "additional_tools"constant` + - `String refusal` - The type of the item. Always `additional_tools`. + The refusal explanation from the model. - - `ADDITIONAL_TOOLS("additional_tools")` + - `JsonValue; type "refusal"constant` - - `Optional agent` + The type of the refusal. Always `refusal`. - The agent that produced this item. + - `REFUSAL("refusal")` - - `String agentName` + - `JsonValue; role "assistant"constant` - The canonical name of the agent that produced this item. + The role of the output message. Always `assistant`. - - `class BetaResponseCompactionItem:` + - `ASSISTANT("assistant")` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `Status status` - - `String id` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The unique ID of the compaction item. + - `IN_PROGRESS("in_progress")` - - `String encryptedContent` + - `COMPLETED("completed")` - The encrypted content that was produced by compaction. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "compaction"constant` + - `JsonValue; type "message"constant` - The type of the item. Always `compaction`. + The type of the output message. Always `message`. - - `COMPACTION("compaction")` + - `MESSAGE("message")` - `Optional agent` @@ -114189,37 +126897,49 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional createdBy` + - `Optional phase` - The identifier of the actor that created the item. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `ImageGenerationCall` + - `COMMENTARY("commentary")` + + - `FINAL_ANSWER("final_answer")` + + - `class BetaResponseFileSearchToolCall:` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `String id` - The unique ID of the image generation call. + The unique ID of the file search tool call. - - `Optional result` + - `List queries` - The generated image encoded in base64. + The queries used to search for files. - `Status status` - The status of the image generation call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `IN_PROGRESS("in_progress")` + - `SEARCHING("searching")` + - `COMPLETED("completed")` - - `GENERATING("generating")` + - `INCOMPLETE("incomplete")` - `FAILED("failed")` - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "file_search_call"constant` - The type of the image generation call. Always `image_generation_call`. + The type of the file search tool call. Always `file_search_call`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `FILE_SEARCH_CALL("file_search_call")` - `Optional agent` @@ -114229,53 +126949,73 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. + - `Optional> results` - - `LocalShellCall` + The results of the file search tool call. - - `String id` + - `Optional attributes` - The unique ID of the local shell call. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `Action action` + - `String` - Execute a shell command on the server. + - `double` - - `List command` + - `boolean` - The command to run. + - `Optional fileId` - - `Env env` + The unique ID of the file. - Environment variables to set for the command. + - `Optional filename` - - `JsonValue; type "exec"constant` + The name of the file. - The type of the local shell action. Always `exec`. + - `Optional score` - - `EXEC("exec")` + The relevance score of the file - a value between 0 and 1. - - `Optional timeoutMs` + - `Optional text` - Optional timeout in milliseconds for the command. + The text that was retrieved from the file. - - `Optional user` + - `class BetaResponseComputerToolCall:` - Optional user to run the command as. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `Optional workingDirectory` + - `String id` - Optional working directory to run the command in. + The unique ID of the computer call. - `String callId` - The unique ID of the local shell tool call generated by the model. + An identifier used when responding to the tool call with output. + + - `List pendingSafetyChecks` + + The pending safety checks for the computer call. + + - `String id` + + The ID of the pending safety check. + + - `Optional code` + + The type of the pending safety check. + + - `Optional message` + + Details about the pending safety check. - `Status status` - The status of the local shell call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -114283,227 +127023,270 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `JsonValue; type "local_shell_call"constant` + - `Type type` - The type of the local shell call. Always `local_shell_call`. + The type of the computer call. Always `computer_call`. - - `LOCAL_SHELL_CALL("local_shell_call")` + - `COMPUTER_CALL("computer_call")` - - `Optional agent` + - `Optional action` - The agent that produced this item. + A click action. - - `String agentName` + - `Click` - The canonical name of the agent that produced this item. + - `Button button` - - `LocalShellCallOutput` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `String id` + - `LEFT("left")` - The unique ID of the local shell tool call generated by the model. + - `RIGHT("right")` - - `String output` + - `WHEEL("wheel")` - A JSON string of the output of the local shell tool call. + - `BACK("back")` - - `JsonValue; type "local_shell_call_output"constant` + - `FORWARD("forward")` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `JsonValue; type "click"constant` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + Specifies the event type. For a click action, this property is always `click`. - - `Optional agent` + - `CLICK("click")` - The agent that produced this item. + - `long x` - - `String agentName` + The x-coordinate where the click occurred. - The canonical name of the agent that produced this item. + - `long y` - - `Optional status` + The y-coordinate where the click occurred. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `Optional> keys` - - `IN_PROGRESS("in_progress")` + The keys being held while clicking. - - `COMPLETED("completed")` + - `DoubleClick` - - `INCOMPLETE("incomplete")` + - `Optional> keys` - - `class BetaResponseFunctionShellToolCall:` + The keys being held while double-clicking. - A tool call that executes one or more shell commands in a managed environment. + - `JsonValue; type "double_click"constant` - - `String id` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `DOUBLE_CLICK("double_click")` - - `Action action` + - `long x` - The shell commands and limits that describe how to run the tool call. + The x-coordinate where the double click occurred. + + - `long y` + + The y-coordinate where the double click occurred. + + - `Drag` + + - `List 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> keys` + + The keys being held while dragging the mouse. + + - `Keypress` + + - `List keys` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `List commands` + - `JsonValue; type "keypress"constant` - - `Optional maxOutputLength` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Optional maximum number of characters to return from each command. + - `KEYPRESS("keypress")` - - `Optional timeoutMs` + - `Move` - Optional timeout in milliseconds for the commands. + - `JsonValue; type "move"constant` - - `String callId` + Specifies the event type. For a move action, this property is always set to `move`. - The unique ID of the shell tool call generated by the model. + - `MOVE("move")` - - `Optional environment` + - `long x` - Represents the use of a local environment to perform shell actions. + The x-coordinate to move to. - - `class BetaResponseLocalEnvironment:` + - `long y` - Represents the use of a local environment to perform shell actions. + The y-coordinate to move to. - - `JsonValue; type "local"constant` + - `Optional> keys` - The environment type. Always `local`. + The keys being held while moving the mouse. - - `LOCAL("local")` + - `JsonValue;` - - `class BetaResponseContainerReference:` + - `JsonValue; type "screenshot"constant` - Represents a container created with /v1/containers. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `String containerId` + - `SCREENSHOT("screenshot")` - - `JsonValue; type "container_reference"constant` + - `Scroll` - The environment type. Always `container_reference`. + - `long scrollX` - - `CONTAINER_REFERENCE("container_reference")` + The horizontal scroll distance. - - `Status status` + - `long scrollY` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The vertical scroll distance. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "scroll"constant` - - `COMPLETED("completed")` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `INCOMPLETE("incomplete")` + - `SCROLL("scroll")` - - `JsonValue; type "shell_call"constant` + - `long x` - The type of the item. Always `shell_call`. + The x-coordinate where the scroll occurred. - - `SHELL_CALL("shell_call")` + - `long y` - - `Optional agent` + The y-coordinate where the scroll occurred. - The agent that produced this item. + - `Optional> keys` - - `String agentName` + The keys being held while scrolling. - The canonical name of the agent that produced this item. + - `Type` - - `Optional caller` + - `String text` - The execution context that produced this tool call. + The text to type. - - `JsonValue;` + - `JsonValue; type "type"constant` - - `JsonValue; type "direct"constant` + Specifies the event type. For a type action, this property is always set to `type`. - - `DIRECT("direct")` + - `TYPE("type")` - - `class Program:` + - `JsonValue;` - - `String callerId` + - `JsonValue; type "wait"constant` - The call ID of the program item that produced this tool call. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `JsonValue; type "program"constant` + - `WAIT("wait")` - - `PROGRAM("program")` + - `Optional> actions` - - `Optional createdBy` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The ID of the entity that created this tool call. + - `Click` - - `class BetaResponseFunctionShellToolCallOutput:` + - `DoubleClick` - The output of a shell tool call that was emitted. + - `Drag` - - `String id` + - `Keypress` - The unique ID of the shell call output. Populated when this item is returned via API. + - `Move` - - `String callId` + - `JsonValue;` - The unique ID of the shell tool call generated by the model. + - `Scroll` - - `Optional maxOutputLength` + - `Type` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `JsonValue;` - - `List output` + - `Optional agent` - An array of shell call output contents + The agent that produced this item. - - `Outcome outcome` + - `String agentName` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The canonical name of the agent that produced this item. - - `JsonValue;` + - `ComputerCallOutput` - - `JsonValue; type "timeout"constant` + - `String callId` - The outcome type. Always `timeout`. + The ID of the computer tool call that produced the output. - - `TIMEOUT("timeout")` + - `BetaResponseComputerToolCallOutputScreenshot output` - - `class Exit:` + A computer screenshot image used with the computer use tool. - Indicates that the shell commands finished and returned an exit code. + - `JsonValue; type "computer_screenshot"constant` - - `long exitCode` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Exit code from the shell process. + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `JsonValue; type "exit"constant` + - `Optional fileId` - The outcome type. Always `exit`. + The identifier of an uploaded file that contains the screenshot. - - `EXIT("exit")` + - `Optional imageUrl` - - `String stderr` + The URL of the screenshot image. - The standard error output that was captured. + - `JsonValue; type "computer_call_output"constant` - - `String stdout` + The type of the computer tool call output. Always `computer_call_output`. - The standard output that was captured. + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `Optional createdBy` + - `Optional id` - The identifier of the actor that created the item. + The ID of the computer tool call output. - - `Status status` + - `Optional> acknowledgedSafetyChecks` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The safety checks reported by the API that have been acknowledged by the developer. - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The ID of the pending safety check. - - `INCOMPLETE("incomplete")` + - `Optional code` - - `JsonValue; type "shell_call_output"constant` + The type of the pending safety check. - The type of the shell call output. Always `shell_call_output`. + - `Optional message` - - `SHELL_CALL_OUTPUT("shell_call_output")` + Details about the pending safety check. - `Optional agent` @@ -114513,109 +127296,111 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` + - `Optional status` - - `JsonValue; type "direct"constant` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `DIRECT("direct")` + - `IN_PROGRESS("in_progress")` - - `class Program:` + - `COMPLETED("completed")` - - `String callerId` + - `INCOMPLETE("incomplete")` - The call ID of the program item that produced this tool call. + - `class BetaResponseFunctionWebSearch:` - - `JsonValue; type "program"constant` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `PROGRAM("program")` + - `String id` - - `Optional createdBy` + The unique ID of the web search tool call. - The identifier of the actor that created the item. + - `Action action` - - `class BetaResponseApplyPatchToolCall:` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - A tool call that applies file diffs by creating, deleting, or updating files. + - `class Search:` - - `String id` + Action type "search" - Performs a web search query. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `JsonValue; type "search"constant` - - `String callId` + The action type. - The unique ID of the apply patch tool call generated by the model. + - `SEARCH("search")` - - `Operation operation` + - `Optional> queries` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The search queries. - - `class CreateFile:` + - `Optional query` - Instruction describing how to create a file via the apply_patch tool. + The search query. - - `String diff` + - `Optional> sources` - Diff to apply. + The sources used in the search. - - `String path` + - `JsonValue; type "url"constant` - Path of the file to create. + The type of source. Always `url`. - - `JsonValue; type "create_file"constant` + - `URL("url")` - Create a new file with the provided diff. + - `String url` - - `CREATE_FILE("create_file")` + The URL of the source. - - `class DeleteFile:` + - `class OpenPage:` - Instruction describing how to delete a file via the apply_patch tool. + Action type "open_page" - Opens a specific URL from search results. - - `String path` + - `JsonValue; type "open_page"constant` - Path of the file to delete. + The action type. - - `JsonValue; type "delete_file"constant` + - `OPEN_PAGE("open_page")` - Delete the specified file. + - `Optional url` - - `DELETE_FILE("delete_file")` + The URL opened by the model. - - `class UpdateFile:` + - `class FindInPage:` - Instruction describing how to update a file via the apply_patch tool. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `String diff` + - `String pattern` - Diff to apply. + The pattern or text to search for within the page. - - `String path` + - `JsonValue; type "find_in_page"constant` - Path of the file to update. + The action type. - - `JsonValue; type "update_file"constant` + - `FIND_IN_PAGE("find_in_page")` - Update an existing file with the provided diff. + - `String url` - - `UPDATE_FILE("update_file")` + The URL of the page searched for the pattern. - `Status status` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of the web search tool call. - `IN_PROGRESS("in_progress")` + - `SEARCHING("searching")` + - `COMPLETED("completed")` - - `JsonValue; type "apply_patch_call"constant` + - `FAILED("failed")` - The type of the item. Always `apply_patch_call`. + - `JsonValue; type "web_search_call"constant` - - `APPLY_PATCH_CALL("apply_patch_call")` + The type of the web search tool call. Always `web_search_call`. + + - `WEB_SEARCH_CALL("web_search_call")` - `Optional agent` @@ -114625,55 +127410,32 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional createdBy` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput:` + - `class BetaResponseFunctionToolCall:` - The output emitted by an apply patch tool call. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `String id` + - `String arguments` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + A JSON string of the arguments to pass to the function. - `String callId` - The unique ID of the apply patch tool call generated by the model. + The unique ID of the function tool call generated by the model. - - `Status status` + - `String name` - The status of the apply patch tool call output. One of `completed` or `failed`. + The name of the function to run. - - `COMPLETED("completed")` + - `JsonValue; type "function_call"constant` - - `FAILED("failed")` + The type of the function tool call. Always `function_call`. - - `JsonValue; type "apply_patch_call_output"constant` + - `FUNCTION_CALL("function_call")` - The type of the item. Always `apply_patch_call_output`. + - `Optional id` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The unique ID of the function tool call. - `Optional agent` @@ -114703,172 +127465,154 @@ public final class Main { - `PROGRAM("program")` - - `Optional createdBy` - - The ID of the entity that created this tool call output. - - - `Optional output` - - Optional textual output returned by the apply patch tool. - - - `McpCall` - - - `String id` - - The unique ID of the tool call. - - - `String arguments` - - A JSON string of the arguments passed to the tool. - - - `String name` + - `Optional namespace` - The name of the tool that was run. + The namespace of the function to run. - - `String serverLabel` + - `Optional status` - The label of the MCP server running the tool. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue; type "mcp_call"constant` + - `IN_PROGRESS("in_progress")` - The type of the item. Always `mcp_call`. + - `COMPLETED("completed")` - - `MCP_CALL("mcp_call")` + - `INCOMPLETE("incomplete")` - - `Optional agent` + - `FunctionCallOutput` - The agent that produced this item. + - `String callId` - - `String agentName` + The unique ID of the function tool call generated by the model. - The canonical name of the agent that produced this item. + - `Output output` - - `Optional approvalRequestId` + Text, image, or file output of the function tool call. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `String` - - `Optional error` + - `List` - The error from the tool call, if any. + - `class BetaResponseInputTextContent:` - - `Optional output` + A text input to the model. - The output from the tool call. + - `String text` - - `Optional status` + The text input to the model. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `JsonValue; type "input_text"constant` - - `IN_PROGRESS("in_progress")` + The type of the input item. Always `input_text`. - - `COMPLETED("completed")` + - `INPUT_TEXT("input_text")` - - `INCOMPLETE("incomplete")` + - `Optional promptCacheBreakpoint` - - `CALLING("calling")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `FAILED("failed")` + - `JsonValue; mode "explicit"constant` - - `McpListTools` + The breakpoint mode. Always `explicit`. - - `String id` + - `EXPLICIT("explicit")` - The unique ID of the list. + - `class BetaResponseInputImageContent:` - - `String serverLabel` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The label of the MCP server. + - `JsonValue; type "input_image"constant` - - `List tools` + The type of the input item. Always `input_image`. - The tools available on the server. + - `INPUT_IMAGE("input_image")` - - `JsonValue inputSchema` + - `Optional detail` - The JSON schema describing the tool's input. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `String name` + - `LOW("low")` - The name of the tool. + - `HIGH("high")` - - `Optional annotations` + - `AUTO("auto")` - Additional annotations about the tool. + - `ORIGINAL("original")` - - `Optional description` + - `Optional fileId` - The description of the tool. + The ID of the file to be sent to the model. - - `JsonValue; type "mcp_list_tools"constant` + - `Optional imageUrl` - The type of the item. Always `mcp_list_tools`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `Optional promptCacheBreakpoint` - - `Optional agent` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The agent that produced this item. + - `JsonValue; mode "explicit"constant` - - `String agentName` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `EXPLICIT("explicit")` - - `Optional error` + - `class BetaResponseInputFileContent:` - Error message if the server could not list tools. + A file input to the model. - - `McpApprovalRequest` + - `JsonValue; type "input_file"constant` - - `String id` + The type of the input item. Always `input_file`. - The unique ID of the approval request. + - `INPUT_FILE("input_file")` - - `String arguments` + - `Optional detail` - A JSON string of arguments for the tool. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `String name` + - `AUTO("auto")` - The name of the tool to run. + - `LOW("low")` - - `String serverLabel` + - `HIGH("high")` - The label of the MCP server making the request. + - `Optional fileData` - - `JsonValue; type "mcp_approval_request"constant` + The base64-encoded data of the file to be sent to the model. - The type of the item. Always `mcp_approval_request`. + - `Optional fileId` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + The ID of the file to be sent to the model. - - `Optional agent` + - `Optional fileUrl` - The agent that produced this item. + The URL of the file to be sent to the model. - - `String agentName` + - `Optional filename` - The canonical name of the agent that produced this item. + The name of the file to be sent to the model. - - `McpApprovalResponse` + - `Optional promptCacheBreakpoint` - - `String id` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The unique ID of the approval response + - `JsonValue; mode "explicit"constant` - - `String approvalRequestId` + The breakpoint mode. Always `explicit`. - The ID of the approval request being answered. + - `EXPLICIT("explicit")` - - `boolean approve` + - `JsonValue; type "function_call_output"constant` - Whether the request was approved. + The type of the function tool call output. Always `function_call_output`. - - `JsonValue; type "mcp_approval_response"constant` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - The type of the item. Always `mcp_approval_response`. + - `Optional id` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + The unique ID of the function tool call output. Populated when this item is returned via API. - `Optional agent` @@ -114878,1784 +127622,1711 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional reason` - - Optional reason for the decision. - - - `class BetaResponseCustomToolCall:` - - A call to a custom tool created by the model. + - `Optional caller` - - `class BetaResponseCustomToolCallOutputItem:` + The execution context that produced this tool call. - The output of a custom tool call from your code, being sent back to the model. + - `JsonValue;` - - `String id` + - `JsonValue; type "direct"constant` - The unique ID of the custom tool call output item. + The caller type. Always `direct`. - - `Status status` + - `DIRECT("direct")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class Program:` - - `IN_PROGRESS("in_progress")` + - `String callerId` - - `COMPLETED("completed")` + The call ID of the program item that produced this tool call. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "program"constant` - - `Optional createdBy` + The caller type. Always `program`. - The identifier of the actor that created the item. + - `PROGRAM("program")` - - `boolean parallelToolCalls` + - `Optional status` - Whether to allow the model to run tool calls in parallel. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `Optional temperature` + - `IN_PROGRESS("in_progress")` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `COMPLETED("completed")` - - `ToolChoice toolChoice` + - `INCOMPLETE("incomplete")` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `AgentMessage` - - `enum BetaToolChoiceOptions:` + - `String author` - Controls which (if any) tool is called by the model. + The sending agent identity. - `none` means the model will not call any tool and instead generates a message. + - `List content` - `auto` means the model can pick between generating a message or calling one or - more tools. + Plaintext, image, or encrypted content sent between agents. - `required` means the model must call one or more tools. + - `class BetaResponseInputTextContent:` - - `NONE("none")` + A text input to the model. - - `AUTO("auto")` + - `class BetaResponseInputImageContent:` - - `REQUIRED("required")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class BetaToolChoiceAllowed:` + - `class EncryptedContent:` - Constrains the tools available to the model to a pre-defined set. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `Mode mode` + - `String encryptedContent` - Constrains the tools available to the model to a pre-defined set. + Opaque encrypted content. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `JsonValue; type "encrypted_content"constant` - `required` requires the model to call one or more of the allowed tools. + The type of the input item. Always `encrypted_content`. - - `AUTO("auto")` + - `ENCRYPTED_CONTENT("encrypted_content")` - - `REQUIRED("required")` + - `String recipient` - - `List tools` + The destination agent identity. - A list of tool definitions that the model should be allowed to call. + - `JsonValue; type "agent_message"constant` - For the Responses API, the list of tool definitions might look like: + The item type. Always `agent_message`. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `AGENT_MESSAGE("agent_message")` - - `JsonValue; type "allowed_tools"constant` + - `Optional id` - Allowed tool configuration type. Always `allowed_tools`. + The unique ID of this agent message item. - - `ALLOWED_TOOLS("allowed_tools")` + - `Optional agent` - - `class BetaToolChoiceTypes:` + The agent that produced this item. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `String agentName` - - `Type type` + The canonical name of the agent that produced this item. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `MultiAgentCall` - Allowed values are: + - `Action action` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The multi-agent action that was executed. - - `FILE_SEARCH("file_search")` + - `SPAWN_AGENT("spawn_agent")` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `COMPUTER("computer")` + - `LIST_AGENTS("list_agents")` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `SEND_MESSAGE("send_message")` - - `COMPUTER_USE("computer_use")` + - `FOLLOWUP_TASK("followup_task")` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `WAIT_AGENT("wait_agent")` - - `IMAGE_GENERATION("image_generation")` + - `String arguments` - - `CODE_INTERPRETER("code_interpreter")` + The action arguments as a JSON string. - - `class BetaToolChoiceFunction:` + - `String callId` - Use this option to force the model to call a specific function. + The unique ID linking this call to its output. - - `String name` + - `JsonValue; type "multi_agent_call"constant` - The name of the function to call. + The item type. Always `multi_agent_call`. - - `JsonValue; type "function"constant` + - `MULTI_AGENT_CALL("multi_agent_call")` - For function calling, the type is always `function`. + - `Optional id` - - `FUNCTION("function")` + The unique ID of this multi-agent call. - - `class BetaToolChoiceMcp:` + - `Optional agent` - Use this option to force the model to call a specific tool on a remote MCP server. + The agent that produced this item. - - `String serverLabel` + - `String agentName` - The label of the MCP server to use. + The canonical name of the agent that produced this item. - - `JsonValue; type "mcp"constant` + - `MultiAgentCallOutput` - For MCP tools, the type is always `mcp`. + - `Action action` - - `MCP("mcp")` + The multi-agent action that produced this result. - - `Optional name` + - `SPAWN_AGENT("spawn_agent")` - The name of the tool to call on the server. + - `INTERRUPT_AGENT("interrupt_agent")` - - `class BetaToolChoiceCustom:` + - `LIST_AGENTS("list_agents")` - Use this option to force the model to call a specific custom tool. + - `SEND_MESSAGE("send_message")` - - `String name` + - `FOLLOWUP_TASK("followup_task")` - The name of the custom tool to call. + - `WAIT_AGENT("wait_agent")` - - `JsonValue; type "custom"constant` + - `String callId` - For custom tool calling, the type is always `custom`. + The unique ID of the multi-agent call. - - `CUSTOM("custom")` + - `List output` - - `JsonValue;` + Text output returned by the multi-agent action. - - `JsonValue; type "programmatic_tool_calling"constant` + - `String text` - The tool to call. Always `programmatic_tool_calling`. + The text content. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `JsonValue; type "output_text"constant` - - `class BetaToolChoiceApplyPatch:` + The content type. Always `output_text`. - Forces the model to call the apply_patch tool when executing a tool call. + - `OUTPUT_TEXT("output_text")` - - `JsonValue; type "apply_patch"constant` + - `Optional annotations` - The tool to call. Always `apply_patch`. + Citations associated with the text content. - - `APPLY_PATCH("apply_patch")` + - `List` - - `class BetaToolChoiceShell:` + - `String fileId` - Forces the model to call the shell tool when a tool call is required. + The ID of the file. - - `JsonValue; type "shell"constant` + - `String filename` - The tool to call. Always `shell`. + The filename of the file cited. - - `SHELL("shell")` + - `long index` - - `List tools` + The index of the file in the list of files. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `JsonValue; type "file_citation"constant` - We support the following categories of tools: + The citation type. Always `file_citation`. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `FILE_CITATION("file_citation")` - - `class BetaFunctionTool:` + - `List` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `long endIndex` - - `class BetaFileSearchTool:` + The index of the last character of the citation in the message. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `long startIndex` - - `class BetaComputerTool:` + The index of the first character of the citation in the message. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String title` - - `class BetaComputerUsePreviewTool:` + The title of the cited resource. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JsonValue; type "url_citation"constant` - - `class BetaWebSearchTool:` + The citation type. Always `url_citation`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `URL_CITATION("url_citation")` - - `Mcp` + - `String url` - - `CodeInterpreter` + The URL of the cited resource. - - `JsonValue;` + - `List` - - `ImageGeneration` + - `String containerId` - - `JsonValue;` + The ID of the container. - - `class BetaFunctionShellTool:` + - `long endIndex` - A tool that allows the model to execute shell commands. + The index of the last character of the citation in the message. - - `class BetaCustomTool:` + - `String fileId` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The ID of the container file. - - `class BetaNamespaceTool:` + - `String filename` - Groups function/custom tools under a shared namespace. + The filename of the container file cited. - - `class BetaToolSearchTool:` + - `long startIndex` - Hosted or BYOT tool search configuration for deferred tools. + The index of the first character of the citation in the message. - - `class BetaWebSearchPreviewTool:` + - `JsonValue; type "container_file_citation"constant` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The citation type. Always `container_file_citation`. - - `class BetaApplyPatchTool:` + - `CONTAINER_FILE_CITATION("container_file_citation")` - Allows the assistant to create, delete, or update files using unified diffs. + - `JsonValue; type "multi_agent_call_output"constant` - - `Optional topP` + The item type. Always `multi_agent_call_output`. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - We generally recommend altering this or `temperature` but not both. + - `Optional id` - - `Optional background` + The unique ID of this multi-agent call output. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `Optional agent` - - `Optional completedAt` + The agent that produced this item. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `String agentName` - - `Optional conversation` + The canonical name of the agent that produced this item. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `ToolSearchCall` - - `String id` + - `JsonValue arguments` - The unique ID of the conversation that this response was associated with. + The arguments supplied to the tool search call. - - `Optional maxOutputTokens` + - `JsonValue; type "tool_search_call"constant` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The item type. Always `tool_search_call`. - - `Optional maxToolCalls` + - `TOOL_SEARCH_CALL("tool_search_call")` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `Optional id` - - `Optional moderation` + The unique ID of this tool search call. - Moderation results for the response input and output, if moderated completions were requested. + - `Optional agent` - - `Input input` + The agent that produced this item. - Moderation for the response input. + - `String agentName` - - `class ModerationResult:` + The canonical name of the agent that produced this item. - A moderation result produced for the response input or output. + - `Optional callId` - - `Categories categories` + The unique ID of the tool search call generated by the model. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `Optional execution` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + Whether tool search was executed by the server or by the client. - Which modalities of input are reflected by the score for each category. + - `SERVER("server")` - - `TEXT("text")` + - `CLIENT("client")` - - `IMAGE("image")` + - `Optional status` - - `CategoryScores categoryScores` + The status of the tool search call. - A dictionary of moderation categories to scores. + - `IN_PROGRESS("in_progress")` - - `boolean flagged` + - `COMPLETED("completed")` - A boolean indicating whether the content was flagged by any category. + - `INCOMPLETE("incomplete")` - - `String model` + - `class BetaResponseToolSearchOutputItemParam:` - The moderation model that produced this result. + - `List tools` - - `JsonValue; type "moderation_result"constant` + The loaded tool definitions returned by the tool search output. - The object type, which was always `moderation_result` for successful moderation results. + - `class BetaFunctionTool:` - - `MODERATION_RESULT("moderation_result")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `class Error:` + - `String name` - An error produced while attempting moderation for the response input or output. + The name of the function to call. - - `String code` + - `Optional parameters` - The error code. + A JSON schema object describing the parameters of the function. - - `String message` + - `Optional strict` - The error message. + Whether strict parameter validation is enforced for this function tool. - - `JsonValue; type "error"constant` + - `JsonValue; type "function"constant` - The object type, which was always `error` for moderation failures. + The type of the function tool. Always `function`. - - `ERROR("error")` + - `FUNCTION("function")` - - `Output output` + - `Optional> allowedCallers` - Moderation for the response output. + The tool invocation context(s). - - `class ModerationResult:` + - `DIRECT("direct")` - A moderation result produced for the response input or output. + - `PROGRAMMATIC("programmatic")` - - `Categories categories` + - `Optional deferLoading` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Whether this function is deferred and loaded via tool search. - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `Optional description` - Which modalities of input are reflected by the score for each category. + A description of the function. Used by the model to determine whether or not to call the function. - - `TEXT("text")` + - `Optional outputSchema` - - `IMAGE("image")` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `CategoryScores categoryScores` + - `class BetaFileSearchTool:` - A dictionary of moderation categories to scores. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `boolean flagged` + - `JsonValue; type "file_search"constant` - A boolean indicating whether the content was flagged by any category. + The type of the file search tool. Always `file_search`. - - `String model` + - `FILE_SEARCH("file_search")` - The moderation model that produced this result. + - `List vectorStoreIds` - - `JsonValue; type "moderation_result"constant` + The IDs of the vector stores to search. - The object type, which was always `moderation_result` for successful moderation results. + - `Optional filters` - - `MODERATION_RESULT("moderation_result")` + A filter to apply. - - `class Error:` + - `class ComparisonFilter:` - An error produced while attempting moderation for the response input or output. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `String code` + - `String key` - The error code. + The key to compare against the value. - - `String message` + - `Type type` - The error message. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `JsonValue; type "error"constant` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The object type, which was always `error` for moderation failures. + - `EQ("eq")` - - `ERROR("error")` + - `NE("ne")` - - `Optional previousResponseId` + - `GT("gt")` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `GTE("gte")` - - `Optional prompt` + - `LT("lt")` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `LTE("lte")` - - `String id` + - `IN("in")` - The unique identifier of the prompt template to use. + - `NIN("nin")` - - `Optional variables` + - `Value value` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The value to compare against the attribute key; supports string, number, or boolean types. - `String` - - `class BetaResponseInputText:` - - A text input to the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `Optional version` - - Optional version of the prompt template. - - - `Optional promptCacheKey` - - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - - `Optional promptCacheOptions` - - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - - `Mode mode` + - `double` - Whether implicit prompt-cache breakpoints were enabled. + - `boolean` - - `IMPLICIT("implicit")` + - `List` - - `EXPLICIT("explicit")` + - `String` - - `Ttl ttl` + - `double` - The minimum lifetime applied to each cache breakpoint. + - `class CompoundFilter:` - - `_30M("30m")` + Combine multiple filters using `and` or `or`. - - `Optional promptCacheRetention` + - `List filters` - Deprecated. Use `prompt_cache_options.ttl` instead. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `class ComparisonFilter:` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `String key` - - `IN_MEMORY("in_memory")` + The key to compare against the value. - - `_24H("24h")` + - `Type type` - - `Optional reasoning` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - **gpt-5 and o-series models only** + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `EQ("eq")` - - `Optional context` + - `NE("ne")` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `GT("gt")` - - `AUTO("auto")` + - `GTE("gte")` - - `CURRENT_TURN("current_turn")` + - `LT("lt")` - - `ALL_TURNS("all_turns")` + - `LTE("lte")` - - `Optional effort` + - `IN("in")` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `NIN("nin")` - - `NONE("none")` + - `Value value` - - `MINIMAL("minimal")` + The value to compare against the attribute key; supports string, number, or boolean types. - - `LOW("low")` + - `String` - - `MEDIUM("medium")` + - `double` - - `HIGH("high")` + - `boolean` - - `XHIGH("xhigh")` + - `List` - - `MAX("max")` + - `String` - - `Optional generateSummary` + - `double` - **Deprecated:** use `summary` instead. + - `JsonValue` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `Type type` - - `AUTO("auto")` + Type of operation: `and` or `or`. - - `CONCISE("concise")` + - `AND("and")` - - `DETAILED("detailed")` + - `OR("or")` - - `Optional mode` + - `Optional maxNumResults` - Controls the reasoning execution mode for the request. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - When returned on a response, this is the effective execution mode. + - `Optional rankingOptions` - - `STANDARD("standard")` + Ranking options for search. - - `PRO("pro")` + - `Optional hybridSearch` - - `Optional summary` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `double embeddingWeight` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The weight of the embedding in the reciprocal ranking fusion. - - `AUTO("auto")` + - `double textWeight` - - `CONCISE("concise")` + The weight of the text in the reciprocal ranking fusion. - - `DETAILED("detailed")` + - `Optional ranker` - - `Optional safetyIdentifier` + The ranker to use for the file search. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `AUTO("auto")` - - `Optional serviceTier` + - `DEFAULT_2024_11_15("default-2024-11-15")` - Specifies the processing type used for serving the request. + - `Optional scoreThreshold` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The 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. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `class BetaComputerTool:` - - `AUTO("auto")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `DEFAULT("default")` + - `JsonValue; type "computer"constant` - - `FLEX("flex")` + The type of the computer tool. Always `computer`. - - `SCALE("scale")` + - `COMPUTER("computer")` - - `PRIORITY("priority")` + - `class BetaComputerUsePreviewTool:` - - `Optional status` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `long displayHeight` - - `COMPLETED("completed")` + The height of the computer display. - - `FAILED("failed")` + - `long displayWidth` - - `IN_PROGRESS("in_progress")` + The width of the computer display. - - `CANCELLED("cancelled")` + - `Environment environment` - - `QUEUED("queued")` + The type of computer environment to control. - - `INCOMPLETE("incomplete")` + - `WINDOWS("windows")` - - `Optional text` + - `MAC("mac")` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `LINUX("linux")` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `UBUNTU("ubuntu")` - - `Optional format` + - `BROWSER("browser")` - An object specifying the format that the model must output. + - `JsonValue; type "computer_use_preview"constant` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The type of the computer use tool. Always `computer_use_preview`. - The default format is `{ "type": "text" }` with no additional options. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - **Not recommended for gpt-4o and newer models:** + - `class BetaWebSearchTool:` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue;` + - `Type type` - - `JsonValue; type "text"constant` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The type of response format being defined. Always `text`. + - `WEB_SEARCH("web_search")` - - `TEXT("text")` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `Optional filters` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Filters for the search. - - `String name` + - `Optional> allowedDomains` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `Schema schema` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `Optional searchContextSize` - - `JsonValue; type "json_schema"constant` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The type of response format being defined. Always `json_schema`. + - `LOW("low")` - - `JSON_SCHEMA("json_schema")` + - `MEDIUM("medium")` - - `Optional description` + - `HIGH("high")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Optional userLocation` - - `Optional strict` + The approximate location of the user. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `Optional city` - - `JsonValue;` + Free text input for the city of the user, e.g. `San Francisco`. - - `JsonValue; type "json_object"constant` + - `Optional country` - The type of response format being defined. Always `json_object`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `JSON_OBJECT("json_object")` + - `Optional region` - - `Optional verbosity` + Free text input for the region of the user, e.g. `California`. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `Optional timezone` - - `LOW("low")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `MEDIUM("medium")` + - `Optional type` - - `HIGH("high")` + The type of location approximation. Always `approximate`. - - `Optional topLogprobs` + - `APPROXIMATE("approximate")` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `Mcp` - - `Optional truncation` + - `String serverLabel` - The truncation strategy to use for the model response. + A label for this MCP server, used to identify it in tool calls. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `JsonValue; type "mcp"constant` - - `AUTO("auto")` + The type of the MCP tool. Always `mcp`. - - `DISABLED("disabled")` + - `MCP("mcp")` - - `Optional usage` + - `Optional> allowedCallers` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The tool invocation context(s). - - `long inputTokens` + - `DIRECT("direct")` - The number of input tokens. + - `PROGRAMMATIC("programmatic")` - - `InputTokensDetails inputTokensDetails` + - `Optional allowedTools` - A detailed breakdown of the input tokens. + List of allowed tool names or a filter object. - - `long cacheWriteTokens` + - `List` - The number of input tokens that were written to the cache. + - `class McpToolFilter:` - - `long cachedTokens` + A filter object to specify which tools are allowed. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `Optional readOnly` - - `long outputTokens` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The number of output tokens. + - `Optional> toolNames` - - `OutputTokensDetails outputTokensDetails` + List of allowed tool names. - A detailed breakdown of the output tokens. + - `Optional authorization` - - `long reasoningTokens` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The number of reasoning tokens. + - `Optional connectorId` - - `long totalTokens` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The total number of tokens used. + Currently supported `connector_id` values are: - - `Optional user` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `long sequenceNumber` + - `CONNECTOR_GMAIL("connector_gmail")` - The sequence number for this event. + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `JsonValue; type "response.queued"constant` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - The type of the event. Always 'response.queued'. + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `RESPONSE_QUEUED("response.queued")` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `Optional agent` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - The agent that owns this multi-agent streaming event. + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - - `String agentName` + - `Optional deferLoading` - The canonical name of the agent that produced this item. + Whether this MCP tool is deferred and discovered via tool search. -### Beta Response Reasoning Item + - `Optional headers` -- `class BetaResponseReasoningItem:` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `Optional requireApproval` - - `String id` + Specify which of the MCP server's tools require approval. - The unique identifier of the reasoning content. + - `class McpToolApprovalFilter:` - - `List summary` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Reasoning summary content. + - `Optional always` - - `String text` + A filter object to specify which tools are allowed. - A summary of the reasoning output from the model so far. + - `Optional readOnly` - - `JsonValue; type "summary_text"constant` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the object. Always `summary_text`. + - `Optional> toolNames` - - `SUMMARY_TEXT("summary_text")` + List of allowed tool names. - - `JsonValue; type "reasoning"constant` + - `Optional never` - The type of the object. Always `reasoning`. + A filter object to specify which tools are allowed. - - `REASONING("reasoning")` + - `Optional readOnly` - - `Optional agent` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The agent that produced this item. + - `Optional> toolNames` - - `String agentName` + List of allowed tool names. - The canonical name of the agent that produced this item. + - `enum McpToolApprovalSetting:` - - `Optional> content` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - Reasoning text content. + - `ALWAYS("always")` - - `String text` + - `NEVER("never")` - The reasoning text from the model. + - `Optional serverDescription` - - `JsonValue; type "reasoning_text"constant` + Optional description of the MCP server, used to provide more context. - The type of the reasoning text. Always `reasoning_text`. + - `Optional serverUrl` - - `REASONING_TEXT("reasoning_text")` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `Optional encryptedContent` + - `Optional tunnelId` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `Optional status` + - `CodeInterpreter` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Container container` - - `IN_PROGRESS("in_progress")` + 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. - - `COMPLETED("completed")` + - `String` - - `INCOMPLETE("incomplete")` + - `class CodeInterpreterToolAuto:` -### Beta Response Reasoning Summary Part Added Event + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. -- `class BetaResponseReasoningSummaryPartAddedEvent:` + - `JsonValue; type "auto"constant` - Emitted when a new reasoning summary part is added. + Always `auto`. - - `String itemId` + - `AUTO("auto")` - The ID of the item this summary part is associated with. + - `Optional> fileIds` - - `long outputIndex` + An optional list of uploaded files to make available to your code. - The index of the output item this summary part is associated with. + - `Optional memoryLimit` - - `Part part` + The memory limit for the code interpreter container. - The summary part that was added. + - `_1G("1g")` - - `String text` + - `_4G("4g")` - The text of the summary part. + - `_16G("16g")` - - `JsonValue; type "summary_text"constant` + - `_64G("64g")` - The type of the summary part. Always `summary_text`. + - `Optional networkPolicy` - - `SUMMARY_TEXT("summary_text")` + Network access policy for the container. - - `long sequenceNumber` + - `class BetaContainerNetworkPolicyDisabled:` - The sequence number of this event. + - `JsonValue; type "disabled"constant` - - `long summaryIndex` + Disable outbound network access. Always `disabled`. - The index of the summary part within the reasoning summary. + - `DISABLED("disabled")` - - `JsonValue; type "response.reasoning_summary_part.added"constant` + - `class BetaContainerNetworkPolicyAllowlist:` - The type of the event. Always `response.reasoning_summary_part.added`. + - `List allowedDomains` - - `RESPONSE_REASONING_SUMMARY_PART_ADDED("response.reasoning_summary_part.added")` + A list of allowed domains when type is `allowlist`. - - `Optional agent` + - `JsonValue; type "allowlist"constant` - The agent that owns this multi-agent streaming event. + Allow outbound network access only to specified domains. Always `allowlist`. - - `String agentName` + - `ALLOWLIST("allowlist")` - The canonical name of the agent that produced this item. + - `Optional> domainSecrets` -### Beta Response Reasoning Summary Part Done Event + Optional domain-scoped secrets for allowlisted domains. -- `class BetaResponseReasoningSummaryPartDoneEvent:` + - `String domain` - Emitted when a reasoning summary part is completed. + The domain associated with the secret. - - `String itemId` + - `String name` - The ID of the item this summary part is associated with. + The name of the secret to inject for the domain. - - `long outputIndex` + - `String value` - The index of the output item this summary part is associated with. + The secret value to inject for the domain. - - `Part part` + - `JsonValue; type "code_interpreter"constant` - The completed summary part. + The type of the code interpreter tool. Always `code_interpreter`. - - `String text` + - `CODE_INTERPRETER("code_interpreter")` - The text of the summary part. + - `Optional> allowedCallers` - - `JsonValue; type "summary_text"constant` + The tool invocation context(s). - The type of the summary part. Always `summary_text`. + - `DIRECT("direct")` - - `SUMMARY_TEXT("summary_text")` + - `PROGRAMMATIC("programmatic")` - - `long sequenceNumber` + - `JsonValue;` - The sequence number of this event. + - `JsonValue; type "programmatic_tool_calling"constant` - - `long summaryIndex` + The type of the tool. Always `programmatic_tool_calling`. - The index of the summary part within the reasoning summary. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `JsonValue; type "response.reasoning_summary_part.done"constant` + - `ImageGeneration` - The type of the event. Always `response.reasoning_summary_part.done`. + - `JsonValue; type "image_generation"constant` - - `RESPONSE_REASONING_SUMMARY_PART_DONE("response.reasoning_summary_part.done")` + The type of the image generation tool. Always `image_generation`. - - `Optional agent` + - `IMAGE_GENERATION("image_generation")` - The agent that owns this multi-agent streaming event. + - `Optional action` - - `String agentName` + Whether to generate a new image or edit an existing image. Default: `auto`. - The canonical name of the agent that produced this item. + - `GENERATE("generate")` - - `Optional status` + - `EDIT("edit")` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `AUTO("auto")` - - `INCOMPLETE("incomplete")` + - `Optional background` -### Beta Response Reasoning Summary Text Delta Event + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. -- `class BetaResponseReasoningSummaryTextDeltaEvent:` + `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. - Emitted when a delta is added to a reasoning summary text. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `String delta` + - `TRANSPARENT("transparent")` - The text delta that was added to the summary. + - `OPAQUE("opaque")` - - `String itemId` + - `AUTO("auto")` - The ID of the item this summary text delta is associated with. + - `Optional inputFidelity` - - `long outputIndex` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The index of the output item this summary text delta is associated with. + - `HIGH("high")` - - `long sequenceNumber` + - `LOW("low")` - The sequence number of this event. + - `Optional inputImageMask` - - `long summaryIndex` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The index of the summary part within the reasoning summary. + - `Optional fileId` - - `JsonValue; type "response.reasoning_summary_text.delta"constant` + File ID for the mask image. - The type of the event. Always `response.reasoning_summary_text.delta`. + - `Optional imageUrl` - - `RESPONSE_REASONING_SUMMARY_TEXT_DELTA("response.reasoning_summary_text.delta")` + Base64-encoded mask image. - - `Optional agent` + - `Optional model` - The agent that owns this multi-agent streaming event. + The image generation model to use. Default: `gpt-image-1`. - - `String agentName` + - `GPT_IMAGE_1("gpt-image-1")` - The canonical name of the agent that produced this item. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` -### Beta Response Reasoning Summary Text Done Event + - `GPT_IMAGE_2("gpt-image-2")` -- `class BetaResponseReasoningSummaryTextDoneEvent:` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - Emitted when a reasoning summary text is completed. + - `GPT_IMAGE_1_5("gpt-image-1.5")` - - `String itemId` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - The ID of the item this summary text is associated with. + - `Optional moderation` - - `long outputIndex` + Moderation level for the generated image. Default: `auto`. - The index of the output item this summary text is associated with. + - `AUTO("auto")` - - `long sequenceNumber` + - `LOW("low")` - The sequence number of this event. + - `Optional outputCompression` - - `long summaryIndex` + Compression level for the output image. Default: 100. - The index of the summary part within the reasoning summary. + - `Optional outputFormat` - - `String text` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The full text of the completed reasoning summary. + - `PNG("png")` - - `JsonValue; type "response.reasoning_summary_text.done"constant` + - `WEBP("webp")` - The type of the event. Always `response.reasoning_summary_text.done`. + - `JPEG("jpeg")` - - `RESPONSE_REASONING_SUMMARY_TEXT_DONE("response.reasoning_summary_text.done")` + - `Optional partialImages` - - `Optional agent` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The agent that owns this multi-agent streaming event. + - `Optional quality` - - `String agentName` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The canonical name of the agent that produced this item. + - `LOW("low")` -### Beta Response Reasoning Text Delta Event + - `MEDIUM("medium")` -- `class BetaResponseReasoningTextDeltaEvent:` + - `HIGH("high")` - Emitted when a delta is added to a reasoning text. + - `AUTO("auto")` - - `long contentIndex` + - `Optional size` - The index of the reasoning content part this delta is associated with. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `String delta` + - `_1024X1024("1024x1024")` - The text delta that was added to the reasoning content. + - `_1024X1536("1024x1536")` - - `String itemId` + - `_1536X1024("1536x1024")` - The ID of the item this reasoning text delta is associated with. + - `AUTO("auto")` - - `long outputIndex` + - `JsonValue;` - The index of the output item this reasoning text delta is associated with. + - `JsonValue; type "local_shell"constant` - - `long sequenceNumber` + The type of the local shell tool. Always `local_shell`. - The sequence number of this event. + - `LOCAL_SHELL("local_shell")` - - `JsonValue; type "response.reasoning_text.delta"constant` + - `class BetaFunctionShellTool:` - The type of the event. Always `response.reasoning_text.delta`. + A tool that allows the model to execute shell commands. - - `RESPONSE_REASONING_TEXT_DELTA("response.reasoning_text.delta")` + - `JsonValue; type "shell"constant` - - `Optional agent` + The type of the shell tool. Always `shell`. - The agent that owns this multi-agent streaming event. + - `SHELL("shell")` - - `String agentName` + - `Optional> allowedCallers` - The canonical name of the agent that produced this item. + The tool invocation context(s). -### Beta Response Reasoning Text Done Event + - `DIRECT("direct")` -- `class BetaResponseReasoningTextDoneEvent:` + - `PROGRAMMATIC("programmatic")` - Emitted when a reasoning text is completed. + - `Optional environment` - - `long contentIndex` + - `class BetaContainerAuto:` - The index of the reasoning content part. + - `JsonValue; type "container_auto"constant` - - `String itemId` + Automatically creates a container for this request - The ID of the item this reasoning text is associated with. + - `CONTAINER_AUTO("container_auto")` - - `long outputIndex` + - `Optional> fileIds` - The index of the output item this reasoning text is associated with. + An optional list of uploaded files to make available to your code. - - `long sequenceNumber` + - `Optional memoryLimit` - The sequence number of this event. + The memory limit for the container. - - `String text` + - `_1G("1g")` - The full text of the completed reasoning content. + - `_4G("4g")` - - `JsonValue; type "response.reasoning_text.done"constant` + - `_16G("16g")` - The type of the event. Always `response.reasoning_text.done`. + - `_64G("64g")` - - `RESPONSE_REASONING_TEXT_DONE("response.reasoning_text.done")` + - `Optional networkPolicy` - - `Optional agent` + Network access policy for the container. - The agent that owns this multi-agent streaming event. + - `class BetaContainerNetworkPolicyDisabled:` - - `String agentName` + - `class BetaContainerNetworkPolicyAllowlist:` - The canonical name of the agent that produced this item. + - `Optional> skills` -### Beta Response Refusal Delta Event + An optional list of skills referenced by id or inline data. -- `class BetaResponseRefusalDeltaEvent:` + - `class BetaSkillReference:` - Emitted when there is a partial refusal text. + - `String skillId` - - `long contentIndex` + The ID of the referenced skill. - The index of the content part that the refusal text is added to. + - `JsonValue; type "skill_reference"constant` - - `String delta` + References a skill created with the /v1/skills endpoint. - The refusal text that is added. + - `SKILL_REFERENCE("skill_reference")` - - `String itemId` + - `Optional version` - The ID of the output item that the refusal text is added to. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `long outputIndex` + - `class BetaInlineSkill:` - The index of the output item that the refusal text is added to. + - `String description` - - `long sequenceNumber` + The description of the skill. - The sequence number of this event. + - `String name` - - `JsonValue; type "response.refusal.delta"constant` + The name of the skill. - The type of the event. Always `response.refusal.delta`. + - `BetaInlineSkillSource source` - - `RESPONSE_REFUSAL_DELTA("response.refusal.delta")` + Inline skill payload - - `Optional agent` + - `String data` - The agent that owns this multi-agent streaming event. + Base64-encoded skill zip bundle. - - `String agentName` + - `JsonValue; mediaType "application/zip"constant` - The canonical name of the agent that produced this item. + The media type of the inline skill payload. Must be `application/zip`. -### Beta Response Refusal Done Event + - `APPLICATION_ZIP("application/zip")` -- `class BetaResponseRefusalDoneEvent:` + - `JsonValue; type "base64"constant` - Emitted when refusal text is finalized. + The type of the inline skill source. Must be `base64`. - - `long contentIndex` + - `BASE64("base64")` - The index of the content part that the refusal text is finalized. + - `JsonValue; type "inline"constant` - - `String itemId` + Defines an inline skill for this request. - The ID of the output item that the refusal text is finalized. + - `INLINE("inline")` - - `long outputIndex` + - `class BetaLocalEnvironment:` - The index of the output item that the refusal text is finalized. + - `JsonValue; type "local"constant` - - `String refusal` + Use a local computer environment. - The refusal text that is finalized. + - `LOCAL("local")` - - `long sequenceNumber` + - `Optional> skills` - The sequence number of this event. + An optional list of skills. - - `JsonValue; type "response.refusal.done"constant` + - `String description` - The type of the event. Always `response.refusal.done`. + The description of the skill. - - `RESPONSE_REFUSAL_DONE("response.refusal.done")` + - `String name` - - `Optional agent` + The name of the skill. - The agent that owns this multi-agent streaming event. + - `String path` - - `String agentName` + The path to the directory containing the skill. - The canonical name of the agent that produced this item. + - `class BetaContainerReference:` -### Beta Response Status + - `String containerId` -- `enum BetaResponseStatus:` + The ID of the referenced container. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `JsonValue; type "container_reference"constant` - - `COMPLETED("completed")` + References a container created with the /v1/containers endpoint - - `FAILED("failed")` + - `CONTAINER_REFERENCE("container_reference")` - - `IN_PROGRESS("in_progress")` + - `class BetaCustomTool:` - - `CANCELLED("cancelled")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `QUEUED("queued")` + - `String name` - - `INCOMPLETE("incomplete")` + The name of the custom tool, used to identify it in tool calls. -### Beta Response Stream Event + - `JsonValue; type "custom"constant` -- `class BetaResponseStreamEvent: A class that can be one of several variants.union` + The type of the custom tool. Always `custom`. - Emitted when there is a partial audio response. + - `CUSTOM("custom")` - - `class BetaResponseAudioDeltaEvent:` + - `Optional> allowedCallers` - Emitted when there is a partial audio response. + The tool invocation context(s). - - `String delta` + - `DIRECT("direct")` - A chunk of Base64 encoded response audio bytes. + - `PROGRAMMATIC("programmatic")` - - `long sequenceNumber` + - `Optional deferLoading` - A sequence number for this chunk of the stream response. + Whether this tool should be deferred and discovered via tool search. - - `JsonValue; type "response.audio.delta"constant` + - `Optional description` - The type of the event. Always `response.audio.delta`. + Optional description of the custom tool, used to provide more context. - - `RESPONSE_AUDIO_DELTA("response.audio.delta")` + - `Optional format` - - `Optional agent` + The input format for the custom tool. Default is unconstrained text. - The agent that owns this multi-agent streaming event. + - `JsonValue;` - - `String agentName` + - `JsonValue; type "text"constant` - The canonical name of the agent that produced this item. + Unconstrained text format. Always `text`. - - `class BetaResponseAudioDoneEvent:` + - `TEXT("text")` - Emitted when the audio response is complete. + - `class Grammar:` - - `long sequenceNumber` + A grammar defined by the user. - The sequence number of the delta. + - `String definition` - - `JsonValue; type "response.audio.done"constant` + The grammar definition. - The type of the event. Always `response.audio.done`. + - `Syntax syntax` - - `RESPONSE_AUDIO_DONE("response.audio.done")` + The syntax of the grammar definition. One of `lark` or `regex`. - - `Optional agent` + - `LARK("lark")` - The agent that owns this multi-agent streaming event. + - `REGEX("regex")` - - `String agentName` + - `JsonValue; type "grammar"constant` - The canonical name of the agent that produced this item. + Grammar format. Always `grammar`. - - `class BetaResponseAudioTranscriptDeltaEvent:` + - `GRAMMAR("grammar")` - Emitted when there is a partial transcript of audio. + - `class BetaNamespaceTool:` - - `String delta` + Groups function/custom tools under a shared namespace. - The partial transcript of the audio response. + - `String description` - - `long sequenceNumber` + A description of the namespace shown to the model. - The sequence number of this event. + - `String name` - - `JsonValue; type "response.audio.transcript.delta"constant` + The namespace name used in tool calls (for example, `crm`). - The type of the event. Always `response.audio.transcript.delta`. + - `List tools` - - `RESPONSE_AUDIO_TRANSCRIPT_DELTA("response.audio.transcript.delta")` + The function/custom tools available inside this namespace. - - `Optional agent` + - `class Function:` - The agent that owns this multi-agent streaming event. + - `String name` - - `String agentName` + - `JsonValue; type "function"constant` - The canonical name of the agent that produced this item. + - `FUNCTION("function")` - - `class BetaResponseAudioTranscriptDoneEvent:` + - `Optional> allowedCallers` - Emitted when the full audio transcript is completed. + The tool invocation context(s). - - `long sequenceNumber` + - `DIRECT("direct")` - The sequence number of this event. + - `PROGRAMMATIC("programmatic")` - - `JsonValue; type "response.audio.transcript.done"constant` + - `Optional deferLoading` - The type of the event. Always `response.audio.transcript.done`. + Whether this function should be deferred and discovered via tool search. - - `RESPONSE_AUDIO_TRANSCRIPT_DONE("response.audio.transcript.done")` + - `Optional description` - - `Optional agent` + - `Optional outputSchema` - The agent that owns this multi-agent streaming event. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `String agentName` + - `Optional parameters` - The canonical name of the agent that produced this item. + - `Optional strict` - - `class BetaResponseCodeInterpreterCallCodeDeltaEvent:` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - Emitted when a partial code snippet is streamed by the code interpreter. + - `class BetaCustomTool:` - - `String delta` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The partial code snippet being streamed by the code interpreter. + - `JsonValue; type "namespace"constant` - - `String itemId` + The type of the tool. Always `namespace`. - The unique identifier of the code interpreter tool call item. + - `NAMESPACE("namespace")` - - `long outputIndex` + - `class BetaToolSearchTool:` - The index of the output item in the response for which the code is being streamed. + Hosted or BYOT tool search configuration for deferred tools. - - `long sequenceNumber` + - `JsonValue; type "tool_search"constant` - The sequence number of this event, used to order streaming events. + The type of the tool. Always `tool_search`. - - `JsonValue; type "response.code_interpreter_call_code.delta"constant` + - `TOOL_SEARCH("tool_search")` - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `Optional description` - - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DELTA("response.code_interpreter_call_code.delta")` + Description shown to the model for a client-executed tool search tool. - - `Optional agent` + - `Optional execution` - The agent that owns this multi-agent streaming event. + Whether tool search is executed by the server or by the client. - - `String agentName` + - `SERVER("server")` - The canonical name of the agent that produced this item. + - `CLIENT("client")` - - `class BetaResponseCodeInterpreterCallCodeDoneEvent:` + - `Optional parameters` - Emitted when the code snippet is finalized by the code interpreter. + Parameter schema for a client-executed tool search tool. - - `String code` + - `class BetaWebSearchPreviewTool:` - The final code snippet output by the code interpreter. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `String itemId` + - `Type type` - The unique identifier of the code interpreter tool call item. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `long outputIndex` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - The index of the output item in the response for which the code is finalized. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `long sequenceNumber` + - `Optional> searchContentTypes` - The sequence number of this event, used to order streaming events. + - `TEXT("text")` - - `JsonValue; type "response.code_interpreter_call_code.done"constant` + - `IMAGE("image")` - The type of the event. Always `response.code_interpreter_call_code.done`. + - `Optional searchContextSize` - - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DONE("response.code_interpreter_call_code.done")` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Optional agent` + - `LOW("low")` - The agent that owns this multi-agent streaming event. + - `MEDIUM("medium")` - - `String agentName` + - `HIGH("high")` - The canonical name of the agent that produced this item. + - `Optional userLocation` - - `class BetaResponseCodeInterpreterCallCompletedEvent:` + The user's location. - Emitted when the code interpreter call is completed. + - `JsonValue; type "approximate"constant` - - `String itemId` + The type of location approximation. Always `approximate`. - The unique identifier of the code interpreter tool call item. + - `APPROXIMATE("approximate")` - - `long outputIndex` + - `Optional city` - The index of the output item in the response for which the code interpreter call is completed. + Free text input for the city of the user, e.g. `San Francisco`. - - `long sequenceNumber` + - `Optional country` - The sequence number of this event, used to order streaming events. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `JsonValue; type "response.code_interpreter_call.completed"constant` + - `Optional region` - The type of the event. Always `response.code_interpreter_call.completed`. + Free text input for the region of the user, e.g. `California`. - - `RESPONSE_CODE_INTERPRETER_CALL_COMPLETED("response.code_interpreter_call.completed")` + - `Optional timezone` - - `Optional agent` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The agent that owns this multi-agent streaming event. + - `class BetaApplyPatchTool:` - - `String agentName` + Allows the assistant to create, delete, or update files using unified diffs. - The canonical name of the agent that produced this item. + - `JsonValue; type "apply_patch"constant` - - `class BetaResponseCodeInterpreterCallInProgressEvent:` + The type of the tool. Always `apply_patch`. - Emitted when a code interpreter call is in progress. + - `APPLY_PATCH("apply_patch")` - - `String itemId` + - `Optional> allowedCallers` - The unique identifier of the code interpreter tool call item. + The tool invocation context(s). - - `long outputIndex` + - `DIRECT("direct")` - The index of the output item in the response for which the code interpreter call is in progress. + - `PROGRAMMATIC("programmatic")` - - `long sequenceNumber` + - `JsonValue; type "tool_search_output"constant` - The sequence number of this event, used to order streaming events. + The item type. Always `tool_search_output`. - - `JsonValue; type "response.code_interpreter_call.in_progress"constant` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `Optional id` - - `RESPONSE_CODE_INTERPRETER_CALL_IN_PROGRESS("response.code_interpreter_call.in_progress")` + The unique ID of this tool search output. - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterCallInterpretingEvent:` + - `Optional callId` - Emitted when the code interpreter is actively interpreting the code snippet. + The unique ID of the tool search call generated by the model. - - `String itemId` + - `Optional execution` - The unique identifier of the code interpreter tool call item. + Whether tool search was executed by the server or by the client. - - `long outputIndex` + - `SERVER("server")` - The index of the output item in the response for which the code interpreter is interpreting code. + - `CLIENT("client")` - - `long sequenceNumber` + - `Optional status` - The sequence number of this event, used to order streaming events. + The status of the tool search output. - - `JsonValue; type "response.code_interpreter_call.interpreting"constant` + - `IN_PROGRESS("in_progress")` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `COMPLETED("completed")` - - `RESPONSE_CODE_INTERPRETER_CALL_INTERPRETING("response.code_interpreter_call.interpreting")` + - `INCOMPLETE("incomplete")` - - `Optional agent` + - `AdditionalTools` - The agent that owns this multi-agent streaming event. + - `JsonValue; role "developer"constant` - - `String agentName` + The role that provided the additional tools. Only `developer` is supported. - The canonical name of the agent that produced this item. + - `DEVELOPER("developer")` - - `class BetaResponseCompletedEvent:` + - `List tools` - Emitted when the model response is complete. + A list of additional tools made available at this item. - - `BetaResponse response` + - `class BetaFunctionTool:` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool:` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool:` - Properties of the completed response. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String id` + - `class BetaComputerUsePreviewTool:` - Unique identifier for this Response. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `double createdAt` + - `class BetaWebSearchTool:` - Unix timestamp (in seconds) of when this Response was created. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional error` + - `Mcp` - An error object returned when the model fails to generate a Response. + - `CodeInterpreter` - - `Code code` + - `JsonValue;` - The error code for the response. + - `ImageGeneration` - - `SERVER_ERROR("server_error")` + - `JsonValue;` - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `class BetaFunctionShellTool:` - - `INVALID_PROMPT("invalid_prompt")` + A tool that allows the model to execute shell commands. - - `BIO_POLICY("bio_policy")` + - `class BetaCustomTool:` - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `INVALID_IMAGE("invalid_image")` + - `class BetaNamespaceTool:` - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + Groups function/custom tools under a shared namespace. - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `class BetaToolSearchTool:` - - `INVALID_IMAGE_URL("invalid_image_url")` + Hosted or BYOT tool search configuration for deferred tools. - - `IMAGE_TOO_LARGE("image_too_large")` + - `class BetaWebSearchPreviewTool:` - - `IMAGE_TOO_SMALL("image_too_small")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `IMAGE_PARSE_ERROR("image_parse_error")` + - `class BetaApplyPatchTool:` - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + Allows the assistant to create, delete, or update files using unified diffs. - - `INVALID_IMAGE_MODE("invalid_image_mode")` + - `JsonValue; type "additional_tools"constant` - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + The item type. Always `additional_tools`. - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + - `ADDITIONAL_TOOLS("additional_tools")` - - `EMPTY_IMAGE_FILE("empty_image_file")` + - `Optional id` - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + The unique ID of this additional tools item. - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + - `Optional agent` - - `String message` + The agent that produced this item. - A human-readable description of the error. + - `String agentName` - - `Optional incompleteDetails` + The canonical name of the agent that produced this item. - Details about why the response is incomplete. + - `class BetaResponseReasoningItem:` - - `Optional reason` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - The reason why the response is incomplete. + - `String id` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + The unique identifier of the reasoning content. - - `CONTENT_FILTER("content_filter")` + - `List summary` - - `Optional instructions` + Reasoning summary content. - A system (or developer) message inserted into the model's context. + - `String text` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + A summary of the reasoning output from the model so far. - - `String` + - `JsonValue; type "summary_text"constant` - - `List` + The type of the object. Always `summary_text`. - - `class BetaEasyInputMessage:` + - `SUMMARY_TEXT("summary_text")` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `JsonValue; type "reasoning"constant` - - `Content content` + The type of the object. Always `reasoning`. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `REASONING("reasoning")` - - `String` + - `Optional agent` - - `List` + The agent that produced this item. - - `class BetaResponseInputText:` + - `String agentName` - A text input to the model. + The canonical name of the agent that produced this item. - - `String text` + - `Optional> content` - The text input to the model. + Reasoning text content. - - `JsonValue; type "input_text"constant` + - `String text` - The type of the input item. Always `input_text`. + The reasoning text from the model. - - `INPUT_TEXT("input_text")` + - `JsonValue; type "reasoning_text"constant` - - `Optional promptCacheBreakpoint` + The type of the reasoning text. Always `reasoning_text`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `REASONING_TEXT("reasoning_text")` - - `JsonValue; mode "explicit"constant` + - `Optional encryptedContent` - The breakpoint mode. Always `explicit`. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `EXPLICIT("explicit")` + - `Optional status` - - `class BetaResponseInputImage:` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `IN_PROGRESS("in_progress")` - - `Detail detail` + - `COMPLETED("completed")` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `INCOMPLETE("incomplete")` - - `LOW("low")` + - `class BetaResponseCompactionItemParam:` - - `HIGH("high")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `AUTO("auto")` + - `String encryptedContent` - - `ORIGINAL("original")` + The encrypted content of the compaction summary. - - `JsonValue; type "input_image"constant` + - `JsonValue; type "compaction"constant` - The type of the input item. Always `input_image`. + The type of the item. Always `compaction`. - - `INPUT_IMAGE("input_image")` + - `COMPACTION("compaction")` - - `Optional fileId` + - `Optional id` - The ID of the file to be sent to the model. + The ID of the compaction item. - - `Optional imageUrl` + - `Optional agent` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The agent that produced this item. - - `Optional promptCacheBreakpoint` + - `String agentName` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The canonical name of the agent that produced this item. - - `JsonValue; mode "explicit"constant` + - `ImageGenerationCall` - The breakpoint mode. Always `explicit`. + - `String id` - - `EXPLICIT("explicit")` + The unique ID of the image generation call. - - `class BetaResponseInputFile:` + - `Optional result` - A file input to the model. + The generated image encoded in base64. - - `JsonValue; type "input_file"constant` + - `Status status` - The type of the input item. Always `input_file`. + The status of the image generation call. - - `INPUT_FILE("input_file")` + - `IN_PROGRESS("in_progress")` - - `Optional detail` + - `COMPLETED("completed")` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `GENERATING("generating")` - - `AUTO("auto")` + - `FAILED("failed")` - - `LOW("low")` + - `JsonValue; type "image_generation_call"constant` - - `HIGH("high")` + The type of the image generation call. Always `image_generation_call`. - - `Optional fileData` + - `IMAGE_GENERATION_CALL("image_generation_call")` - The content of the file to be sent to the model. + - `Optional agent` - - `Optional fileId` + The agent that produced this item. - The ID of the file to be sent to the model. + - `String agentName` - - `Optional fileUrl` + The canonical name of the agent that produced this item. - The URL of the file to be sent to the model. + - `class BetaResponseCodeInterpreterToolCall:` - - `Optional filename` + A tool call to run code. - The name of the file to be sent to the model. + - `String id` - - `Optional promptCacheBreakpoint` + The unique ID of the code interpreter tool call. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional code` - - `JsonValue; mode "explicit"constant` + The code to run, or null if not available. - The breakpoint mode. Always `explicit`. + - `String containerId` - - `EXPLICIT("explicit")` + The ID of the container used to run the code. - - `Role role` + - `Optional> outputs` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `USER("user")` + - `class Logs:` - - `ASSISTANT("assistant")` + The logs output from the code interpreter. - - `SYSTEM("system")` + - `String logs` - - `DEVELOPER("developer")` + The logs output from the code interpreter. - - `Optional phase` + - `JsonValue; type "logs"constant` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The type of the output. Always `logs`. - - `COMMENTARY("commentary")` + - `LOGS("logs")` - - `Optional type` + - `class Image:` - The type of the message input. Always `message`. + The image output from the code interpreter. - - `MESSAGE("message")` + - `JsonValue; type "image"constant` - - `Message` + The type of the output. Always `image`. - - `List content` + - `IMAGE("image")` - A list of one or many input items to the model, containing different content - types. + - `String url` - - `class BetaResponseInputText:` + The URL of the image output from the code interpreter. - A text input to the model. + - `Status status` - - `class BetaResponseInputImage:` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `IN_PROGRESS("in_progress")` - - `class BetaResponseInputFile:` + - `COMPLETED("completed")` - A file input to the model. + - `INCOMPLETE("incomplete")` - - `Role role` + - `INTERPRETING("interpreting")` - The role of the message input. One of `user`, `system`, or `developer`. + - `FAILED("failed")` - - `USER("user")` + - `JsonValue; type "code_interpreter_call"constant` - - `SYSTEM("system")` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `DEVELOPER("developer")` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - `Optional agent` @@ -116665,189 +129336,179 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional 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")` + - `LocalShellCall` - - `Optional type` + - `String id` - The type of the message input. Always set to `message`. + The unique ID of the local shell call. - - `MESSAGE("message")` + - `Action action` - - `class BetaResponseOutputMessage:` + Execute a shell command on the server. - An output message from the model. + - `List command` - - `String id` + The command to run. - The unique ID of the output message. + - `Env env` - - `List content` + Environment variables to set for the command. - The content of the output message. + - `JsonValue; type "exec"constant` - - `class BetaResponseOutputText:` + The type of the local shell action. Always `exec`. - A text output from the model. + - `EXEC("exec")` - - `List annotations` + - `Optional timeoutMs` - The annotations of the text output. + Optional timeout in milliseconds for the command. - - `class FileCitation:` + - `Optional user` - A citation to a file. + Optional user to run the command as. - - `String fileId` + - `Optional workingDirectory` - The ID of the file. + Optional working directory to run the command in. - - `String filename` + - `String callId` - The filename of the file cited. + The unique ID of the local shell tool call generated by the model. - - `long index` + - `Status status` - The index of the file in the list of files. + The status of the local shell call. - - `JsonValue; type "file_citation"constant` + - `IN_PROGRESS("in_progress")` - The type of the file citation. Always `file_citation`. + - `COMPLETED("completed")` - - `FILE_CITATION("file_citation")` + - `INCOMPLETE("incomplete")` - - `class UrlCitation:` + - `JsonValue; type "local_shell_call"constant` - A citation for a web resource used to generate a model response. + The type of the local shell call. Always `local_shell_call`. - - `long endIndex` + - `LOCAL_SHELL_CALL("local_shell_call")` - The index of the last character of the URL citation in the message. + - `Optional agent` - - `long startIndex` + The agent that produced this item. - The index of the first character of the URL citation in the message. + - `String agentName` - - `String title` + The canonical name of the agent that produced this item. - The title of the web resource. + - `LocalShellCallOutput` - - `JsonValue; type "url_citation"constant` + - `String id` - The type of the URL citation. Always `url_citation`. + The unique ID of the local shell tool call generated by the model. - - `URL_CITATION("url_citation")` + - `String output` - - `String url` + A JSON string of the output of the local shell tool call. - The URL of the web resource. + - `JsonValue; type "local_shell_call_output"constant` - - `class ContainerFileCitation:` + The type of the local shell tool call output. Always `local_shell_call_output`. - A citation for a container file used to generate a model response. + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `String containerId` + - `Optional agent` - The ID of the container file. + The agent that produced this item. - - `long endIndex` + - `String agentName` - The index of the last character of the container file citation in the message. + The canonical name of the agent that produced this item. - - `String fileId` + - `Optional status` - The ID of the file. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `String filename` + - `IN_PROGRESS("in_progress")` - The filename of the container file cited. + - `COMPLETED("completed")` - - `long startIndex` + - `INCOMPLETE("incomplete")` - The index of the first character of the container file citation in the message. + - `ShellCall` - - `JsonValue; type "container_file_citation"constant` + - `Action action` - The type of the container file citation. Always `container_file_citation`. + The shell commands and limits that describe how to run the tool call. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `List commands` - - `class FilePath:` + Ordered shell commands for the execution environment to run. - A path to a file. + - `Optional maxOutputLength` - - `String fileId` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The ID of the file. + - `Optional timeoutMs` - - `long index` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The index of the file in the list of files. + - `String callId` - - `JsonValue; type "file_path"constant` + The unique ID of the shell tool call generated by the model. - The type of the file path. Always `file_path`. + - `JsonValue; type "shell_call"constant` - - `FILE_PATH("file_path")` + The type of the item. Always `shell_call`. - - `String text` + - `SHELL_CALL("shell_call")` - The text output from the model. + - `Optional id` - - `JsonValue; type "output_text"constant` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of the output text. Always `output_text`. + - `Optional agent` - - `OUTPUT_TEXT("output_text")` + The agent that produced this item. - - `Optional> logprobs` + - `String agentName` - - `String token` + The canonical name of the agent that produced this item. - - `List bytes` + - `Optional caller` - - `double logprob` + The execution context that produced this tool call. - - `List topLogprobs` + - `JsonValue;` - - `String token` + - `JsonValue; type "direct"constant` - - `List bytes` + The caller type. Always `direct`. - - `double logprob` + - `DIRECT("direct")` - - `class BetaResponseOutputRefusal:` + - `class Program:` - A refusal from the model. + - `String callerId` - - `String refusal` + The call ID of the program item that produced this tool call. - The refusal explanation from the model. + - `JsonValue; type "program"constant` - - `JsonValue; type "refusal"constant` + The caller type. Always `program`. - The type of the refusal. Always `refusal`. + - `PROGRAM("program")` - - `REFUSAL("refusal")` + - `Optional environment` - - `JsonValue; role "assistant"constant` + The environment to execute the shell commands in. - The role of the output message. Always `assistant`. + - `class BetaLocalEnvironment:` - - `ASSISTANT("assistant")` + - `class BetaContainerReference:` - - `Status status` + - `Optional status` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` @@ -116855,61 +129516,59 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `JsonValue; type "message"constant` + - `ShellCallOutput` - The type of the output message. Always `message`. + - `String callId` - - `MESSAGE("message")` + The unique ID of the shell tool call generated by the model. - - `Optional agent` + - `List output` - The agent that produced this item. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `String agentName` + - `Outcome outcome` - The canonical name of the agent that produced this item. + The exit or timeout outcome associated with this shell call. - - `Optional phase` + - `JsonValue;` - 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. + - `JsonValue; type "timeout"constant` - - `COMMENTARY("commentary")` + The outcome type. Always `timeout`. - - `class BetaResponseFileSearchToolCall:` + - `TIMEOUT("timeout")` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `class Exit:` - - `String id` + Indicates that the shell commands finished and returned an exit code. - The unique ID of the file search tool call. + - `long exitCode` - - `List queries` + The exit code returned by the shell process. - The queries used to search for files. + - `JsonValue; type "exit"constant` - - `Status status` + The outcome type. Always `exit`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `EXIT("exit")` - - `IN_PROGRESS("in_progress")` + - `String stderr` - - `SEARCHING("searching")` + Captured stderr output for the shell call. - - `COMPLETED("completed")` + - `String stdout` - - `INCOMPLETE("incomplete")` + Captured stdout output for the shell call. - - `FAILED("failed")` + - `JsonValue; type "shell_call_output"constant` - - `JsonValue; type "file_search_call"constant` + The type of the item. Always `shell_call_output`. - The type of the file search tool call. Always `file_search_call`. + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `FILE_SEARCH_CALL("file_search_call")` + - `Optional id` + + The unique ID of the shell tool call output. Populated when this item is returned via API. - `Optional agent` @@ -116919,493 +129578,481 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional> results` - - The results of the file search tool call. + - `Optional caller` - - `Optional attributes` + The execution context that produced this tool call. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `JsonValue;` - - `String` + - `JsonValue; type "direct"constant` - - `double` + The caller type. Always `direct`. - - `boolean` + - `DIRECT("direct")` - - `Optional fileId` + - `class Program:` - The unique ID of the file. + - `String callerId` - - `Optional filename` + The call ID of the program item that produced this tool call. - The name of the file. + - `JsonValue; type "program"constant` - - `Optional score` + The caller type. Always `program`. - The relevance score of the file - a value between 0 and 1. + - `PROGRAM("program")` - - `Optional text` + - `Optional maxOutputLength` - The text that was retrieved from the file. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseComputerToolCall:` + - `Optional status` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The status of the shell call output. - - `String id` + - `IN_PROGRESS("in_progress")` - The unique ID of the computer call. + - `COMPLETED("completed")` - - `String callId` + - `INCOMPLETE("incomplete")` - An identifier used when responding to the tool call with output. + - `ApplyPatchCall` - - `List pendingSafetyChecks` + - `String callId` - The pending safety checks for the computer call. + The unique ID of the apply patch tool call generated by the model. - - `String id` + - `Operation operation` - The ID of the pending safety check. + The specific create, delete, or update instruction for the apply_patch tool call. - - `Optional code` + - `class CreateFile:` - The type of the pending safety check. + Instruction for creating a new file via the apply_patch tool. - - `Optional message` + - `String diff` - Details about the pending safety check. + Unified diff content to apply when creating the file. - - `Status status` + - `String path` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Path of the file to create relative to the workspace root. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "create_file"constant` - - `COMPLETED("completed")` + The operation type. Always `create_file`. - - `INCOMPLETE("incomplete")` + - `CREATE_FILE("create_file")` - - `Type type` + - `class DeleteFile:` - The type of the computer call. Always `computer_call`. + Instruction for deleting an existing file via the apply_patch tool. - - `COMPUTER_CALL("computer_call")` + - `String path` - - `Optional action` + Path of the file to delete relative to the workspace root. - A click action. + - `JsonValue; type "delete_file"constant` - - `Click` + The operation type. Always `delete_file`. - - `Button button` + - `DELETE_FILE("delete_file")` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `class UpdateFile:` - - `LEFT("left")` + Instruction for updating an existing file via the apply_patch tool. - - `RIGHT("right")` + - `String diff` - - `WHEEL("wheel")` + Unified diff content to apply to the existing file. - - `BACK("back")` + - `String path` - - `FORWARD("forward")` + Path of the file to update relative to the workspace root. - - `JsonValue; type "click"constant` + - `JsonValue; type "update_file"constant` - Specifies the event type. For a click action, this property is always `click`. + The operation type. Always `update_file`. - - `CLICK("click")` + - `UPDATE_FILE("update_file")` - - `long x` + - `Status status` - The x-coordinate where the click occurred. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `long y` + - `IN_PROGRESS("in_progress")` - The y-coordinate where the click occurred. + - `COMPLETED("completed")` - - `Optional> keys` + - `JsonValue; type "apply_patch_call"constant` - The keys being held while clicking. + The type of the item. Always `apply_patch_call`. - - `DoubleClick` + - `APPLY_PATCH_CALL("apply_patch_call")` - - `Optional> keys` + - `Optional id` - The keys being held while double-clicking. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `JsonValue; type "double_click"constant` + - `Optional agent` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The agent that produced this item. - - `DOUBLE_CLICK("double_click")` + - `String agentName` - - `long x` + The canonical name of the agent that produced this item. - The x-coordinate where the double click occurred. + - `Optional caller` - - `long y` + The execution context that produced this tool call. - The y-coordinate where the double click occurred. + - `JsonValue;` - - `Drag` + - `JsonValue; type "direct"constant` - - `List path` + The caller type. Always `direct`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `DIRECT("direct")` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `class Program:` - - `long x` + - `String callerId` - The x-coordinate. + The call ID of the program item that produced this tool call. - - `long y` + - `JsonValue; type "program"constant` - The y-coordinate. + The caller type. Always `program`. - - `JsonValue; type "drag"constant` + - `PROGRAM("program")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `ApplyPatchCallOutput` - - `DRAG("drag")` + - `String callId` - - `Optional> keys` + The unique ID of the apply patch tool call generated by the model. - The keys being held while dragging the mouse. + - `Status status` - - `Keypress` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `List keys` + - `COMPLETED("completed")` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `FAILED("failed")` - - `JsonValue; type "keypress"constant` + - `JsonValue; type "apply_patch_call_output"constant` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The type of the item. Always `apply_patch_call_output`. - - `KEYPRESS("keypress")` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `Move` + - `Optional id` - - `JsonValue; type "move"constant` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Specifies the event type. For a move action, this property is always set to `move`. + - `Optional agent` - - `MOVE("move")` + The agent that produced this item. - - `long x` + - `String agentName` - The x-coordinate to move to. + The canonical name of the agent that produced this item. - - `long y` + - `Optional caller` - The y-coordinate to move to. + The execution context that produced this tool call. - - `Optional> keys` + - `JsonValue;` - The keys being held while moving the mouse. + - `JsonValue; type "direct"constant` - - `JsonValue;` + The caller type. Always `direct`. - - `JsonValue; type "screenshot"constant` + - `DIRECT("direct")` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `class Program:` - - `SCREENSHOT("screenshot")` + - `String callerId` - - `Scroll` + The call ID of the program item that produced this tool call. - - `long scrollX` + - `JsonValue; type "program"constant` - The horizontal scroll distance. + The caller type. Always `program`. - - `long scrollY` + - `PROGRAM("program")` - The vertical scroll distance. + - `Optional output` - - `JsonValue; type "scroll"constant` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `McpListTools` - - `SCROLL("scroll")` + - `String id` - - `long x` + The unique ID of the list. - The x-coordinate where the scroll occurred. + - `String serverLabel` - - `long y` + The label of the MCP server. - The y-coordinate where the scroll occurred. + - `List tools` - - `Optional> keys` + The tools available on the server. - The keys being held while scrolling. + - `JsonValue inputSchema` - - `Type` + The JSON schema describing the tool's input. - - `String text` + - `String name` - The text to type. + The name of the tool. - - `JsonValue; type "type"constant` + - `Optional annotations` - Specifies the event type. For a type action, this property is always set to `type`. + Additional annotations about the tool. - - `TYPE("type")` + - `Optional description` - - `JsonValue;` + The description of the tool. - - `JsonValue; type "wait"constant` + - `JsonValue; type "mcp_list_tools"constant` - Specifies the event type. For a wait action, this property is always set to `wait`. + The type of the item. Always `mcp_list_tools`. - - `WAIT("wait")` + - `MCP_LIST_TOOLS("mcp_list_tools")` - - `Optional> actions` + - `Optional agent` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The agent that produced this item. - - `Click` + - `String agentName` - - `DoubleClick` + The canonical name of the agent that produced this item. - - `Drag` + - `Optional error` - - `Keypress` + Error message if the server could not list tools. - - `Move` + - `McpApprovalRequest` - - `JsonValue;` + - `String id` - - `Scroll` + The unique ID of the approval request. - - `Type` + - `String arguments` - - `JsonValue;` + A JSON string of arguments for the tool. - - `Optional agent` + - `String name` - The agent that produced this item. + The name of the tool to run. - - `String agentName` + - `String serverLabel` - The canonical name of the agent that produced this item. + The label of the MCP server making the request. - - `ComputerCallOutput` + - `JsonValue; type "mcp_approval_request"constant` - - `String callId` + The type of the item. Always `mcp_approval_request`. - The ID of the computer tool call that produced the output. + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `Optional agent` - A computer screenshot image used with the computer use tool. + The agent that produced this item. - - `JsonValue; type "computer_screenshot"constant` + - `String agentName` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The canonical name of the agent that produced this item. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `McpApprovalResponse` - - `Optional fileId` + - `String approvalRequestId` - The identifier of an uploaded file that contains the screenshot. + The ID of the approval request being answered. - - `Optional imageUrl` + - `boolean approve` - The URL of the screenshot image. + Whether the request was approved. - - `JsonValue; type "computer_call_output"constant` + - `JsonValue; type "mcp_approval_response"constant` - The type of the computer tool call output. Always `computer_call_output`. + The type of the item. Always `mcp_approval_response`. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - `Optional id` - The ID of the computer tool call output. + The unique ID of the approval response - - `Optional> acknowledgedSafetyChecks` + - `Optional agent` - The safety checks reported by the API that have been acknowledged by the developer. + The agent that produced this item. - - `String id` + - `String agentName` - The ID of the pending safety check. + The canonical name of the agent that produced this item. - - `Optional code` + - `Optional reason` - The type of the pending safety check. + Optional reason for the decision. - - `Optional message` + - `McpCall` - Details about the pending safety check. + - `String id` - - `Optional agent` + The unique ID of the tool call. - The agent that produced this item. + - `String arguments` - - `String agentName` + A JSON string of the arguments passed to the tool. - The canonical name of the agent that produced this item. + - `String name` - - `Optional status` + The name of the tool that was run. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `String serverLabel` - - `IN_PROGRESS("in_progress")` + The label of the MCP server running the tool. - - `COMPLETED("completed")` + - `JsonValue; type "mcp_call"constant` - - `INCOMPLETE("incomplete")` + The type of the item. Always `mcp_call`. - - `class BetaResponseFunctionWebSearch:` + - `MCP_CALL("mcp_call")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Optional agent` - - `String id` + The agent that produced this item. - The unique ID of the web search tool call. + - `String agentName` - - `Action action` + The canonical name of the agent that produced this item. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `Optional approvalRequestId` - - `class Search:` + 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. - Action type "search" - Performs a web search query. + - `Optional error` - - `JsonValue; type "search"constant` + The error from the tool call, if any. - The action type. + - `Optional output` - - `SEARCH("search")` + The output from the tool call. - - `Optional> queries` + - `Optional status` - The search queries. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `Optional query` + - `IN_PROGRESS("in_progress")` - The search query. + - `COMPLETED("completed")` - - `Optional> sources` + - `INCOMPLETE("incomplete")` - The sources used in the search. + - `CALLING("calling")` - - `JsonValue; type "url"constant` + - `FAILED("failed")` - The type of source. Always `url`. + - `class BetaResponseCustomToolCallOutput:` - - `URL("url")` + The output of a custom tool call from your code, being sent back to the model. - - `String url` + - `String callId` - The URL of the source. + The call ID, used to map this custom tool call output to a custom tool call. - - `class OpenPage:` + - `Output output` - Action type "open_page" - Opens a specific URL from search results. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `JsonValue; type "open_page"constant` + - `String` - The action type. + - `List` - - `OPEN_PAGE("open_page")` + - `class BetaResponseInputText:` - - `Optional url` + A text input to the model. - The URL opened by the model. + - `class BetaResponseInputImage:` - - `class FindInPage:` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Action type "find_in_page": Searches for a pattern within a loaded page. + - `class BetaResponseInputFile:` - - `String pattern` + A file input to the model. - The pattern or text to search for within the page. + - `JsonValue; type "custom_tool_call_output"constant` - - `JsonValue; type "find_in_page"constant` + The type of the custom tool call output. Always `custom_tool_call_output`. - The action type. + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - - `FIND_IN_PAGE("find_in_page")` + - `Optional id` - - `String url` + The unique ID of the custom tool call output in the OpenAI platform. - The URL of the page searched for the pattern. + - `Optional agent` - - `Status status` + The agent that produced this item. - The status of the web search tool call. + - `String agentName` - - `IN_PROGRESS("in_progress")` + The canonical name of the agent that produced this item. - - `SEARCHING("searching")` + - `Optional caller` - - `COMPLETED("completed")` + The execution context that produced this tool call. - - `FAILED("failed")` + - `JsonValue;` - - `JsonValue; type "web_search_call"constant` + - `JsonValue; type "direct"constant` - The type of the web search tool call. Always `web_search_call`. + The caller type. Always `direct`. - - `WEB_SEARCH_CALL("web_search_call")` + - `DIRECT("direct")` - - `Optional agent` + - `class Program:` - The agent that produced this item. + - `String callerId` - - `String agentName` + The call ID of the program item that produced this tool call. - The canonical name of the agent that produced this item. + - `JsonValue; type "program"constant` - - `class BetaResponseFunctionToolCall:` + The caller type. Always `program`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `PROGRAM("program")` - - `String arguments` + - `class BetaResponseCustomToolCall:` - A JSON string of the arguments to pass to the function. + A call to a custom tool created by the model. - `String callId` - The unique ID of the function tool call generated by the model. + 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 function to run. + The name of the custom tool being called. - - `JsonValue; type "function_call"constant` + - `JsonValue; type "custom_tool_call"constant` - The type of the function tool call. Always `function_call`. + The type of the custom tool call. Always `custom_tool_call`. - - `FUNCTION_CALL("function_call")` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - `Optional id` - The unique ID of the function tool call. + The unique ID of the custom tool call in the OpenAI platform. - `Optional agent` @@ -117437,1543 +130084,1533 @@ public final class Main { - `Optional namespace` - The namespace of the function to run. + The namespace of the custom tool being called. - - `Optional status` + - `CompactionTrigger` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `JsonValue; type "compaction_trigger"constant` - - `IN_PROGRESS("in_progress")` + The type of the item. Always `compaction_trigger`. + + - `COMPACTION_TRIGGER("compaction_trigger")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ItemReference` + + - `String id` - - `COMPLETED("completed")` + The ID of the item to reference. - - `INCOMPLETE("incomplete")` + - `Optional agent` - - `FunctionCallOutput` + The agent that produced this item. - - `String callId` + - `String agentName` - The unique ID of the function tool call generated by the model. + The canonical name of the agent that produced this item. - - `Output output` + - `Optional type` - Text, image, or file output of the function tool call. + The type of item to reference. Always `item_reference`. - - `String` + - `ITEM_REFERENCE("item_reference")` - - `List` + - `Program` - - `class BetaResponseInputTextContent:` + - `String id` - A text input to the model. + The unique ID of this program item. - - `String text` + - `String callId` - The text input to the model. + The stable call ID of the program item. - - `JsonValue; type "input_text"constant` + - `String code` - The type of the input item. Always `input_text`. + The JavaScript source executed by programmatic tool calling. - - `INPUT_TEXT("input_text")` + - `String fingerprint` - - `Optional promptCacheBreakpoint` + Opaque program replay fingerprint that must be round-tripped. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; type "program"constant` - - `JsonValue; mode "explicit"constant` + The item type. Always `program`. - The breakpoint mode. Always `explicit`. + - `PROGRAM("program")` - - `EXPLICIT("explicit")` + - `Optional agent` - - `class BetaResponseInputImageContent:` + The agent that produced this item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `String agentName` - - `JsonValue; type "input_image"constant` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_image`. + - `ProgramOutput` - - `INPUT_IMAGE("input_image")` + - `String id` - - `Optional detail` + The unique ID of this program output item. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `String callId` - - `LOW("low")` + The call ID of the program item. - - `HIGH("high")` + - `String result` - - `AUTO("auto")` + The result produced by the program item. - - `ORIGINAL("original")` + - `Status status` - - `Optional fileId` + The terminal status of the program output. - The ID of the file to be sent to the model. + - `COMPLETED("completed")` - - `Optional imageUrl` + - `INCOMPLETE("incomplete")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `JsonValue; type "program_output"constant` - - `Optional promptCacheBreakpoint` + The item type. Always `program_output`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `PROGRAM_OUTPUT("program_output")` - - `JsonValue; mode "explicit"constant` + - `Optional agent` - The breakpoint mode. Always `explicit`. + The agent that produced this item. - - `EXPLICIT("explicit")` + - `String agentName` - - `class BetaResponseInputFileContent:` + The canonical name of the agent that produced this item. - A file input to the model. + - `Optional metadata` - - `JsonValue; type "input_file"constant` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The type of the input item. Always `input_file`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `INPUT_FILE("input_file")` + - `Model model` - - `Optional detail` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `GPT_5_6_SOL("gpt-5.6-sol")` - - `AUTO("auto")` + - `GPT_5_6_TERRA("gpt-5.6-terra")` - - `LOW("low")` + - `GPT_5_6_LUNA("gpt-5.6-luna")` - - `HIGH("high")` + - `GPT_5_4("gpt-5.4")` - - `Optional fileData` + - `GPT_5_4_MINI("gpt-5.4-mini")` - The base64-encoded data of the file to be sent to the model. + - `GPT_5_4_NANO("gpt-5.4-nano")` - - `Optional fileId` + - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - The ID of the file to be sent to the model. + - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - `Optional fileUrl` + - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - The URL of the file to be sent to the model. + - `GPT_5_2("gpt-5.2")` - - `Optional filename` + - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - The name of the file to be sent to the model. + - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - `Optional promptCacheBreakpoint` + - `GPT_5_2_PRO("gpt-5.2-pro")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - `JsonValue; mode "explicit"constant` + - `GPT_5_1("gpt-5.1")` - The breakpoint mode. Always `explicit`. + - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - `EXPLICIT("explicit")` + - `GPT_5_1_CODEX("gpt-5.1-codex")` - - `JsonValue; type "function_call_output"constant` + - `GPT_5_1_MINI("gpt-5.1-mini")` - The type of the function tool call output. Always `function_call_output`. + - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `GPT_5("gpt-5")` - - `Optional id` + - `GPT_5_MINI("gpt-5-mini")` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `GPT_5_NANO("gpt-5-nano")` - - `Optional agent` + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - The agent that produced this item. + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `String agentName` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - The canonical name of the agent that produced this item. + - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - `Optional caller` + - `GPT_4_1("gpt-4.1")` - The execution context that produced this tool call. + - `GPT_4_1_MINI("gpt-4.1-mini")` - - `JsonValue;` + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `JsonValue; type "direct"constant` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - The caller type. Always `direct`. + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `DIRECT("direct")` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - - `class Program:` + - `O4_MINI("o4-mini")` - - `String callerId` + - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - The call ID of the program item that produced this tool call. + - `O3("o3")` - - `JsonValue; type "program"constant` + - `O3_2025_04_16("o3-2025-04-16")` - The caller type. Always `program`. + - `O3_MINI("o3-mini")` - - `PROGRAM("program")` + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - `Optional status` + - `O1("o1")` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `O1_2024_12_17("o1-2024-12-17")` - - `IN_PROGRESS("in_progress")` + - `O1_PREVIEW("o1-preview")` - - `COMPLETED("completed")` + - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - - `INCOMPLETE("incomplete")` + - `O1_MINI("o1-mini")` - - `AgentMessage` + - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - - `String author` + - `GPT_4O("gpt-4o")` - The sending agent identity. + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - - `List content` + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - Plaintext, image, or encrypted content sent between agents. + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - - `class BetaResponseInputTextContent:` + - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - A text input to the model. + - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - `class BetaResponseInputImageContent:` + - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - - `class EncryptedContent:` + - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - `String encryptedContent` + - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - Opaque encrypted content. + - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - `JsonValue; type "encrypted_content"constant` + - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - The type of the input item. Always `encrypted_content`. + - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - `String recipient` + - `CODEX_MINI_LATEST("codex-mini-latest")` - The destination agent identity. + - `GPT_4O_MINI("gpt-4o-mini")` - - `JsonValue; type "agent_message"constant` + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - The item type. Always `agent_message`. + - `GPT_4_TURBO("gpt-4-turbo")` - - `AGENT_MESSAGE("agent_message")` + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - - `Optional id` + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - The unique ID of this agent message item. + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `Optional agent` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - The agent that produced this item. + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - - `String agentName` + - `GPT_4("gpt-4")` - The canonical name of the agent that produced this item. + - `GPT_4_0314("gpt-4-0314")` - - `MultiAgentCall` + - `GPT_4_0613("gpt-4-0613")` - - `Action action` + - `GPT_4_32K("gpt-4-32k")` - The multi-agent action that was executed. + - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `SPAWN_AGENT("spawn_agent")` + - `GPT_4_32K_0613("gpt-4-32k-0613")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - - `LIST_AGENTS("list_agents")` + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - - `SEND_MESSAGE("send_message")` + - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - - `FOLLOWUP_TASK("followup_task")` + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `WAIT_AGENT("wait_agent")` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - - `String arguments` + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - The action arguments as a JSON string. + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - - `String callId` + - `O1_PRO("o1-pro")` - The unique ID linking this call to its output. + - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - - `JsonValue; type "multi_agent_call"constant` + - `O3_PRO("o3-pro")` - The item type. Always `multi_agent_call`. + - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `O3_DEEP_RESEARCH("o3-deep-research")` - - `Optional id` + - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - The unique ID of this multi-agent call. + - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - - `Optional agent` + - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - The agent that produced this item. + - `COMPUTER_USE_PREVIEW("computer-use-preview")` - - `String agentName` + - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - The canonical name of the agent that produced this item. + - `GPT_5_CODEX("gpt-5-codex")` - - `MultiAgentCallOutput` + - `GPT_5_PRO("gpt-5-pro")` - - `Action action` + - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - The multi-agent action that produced this result. + - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - - `SPAWN_AGENT("spawn_agent")` + - `JsonValue; object_ "response"constant` - - `INTERRUPT_AGENT("interrupt_agent")` + The object type of this resource - always set to `response`. - - `LIST_AGENTS("list_agents")` + - `RESPONSE("response")` - - `SEND_MESSAGE("send_message")` + - `List output` - - `FOLLOWUP_TASK("followup_task")` + An array of content items generated by the model. - - `WAIT_AGENT("wait_agent")` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `String callId` + - `class BetaResponseOutputMessage:` - The unique ID of the multi-agent call. + An output message from the model. - - `List output` + - `class BetaResponseFileSearchToolCall:` - Text output returned by the multi-agent action. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `String text` + - `class BetaResponseFunctionToolCall:` - The text content. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `JsonValue; type "output_text"constant` + - `class BetaResponseFunctionToolCallOutputItem:` - The content type. Always `output_text`. + - `String id` - - `OUTPUT_TEXT("output_text")` + The unique ID of the function call tool output. - - `Optional annotations` + - `String callId` - Citations associated with the text content. + The unique ID of the function tool call generated by the model. - - `List` + - `Output output` - - `String fileId` + The output from the function call generated by your code. + Can be a string or an list of output content. - The ID of the file. + - `String` - - `String filename` + - `List` - The filename of the file cited. + - `class BetaResponseInputText:` - - `long index` + A text input to the model. - The index of the file in the list of files. + - `class BetaResponseInputImage:` - - `JsonValue; type "file_citation"constant` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The citation type. Always `file_citation`. + - `class BetaResponseInputFile:` - - `FILE_CITATION("file_citation")` + A file input to the model. - - `List` + - `Status status` - - `long endIndex` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The index of the last character of the citation in the message. + - `IN_PROGRESS("in_progress")` - - `long startIndex` + - `COMPLETED("completed")` - The index of the first character of the citation in the message. + - `INCOMPLETE("incomplete")` - - `String title` + - `JsonValue; type "function_call_output"constant` - The title of the cited resource. + The type of the function tool call output. Always `function_call_output`. - - `JsonValue; type "url_citation"constant` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - The citation type. Always `url_citation`. + - `Optional agent` - - `URL_CITATION("url_citation")` + The agent that produced this item. - - `String url` + - `String agentName` - The URL of the cited resource. + The canonical name of the agent that produced this item. - - `List` + - `Optional caller` - - `String containerId` + The execution context that produced this tool call. - The ID of the container. + - `JsonValue;` - - `long endIndex` + - `JsonValue; type "direct"constant` - The index of the last character of the citation in the message. + The caller type. Always `direct`. - - `String fileId` + - `DIRECT("direct")` - The ID of the container file. + - `class Program:` - - `String filename` + - `String callerId` - The filename of the container file cited. + The call ID of the program item that produced this tool call. - - `long startIndex` + - `JsonValue; type "program"constant` - The index of the first character of the citation in the message. + The caller type. Always `program`. - - `JsonValue; type "container_file_citation"constant` + - `PROGRAM("program")` - The citation type. Always `container_file_citation`. + - `Optional createdBy` - - `CONTAINER_FILE_CITATION("container_file_citation")` + The identifier of the actor that created the item. - - `JsonValue; type "multi_agent_call_output"constant` + - `AgentMessage` - The item type. Always `multi_agent_call_output`. + - `String id` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + The unique ID of the agent message. - - `Optional id` + - `String author` - The unique ID of this multi-agent call output. + The sending agent identity. - - `Optional agent` + - `List content` - The agent that produced this item. + Encrypted content sent between agents. - - `String agentName` + - `class BetaResponseInputText:` - The canonical name of the agent that produced this item. + A text input to the model. - - `ToolSearchCall` + - `class BetaResponseOutputText:` - - `JsonValue arguments` + A text output from the model. - The arguments supplied to the tool search call. + - `class Text:` - - `JsonValue; type "tool_search_call"constant` + A text content. - The item type. Always `tool_search_call`. + - `String text` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `JsonValue; type "text"constant` - - `Optional id` + - `TEXT("text")` - The unique ID of this tool search call. + - `class SummaryText:` - - `Optional agent` + A summary text from the model. - The agent that produced this item. + - `String text` - - `String agentName` + A summary of the reasoning output from the model so far. - The canonical name of the agent that produced this item. + - `JsonValue; type "summary_text"constant` - - `Optional callId` + The type of the object. Always `summary_text`. - The unique ID of the tool search call generated by the model. + - `SUMMARY_TEXT("summary_text")` - - `Optional execution` + - `class ReasoningText:` - Whether tool search was executed by the server or by the client. + Reasoning text from the model. - - `SERVER("server")` + - `String text` - - `CLIENT("client")` + The reasoning text from the model. - - `Optional status` + - `JsonValue; type "reasoning_text"constant` - The status of the tool search call. + The type of the reasoning text. Always `reasoning_text`. - - `IN_PROGRESS("in_progress")` + - `REASONING_TEXT("reasoning_text")` - - `COMPLETED("completed")` + - `class BetaResponseOutputRefusal:` - - `INCOMPLETE("incomplete")` + A refusal from the model. - - `class BetaResponseToolSearchOutputItemParam:` + - `class BetaResponseInputImage:` - - `List tools` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The loaded tool definitions returned by the tool search output. + - `class ComputerScreenshot:` - - `class BetaFunctionTool:` + A screenshot of a computer. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Detail detail` - - `String name` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The name of the function to call. + - `LOW("low")` - - `Optional parameters` + - `HIGH("high")` - A JSON schema object describing the parameters of the function. + - `AUTO("auto")` - - `Optional strict` + - `ORIGINAL("original")` - Whether strict parameter validation is enforced for this function tool. + - `Optional fileId` - - `JsonValue; type "function"constant` + The identifier of an uploaded file that contains the screenshot. - The type of the function tool. Always `function`. + - `Optional imageUrl` - - `FUNCTION("function")` + The URL of the screenshot image. - - `Optional> allowedCallers` + - `JsonValue; type "computer_screenshot"constant` - The tool invocation context(s). + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `DIRECT("direct")` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `PROGRAMMATIC("programmatic")` + - `Optional promptCacheBreakpoint` - - `Optional deferLoading` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Whether this function is deferred and loaded via tool search. + - `JsonValue; mode "explicit"constant` - - `Optional description` + The breakpoint mode. Always `explicit`. - A description of the function. Used by the model to determine whether or not to call the function. + - `EXPLICIT("explicit")` - - `Optional outputSchema` + - `class BetaResponseInputFile:` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A file input to the model. - - `class BetaFileSearchTool:` + - `class EncryptedContent:` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `JsonValue; type "file_search"constant` + - `String encryptedContent` - The type of the file search tool. Always `file_search`. + Opaque encrypted content. - - `FILE_SEARCH("file_search")` + - `JsonValue; type "encrypted_content"constant` - - `List vectorStoreIds` + The type of the input item. Always `encrypted_content`. - The IDs of the vector stores to search. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `Optional filters` + - `String recipient` - A filter to apply. + The destination agent identity. - - `class ComparisonFilter:` + - `JsonValue; type "agent_message"constant` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The type of the item. Always `agent_message`. - - `String key` + - `AGENT_MESSAGE("agent_message")` - The key to compare against the value. + - `Optional agent` - - `Type type` + The agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `String agentName` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The canonical name of the agent that produced this item. - - `EQ("eq")` + - `MultiAgentCall` - - `NE("ne")` + - `String id` - - `GT("gt")` + The unique ID of the multi-agent call item. - - `GTE("gte")` + - `Action action` - - `LT("lt")` + The multi-agent action to execute. - - `LTE("lte")` + - `SPAWN_AGENT("spawn_agent")` - - `IN("in")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `NIN("nin")` + - `LIST_AGENTS("list_agents")` - - `Value value` + - `SEND_MESSAGE("send_message")` - The value to compare against the attribute key; supports string, number, or boolean types. + - `FOLLOWUP_TASK("followup_task")` - - `String` + - `WAIT_AGENT("wait_agent")` - - `double` + - `String arguments` - - `boolean` + The JSON string of arguments generated for the action. - - `List` + - `String callId` - - `class CompoundFilter:` + The unique ID linking this call to its output. - Combine multiple filters using `and` or `or`. + - `JsonValue; type "multi_agent_call"constant` - - `List filters` + The type of the multi-agent call. Always `multi_agent_call`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `MULTI_AGENT_CALL("multi_agent_call")` - - `class ComparisonFilter:` + - `Optional agent` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The agent that produced this item. - - `String key` + - `String agentName` - The key to compare against the value. + The canonical name of the agent that produced this item. - - `Type type` + - `MultiAgentCallOutput` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `String id` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The unique ID of the multi-agent call output item. - - `EQ("eq")` + - `Action action` - - `NE("ne")` + The multi-agent action that produced this result. - - `GT("gt")` + - `SPAWN_AGENT("spawn_agent")` - - `GTE("gte")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `LT("lt")` + - `LIST_AGENTS("list_agents")` - - `LTE("lte")` + - `SEND_MESSAGE("send_message")` - - `IN("in")` + - `FOLLOWUP_TASK("followup_task")` - - `NIN("nin")` + - `WAIT_AGENT("wait_agent")` - - `Value value` + - `String callId` - The value to compare against the attribute key; supports string, number, or boolean types. + The unique ID of the multi-agent call. - - `String` + - `List output` - - `double` + Text output returned by the multi-agent action. - - `boolean` + - `List annotations` - - `List` + The annotations of the text output. - - `JsonValue` + - `String text` - - `Type type` + The text output from the model. - Type of operation: `and` or `or`. + - `JsonValue; type "output_text"constant` - - `AND("and")` + The type of the output text. Always `output_text`. - - `OR("or")` + - `Optional> logprobs` - - `Optional maxNumResults` + - `JsonValue; type "multi_agent_call_output"constant` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `Optional rankingOptions` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - Ranking options for search. + - `Optional agent` - - `Optional hybridSearch` + The agent that produced this item. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `String agentName` - - `double embeddingWeight` + The canonical name of the agent that produced this item. - The weight of the embedding in the reciprocal ranking fusion. + - `class BetaResponseFunctionWebSearch:` - - `double textWeight` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The weight of the text in the reciprocal ranking fusion. + - `class BetaResponseComputerToolCall:` - - `Optional ranker` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The ranker to use for the file search. + - `class BetaResponseComputerToolCallOutputItem:` - - `AUTO("auto")` + - `String id` - - `DEFAULT_2024_11_15("default-2024-11-15")` + The unique ID of the computer call tool output. - - `Optional scoreThreshold` + - `String callId` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The ID of the computer tool call that produced the output. - - `class BetaComputerTool:` + - `BetaResponseComputerToolCallOutputScreenshot output` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A computer screenshot image used with the computer use tool. - - `JsonValue; type "computer"constant` + - `Status status` - The type of the computer tool. Always `computer`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `COMPUTER("computer")` + - `COMPLETED("completed")` - - `class BetaComputerUsePreviewTool:` + - `INCOMPLETE("incomplete")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `FAILED("failed")` - - `long displayHeight` + - `IN_PROGRESS("in_progress")` - The height of the computer display. + - `JsonValue; type "computer_call_output"constant` - - `long displayWidth` + The type of the computer tool call output. Always `computer_call_output`. - The width of the computer display. + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - - `Environment environment` + - `Optional> acknowledgedSafetyChecks` - The type of computer environment to control. + The safety checks reported by the API that have been acknowledged by the + developer. - - `WINDOWS("windows")` + - `String id` - - `MAC("mac")` + The ID of the pending safety check. - - `LINUX("linux")` + - `Optional code` - - `UBUNTU("ubuntu")` + The type of the pending safety check. - - `BROWSER("browser")` + - `Optional message` - - `JsonValue; type "computer_use_preview"constant` + Details about the pending safety check. - The type of the computer use tool. Always `computer_use_preview`. + - `Optional agent` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The agent that produced this item. - - `class BetaWebSearchTool:` + - `String agentName` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The canonical name of the agent that produced this item. - - `Type type` + - `Optional createdBy` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The identifier of the actor that created the item. - - `WEB_SEARCH("web_search")` + - `class BetaResponseReasoningItem:` - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `Optional filters` + - `Program` - Filters for the search. + - `String id` - - `Optional> allowedDomains` + The unique ID of the program item. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `String callId` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The stable call ID of the program item. - - `Optional searchContextSize` + - `String code` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The JavaScript source executed by programmatic tool calling. - - `LOW("low")` + - `String fingerprint` - - `MEDIUM("medium")` + Opaque program replay fingerprint that must be round-tripped. - - `HIGH("high")` + - `JsonValue; type "program"constant` - - `Optional userLocation` + The type of the item. Always `program`. - The approximate location of the user. + - `PROGRAM("program")` - - `Optional city` + - `Optional agent` - Free text input for the city of the user, e.g. `San Francisco`. + The agent that produced this item. - - `Optional country` + - `String agentName` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The canonical name of the agent that produced this item. - - `Optional region` + - `ProgramOutput` - Free text input for the region of the user, e.g. `California`. + - `String id` - - `Optional timezone` + The unique ID of the program output item. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `String callId` - - `Optional type` + The call ID of the program item. - The type of location approximation. Always `approximate`. + - `String result` - - `APPROXIMATE("approximate")` + The result produced by the program item. - - `Mcp` + - `Status status` - - `String serverLabel` + The terminal status of the program output item. - A label for this MCP server, used to identify it in tool calls. + - `COMPLETED("completed")` - - `JsonValue; type "mcp"constant` + - `INCOMPLETE("incomplete")` - The type of the MCP tool. Always `mcp`. + - `JsonValue; type "program_output"constant` - - `MCP("mcp")` + The type of the item. Always `program_output`. - - `Optional> allowedCallers` + - `PROGRAM_OUTPUT("program_output")` - The tool invocation context(s). + - `Optional agent` - - `DIRECT("direct")` + The agent that produced this item. - - `PROGRAMMATIC("programmatic")` + - `String agentName` - - `Optional allowedTools` + The canonical name of the agent that produced this item. - List of allowed tool names or a filter object. + - `class BetaResponseToolSearchCall:` - - `List` + - `String id` - - `class McpToolFilter:` + The unique ID of the tool search call item. - A filter object to specify which tools are allowed. + - `JsonValue arguments` - - `Optional readOnly` + Arguments used for the tool search call. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Optional callId` - - `Optional> toolNames` + The unique ID of the tool search call generated by the model. - List of allowed tool names. + - `Execution execution` - - `Optional authorization` + Whether tool search was executed by the server or by the client. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `SERVER("server")` - - `Optional connectorId` + - `CLIENT("client")` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `Status status` - Currently supported `connector_id` values are: + The status of the tool search call item that was recorded. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `IN_PROGRESS("in_progress")` - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `COMPLETED("completed")` - - `CONNECTOR_GMAIL("connector_gmail")` + - `INCOMPLETE("incomplete")` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `JsonValue; type "tool_search_call"constant` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + The type of the item. Always `tool_search_call`. - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `TOOL_SEARCH_CALL("tool_search_call")` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `Optional agent` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + The agent that produced this item. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `String agentName` - - `Optional deferLoading` + The canonical name of the agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `Optional createdBy` - - `Optional headers` + The identifier of the actor that created the item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `class BetaResponseToolSearchOutputItem:` - - `Optional requireApproval` + - `String id` - Specify which of the MCP server's tools require approval. + The unique ID of the tool search output item. - - `class McpToolApprovalFilter:` + - `Optional callId` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The unique ID of the tool search call generated by the model. - - `Optional always` + - `Execution execution` - A filter object to specify which tools are allowed. + Whether tool search was executed by the server or by the client. - - `Optional readOnly` + - `SERVER("server")` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `CLIENT("client")` - - `Optional> toolNames` + - `Status status` - List of allowed tool names. + The status of the tool search output item that was recorded. - - `Optional never` + - `IN_PROGRESS("in_progress")` - A filter object to specify which tools are allowed. + - `COMPLETED("completed")` - - `Optional readOnly` + - `INCOMPLETE("incomplete")` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `List tools` - - `Optional> toolNames` + The loaded tool definitions returned by tool search. - List of allowed tool names. + - `class BetaFunctionTool:` - - `enum McpToolApprovalSetting:` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `class BetaFileSearchTool:` - - `ALWAYS("always")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `NEVER("never")` + - `class BetaComputerTool:` - - `Optional serverDescription` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Optional description of the MCP server, used to provide more context. + - `class BetaComputerUsePreviewTool:` - - `Optional serverUrl` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `class BetaWebSearchTool:` - - `Optional tunnelId` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `Mcp` - `CodeInterpreter` - - `Container container` + - `JsonValue;` - 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. + - `ImageGeneration` - - `String` + - `JsonValue;` - - `class CodeInterpreterToolAuto:` + - `class BetaFunctionShellTool:` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + A tool that allows the model to execute shell commands. - - `JsonValue; type "auto"constant` + - `class BetaCustomTool:` - Always `auto`. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `AUTO("auto")` + - `class BetaNamespaceTool:` - - `Optional> fileIds` + Groups function/custom tools under a shared namespace. - An optional list of uploaded files to make available to your code. + - `class BetaToolSearchTool:` - - `Optional memoryLimit` + Hosted or BYOT tool search configuration for deferred tools. - The memory limit for the code interpreter container. + - `class BetaWebSearchPreviewTool:` - - `_1G("1g")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `_4G("4g")` + - `class BetaApplyPatchTool:` - - `_16G("16g")` + Allows the assistant to create, delete, or update files using unified diffs. - - `_64G("64g")` + - `JsonValue; type "tool_search_output"constant` - - `Optional networkPolicy` + The type of the item. Always `tool_search_output`. - Network access policy for the container. + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional agent` - - `JsonValue; type "disabled"constant` + The agent that produced this item. - Disable outbound network access. Always `disabled`. + - `String agentName` - - `DISABLED("disabled")` + The canonical name of the agent that produced this item. - - `class BetaContainerNetworkPolicyAllowlist:` + - `Optional createdBy` - - `List allowedDomains` + The identifier of the actor that created the item. - A list of allowed domains when type is `allowlist`. + - `AdditionalTools` - - `JsonValue; type "allowlist"constant` + - `String id` - Allow outbound network access only to specified domains. Always `allowlist`. + The unique ID of the additional tools item. - - `ALLOWLIST("allowlist")` + - `Role role` - - `Optional> domainSecrets` + The role that provided the additional tools. - Optional domain-scoped secrets for allowlisted domains. + - `UNKNOWN("unknown")` - - `String domain` + - `USER("user")` - The domain associated with the secret. + - `ASSISTANT("assistant")` - - `String name` + - `SYSTEM("system")` - The name of the secret to inject for the domain. + - `CRITIC("critic")` - - `String value` + - `DISCRIMINATOR("discriminator")` - The secret value to inject for the domain. + - `DEVELOPER("developer")` - - `JsonValue; type "code_interpreter"constant` + - `TOOL("tool")` - The type of the code interpreter tool. Always `code_interpreter`. + - `List tools` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool:` - - `CODE_INTERPRETER("code_interpreter")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `Optional> allowedCallers` + - `class BetaFileSearchTool:` - The tool invocation context(s). + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `DIRECT("direct")` + - `class BetaComputerTool:` - - `PROGRAMMATIC("programmatic")` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue;` + - `class BetaComputerUsePreviewTool:` - - `JsonValue; type "programmatic_tool_calling"constant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the tool. Always `programmatic_tool_calling`. + - `class BetaWebSearchTool:` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `ImageGeneration` + - `Mcp` - - `JsonValue; type "image_generation"constant` + - `CodeInterpreter` - The type of the image generation tool. Always `image_generation`. + - `JsonValue;` - - `IMAGE_GENERATION("image_generation")` + - `ImageGeneration` - - `Optional action` + - `JsonValue;` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `class BetaFunctionShellTool:` - - `GENERATE("generate")` + A tool that allows the model to execute shell commands. - - `EDIT("edit")` + - `class BetaCustomTool:` - - `AUTO("auto")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional background` + - `class BetaNamespaceTool:` - 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. + Groups function/custom tools under a shared namespace. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `class BetaToolSearchTool:` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Hosted or BYOT tool search configuration for deferred tools. - - `TRANSPARENT("transparent")` + - `class BetaWebSearchPreviewTool:` - - `OPAQUE("opaque")` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `AUTO("auto")` + - `class BetaApplyPatchTool:` - - `Optional inputFidelity` + Allows the assistant to create, delete, or update files using unified diffs. - 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`. + - `JsonValue; type "additional_tools"constant` - - `HIGH("high")` + The type of the item. Always `additional_tools`. - - `LOW("low")` + - `ADDITIONAL_TOOLS("additional_tools")` - - `Optional inputImageMask` + - `Optional agent` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The agent that produced this item. - - `Optional fileId` + - `String agentName` - File ID for the mask image. + The canonical name of the agent that produced this item. - - `Optional imageUrl` + - `class BetaResponseCompactionItem:` - Base64-encoded mask image. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `Optional model` + - `String id` - The image generation model to use. Default: `gpt-image-1`. + The unique ID of the compaction item. - - `GPT_IMAGE_1("gpt-image-1")` + - `String encryptedContent` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + The encrypted content that was produced by compaction. - - `GPT_IMAGE_2("gpt-image-2")` + - `JsonValue; type "compaction"constant` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The type of the item. Always `compaction`. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `COMPACTION("compaction")` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `Optional agent` - - `Optional moderation` + The agent that produced this item. - Moderation level for the generated image. Default: `auto`. + - `String agentName` - - `AUTO("auto")` + The canonical name of the agent that produced this item. - - `LOW("low")` + - `Optional createdBy` - - `Optional outputCompression` + The identifier of the actor that created the item. - Compression level for the output image. Default: 100. + - `ImageGenerationCall` - - `Optional outputFormat` + - `String id` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The unique ID of the image generation call. - - `PNG("png")` + - `Optional result` - - `WEBP("webp")` + The generated image encoded in base64. - - `JPEG("jpeg")` + - `Status status` - - `Optional partialImages` + The status of the image generation call. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `IN_PROGRESS("in_progress")` - - `Optional quality` + - `COMPLETED("completed")` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `GENERATING("generating")` - - `LOW("low")` + - `FAILED("failed")` - - `MEDIUM("medium")` + - `JsonValue; type "image_generation_call"constant` - - `HIGH("high")` + The type of the image generation call. Always `image_generation_call`. - - `AUTO("auto")` + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `Optional size` + - `Optional agent` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The agent that produced this item. - - `_1024X1024("1024x1024")` + - `String agentName` - - `_1024X1536("1024x1536")` + The canonical name of the agent that produced this item. - - `_1536X1024("1536x1024")` + - `class BetaResponseCodeInterpreterToolCall:` - - `AUTO("auto")` + A tool call to run code. - - `JsonValue;` + - `LocalShellCall` - - `JsonValue; type "local_shell"constant` + - `String id` - The type of the local shell tool. Always `local_shell`. + The unique ID of the local shell call. - - `LOCAL_SHELL("local_shell")` + - `Action action` - - `class BetaFunctionShellTool:` + Execute a shell command on the server. - A tool that allows the model to execute shell commands. + - `List command` - - `JsonValue; type "shell"constant` + The command to run. - The type of the shell tool. Always `shell`. + - `Env env` - - `SHELL("shell")` + Environment variables to set for the command. - - `Optional> allowedCallers` + - `JsonValue; type "exec"constant` - The tool invocation context(s). + The type of the local shell action. Always `exec`. - - `DIRECT("direct")` + - `EXEC("exec")` - - `PROGRAMMATIC("programmatic")` + - `Optional timeoutMs` - - `Optional environment` + Optional timeout in milliseconds for the command. - - `class BetaContainerAuto:` + - `Optional user` - - `JsonValue; type "container_auto"constant` + Optional user to run the command as. - Automatically creates a container for this request + - `Optional workingDirectory` - - `CONTAINER_AUTO("container_auto")` + Optional working directory to run the command in. - - `Optional> fileIds` + - `String callId` - An optional list of uploaded files to make available to your code. + The unique ID of the local shell tool call generated by the model. - - `Optional memoryLimit` + - `Status status` - The memory limit for the container. + The status of the local shell call. - - `_1G("1g")` + - `IN_PROGRESS("in_progress")` - - `_4G("4g")` + - `COMPLETED("completed")` - - `_16G("16g")` + - `INCOMPLETE("incomplete")` - - `_64G("64g")` + - `JsonValue; type "local_shell_call"constant` - - `Optional networkPolicy` + The type of the local shell call. Always `local_shell_call`. - Network access policy for the container. + - `LOCAL_SHELL_CALL("local_shell_call")` - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional agent` - - `class BetaContainerNetworkPolicyAllowlist:` + The agent that produced this item. - - `Optional> skills` + - `String agentName` - An optional list of skills referenced by id or inline data. + The canonical name of the agent that produced this item. - - `class BetaSkillReference:` + - `LocalShellCallOutput` - - `String skillId` + - `String id` - The ID of the referenced skill. + The unique ID of the local shell tool call generated by the model. - - `JsonValue; type "skill_reference"constant` + - `String output` - References a skill created with the /v1/skills endpoint. + A JSON string of the output of the local shell tool call. - - `SKILL_REFERENCE("skill_reference")` + - `JsonValue; type "local_shell_call_output"constant` - - `Optional version` + The type of the local shell tool call output. Always `local_shell_call_output`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - - `class BetaInlineSkill:` + - `Optional agent` - - `String description` + The agent that produced this item. - The description of the skill. + - `String agentName` - - `String name` + The canonical name of the agent that produced this item. - The name of the skill. + - `Optional status` - - `BetaInlineSkillSource source` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Inline skill payload + - `IN_PROGRESS("in_progress")` - - `String data` + - `COMPLETED("completed")` - Base64-encoded skill zip bundle. + - `INCOMPLETE("incomplete")` - - `JsonValue; mediaType "application/zip"constant` + - `class BetaResponseFunctionShellToolCall:` - The media type of the inline skill payload. Must be `application/zip`. + A tool call that executes one or more shell commands in a managed environment. - - `APPLICATION_ZIP("application/zip")` + - `String id` - - `JsonValue; type "base64"constant` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of the inline skill source. Must be `base64`. + - `Action action` - - `BASE64("base64")` + The shell commands and limits that describe how to run the tool call. - - `JsonValue; type "inline"constant` + - `List commands` - Defines an inline skill for this request. + - `Optional maxOutputLength` - - `INLINE("inline")` + Optional maximum number of characters to return from each command. - - `class BetaLocalEnvironment:` + - `Optional timeoutMs` - - `JsonValue; type "local"constant` + Optional timeout in milliseconds for the commands. - Use a local computer environment. + - `String callId` - - `LOCAL("local")` + The unique ID of the shell tool call generated by the model. - - `Optional> skills` + - `Optional environment` - An optional list of skills. + Represents the use of a local environment to perform shell actions. - - `String description` + - `class BetaResponseLocalEnvironment:` - The description of the skill. + Represents the use of a local environment to perform shell actions. - - `String name` + - `JsonValue; type "local"constant` - The name of the skill. + The environment type. Always `local`. - - `String path` + - `LOCAL("local")` - The path to the directory containing the skill. + - `class BetaResponseContainerReference:` - - `class BetaContainerReference:` + Represents a container created with /v1/containers. - `String containerId` - The ID of the referenced container. - - `JsonValue; type "container_reference"constant` - References a container created with the /v1/containers endpoint + The environment type. Always `container_reference`. - `CONTAINER_REFERENCE("container_reference")` - - `class BetaCustomTool:` + - `Status status` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String name` + - `IN_PROGRESS("in_progress")` - The name of the custom tool, used to identify it in tool calls. + - `COMPLETED("completed")` - - `JsonValue; type "custom"constant` + - `INCOMPLETE("incomplete")` - The type of the custom tool. Always `custom`. + - `JsonValue; type "shell_call"constant` - - `CUSTOM("custom")` + The type of the item. Always `shell_call`. - - `Optional> allowedCallers` + - `SHELL_CALL("shell_call")` - The tool invocation context(s). + - `Optional agent` - - `DIRECT("direct")` + The agent that produced this item. - - `PROGRAMMATIC("programmatic")` + - `String agentName` - - `Optional deferLoading` + The canonical name of the agent that produced this item. - Whether this tool should be deferred and discovered via tool search. + - `Optional caller` - - `Optional description` + The execution context that produced this tool call. - Optional description of the custom tool, used to provide more context. + - `JsonValue;` - - `Optional format` + - `JsonValue; type "direct"constant` - The input format for the custom tool. Default is unconstrained text. + - `DIRECT("direct")` - - `JsonValue;` + - `class Program:` - - `JsonValue; type "text"constant` + - `String callerId` - Unconstrained text format. Always `text`. + The call ID of the program item that produced this tool call. - - `TEXT("text")` + - `JsonValue; type "program"constant` - - `class Grammar:` + - `PROGRAM("program")` - A grammar defined by the user. + - `Optional createdBy` - - `String definition` + The ID of the entity that created this tool call. - The grammar definition. + - `class BetaResponseFunctionShellToolCallOutput:` - - `Syntax syntax` + The output of a shell tool call that was emitted. - The syntax of the grammar definition. One of `lark` or `regex`. + - `String id` - - `LARK("lark")` + The unique ID of the shell call output. Populated when this item is returned via API. - - `REGEX("regex")` + - `String callId` - - `JsonValue; type "grammar"constant` + The unique ID of the shell tool call generated by the model. - Grammar format. Always `grammar`. + - `Optional maxOutputLength` - - `GRAMMAR("grammar")` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `class BetaNamespaceTool:` + - `List output` - Groups function/custom tools under a shared namespace. + An array of shell call output contents - - `String description` + - `Outcome outcome` - A description of the namespace shown to the model. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `String name` + - `JsonValue;` - The namespace name used in tool calls (for example, `crm`). + - `JsonValue; type "timeout"constant` - - `List tools` + The outcome type. Always `timeout`. - The function/custom tools available inside this namespace. + - `TIMEOUT("timeout")` - - `class Function:` + - `class Exit:` - - `String name` + Indicates that the shell commands finished and returned an exit code. - - `JsonValue; type "function"constant` + - `long exitCode` - - `FUNCTION("function")` + Exit code from the shell process. - - `Optional> allowedCallers` + - `JsonValue; type "exit"constant` - The tool invocation context(s). + The outcome type. Always `exit`. - - `DIRECT("direct")` + - `EXIT("exit")` - - `PROGRAMMATIC("programmatic")` + - `String stderr` - - `Optional deferLoading` + The standard error output that was captured. - Whether this function should be deferred and discovered via tool search. + - `String stdout` - - `Optional description` + The standard output that was captured. - - `Optional outputSchema` + - `Optional createdBy` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The identifier of the actor that created the item. - - `Optional parameters` + - `Status status` - - `Optional strict` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `IN_PROGRESS("in_progress")` - - `class BetaCustomTool:` + - `COMPLETED("completed")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `INCOMPLETE("incomplete")` - - `JsonValue; type "namespace"constant` + - `JsonValue; type "shell_call_output"constant` - The type of the tool. Always `namespace`. + The type of the shell call output. Always `shell_call_output`. - - `NAMESPACE("namespace")` + - `SHELL_CALL_OUTPUT("shell_call_output")` - - `class BetaToolSearchTool:` + - `Optional agent` - Hosted or BYOT tool search configuration for deferred tools. + The agent that produced this item. - - `JsonValue; type "tool_search"constant` + - `String agentName` - The type of the tool. Always `tool_search`. + The canonical name of the agent that produced this item. - - `TOOL_SEARCH("tool_search")` + - `Optional caller` - - `Optional description` + The execution context that produced this tool call. - Description shown to the model for a client-executed tool search tool. + - `JsonValue;` - - `Optional execution` + - `JsonValue; type "direct"constant` - Whether tool search is executed by the server or by the client. + - `DIRECT("direct")` - - `SERVER("server")` + - `class Program:` - - `CLIENT("client")` + - `String callerId` - - `Optional parameters` + The call ID of the program item that produced this tool call. - Parameter schema for a client-executed tool search tool. + - `JsonValue; type "program"constant` - - `class BetaWebSearchPreviewTool:` + - `PROGRAM("program")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional createdBy` - - `Type type` + The identifier of the actor that created the item. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `class BetaResponseApplyPatchToolCall:` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `String id` - - `Optional> searchContentTypes` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `TEXT("text")` + - `String callId` - - `IMAGE("image")` + The unique ID of the apply patch tool call generated by the model. - - `Optional searchContextSize` + - `Operation operation` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `LOW("low")` + - `class CreateFile:` - - `MEDIUM("medium")` + Instruction describing how to create a file via the apply_patch tool. - - `HIGH("high")` + - `String diff` - - `Optional userLocation` + Diff to apply. - The user's location. + - `String path` - - `JsonValue; type "approximate"constant` + Path of the file to create. - The type of location approximation. Always `approximate`. + - `JsonValue; type "create_file"constant` - - `APPROXIMATE("approximate")` + Create a new file with the provided diff. - - `Optional city` + - `CREATE_FILE("create_file")` - Free text input for the city of the user, e.g. `San Francisco`. + - `class DeleteFile:` - - `Optional country` + Instruction describing how to delete a file via the apply_patch tool. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `String path` - - `Optional region` + Path of the file to delete. - Free text input for the region of the user, e.g. `California`. + - `JsonValue; type "delete_file"constant` - - `Optional timezone` + Delete the specified file. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `DELETE_FILE("delete_file")` - - `class BetaApplyPatchTool:` + - `class UpdateFile:` - Allows the assistant to create, delete, or update files using unified diffs. + Instruction describing how to update a file via the apply_patch tool. - - `JsonValue; type "apply_patch"constant` + - `String diff` - The type of the tool. Always `apply_patch`. + Diff to apply. - - `APPLY_PATCH("apply_patch")` + - `String path` - - `Optional> allowedCallers` + Path of the file to update. - The tool invocation context(s). + - `JsonValue; type "update_file"constant` - - `DIRECT("direct")` + Update an existing file with the provided diff. - - `PROGRAMMATIC("programmatic")` + - `UPDATE_FILE("update_file")` - - `JsonValue; type "tool_search_output"constant` + - `Status status` - The item type. Always `tool_search_output`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `IN_PROGRESS("in_progress")` - - `Optional id` + - `COMPLETED("completed")` - The unique ID of this tool search output. + - `JsonValue; type "apply_patch_call"constant` + + The type of the item. Always `apply_patch_call`. + + - `APPLY_PATCH_CALL("apply_patch_call")` - `Optional agent` @@ -118983,199 +131620,186 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional callId` + - `Optional caller` - The unique ID of the tool search call generated by the model. + The execution context that produced this tool call. - - `Optional execution` + - `JsonValue;` - Whether tool search was executed by the server or by the client. + - `JsonValue; type "direct"constant` - - `SERVER("server")` + - `DIRECT("direct")` - - `CLIENT("client")` + - `class Program:` - - `Optional status` + - `String callerId` - The status of the tool search output. + The call ID of the program item that produced this tool call. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "program"constant` - - `COMPLETED("completed")` + - `PROGRAM("program")` - - `INCOMPLETE("incomplete")` + - `Optional createdBy` - - `AdditionalTools` + The ID of the entity that created this tool call. - - `JsonValue; role "developer"constant` + - `class BetaResponseApplyPatchToolCallOutput:` - The role that provided the additional tools. Only `developer` is supported. + The output emitted by an apply patch tool call. - - `DEVELOPER("developer")` + - `String id` - - `List tools` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A list of additional tools made available at this item. + - `String callId` - - `class BetaFunctionTool:` + The unique ID of the apply patch tool call generated by the model. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `Status status` - - `class BetaFileSearchTool:` + The status of the apply patch tool call output. One of `completed` or `failed`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `COMPLETED("completed")` - - `class BetaComputerTool:` + - `FAILED("failed")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JsonValue; type "apply_patch_call_output"constant` - - `class BetaComputerUsePreviewTool:` + The type of the item. Always `apply_patch_call_output`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `class BetaWebSearchTool:` + - `Optional agent` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The agent that produced this item. - - `Mcp` + - `String agentName` - - `CodeInterpreter` + The canonical name of the agent that produced this item. - - `JsonValue;` + - `Optional caller` - - `ImageGeneration` + The execution context that produced this tool call. - `JsonValue;` - - `class BetaFunctionShellTool:` - - A tool that allows the model to execute shell commands. - - - `class BetaCustomTool:` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class BetaNamespaceTool:` + - `JsonValue; type "direct"constant` - Groups function/custom tools under a shared namespace. + - `DIRECT("direct")` - - `class BetaToolSearchTool:` + - `class Program:` - Hosted or BYOT tool search configuration for deferred tools. + - `String callerId` - - `class BetaWebSearchPreviewTool:` + The call ID of the program item that produced this tool call. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "program"constant` - - `class BetaApplyPatchTool:` + - `PROGRAM("program")` - Allows the assistant to create, delete, or update files using unified diffs. + - `Optional createdBy` - - `JsonValue; type "additional_tools"constant` + The ID of the entity that created this tool call output. - The item type. Always `additional_tools`. + - `Optional output` - - `ADDITIONAL_TOOLS("additional_tools")` + Optional textual output returned by the apply patch tool. - - `Optional id` + - `McpCall` - The unique ID of this additional tools item. + - `String id` - - `Optional agent` + The unique ID of the tool call. - The agent that produced this item. + - `String arguments` - - `String agentName` + A JSON string of the arguments passed to the tool. - The canonical name of the agent that produced this item. + - `String name` - - `class BetaResponseReasoningItem:` + The name of the tool that was run. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `String serverLabel` - - `String id` + The label of the MCP server running the tool. - The unique identifier of the reasoning content. + - `JsonValue; type "mcp_call"constant` - - `List summary` + The type of the item. Always `mcp_call`. - Reasoning summary content. + - `MCP_CALL("mcp_call")` - - `String text` + - `Optional agent` - A summary of the reasoning output from the model so far. + The agent that produced this item. - - `JsonValue; type "summary_text"constant` + - `String agentName` - The type of the object. Always `summary_text`. + The canonical name of the agent that produced this item. - - `SUMMARY_TEXT("summary_text")` + - `Optional approvalRequestId` - - `JsonValue; type "reasoning"constant` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The type of the object. Always `reasoning`. + - `Optional error` - - `REASONING("reasoning")` + The error from the tool call, if any. - - `Optional agent` + - `Optional output` - The agent that produced this item. + The output from the tool call. - - `String agentName` + - `Optional status` - The canonical name of the agent that produced this item. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `Optional> content` + - `IN_PROGRESS("in_progress")` - Reasoning text content. + - `COMPLETED("completed")` - - `String text` + - `INCOMPLETE("incomplete")` - The reasoning text from the model. + - `CALLING("calling")` - - `JsonValue; type "reasoning_text"constant` + - `FAILED("failed")` - The type of the reasoning text. Always `reasoning_text`. + - `McpListTools` - - `REASONING_TEXT("reasoning_text")` + - `String id` - - `Optional encryptedContent` + The unique ID of the list. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `String serverLabel` - - `Optional status` + The label of the MCP server. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `List tools` - - `IN_PROGRESS("in_progress")` + The tools available on the server. - - `COMPLETED("completed")` + - `JsonValue inputSchema` - - `INCOMPLETE("incomplete")` + The JSON schema describing the tool's input. - - `class BetaResponseCompactionItemParam:` + - `String name` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The name of the tool. - - `String encryptedContent` + - `Optional annotations` - The encrypted content of the compaction summary. + Additional annotations about the tool. - - `JsonValue; type "compaction"constant` + - `Optional description` - The type of the item. Always `compaction`. + The description of the tool. - - `COMPACTION("compaction")` + - `JsonValue; type "mcp_list_tools"constant` - - `Optional id` + The type of the item. Always `mcp_list_tools`. - The ID of the compaction item. + - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` @@ -119185,33 +131809,33 @@ public final class Main { The canonical name of the agent that produced this item. - - `ImageGenerationCall` + - `Optional error` - - `String id` + Error message if the server could not list tools. - The unique ID of the image generation call. + - `McpApprovalRequest` - - `Optional result` + - `String id` - The generated image encoded in base64. + The unique ID of the approval request. - - `Status status` + - `String arguments` - The status of the image generation call. + A JSON string of arguments for the tool. - - `IN_PROGRESS("in_progress")` + - `String name` - - `COMPLETED("completed")` + The name of the tool to run. - - `GENERATING("generating")` + - `String serverLabel` - - `FAILED("failed")` + The label of the MCP server making the request. - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "mcp_approval_request"constant` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `mcp_approval_request`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - `Optional agent` @@ -119221,58 +131845,54 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. + - `McpApprovalResponse` - `String id` - The unique ID of the code interpreter tool call. - - - `Optional code` + The unique ID of the approval response - The code to run, or null if not available. + - `String approvalRequestId` - - `String containerId` + The ID of the approval request being answered. - The ID of the container used to run the code. + - `boolean approve` - - `Optional> outputs` + Whether the request was approved. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `JsonValue; type "mcp_approval_response"constant` - - `class Logs:` + The type of the item. Always `mcp_approval_response`. - The logs output from the code interpreter. + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `String logs` + - `Optional agent` - The logs output from the code interpreter. + The agent that produced this item. - - `JsonValue; type "logs"constant` + - `String agentName` - The type of the output. Always `logs`. + The canonical name of the agent that produced this item. - - `LOGS("logs")` + - `Optional reason` - - `class Image:` + Optional reason for the decision. - The image output from the code interpreter. + - `class BetaResponseCustomToolCall:` - - `JsonValue; type "image"constant` + A call to a custom tool created by the model. - The type of the output. Always `image`. + - `class BetaResponseCustomToolCallOutputItem:` - - `IMAGE("image")` + The output of a custom tool call from your code, being sent back to the model. - - `String url` + - `String id` - The URL of the image output from the code interpreter. + The unique ID of the custom tool call output item. - `Status status` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` @@ -119280,5221 +131900,5287 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `INTERPRETING("interpreting")` + - `Optional createdBy` - - `FAILED("failed")` + The identifier of the actor that created the item. - - `JsonValue; type "code_interpreter_call"constant` + - `boolean parallelToolCalls` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Whether to allow the model to run tool calls in parallel. - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `Optional temperature` - - `Optional agent` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The agent that produced this item. + - `ToolChoice toolChoice` - - `String agentName` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The canonical name of the agent that produced this item. + - `enum BetaToolChoiceOptions:` - - `LocalShellCall` + Controls which (if any) tool is called by the model. - - `String id` + `none` means the model will not call any tool and instead generates a message. - The unique ID of the local shell call. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `Action action` + `required` means the model must call one or more tools. - Execute a shell command on the server. + - `NONE("none")` - - `List command` + - `AUTO("auto")` - The command to run. + - `REQUIRED("required")` - - `Env env` + - `class BetaToolChoiceAllowed:` - Environment variables to set for the command. + Constrains the tools available to the model to a pre-defined set. - - `JsonValue; type "exec"constant` + - `Mode mode` - The type of the local shell action. Always `exec`. + Constrains the tools available to the model to a pre-defined set. - - `EXEC("exec")` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `Optional timeoutMs` + `required` requires the model to call one or more of the allowed tools. - Optional timeout in milliseconds for the command. + - `AUTO("auto")` - - `Optional user` + - `REQUIRED("required")` - Optional user to run the command as. + - `List tools` - - `Optional workingDirectory` + A list of tool definitions that the model should be allowed to call. - Optional working directory to run the command in. + For the Responses API, the list of tool definitions might look like: - - `String callId` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The unique ID of the local shell tool call generated by the model. + - `JsonValue; type "allowed_tools"constant` - - `Status status` + Allowed tool configuration type. Always `allowed_tools`. - The status of the local shell call. + - `ALLOWED_TOOLS("allowed_tools")` - - `IN_PROGRESS("in_progress")` + - `class BetaToolChoiceTypes:` - - `COMPLETED("completed")` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `INCOMPLETE("incomplete")` + - `Type type` - - `JsonValue; type "local_shell_call"constant` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The type of the local shell call. Always `local_shell_call`. + Allowed values are: - - `LOCAL_SHELL_CALL("local_shell_call")` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `Optional agent` + - `FILE_SEARCH("file_search")` - The agent that produced this item. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `String agentName` + - `COMPUTER("computer")` - The canonical name of the agent that produced this item. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `LocalShellCallOutput` + - `COMPUTER_USE("computer_use")` - - `String id` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - The unique ID of the local shell tool call generated by the model. + - `IMAGE_GENERATION("image_generation")` - - `String output` + - `CODE_INTERPRETER("code_interpreter")` - A JSON string of the output of the local shell tool call. + - `class BetaToolChoiceFunction:` - - `JsonValue; type "local_shell_call_output"constant` + Use this option to force the model to call a specific function. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `String name` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The name of the function to call. - - `Optional agent` + - `JsonValue; type "function"constant` - The agent that produced this item. + For function calling, the type is always `function`. - - `String agentName` + - `FUNCTION("function")` - The canonical name of the agent that produced this item. + - `class BetaToolChoiceMcp:` - - `Optional status` + Use this option to force the model to call a specific tool on a remote MCP server. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `String serverLabel` - - `IN_PROGRESS("in_progress")` + The label of the MCP server to use. - - `COMPLETED("completed")` + - `JsonValue; type "mcp"constant` - - `INCOMPLETE("incomplete")` + For MCP tools, the type is always `mcp`. - - `ShellCall` + - `MCP("mcp")` - - `Action action` + - `Optional name` - The shell commands and limits that describe how to run the tool call. + The name of the tool to call on the server. - - `List commands` + - `class BetaToolChoiceCustom:` - Ordered shell commands for the execution environment to run. + Use this option to force the model to call a specific custom tool. - - `Optional maxOutputLength` + - `String name` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + The name of the custom tool to call. - - `Optional timeoutMs` + - `JsonValue; type "custom"constant` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + For custom tool calling, the type is always `custom`. - - `String callId` + - `CUSTOM("custom")` - The unique ID of the shell tool call generated by the model. + - `JsonValue;` - - `JsonValue; type "shell_call"constant` + - `JsonValue; type "programmatic_tool_calling"constant` - The type of the item. Always `shell_call`. + The tool to call. Always `programmatic_tool_calling`. - - `SHELL_CALL("shell_call")` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `Optional id` + - `class BetaToolChoiceApplyPatch:` - The unique ID of the shell tool call. Populated when this item is returned via API. + Forces the model to call the apply_patch tool when executing a tool call. - - `Optional agent` + - `JsonValue; type "apply_patch"constant` - The agent that produced this item. + The tool to call. Always `apply_patch`. - - `String agentName` + - `APPLY_PATCH("apply_patch")` - The canonical name of the agent that produced this item. + - `class BetaToolChoiceShell:` - - `Optional caller` + Forces the model to call the shell tool when a tool call is required. - The execution context that produced this tool call. + - `JsonValue; type "shell"constant` - - `JsonValue;` + The tool to call. Always `shell`. - - `JsonValue; type "direct"constant` + - `SHELL("shell")` - The caller type. Always `direct`. + - `List tools` - - `DIRECT("direct")` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `class Program:` + We support the following categories of tools: - - `String callerId` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - The call ID of the program item that produced this tool call. + - `class BetaFunctionTool:` - - `JsonValue; type "program"constant` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The caller type. Always `program`. + - `class BetaFileSearchTool:` - - `PROGRAM("program")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Optional environment` + - `class BetaComputerTool:` - The environment to execute the shell commands in. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `class BetaLocalEnvironment:` + - `class BetaComputerUsePreviewTool:` - - `class BetaContainerReference:` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool:` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `Mcp` - - `Optional status` + - `CodeInterpreter` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `JsonValue;` - - `IN_PROGRESS("in_progress")` + - `ImageGeneration` - - `COMPLETED("completed")` + - `JsonValue;` - - `INCOMPLETE("incomplete")` + - `class BetaFunctionShellTool:` - - `ShellCallOutput` + A tool that allows the model to execute shell commands. - - `String callId` + - `class BetaCustomTool:` - The unique ID of the shell tool call generated by the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `List output` + - `class BetaNamespaceTool:` - Captured chunks of stdout and stderr output, along with their associated outcomes. + Groups function/custom tools under a shared namespace. - - `Outcome outcome` + - `class BetaToolSearchTool:` - The exit or timeout outcome associated with this shell call. + Hosted or BYOT tool search configuration for deferred tools. - - `JsonValue;` + - `class BetaWebSearchPreviewTool:` - - `JsonValue; type "timeout"constant` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The outcome type. Always `timeout`. + - `class BetaApplyPatchTool:` - - `TIMEOUT("timeout")` + Allows the assistant to create, delete, or update files using unified diffs. - - `class Exit:` + - `Optional topP` - Indicates that the shell commands finished and returned an exit code. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `long exitCode` + We generally recommend altering this or `temperature` but not both. - The exit code returned by the shell process. + - `Optional background` - - `JsonValue; type "exit"constant` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The outcome type. Always `exit`. + - `Optional completedAt` - - `EXIT("exit")` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `String stderr` + - `Optional conversation` - Captured stderr output for the shell call. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `String stdout` + - `String id` - Captured stdout output for the shell call. + The unique ID of the conversation that this response was associated with. - - `JsonValue; type "shell_call_output"constant` + - `Optional maxOutputTokens` - The type of the item. Always `shell_call_output`. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional maxToolCalls` - - `Optional id` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `Optional moderation` - - `Optional agent` + Moderation results for the response input and output, if moderated completions were requested. - The agent that produced this item. + - `Input input` - - `String agentName` + Moderation for the response input. - The canonical name of the agent that produced this item. + - `class ModerationResult:` - - `Optional caller` + A moderation result produced for the response input or output. - The execution context that produced this tool call. + - `Categories categories` - - `JsonValue;` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `JsonValue; type "direct"constant` + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - The caller type. Always `direct`. + Which modalities of input are reflected by the score for each category. - - `DIRECT("direct")` + - `TEXT("text")` - - `class Program:` + - `IMAGE("image")` - - `String callerId` + - `CategoryScores categoryScores` - The call ID of the program item that produced this tool call. + A dictionary of moderation categories to scores. - - `JsonValue; type "program"constant` + - `boolean flagged` - The caller type. Always `program`. + A boolean indicating whether the content was flagged by any category. - - `PROGRAM("program")` + - `String model` - - `Optional maxOutputLength` + The moderation model that produced this result. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `JsonValue; type "moderation_result"constant` - - `Optional status` + The object type, which was always `moderation_result` for successful moderation results. - The status of the shell call output. + - `MODERATION_RESULT("moderation_result")` - - `IN_PROGRESS("in_progress")` + - `class Error:` - - `COMPLETED("completed")` + An error produced while attempting moderation for the response input or output. - - `INCOMPLETE("incomplete")` + - `String code` - - `ApplyPatchCall` + The error code. - - `String callId` + - `String message` - The unique ID of the apply patch tool call generated by the model. + The error message. - - `Operation operation` + - `JsonValue; type "error"constant` - The specific create, delete, or update instruction for the apply_patch tool call. + The object type, which was always `error` for moderation failures. - - `class CreateFile:` + - `ERROR("error")` - Instruction for creating a new file via the apply_patch tool. + - `Output output` - - `String diff` + Moderation for the response output. - Unified diff content to apply when creating the file. + - `class ModerationResult:` - - `String path` + A moderation result produced for the response input or output. - Path of the file to create relative to the workspace root. + - `Categories categories` - - `JsonValue; type "create_file"constant` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The operation type. Always `create_file`. + - `CategoryAppliedInputTypes categoryAppliedInputTypes` - - `CREATE_FILE("create_file")` + Which modalities of input are reflected by the score for each category. - - `class DeleteFile:` + - `TEXT("text")` - Instruction for deleting an existing file via the apply_patch tool. + - `IMAGE("image")` - - `String path` + - `CategoryScores categoryScores` - Path of the file to delete relative to the workspace root. + A dictionary of moderation categories to scores. - - `JsonValue; type "delete_file"constant` + - `boolean flagged` - The operation type. Always `delete_file`. + A boolean indicating whether the content was flagged by any category. - - `DELETE_FILE("delete_file")` + - `String model` - - `class UpdateFile:` + The moderation model that produced this result. - Instruction for updating an existing file via the apply_patch tool. + - `JsonValue; type "moderation_result"constant` - - `String diff` + The object type, which was always `moderation_result` for successful moderation results. - Unified diff content to apply to the existing file. + - `MODERATION_RESULT("moderation_result")` - - `String path` + - `class Error:` - Path of the file to update relative to the workspace root. + An error produced while attempting moderation for the response input or output. - - `JsonValue; type "update_file"constant` + - `String code` - The operation type. Always `update_file`. + The error code. - - `UPDATE_FILE("update_file")` + - `String message` - - `Status status` + The error message. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `JsonValue; type "error"constant` - - `IN_PROGRESS("in_progress")` + The object type, which was always `error` for moderation failures. - - `COMPLETED("completed")` + - `ERROR("error")` - - `JsonValue; type "apply_patch_call"constant` + - `Optional previousResponseId` - The type of the item. Always `apply_patch_call`. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `Optional prompt` - - `Optional id` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `String id` - - `Optional agent` + The unique identifier of the prompt template to use. - The agent that produced this item. + - `Optional variables` - - `String agentName` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The canonical name of the agent that produced this item. + - `String` - - `Optional caller` + - `class BetaResponseInputText:` - The execution context that produced this tool call. + A text input to the model. - - `JsonValue;` + - `class BetaResponseInputImage:` - - `JsonValue; type "direct"constant` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The caller type. Always `direct`. + - `class BetaResponseInputFile:` - - `DIRECT("direct")` + A file input to the model. - - `class Program:` + - `Optional version` - - `String callerId` + Optional version of the prompt template. - The call ID of the program item that produced this tool call. + - `Optional promptCacheKey` - - `JsonValue; type "program"constant` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The caller type. Always `program`. + - `Optional promptCacheOptions` - - `PROGRAM("program")` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `ApplyPatchCallOutput` + - `Mode mode` - - `String callId` + Whether implicit prompt-cache breakpoints were enabled. - The unique ID of the apply patch tool call generated by the model. + - `IMPLICIT("implicit")` - - `Status status` + - `EXPLICIT("explicit")` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `Ttl ttl` - - `COMPLETED("completed")` + The minimum lifetime applied to each cache breakpoint. - - `FAILED("failed")` + - `_30M("30m")` - - `JsonValue; type "apply_patch_call_output"constant` + - `Optional promptCacheRetention` - The type of the item. Always `apply_patch_call_output`. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `Optional id` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `Optional agent` + - `IN_MEMORY("in_memory")` - The agent that produced this item. + - `_24H("24h")` - - `String agentName` + - `Optional reasoning` - The canonical name of the agent that produced this item. + **gpt-5 and o-series models only** - - `Optional caller` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The execution context that produced this tool call. + - `Optional context` - - `JsonValue;` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `JsonValue; type "direct"constant` + - `AUTO("auto")` - The caller type. Always `direct`. + - `CURRENT_TURN("current_turn")` - - `DIRECT("direct")` + - `ALL_TURNS("all_turns")` - - `class Program:` + - `Optional effort` - - `String callerId` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The call ID of the program item that produced this tool call. + - `NONE("none")` - - `JsonValue; type "program"constant` + - `MINIMAL("minimal")` - The caller type. Always `program`. + - `LOW("low")` - - `PROGRAM("program")` + - `MEDIUM("medium")` - - `Optional output` + - `HIGH("high")` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `XHIGH("xhigh")` - - `McpListTools` + - `MAX("max")` - - `String id` + - `Optional generateSummary` - The unique ID of the list. + **Deprecated:** use `summary` instead. - - `String serverLabel` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The label of the MCP server. + - `AUTO("auto")` - - `List tools` + - `CONCISE("concise")` - The tools available on the server. + - `DETAILED("detailed")` - - `JsonValue inputSchema` + - `Optional mode` - The JSON schema describing the tool's input. + Controls the reasoning execution mode for the request. - - `String name` + When returned on a response, this is the effective execution mode. - The name of the tool. + - `STANDARD("standard")` - - `Optional annotations` + - `PRO("pro")` - Additional annotations about the tool. + - `Optional summary` - - `Optional description` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The description of the tool. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `JsonValue; type "mcp_list_tools"constant` + - `AUTO("auto")` - The type of the item. Always `mcp_list_tools`. + - `CONCISE("concise")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `DETAILED("detailed")` - - `Optional agent` + - `Optional safetyIdentifier` - The agent that produced this item. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `String agentName` + - `Optional serviceTier` - The canonical name of the agent that produced this item. + Specifies the processing type used for serving the request. - - `Optional error` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - Error message if the server could not list tools. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `McpApprovalRequest` + - `AUTO("auto")` - - `String id` + - `DEFAULT("default")` - The unique ID of the approval request. + - `FLEX("flex")` - - `String arguments` + - `SCALE("scale")` - A JSON string of arguments for the tool. + - `PRIORITY("priority")` - - `String name` + - `Optional status` - The name of the tool to run. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `String serverLabel` + - `COMPLETED("completed")` - The label of the MCP server making the request. + - `FAILED("failed")` - - `JsonValue; type "mcp_approval_request"constant` + - `IN_PROGRESS("in_progress")` - The type of the item. Always `mcp_approval_request`. + - `CANCELLED("cancelled")` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `QUEUED("queued")` - - `Optional agent` + - `INCOMPLETE("incomplete")` - The agent that produced this item. + - `Optional text` - - `String agentName` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The canonical name of the agent that produced this item. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `McpApprovalResponse` + - `Optional format` - - `String approvalRequestId` + An object specifying the format that the model must output. - The ID of the approval request being answered. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `boolean approve` + The default format is `{ "type": "text" }` with no additional options. - Whether the request was approved. + **Not recommended for gpt-4o and newer models:** - - `JsonValue; type "mcp_approval_response"constant` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The type of the item. Always `mcp_approval_response`. + - `JsonValue;` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `JsonValue; type "text"constant` - - `Optional id` + The type of response format being defined. Always `text`. - The unique ID of the approval response + - `TEXT("text")` - - `Optional agent` + - `class BetaResponseFormatTextJsonSchemaConfig:` - The agent that produced this item. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `String agentName` + - `String name` - The canonical name of the agent that produced this item. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `Optional reason` + - `Schema schema` - Optional reason for the decision. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `McpCall` + - `JsonValue; type "json_schema"constant` - - `String id` + The type of response format being defined. Always `json_schema`. - The unique ID of the tool call. + - `JSON_SCHEMA("json_schema")` - - `String arguments` + - `Optional description` - A JSON string of the arguments passed to the tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `String name` + - `Optional strict` - The name of the tool that was run. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `String serverLabel` + - `JsonValue;` - The label of the MCP server running the tool. + - `JsonValue; type "json_object"constant` - - `JsonValue; type "mcp_call"constant` + The type of response format being defined. Always `json_object`. - The type of the item. Always `mcp_call`. + - `JSON_OBJECT("json_object")` - - `MCP_CALL("mcp_call")` + - `Optional verbosity` - - `Optional agent` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The agent that produced this item. + - `LOW("low")` - - `String agentName` + - `MEDIUM("medium")` - The canonical name of the agent that produced this item. + - `HIGH("high")` - - `Optional approvalRequestId` + - `Optional topLogprobs` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `Optional error` + - `Optional truncation` - The error from the tool call, if any. + The truncation strategy to use for the model response. - - `Optional output` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The output from the tool call. + - `AUTO("auto")` - - `Optional status` + - `DISABLED("disabled")` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `Optional usage` - - `IN_PROGRESS("in_progress")` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `COMPLETED("completed")` + - `long inputTokens` - - `INCOMPLETE("incomplete")` + The number of input tokens. - - `CALLING("calling")` + - `InputTokensDetails inputTokensDetails` - - `FAILED("failed")` + A detailed breakdown of the input tokens. - - `class BetaResponseCustomToolCallOutput:` + - `long cacheWriteTokens` - The output of a custom tool call from your code, being sent back to the model. + The number of input tokens that were written to the cache. - - `String callId` + - `long cachedTokens` - The call ID, used to map this custom tool call output to a custom tool call. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `Output output` + - `long outputTokens` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The number of output tokens. - - `String` + - `OutputTokensDetails outputTokensDetails` - - `List` + A detailed breakdown of the output tokens. - - `class BetaResponseInputText:` + - `long reasoningTokens` - A text input to the model. + The number of reasoning tokens. - - `class BetaResponseInputImage:` + - `long totalTokens` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The total number of tokens used. - - `class BetaResponseInputFile:` + - `Optional user` - A file input to the model. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `JsonValue; type "custom_tool_call_output"constant` + - `long sequenceNumber` - The type of the custom tool call output. Always `custom_tool_call_output`. + The sequence number for this event. - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `JsonValue; type "response.completed"constant` - - `Optional id` + The type of the event. Always `response.completed`. - The unique ID of the custom tool call output in the OpenAI platform. + - `RESPONSE_COMPLETED("response.completed")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` + - `class BetaResponseContentPartAddedEvent:` - The execution context that produced this tool call. + Emitted when a new content part is added. - - `JsonValue;` + - `long contentIndex` - - `JsonValue; type "direct"constant` + The index of the content part that was added. - The caller type. Always `direct`. + - `String itemId` - - `DIRECT("direct")` + The ID of the output item that the content part was added to. - - `class Program:` + - `long outputIndex` - - `String callerId` + The index of the output item that the content part was added to. - The call ID of the program item that produced this tool call. + - `Part part` - - `JsonValue; type "program"constant` + The content part that was added. - The caller type. Always `program`. + - `class BetaResponseOutputText:` - - `PROGRAM("program")` + A text output from the model. - - `class BetaResponseCustomToolCall:` + - `class BetaResponseOutputRefusal:` - A call to a custom tool created by the model. + A refusal from the model. - - `String callId` + - `class ReasoningText:` - An identifier used to map this custom tool call to a tool call output. + Reasoning text from the model. - - `String input` + - `String text` - The input for the custom tool call generated by the model. + The reasoning text from the model. - - `String name` + - `JsonValue; type "reasoning_text"constant` - The name of the custom tool being called. + The type of the reasoning text. Always `reasoning_text`. - - `JsonValue; type "custom_tool_call"constant` + - `REASONING_TEXT("reasoning_text")` - The type of the custom tool call. Always `custom_tool_call`. + - `long sequenceNumber` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + The sequence number of this event. - - `Optional id` + - `JsonValue; type "response.content_part.added"constant` - The unique ID of the custom tool call in the OpenAI platform. + The type of the event. Always `response.content_part.added`. + + - `RESPONSE_CONTENT_PART_ADDED("response.content_part.added")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` + - `class BetaResponseContentPartDoneEvent:` - - `DIRECT("direct")` + Emitted when a content part is done. - - `class Program:` + - `long contentIndex` - - `String callerId` + The index of the content part that is done. - The call ID of the program item that produced this tool call. + - `String itemId` - - `JsonValue; type "program"constant` + The ID of the output item that the content part was added to. - - `PROGRAM("program")` + - `long outputIndex` - - `Optional namespace` + The index of the output item that the content part was added to. - The namespace of the custom tool being called. + - `Part part` - - `CompactionTrigger` + The content part that is done. - - `JsonValue; type "compaction_trigger"constant` + - `class BetaResponseOutputText:` - The type of the item. Always `compaction_trigger`. + A text output from the model. - - `COMPACTION_TRIGGER("compaction_trigger")` + - `class BetaResponseOutputRefusal:` - - `Optional agent` + A refusal from the model. - The agent that produced this item. + - `class ReasoningText:` - - `String agentName` + Reasoning text from the model. - The canonical name of the agent that produced this item. + - `String text` - - `ItemReference` + The reasoning text from the model. - - `String id` + - `JsonValue; type "reasoning_text"constant` - The ID of the item to reference. + The type of the reasoning text. Always `reasoning_text`. - - `Optional agent` + - `REASONING_TEXT("reasoning_text")` - The agent that produced this item. + - `long sequenceNumber` - - `String agentName` + The sequence number of this event. - The canonical name of the agent that produced this item. + - `JsonValue; type "response.content_part.done"constant` - - `Optional type` + The type of the event. Always `response.content_part.done`. - The type of item to reference. Always `item_reference`. + - `RESPONSE_CONTENT_PART_DONE("response.content_part.done")` - - `ITEM_REFERENCE("item_reference")` + - `Optional agent` - - `Program` + The agent that owns this multi-agent streaming event. - - `String id` + - `String agentName` - The unique ID of this program item. + The canonical name of the agent that produced this item. - - `String callId` + - `class BetaResponseCreatedEvent:` - The stable call ID of the program item. + An event that is emitted when a response is created. - - `String code` + - `BetaResponse response` - The JavaScript source executed by programmatic tool calling. + The response that was created. - - `String fingerprint` + - `long sequenceNumber` - Opaque program replay fingerprint that must be round-tripped. + The sequence number for this event. - - `JsonValue; type "program"constant` + - `JsonValue; type "response.created"constant` - The item type. Always `program`. + The type of the event. Always `response.created`. - - `PROGRAM("program")` + - `RESPONSE_CREATED("response.created")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `ProgramOutput` - - - `String id` + - `class BetaResponseErrorEvent:` - The unique ID of this program output item. + Emitted when an error occurs. - - `String callId` + - `Optional code` - The call ID of the program item. + The error code. - - `String result` + - `String message` - The result produced by the program item. + The error message. - - `Status status` + - `Optional param` - The terminal status of the program output. + The error parameter. - - `COMPLETED("completed")` + - `long sequenceNumber` - - `INCOMPLETE("incomplete")` + The sequence number of this event. - - `JsonValue; type "program_output"constant` + - `JsonValue; type "error"constant` - The item type. Always `program_output`. + The type of the event. Always `error`. - - `PROGRAM_OUTPUT("program_output")` + - `ERROR("error")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional 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. - - - `Model model` - - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. - - - `GPT_5_6_SOL("gpt-5.6-sol")` - - - `GPT_5_6_TERRA("gpt-5.6-terra")` - - - `GPT_5_6_LUNA("gpt-5.6-luna")` + - `class BetaResponseFileSearchCallCompletedEvent:` - - `GPT_5_4("gpt-5.4")` + Emitted when a file search call is completed (results found). - - `GPT_5_4_MINI("gpt-5.4-mini")` + - `String itemId` - - `GPT_5_4_NANO("gpt-5.4-nano")` + The ID of the output item that the file search call is initiated. - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `long outputIndex` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + The index of the output item that the file search call is initiated. - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `long sequenceNumber` - - `GPT_5_2("gpt-5.2")` + The sequence number of this event. - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + - `JsonValue; type "response.file_search_call.completed"constant` - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + The type of the event. Always `response.file_search_call.completed`. - - `GPT_5_2_PRO("gpt-5.2-pro")` + - `RESPONSE_FILE_SEARCH_CALL_COMPLETED("response.file_search_call.completed")` - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + - `Optional agent` - - `GPT_5_1("gpt-5.1")` + The agent that owns this multi-agent streaming event. - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `String agentName` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + The canonical name of the agent that produced this item. - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `class BetaResponseFileSearchCallInProgressEvent:` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + Emitted when a file search call is initiated. - - `GPT_5("gpt-5")` + - `String itemId` - - `GPT_5_MINI("gpt-5-mini")` + The ID of the output item that the file search call is initiated. - - `GPT_5_NANO("gpt-5-nano")` + - `long outputIndex` - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + The index of the output item that the file search call is initiated. - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - `long sequenceNumber` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + The sequence number of this event. - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `JsonValue; type "response.file_search_call.in_progress"constant` - - `GPT_4_1("gpt-4.1")` + The type of the event. Always `response.file_search_call.in_progress`. - - `GPT_4_1_MINI("gpt-4.1-mini")` + - `RESPONSE_FILE_SEARCH_CALL_IN_PROGRESS("response.file_search_call.in_progress")` - - `GPT_4_1_NANO("gpt-4.1-nano")` + - `Optional agent` - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + The agent that owns this multi-agent streaming event. - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` + - `String agentName` - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` + The canonical name of the agent that produced this item. - - `O4_MINI("o4-mini")` + - `class BetaResponseFileSearchCallSearchingEvent:` - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` + Emitted when a file search is currently searching. - - `O3("o3")` + - `String itemId` - - `O3_2025_04_16("o3-2025-04-16")` + The ID of the output item that the file search call is initiated. - - `O3_MINI("o3-mini")` + - `long outputIndex` - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` + The index of the output item that the file search call is searching. - - `O1("o1")` + - `long sequenceNumber` - - `O1_2024_12_17("o1-2024-12-17")` + The sequence number of this event. - - `O1_PREVIEW("o1-preview")` + - `JsonValue; type "response.file_search_call.searching"constant` - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` + The type of the event. Always `response.file_search_call.searching`. - - `O1_MINI("o1-mini")` + - `RESPONSE_FILE_SEARCH_CALL_SEARCHING("response.file_search_call.searching")` - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + - `Optional agent` - - `GPT_4O("gpt-4o")` + The agent that owns this multi-agent streaming event. - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` + - `String agentName` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` + The canonical name of the agent that produced this item. - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` + - `class BetaResponseFunctionCallArgumentsDeltaEvent:` - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` + Emitted when there is a partial function-call arguments delta. - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` + - `String delta` - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` + The function-call arguments delta that is added. - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` + - `String itemId` - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + The ID of the output item that the function-call arguments delta is added to. - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` + - `long outputIndex` - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` + The index of the output item that the function-call arguments delta is added to. - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + - `long sequenceNumber` - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + The sequence number of this event. - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + - `JsonValue; type "response.function_call_arguments.delta"constant` - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + The type of the event. Always `response.function_call_arguments.delta`. - - `CODEX_MINI_LATEST("codex-mini-latest")` + - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DELTA("response.function_call_arguments.delta")` - - `GPT_4O_MINI("gpt-4o-mini")` + - `Optional agent` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + The agent that owns this multi-agent streaming event. - - `GPT_4_TURBO("gpt-4-turbo")` + - `String agentName` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + The canonical name of the agent that produced this item. - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + - `class BetaResponseFunctionCallArgumentsDoneEvent:` - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + Emitted when function-call arguments are finalized. - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `String arguments` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + The function-call arguments. - - `GPT_4("gpt-4")` + - `String itemId` - - `GPT_4_0314("gpt-4-0314")` + The ID of the item. - - `GPT_4_0613("gpt-4-0613")` + - `String name` - - `GPT_4_32K("gpt-4-32k")` + The name of the function that was called. - - `GPT_4_32K_0314("gpt-4-32k-0314")` + - `long outputIndex` - - `GPT_4_32K_0613("gpt-4-32k-0613")` + The index of the output item. - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + - `long sequenceNumber` - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + The sequence number of this event. - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `JsonValue; type "response.function_call_arguments.done"constant` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DONE("response.function_call_arguments.done")` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `Optional agent` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + The agent that owns this multi-agent streaming event. - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + - `String agentName` - - `O1_PRO("o1-pro")` + The canonical name of the agent that produced this item. - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - `class BetaResponseInProgressEvent:` - - `O3_PRO("o3-pro")` + Emitted when the response is in progress. - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `BetaResponse response` - - `O3_DEEP_RESEARCH("o3-deep-research")` + The response that is in progress. - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + - `long sequenceNumber` - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + The sequence number of this event. - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `JsonValue; type "response.in_progress"constant` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + The type of the event. Always `response.in_progress`. - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `RESPONSE_IN_PROGRESS("response.in_progress")` - - `GPT_5_CODEX("gpt-5-codex")` + - `Optional agent` - - `GPT_5_PRO("gpt-5-pro")` + The agent that owns this multi-agent streaming event. - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` + - `String agentName` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` + The canonical name of the agent that produced this item. - - `JsonValue; object_ "response"constant` + - `class BetaResponseFailedEvent:` - The object type of this resource - always set to `response`. + An event that is emitted when a response fails. - - `RESPONSE("response")` + - `BetaResponse response` - - `List output` + The response that failed. - An array of content items generated by the model. + - `long sequenceNumber` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The sequence number of this event. - - `class BetaResponseOutputMessage:` + - `JsonValue; type "response.failed"constant` - An output message from the model. + The type of the event. Always `response.failed`. - - `class BetaResponseFileSearchToolCall:` + - `RESPONSE_FAILED("response.failed")` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `Optional agent` - - `class BetaResponseFunctionToolCall:` + The agent that owns this multi-agent streaming event. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `String agentName` - - `class BetaResponseFunctionToolCallOutputItem:` + The canonical name of the agent that produced this item. - - `String id` + - `class BetaResponseIncompleteEvent:` - The unique ID of the function call tool output. + An event that is emitted when a response finishes as incomplete. - - `String callId` + - `BetaResponse response` - The unique ID of the function tool call generated by the model. + The response that was incomplete. - - `Output output` + - `long sequenceNumber` - The output from the function call generated by your code. - Can be a string or an list of output content. + The sequence number of this event. - - `String` + - `JsonValue; type "response.incomplete"constant` - - `List` + The type of the event. Always `response.incomplete`. - - `class BetaResponseInputText:` + - `RESPONSE_INCOMPLETE("response.incomplete")` - A text input to the model. + - `Optional agent` - - `class BetaResponseInputImage:` + The agent that owns this multi-agent streaming event. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `String agentName` - - `class BetaResponseInputFile:` + The canonical name of the agent that produced this item. - A file input to the model. + - `class BetaResponseOutputItemAddedEvent:` - - `Status status` + Emitted when a new output item is added. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `BetaResponseOutputItem item` - - `IN_PROGRESS("in_progress")` + The output item that was added. - - `COMPLETED("completed")` + - `class BetaResponseOutputMessage:` - - `INCOMPLETE("incomplete")` + An output message from the model. - - `JsonValue; type "function_call_output"constant` + - `class BetaResponseFileSearchToolCall:` - The type of the function tool call output. Always `function_call_output`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `class BetaResponseFunctionToolCall:` - - `Optional agent` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The agent that produced this item. + - `class BetaResponseFunctionToolCallOutputItem:` - - `String agentName` + - `AgentMessage` - The canonical name of the agent that produced this item. + - `MultiAgentCall` - - `Optional caller` + - `MultiAgentCallOutput` - The execution context that produced this tool call. + - `class BetaResponseFunctionWebSearch:` - - `JsonValue;` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `JsonValue; type "direct"constant` + - `class BetaResponseComputerToolCall:` - The caller type. Always `direct`. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `DIRECT("direct")` + - `class BetaResponseComputerToolCallOutputItem:` - - `class Program:` + - `class BetaResponseReasoningItem:` - - `String callerId` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - The call ID of the program item that produced this tool call. + - `Program` - - `JsonValue; type "program"constant` + - `ProgramOutput` - The caller type. Always `program`. + - `class BetaResponseToolSearchCall:` - - `PROGRAM("program")` + - `class BetaResponseToolSearchOutputItem:` - - `Optional createdBy` + - `AdditionalTools` - The identifier of the actor that created the item. + - `class BetaResponseCompactionItem:` - - `AgentMessage` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `String id` + - `ImageGenerationCall` - The unique ID of the agent message. + - `class BetaResponseCodeInterpreterToolCall:` - - `String author` + A tool call to run code. - The sending agent identity. + - `LocalShellCall` - - `List content` + - `LocalShellCallOutput` - Encrypted content sent between agents. + - `class BetaResponseFunctionShellToolCall:` - - `class BetaResponseInputText:` + A tool call that executes one or more shell commands in a managed environment. - A text input to the model. + - `class BetaResponseFunctionShellToolCallOutput:` - - `class BetaResponseOutputText:` + The output of a shell tool call that was emitted. - A text output from the model. + - `class BetaResponseApplyPatchToolCall:` - - `class Text:` + A tool call that applies file diffs by creating, deleting, or updating files. - A text content. + - `class BetaResponseApplyPatchToolCallOutput:` - - `String text` + The output emitted by an apply patch tool call. - - `JsonValue; type "text"constant` + - `McpCall` - - `TEXT("text")` + - `McpListTools` - - `class SummaryText:` + - `McpApprovalRequest` - A summary text from the model. + - `McpApprovalResponse` - - `String text` + - `class BetaResponseCustomToolCall:` - A summary of the reasoning output from the model so far. + A call to a custom tool created by the model. - - `JsonValue; type "summary_text"constant` + - `class BetaResponseCustomToolCallOutputItem:` - The type of the object. Always `summary_text`. + The output of a custom tool call from your code, being sent back to the model. - - `SUMMARY_TEXT("summary_text")` + - `long outputIndex` - - `class ReasoningText:` + The index of the output item that was added. - Reasoning text from the model. + - `long sequenceNumber` - - `String text` + The sequence number of this event. - The reasoning text from the model. + - `JsonValue; type "response.output_item.added"constant` - - `JsonValue; type "reasoning_text"constant` + The type of the event. Always `response.output_item.added`. - The type of the reasoning text. Always `reasoning_text`. + - `RESPONSE_OUTPUT_ITEM_ADDED("response.output_item.added")` - - `REASONING_TEXT("reasoning_text")` + - `Optional agent` - - `class BetaResponseOutputRefusal:` + The agent that owns this multi-agent streaming event. - A refusal from the model. + - `String agentName` - - `class BetaResponseInputImage:` + The canonical name of the agent that produced this item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class BetaResponseOutputItemDoneEvent:` - - `class ComputerScreenshot:` + Emitted when an output item is marked done. - A screenshot of a computer. + - `BetaResponseOutputItem item` - - `Detail detail` + The output item that was marked done. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `long outputIndex` - - `LOW("low")` + The index of the output item that was marked done. - - `HIGH("high")` + - `long sequenceNumber` - - `AUTO("auto")` + The sequence number of this event. - - `ORIGINAL("original")` + - `JsonValue; type "response.output_item.done"constant` - - `Optional fileId` + The type of the event. Always `response.output_item.done`. - The identifier of an uploaded file that contains the screenshot. + - `RESPONSE_OUTPUT_ITEM_DONE("response.output_item.done")` - - `Optional imageUrl` + - `Optional agent` - The URL of the screenshot image. + The agent that owns this multi-agent streaming event. - - `JsonValue; type "computer_screenshot"constant` + - `String agentName` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The canonical name of the agent that produced this item. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `class BetaResponseReasoningSummaryPartAddedEvent:` - - `Optional promptCacheBreakpoint` + Emitted when a new reasoning summary part is added. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `String itemId` - - `JsonValue; mode "explicit"constant` + The ID of the item this summary part is associated with. - The breakpoint mode. Always `explicit`. + - `long outputIndex` - - `EXPLICIT("explicit")` + The index of the output item this summary part is associated with. - - `class BetaResponseInputFile:` + - `Part part` - A file input to the model. + The summary part that was added. - - `class EncryptedContent:` + - `String text` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The text of the summary part. - - `String encryptedContent` + - `JsonValue; type "summary_text"constant` - Opaque encrypted content. + The type of the summary part. Always `summary_text`. - - `JsonValue; type "encrypted_content"constant` + - `SUMMARY_TEXT("summary_text")` - The type of the input item. Always `encrypted_content`. + - `long sequenceNumber` - - `ENCRYPTED_CONTENT("encrypted_content")` + The sequence number of this event. - - `String recipient` + - `long summaryIndex` - The destination agent identity. + The index of the summary part within the reasoning summary. - - `JsonValue; type "agent_message"constant` + - `JsonValue; type "response.reasoning_summary_part.added"constant` - The type of the item. Always `agent_message`. + The type of the event. Always `response.reasoning_summary_part.added`. - - `AGENT_MESSAGE("agent_message")` + - `RESPONSE_REASONING_SUMMARY_PART_ADDED("response.reasoning_summary_part.added")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `MultiAgentCall` + - `class BetaResponseReasoningSummaryPartDoneEvent:` - - `String id` + Emitted when a reasoning summary part is completed. - The unique ID of the multi-agent call item. + - `String itemId` - - `Action action` + The ID of the item this summary part is associated with. - The multi-agent action to execute. + - `long outputIndex` - - `SPAWN_AGENT("spawn_agent")` + The index of the output item this summary part is associated with. - - `INTERRUPT_AGENT("interrupt_agent")` + - `Part part` - - `LIST_AGENTS("list_agents")` + The completed summary part. - - `SEND_MESSAGE("send_message")` + - `String text` - - `FOLLOWUP_TASK("followup_task")` + The text of the summary part. - - `WAIT_AGENT("wait_agent")` + - `JsonValue; type "summary_text"constant` - - `String arguments` + The type of the summary part. Always `summary_text`. - The JSON string of arguments generated for the action. + - `SUMMARY_TEXT("summary_text")` - - `String callId` + - `long sequenceNumber` - The unique ID linking this call to its output. + The sequence number of this event. - - `JsonValue; type "multi_agent_call"constant` + - `long summaryIndex` - The type of the multi-agent call. Always `multi_agent_call`. + The index of the summary part within the reasoning summary. - - `MULTI_AGENT_CALL("multi_agent_call")` + - `JsonValue; type "response.reasoning_summary_part.done"constant` + + The type of the event. Always `response.reasoning_summary_part.done`. + + - `RESPONSE_REASONING_SUMMARY_PART_DONE("response.reasoning_summary_part.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `MultiAgentCallOutput` - - - `String id` + - `Optional status` - The unique ID of the multi-agent call output item. + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `Action action` + - `INCOMPLETE("incomplete")` - The multi-agent action that produced this result. + - `class BetaResponseReasoningSummaryTextDeltaEvent:` - - `SPAWN_AGENT("spawn_agent")` + Emitted when a delta is added to a reasoning summary text. - - `INTERRUPT_AGENT("interrupt_agent")` + - `String delta` - - `LIST_AGENTS("list_agents")` + The text delta that was added to the summary. - - `SEND_MESSAGE("send_message")` + - `String itemId` - - `FOLLOWUP_TASK("followup_task")` + The ID of the item this summary text delta is associated with. - - `WAIT_AGENT("wait_agent")` + - `long outputIndex` - - `String callId` + The index of the output item this summary text delta is associated with. - The unique ID of the multi-agent call. + - `long sequenceNumber` - - `List output` + The sequence number of this event. - Text output returned by the multi-agent action. + - `long summaryIndex` - - `List annotations` + The index of the summary part within the reasoning summary. - The annotations of the text output. + - `JsonValue; type "response.reasoning_summary_text.delta"constant` - - `String text` + The type of the event. Always `response.reasoning_summary_text.delta`. - The text output from the model. + - `RESPONSE_REASONING_SUMMARY_TEXT_DELTA("response.reasoning_summary_text.delta")` - - `JsonValue; type "output_text"constant` + - `Optional agent` - The type of the output text. Always `output_text`. + The agent that owns this multi-agent streaming event. - - `Optional> logprobs` + - `String agentName` - - `JsonValue; type "multi_agent_call_output"constant` + The canonical name of the agent that produced this item. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `class BetaResponseReasoningSummaryTextDoneEvent:` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + Emitted when a reasoning summary text is completed. - - `Optional agent` + - `String itemId` - The agent that produced this item. + The ID of the item this summary text is associated with. - - `String agentName` + - `long outputIndex` - The canonical name of the agent that produced this item. + The index of the output item this summary text is associated with. - - `class BetaResponseFunctionWebSearch:` + - `long sequenceNumber` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The sequence number of this event. - - `class BetaResponseComputerToolCall:` + - `long summaryIndex` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The index of the summary part within the reasoning summary. - - `class BetaResponseComputerToolCallOutputItem:` + - `String text` - - `String id` + The full text of the completed reasoning summary. - The unique ID of the computer call tool output. + - `JsonValue; type "response.reasoning_summary_text.done"constant` - - `String callId` + The type of the event. Always `response.reasoning_summary_text.done`. - The ID of the computer tool call that produced the output. + - `RESPONSE_REASONING_SUMMARY_TEXT_DONE("response.reasoning_summary_text.done")` - - `BetaResponseComputerToolCallOutputScreenshot output` + - `Optional agent` - A computer screenshot image used with the computer use tool. + The agent that owns this multi-agent streaming event. - - `Status status` + - `String agentName` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The canonical name of the agent that produced this item. - - `COMPLETED("completed")` + - `class BetaResponseReasoningTextDeltaEvent:` - - `INCOMPLETE("incomplete")` + Emitted when a delta is added to a reasoning text. - - `FAILED("failed")` + - `long contentIndex` - - `IN_PROGRESS("in_progress")` + The index of the reasoning content part this delta is associated with. - - `JsonValue; type "computer_call_output"constant` + - `String delta` - The type of the computer tool call output. Always `computer_call_output`. + The text delta that was added to the reasoning content. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `String itemId` - - `Optional> acknowledgedSafetyChecks` + The ID of the item this reasoning text delta is associated with. - The safety checks reported by the API that have been acknowledged by the - developer. + - `long outputIndex` - - `String id` + The index of the output item this reasoning text delta is associated with. - The ID of the pending safety check. + - `long sequenceNumber` - - `Optional code` + The sequence number of this event. - The type of the pending safety check. + - `JsonValue; type "response.reasoning_text.delta"constant` - - `Optional message` + The type of the event. Always `response.reasoning_text.delta`. - Details about the pending safety check. + - `RESPONSE_REASONING_TEXT_DELTA("response.reasoning_text.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. + - `class BetaResponseReasoningTextDoneEvent:` - - `class BetaResponseReasoningItem:` + Emitted when a reasoning text is completed. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `long contentIndex` - - `Program` + The index of the reasoning content part. - - `String id` + - `String itemId` - The unique ID of the program item. + The ID of the item this reasoning text is associated with. - - `String callId` + - `long outputIndex` - The stable call ID of the program item. + The index of the output item this reasoning text is associated with. - - `String code` + - `long sequenceNumber` - The JavaScript source executed by programmatic tool calling. + The sequence number of this event. - - `String fingerprint` + - `String text` - Opaque program replay fingerprint that must be round-tripped. + The full text of the completed reasoning content. - - `JsonValue; type "program"constant` + - `JsonValue; type "response.reasoning_text.done"constant` - The type of the item. Always `program`. + The type of the event. Always `response.reasoning_text.done`. - - `PROGRAM("program")` + - `RESPONSE_REASONING_TEXT_DONE("response.reasoning_text.done")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `ProgramOutput` + - `class BetaResponseRefusalDeltaEvent:` - - `String id` + Emitted when there is a partial refusal text. - The unique ID of the program output item. + - `long contentIndex` - - `String callId` + The index of the content part that the refusal text is added to. - The call ID of the program item. + - `String delta` - - `String result` + The refusal text that is added. - The result produced by the program item. + - `String itemId` - - `Status status` + The ID of the output item that the refusal text is added to. - The terminal status of the program output item. + - `long outputIndex` - - `COMPLETED("completed")` + The index of the output item that the refusal text is added to. - - `INCOMPLETE("incomplete")` + - `long sequenceNumber` - - `JsonValue; type "program_output"constant` + The sequence number of this event. - The type of the item. Always `program_output`. + - `JsonValue; type "response.refusal.delta"constant` - - `PROGRAM_OUTPUT("program_output")` + The type of the event. Always `response.refusal.delta`. + + - `RESPONSE_REFUSAL_DELTA("response.refusal.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseToolSearchCall:` + - `class BetaResponseRefusalDoneEvent:` - - `String id` + Emitted when refusal text is finalized. - The unique ID of the tool search call item. + - `long contentIndex` - - `JsonValue arguments` + The index of the content part that the refusal text is finalized. - Arguments used for the tool search call. + - `String itemId` - - `Optional callId` + The ID of the output item that the refusal text is finalized. - The unique ID of the tool search call generated by the model. + - `long outputIndex` - - `Execution execution` + The index of the output item that the refusal text is finalized. - Whether tool search was executed by the server or by the client. + - `String refusal` - - `SERVER("server")` + The refusal text that is finalized. - - `CLIENT("client")` + - `long sequenceNumber` - - `Status status` + The sequence number of this event. - The status of the tool search call item that was recorded. + - `JsonValue; type "response.refusal.done"constant` - - `IN_PROGRESS("in_progress")` + The type of the event. Always `response.refusal.done`. - - `COMPLETED("completed")` + - `RESPONSE_REFUSAL_DONE("response.refusal.done")` - - `INCOMPLETE("incomplete")` + - `Optional agent` - - `JsonValue; type "tool_search_call"constant` + The agent that owns this multi-agent streaming event. - The type of the item. Always `tool_search_call`. + - `String agentName` - - `TOOL_SEARCH_CALL("tool_search_call")` + The canonical name of the agent that produced this item. - - `Optional agent` + - `class BetaResponseTextDeltaEvent:` - The agent that produced this item. + Emitted when there is an additional text delta. - - `String agentName` + - `long contentIndex` - The canonical name of the agent that produced this item. + The index of the content part that the text delta was added to. - - `Optional createdBy` + - `String delta` - The identifier of the actor that created the item. + The text delta that was added. - - `class BetaResponseToolSearchOutputItem:` + - `String itemId` - - `String id` + The ID of the output item that the text delta was added to. - The unique ID of the tool search output item. + - `List logprobs` - - `Optional callId` + The log probabilities of the tokens in the delta. - The unique ID of the tool search call generated by the model. + - `String token` - - `Execution execution` + A possible text token. - Whether tool search was executed by the server or by the client. + - `double logprob` - - `SERVER("server")` + The log probability of this token. - - `CLIENT("client")` + - `Optional> topLogprobs` - - `Status status` + The log probabilities of up to 20 of the most likely tokens. - The status of the tool search output item that was recorded. + - `Optional token` - - `IN_PROGRESS("in_progress")` + A possible text token. - - `COMPLETED("completed")` + - `Optional logprob` - - `INCOMPLETE("incomplete")` + The log probability of this token. - - `List tools` + - `long outputIndex` - The loaded tool definitions returned by tool search. + The index of the output item that the text delta was added to. - - `class BetaFunctionTool:` + - `long sequenceNumber` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The sequence number for this event. - - `class BetaFileSearchTool:` + - `JsonValue; type "response.output_text.delta"constant` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The type of the event. Always `response.output_text.delta`. - - `class BetaComputerTool:` + - `RESPONSE_OUTPUT_TEXT_DELTA("response.output_text.delta")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional agent` - - `class BetaComputerUsePreviewTool:` + The agent that owns this multi-agent streaming event. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String agentName` - - `class BetaWebSearchTool:` + The canonical name of the agent that produced this item. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class BetaResponseTextDoneEvent:` - - `Mcp` + Emitted when text content is finalized. - - `CodeInterpreter` + - `long contentIndex` - - `JsonValue;` + The index of the content part that the text content is finalized. - - `ImageGeneration` + - `String itemId` - - `JsonValue;` + The ID of the output item that the text content is finalized. - - `class BetaFunctionShellTool:` + - `List logprobs` - A tool that allows the model to execute shell commands. + The log probabilities of the tokens in the delta. - - `class BetaCustomTool:` + - `String token` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + A possible text token. - - `class BetaNamespaceTool:` + - `double logprob` - Groups function/custom tools under a shared namespace. + The log probability of this token. - - `class BetaToolSearchTool:` + - `Optional> topLogprobs` - Hosted or BYOT tool search configuration for deferred tools. + The log probabilities of up to 20 of the most likely tokens. - - `class BetaWebSearchPreviewTool:` + - `Optional token` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A possible text token. - - `class BetaApplyPatchTool:` + - `Optional logprob` - Allows the assistant to create, delete, or update files using unified diffs. + The log probability of this token. - - `JsonValue; type "tool_search_output"constant` + - `long outputIndex` - The type of the item. Always `tool_search_output`. + The index of the output item that the text content is finalized. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `long sequenceNumber` - - `Optional agent` + The sequence number for this event. - The agent that produced this item. + - `String text` - - `String agentName` + The text content that is finalized. - The canonical name of the agent that produced this item. + - `JsonValue; type "response.output_text.done"constant` - - `Optional createdBy` + The type of the event. Always `response.output_text.done`. - The identifier of the actor that created the item. + - `RESPONSE_OUTPUT_TEXT_DONE("response.output_text.done")` - - `AdditionalTools` + - `Optional agent` - - `String id` + The agent that owns this multi-agent streaming event. - The unique ID of the additional tools item. + - `String agentName` - - `Role role` + The canonical name of the agent that produced this item. - The role that provided the additional tools. + - `class BetaResponseWebSearchCallCompletedEvent:` - - `UNKNOWN("unknown")` + Emitted when a web search call is completed. - - `USER("user")` + - `String itemId` - - `ASSISTANT("assistant")` + Unique ID for the output item associated with the web search call. - - `SYSTEM("system")` + - `long outputIndex` - - `CRITIC("critic")` + The index of the output item that the web search call is associated with. - - `DISCRIMINATOR("discriminator")` + - `long sequenceNumber` - - `DEVELOPER("developer")` + The sequence number of the web search call being processed. - - `TOOL("tool")` + - `JsonValue; type "response.web_search_call.completed"constant` - - `List tools` + The type of the event. Always `response.web_search_call.completed`. - The additional tool definitions made available at this item. + - `RESPONSE_WEB_SEARCH_CALL_COMPLETED("response.web_search_call.completed")` - - `class BetaFunctionTool:` + - `Optional agent` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The agent that owns this multi-agent streaming event. - - `class BetaFileSearchTool:` + - `String agentName` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The canonical name of the agent that produced this item. - - `class BetaComputerTool:` + - `class BetaResponseWebSearchCallInProgressEvent:` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Emitted when a web search call is initiated. - - `class BetaComputerUsePreviewTool:` + - `String itemId` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Unique ID for the output item associated with the web search call. - - `class BetaWebSearchTool:` + - `long outputIndex` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The index of the output item that the web search call is associated with. - - `Mcp` + - `long sequenceNumber` - - `CodeInterpreter` + The sequence number of the web search call being processed. - - `JsonValue;` + - `JsonValue; type "response.web_search_call.in_progress"constant` - - `ImageGeneration` + The type of the event. Always `response.web_search_call.in_progress`. - - `JsonValue;` + - `RESPONSE_WEB_SEARCH_CALL_IN_PROGRESS("response.web_search_call.in_progress")` - - `class BetaFunctionShellTool:` + - `Optional agent` - A tool that allows the model to execute shell commands. + The agent that owns this multi-agent streaming event. - - `class BetaCustomTool:` + - `String agentName` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The canonical name of the agent that produced this item. - - `class BetaNamespaceTool:` + - `class BetaResponseWebSearchCallSearchingEvent:` - Groups function/custom tools under a shared namespace. + Emitted when a web search call is executing. - - `class BetaToolSearchTool:` + - `String itemId` - Hosted or BYOT tool search configuration for deferred tools. + Unique ID for the output item associated with the web search call. - - `class BetaWebSearchPreviewTool:` + - `long outputIndex` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The index of the output item that the web search call is associated with. - - `class BetaApplyPatchTool:` + - `long sequenceNumber` - Allows the assistant to create, delete, or update files using unified diffs. + The sequence number of the web search call being processed. - - `JsonValue; type "additional_tools"constant` + - `JsonValue; type "response.web_search_call.searching"constant` - The type of the item. Always `additional_tools`. + The type of the event. Always `response.web_search_call.searching`. - - `ADDITIONAL_TOOLS("additional_tools")` + - `RESPONSE_WEB_SEARCH_CALL_SEARCHING("response.web_search_call.searching")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseCompactionItem:` + - `class BetaResponseImageGenCallCompletedEvent:` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Emitted when an image generation tool call has completed and the final image is available. - - `String id` + - `String itemId` - The unique ID of the compaction item. + The unique identifier of the image generation item being processed. - - `String encryptedContent` + - `long outputIndex` - The encrypted content that was produced by compaction. + The index of the output item in the response's output array. - - `JsonValue; type "compaction"constant` + - `long sequenceNumber` - The type of the item. Always `compaction`. + The sequence number of this event. - - `COMPACTION("compaction")` + - `JsonValue; type "response.image_generation_call.completed"constant` + + The type of the event. Always 'response.image_generation_call.completed'. + + - `RESPONSE_IMAGE_GENERATION_CALL_COMPLETED("response.image_generation_call.completed")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional createdBy` - - The identifier of the actor that created the item. - - - `ImageGenerationCall` - - - `String id` - - The unique ID of the image generation call. - - - `Optional result` + - `class BetaResponseImageGenCallGeneratingEvent:` - The generated image encoded in base64. + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `Status status` + - `String itemId` - The status of the image generation call. + The unique identifier of the image generation item being processed. - - `IN_PROGRESS("in_progress")` + - `long outputIndex` - - `COMPLETED("completed")` + The index of the output item in the response's output array. - - `GENERATING("generating")` + - `long sequenceNumber` - - `FAILED("failed")` + The sequence number of the image generation item being processed. - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "response.image_generation_call.generating"constant` - The type of the image generation call. Always `image_generation_call`. + The type of the event. Always 'response.image_generation_call.generating'. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `RESPONSE_IMAGE_GENERATION_CALL_GENERATING("response.image_generation_call.generating")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterToolCall:` + - `class BetaResponseImageGenCallInProgressEvent:` - A tool call to run code. + Emitted when an image generation tool call is in progress. - - `LocalShellCall` + - `String itemId` - - `String id` + The unique identifier of the image generation item being processed. - The unique ID of the local shell call. + - `long outputIndex` - - `Action action` + The index of the output item in the response's output array. - Execute a shell command on the server. + - `long sequenceNumber` - - `List command` + The sequence number of the image generation item being processed. - The command to run. + - `JsonValue; type "response.image_generation_call.in_progress"constant` - - `Env env` + The type of the event. Always 'response.image_generation_call.in_progress'. - Environment variables to set for the command. + - `RESPONSE_IMAGE_GENERATION_CALL_IN_PROGRESS("response.image_generation_call.in_progress")` - - `JsonValue; type "exec"constant` + - `Optional agent` - The type of the local shell action. Always `exec`. + The agent that owns this multi-agent streaming event. - - `EXEC("exec")` + - `String agentName` - - `Optional timeoutMs` + The canonical name of the agent that produced this item. - Optional timeout in milliseconds for the command. + - `class BetaResponseImageGenCallPartialImageEvent:` - - `Optional user` + Emitted when a partial image is available during image generation streaming. - Optional user to run the command as. + - `String itemId` - - `Optional workingDirectory` + The unique identifier of the image generation item being processed. - Optional working directory to run the command in. + - `long outputIndex` - - `String callId` + The index of the output item in the response's output array. - The unique ID of the local shell tool call generated by the model. + - `String partialImageB64` - - `Status status` + Base64-encoded partial image data, suitable for rendering as an image. - The status of the local shell call. + - `long partialImageIndex` - - `IN_PROGRESS("in_progress")` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `COMPLETED("completed")` + - `long sequenceNumber` - - `INCOMPLETE("incomplete")` + The sequence number of the image generation item being processed. - - `JsonValue; type "local_shell_call"constant` + - `JsonValue; type "response.image_generation_call.partial_image"constant` - The type of the local shell call. Always `local_shell_call`. + The type of the event. Always 'response.image_generation_call.partial_image'. - - `LOCAL_SHELL_CALL("local_shell_call")` + - `RESPONSE_IMAGE_GENERATION_CALL_PARTIAL_IMAGE("response.image_generation_call.partial_image")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `LocalShellCallOutput` + - `class BetaResponseMcpCallArgumentsDeltaEvent:` - - `String id` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - The unique ID of the local shell tool call generated by the model. + - `String delta` - - `String output` + A JSON string containing the partial update to the arguments for the MCP tool call. - A JSON string of the output of the local shell tool call. + - `String itemId` - - `JsonValue; type "local_shell_call_output"constant` + The unique identifier of the MCP tool call item being processed. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `long outputIndex` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The index of the output item in the response's output array. + + - `long sequenceNumber` + + The sequence number of this event. + + - `JsonValue; type "response.mcp_call_arguments.delta"constant` + + The type of the event. Always 'response.mcp_call_arguments.delta'. + + - `RESPONSE_MCP_CALL_ARGUMENTS_DELTA("response.mcp_call_arguments.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional status` + - `class BetaResponseMcpCallArgumentsDoneEvent:` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Emitted when the arguments for an MCP tool call are finalized. - - `IN_PROGRESS("in_progress")` + - `String arguments` - - `COMPLETED("completed")` + A JSON string containing the finalized arguments for the MCP tool call. - - `INCOMPLETE("incomplete")` + - `String itemId` - - `class BetaResponseFunctionShellToolCall:` + The unique identifier of the MCP tool call item being processed. - A tool call that executes one or more shell commands in a managed environment. + - `long outputIndex` - - `String id` + The index of the output item in the response's output array. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `long sequenceNumber` - - `Action action` + The sequence number of this event. - The shell commands and limits that describe how to run the tool call. + - `JsonValue; type "response.mcp_call_arguments.done"constant` - - `List commands` + The type of the event. Always 'response.mcp_call_arguments.done'. - - `Optional maxOutputLength` + - `RESPONSE_MCP_CALL_ARGUMENTS_DONE("response.mcp_call_arguments.done")` - Optional maximum number of characters to return from each command. + - `Optional agent` - - `Optional timeoutMs` + The agent that owns this multi-agent streaming event. - Optional timeout in milliseconds for the commands. + - `String agentName` - - `String callId` + The canonical name of the agent that produced this item. - The unique ID of the shell tool call generated by the model. + - `class BetaResponseMcpCallCompletedEvent:` - - `Optional environment` + Emitted when an MCP tool call has completed successfully. - Represents the use of a local environment to perform shell actions. + - `String itemId` - - `class BetaResponseLocalEnvironment:` + The ID of the MCP tool call item that completed. - Represents the use of a local environment to perform shell actions. + - `long outputIndex` - - `JsonValue; type "local"constant` + The index of the output item that completed. - The environment type. Always `local`. + - `long sequenceNumber` - - `LOCAL("local")` + The sequence number of this event. - - `class BetaResponseContainerReference:` + - `JsonValue; type "response.mcp_call.completed"constant` - Represents a container created with /v1/containers. + The type of the event. Always 'response.mcp_call.completed'. - - `String containerId` + - `RESPONSE_MCP_CALL_COMPLETED("response.mcp_call.completed")` - - `JsonValue; type "container_reference"constant` + - `Optional agent` - The environment type. Always `container_reference`. + The agent that owns this multi-agent streaming event. - - `CONTAINER_REFERENCE("container_reference")` + - `String agentName` - - `Status status` + The canonical name of the agent that produced this item. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `class BetaResponseMcpCallFailedEvent:` - - `IN_PROGRESS("in_progress")` + Emitted when an MCP tool call has failed. - - `COMPLETED("completed")` + - `String itemId` - - `INCOMPLETE("incomplete")` + The ID of the MCP tool call item that failed. - - `JsonValue; type "shell_call"constant` + - `long outputIndex` - The type of the item. Always `shell_call`. + The index of the output item that failed. - - `SHELL_CALL("shell_call")` + - `long sequenceNumber` + + The sequence number of this event. + + - `JsonValue; type "response.mcp_call.failed"constant` + + The type of the event. Always 'response.mcp_call.failed'. + + - `RESPONSE_MCP_CALL_FAILED("response.mcp_call.failed")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` + - `class BetaResponseMcpCallInProgressEvent:` - The execution context that produced this tool call. + Emitted when an MCP tool call is in progress. - - `JsonValue;` + - `String itemId` - - `JsonValue; type "direct"constant` + The unique identifier of the MCP tool call item being processed. - - `DIRECT("direct")` + - `long outputIndex` - - `class Program:` + The index of the output item in the response's output array. - - `String callerId` + - `long sequenceNumber` - The call ID of the program item that produced this tool call. + The sequence number of this event. - - `JsonValue; type "program"constant` + - `JsonValue; type "response.mcp_call.in_progress"constant` - - `PROGRAM("program")` + The type of the event. Always 'response.mcp_call.in_progress'. - - `Optional createdBy` + - `RESPONSE_MCP_CALL_IN_PROGRESS("response.mcp_call.in_progress")` - The ID of the entity that created this tool call. + - `Optional agent` - - `class BetaResponseFunctionShellToolCallOutput:` + The agent that owns this multi-agent streaming event. - The output of a shell tool call that was emitted. + - `String agentName` - - `String id` + The canonical name of the agent that produced this item. - The unique ID of the shell call output. Populated when this item is returned via API. + - `class BetaResponseMcpListToolsCompletedEvent:` - - `String callId` + Emitted when the list of available MCP tools has been successfully retrieved. - The unique ID of the shell tool call generated by the model. + - `String itemId` - - `Optional maxOutputLength` + The ID of the MCP tool call item that produced this output. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `long outputIndex` - - `List output` + The index of the output item that was processed. - An array of shell call output contents + - `long sequenceNumber` - - `Outcome outcome` + The sequence number of this event. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `JsonValue; type "response.mcp_list_tools.completed"constant` - - `JsonValue;` + The type of the event. Always 'response.mcp_list_tools.completed'. - - `JsonValue; type "timeout"constant` + - `RESPONSE_MCP_LIST_TOOLS_COMPLETED("response.mcp_list_tools.completed")` - The outcome type. Always `timeout`. + - `Optional agent` - - `TIMEOUT("timeout")` + The agent that owns this multi-agent streaming event. - - `class Exit:` + - `String agentName` - Indicates that the shell commands finished and returned an exit code. + The canonical name of the agent that produced this item. - - `long exitCode` + - `class BetaResponseMcpListToolsFailedEvent:` - Exit code from the shell process. + Emitted when the attempt to list available MCP tools has failed. - - `JsonValue; type "exit"constant` + - `String itemId` - The outcome type. Always `exit`. + The ID of the MCP tool call item that failed. - - `EXIT("exit")` + - `long outputIndex` - - `String stderr` + The index of the output item that failed. - The standard error output that was captured. + - `long sequenceNumber` - - `String stdout` + The sequence number of this event. - The standard output that was captured. + - `JsonValue; type "response.mcp_list_tools.failed"constant` - - `Optional createdBy` + The type of the event. Always 'response.mcp_list_tools.failed'. - The identifier of the actor that created the item. + - `RESPONSE_MCP_LIST_TOOLS_FAILED("response.mcp_list_tools.failed")` - - `Status status` + - `Optional agent` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The agent that owns this multi-agent streaming event. - - `IN_PROGRESS("in_progress")` + - `String agentName` - - `COMPLETED("completed")` + The canonical name of the agent that produced this item. - - `INCOMPLETE("incomplete")` + - `class BetaResponseMcpListToolsInProgressEvent:` - - `JsonValue; type "shell_call_output"constant` + Emitted when the system is in the process of retrieving the list of available MCP tools. - The type of the shell call output. Always `shell_call_output`. + - `String itemId` - - `SHELL_CALL_OUTPUT("shell_call_output")` + The ID of the MCP tool call item that is being processed. - - `Optional agent` + - `long outputIndex` - The agent that produced this item. + The index of the output item that is being processed. - - `String agentName` + - `long sequenceNumber` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `Optional caller` + - `JsonValue; type "response.mcp_list_tools.in_progress"constant` - The execution context that produced this tool call. + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `JsonValue;` + - `RESPONSE_MCP_LIST_TOOLS_IN_PROGRESS("response.mcp_list_tools.in_progress")` - - `JsonValue; type "direct"constant` + - `Optional agent` - - `DIRECT("direct")` + The agent that owns this multi-agent streaming event. - - `class Program:` + - `String agentName` - - `String callerId` + The canonical name of the agent that produced this item. - The call ID of the program item that produced this tool call. + - `class BetaResponseOutputTextAnnotationAddedEvent:` - - `JsonValue; type "program"constant` + Emitted when an annotation is added to output text content. - - `PROGRAM("program")` + - `JsonValue annotation` - - `Optional createdBy` + The annotation object being added. (See annotation schema for details.) - The identifier of the actor that created the item. + - `long annotationIndex` - - `class BetaResponseApplyPatchToolCall:` + The index of the annotation within the content part. - A tool call that applies file diffs by creating, deleting, or updating files. + - `long contentIndex` - - `String id` + The index of the content part within the output item. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `String itemId` - - `String callId` + The unique identifier of the item to which the annotation is being added. + + - `long outputIndex` + + The index of the output item in the response's output array. - The unique ID of the apply patch tool call generated by the model. + - `long sequenceNumber` - - `Operation operation` + The sequence number of this event. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `JsonValue; type "response.output_text.annotation.added"constant` - - `class CreateFile:` + The type of the event. Always 'response.output_text.annotation.added'. - Instruction describing how to create a file via the apply_patch tool. + - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` - - `String diff` + - `Optional agent` - Diff to apply. + The agent that owns this multi-agent streaming event. - - `String path` + - `String agentName` - Path of the file to create. + The canonical name of the agent that produced this item. - - `JsonValue; type "create_file"constant` + - `class BetaResponseQueuedEvent:` - Create a new file with the provided diff. + Emitted when a response is queued and waiting to be processed. - - `CREATE_FILE("create_file")` + - `BetaResponse response` - - `class DeleteFile:` + The full response object that is queued. - Instruction describing how to delete a file via the apply_patch tool. + - `long sequenceNumber` - - `String path` + The sequence number for this event. - Path of the file to delete. + - `JsonValue; type "response.queued"constant` - - `JsonValue; type "delete_file"constant` + The type of the event. Always 'response.queued'. - Delete the specified file. + - `RESPONSE_QUEUED("response.queued")` - - `DELETE_FILE("delete_file")` + - `Optional agent` - - `class UpdateFile:` + The agent that owns this multi-agent streaming event. - Instruction describing how to update a file via the apply_patch tool. + - `String agentName` - - `String diff` + The canonical name of the agent that produced this item. - Diff to apply. + - `class BetaResponseCustomToolCallInputDeltaEvent:` - - `String path` + Event representing a delta (partial update) to the input of a custom tool call. - Path of the file to update. + - `String delta` - - `JsonValue; type "update_file"constant` + The incremental input data (delta) for the custom tool call. - Update an existing file with the provided diff. + - `String itemId` - - `UPDATE_FILE("update_file")` + Unique identifier for the API item associated with this event. - - `Status status` + - `long outputIndex` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The index of the output this delta applies to. - - `IN_PROGRESS("in_progress")` + - `long sequenceNumber` - - `COMPLETED("completed")` + The sequence number of this event. - - `JsonValue; type "apply_patch_call"constant` + - `JsonValue; type "response.custom_tool_call_input.delta"constant` - The type of the item. Always `apply_patch_call`. + The event type identifier. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DELTA("response.custom_tool_call_input.delta")` - `Optional agent` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `String agentName` The canonical name of the agent that produced this item. - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` + - `class BetaResponseCustomToolCallInputDoneEvent:` - - `class Program:` + Event indicating that input for a custom tool call is complete. - - `String callerId` + - `String input` - The call ID of the program item that produced this tool call. + The complete input data for the custom tool call. - - `JsonValue; type "program"constant` + - `String itemId` - - `PROGRAM("program")` + Unique identifier for the API item associated with this event. - - `Optional createdBy` + - `long outputIndex` - The ID of the entity that created this tool call. + The index of the output this event applies to. - - `class BetaResponseApplyPatchToolCallOutput:` + - `long sequenceNumber` - The output emitted by an apply patch tool call. + The sequence number of this event. - - `String id` + - `JsonValue; type "response.custom_tool_call_input.done"constant` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The event type identifier. - - `String callId` + - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DONE("response.custom_tool_call_input.done")` - The unique ID of the apply patch tool call generated by the model. + - `Optional agent` - - `Status status` + The agent that owns this multi-agent streaming event. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `String agentName` - - `COMPLETED("completed")` + The canonical name of the agent that produced this item. - - `FAILED("failed")` + - `class BetaResponseInjectCreatedEvent:` - - `JsonValue; type "apply_patch_call_output"constant` + Emitted when all injected input items were validated and committed to the + active response. - The type of the item. Always `apply_patch_call_output`. + - `String responseId` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The ID of the response that accepted the input. - - `Optional agent` + - `long sequenceNumber` - The agent that produced this item. + The sequence number for this event. - - `String agentName` + - `JsonValue; type "response.inject.created"constant` - The canonical name of the agent that produced this item. + The event discriminator. Always `response.inject.created`. - - `Optional caller` + - `RESPONSE_INJECT_CREATED("response.inject.created")` - The execution context that produced this tool call. + - `Optional streamId` - - `JsonValue;` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `JsonValue; type "direct"constant` + - `class BetaResponseInjectFailedEvent:` - - `DIRECT("direct")` + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - - `class Program:` + - `Error error` - - `String callerId` + Information about why the input was not committed. - The call ID of the program item that produced this tool call. + - `Code code` - - `JsonValue; type "program"constant` + A machine-readable error code. - - `PROGRAM("program")` + - `RESPONSE_ALREADY_COMPLETED("response_already_completed")` - - `Optional createdBy` + - `RESPONSE_NOT_FOUND("response_not_found")` - The ID of the entity that created this tool call output. + - `String message` - - `Optional output` + A human-readable description of the error. - Optional textual output returned by the apply patch tool. + - `List input` - - `McpCall` + The raw input items that were not committed. - - `String id` + - `class BetaEasyInputMessage:` - The unique ID of the tool call. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `String arguments` + - `Message` - A JSON string of the arguments passed to the tool. + - `class BetaResponseOutputMessage:` - - `String name` + An output message from the model. - The name of the tool that was run. + - `class BetaResponseFileSearchToolCall:` - - `String serverLabel` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The label of the MCP server running the tool. + - `class BetaResponseComputerToolCall:` - - `JsonValue; type "mcp_call"constant` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - The type of the item. Always `mcp_call`. + - `ComputerCallOutput` - - `MCP_CALL("mcp_call")` + - `class BetaResponseFunctionWebSearch:` - - `Optional agent` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The agent that produced this item. + - `class BetaResponseFunctionToolCall:` - - `String agentName` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The canonical name of the agent that produced this item. + - `FunctionCallOutput` - - `Optional approvalRequestId` + - `AgentMessage` - 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. + - `MultiAgentCall` - - `Optional error` + - `MultiAgentCallOutput` - The error from the tool call, if any. + - `ToolSearchCall` - - `Optional output` + - `class BetaResponseToolSearchOutputItemParam:` - The output from the tool call. + - `AdditionalTools` - - `Optional status` + - `class BetaResponseReasoningItem:` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `IN_PROGRESS("in_progress")` + - `class BetaResponseCompactionItemParam:` - - `COMPLETED("completed")` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `INCOMPLETE("incomplete")` + - `ImageGenerationCall` - - `CALLING("calling")` + - `class BetaResponseCodeInterpreterToolCall:` - - `FAILED("failed")` + A tool call to run code. - - `McpListTools` + - `LocalShellCall` - - `String id` + - `LocalShellCallOutput` - The unique ID of the list. + - `ShellCall` - - `String serverLabel` + - `ShellCallOutput` - The label of the MCP server. + - `ApplyPatchCall` - - `List tools` + - `ApplyPatchCallOutput` - The tools available on the server. + - `McpListTools` - - `JsonValue inputSchema` + - `McpApprovalRequest` - The JSON schema describing the tool's input. + - `McpApprovalResponse` - - `String name` + - `McpCall` - The name of the tool. + - `class BetaResponseCustomToolCallOutput:` - - `Optional annotations` + The output of a custom tool call from your code, being sent back to the model. - Additional annotations about the tool. + - `class BetaResponseCustomToolCall:` - - `Optional description` + A call to a custom tool created by the model. - The description of the tool. + - `CompactionTrigger` - - `JsonValue; type "mcp_list_tools"constant` + - `ItemReference` - The type of the item. Always `mcp_list_tools`. + - `Program` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `ProgramOutput` - - `Optional agent` + - `String responseId` - The agent that produced this item. + The ID of the response that rejected the input. - - `String agentName` + - `long sequenceNumber` - The canonical name of the agent that produced this item. + The sequence number for this event. - - `Optional error` + - `JsonValue; type "response.inject.failed"constant` - Error message if the server could not list tools. + The event discriminator. Always `response.inject.failed`. - - `McpApprovalRequest` + - `RESPONSE_INJECT_FAILED("response.inject.failed")` - - `String id` + - `Optional streamId` - The unique ID of the approval request. + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `String arguments` +### Beta Skill Reference - A JSON string of arguments for the tool. +- `class BetaSkillReference:` - - `String name` + - `String skillId` - The name of the tool to run. + The ID of the referenced skill. - - `String serverLabel` + - `JsonValue; type "skill_reference"constant` - The label of the MCP server making the request. + References a skill created with the /v1/skills endpoint. - - `JsonValue; type "mcp_approval_request"constant` + - `SKILL_REFERENCE("skill_reference")` - The type of the item. Always `mcp_approval_request`. + - `Optional version` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `Optional agent` +### Beta Tool - The agent that produced this item. +- `class BetaTool: A class that can be one of several variants.union` - - `String agentName` + A tool that can be used to generate a response. - The canonical name of the agent that produced this item. + - `class BetaFunctionTool:` - - `McpApprovalResponse` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String id` + - `String name` - The unique ID of the approval response + The name of the function to call. - - `String approvalRequestId` + - `Optional parameters` - The ID of the approval request being answered. + A JSON schema object describing the parameters of the function. - - `boolean approve` + - `Optional strict` - Whether the request was approved. + Whether strict parameter validation is enforced for this function tool. - - `JsonValue; type "mcp_approval_response"constant` + - `JsonValue; type "function"constant` - The type of the item. Always `mcp_approval_response`. + The type of the function tool. Always `function`. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `FUNCTION("function")` - - `Optional agent` + - `Optional> allowedCallers` - The agent that produced this item. + The tool invocation context(s). - - `String agentName` + - `DIRECT("direct")` - The canonical name of the agent that produced this item. + - `PROGRAMMATIC("programmatic")` - - `Optional reason` + - `Optional deferLoading` - Optional reason for the decision. + Whether this function is deferred and loaded via tool search. - - `class BetaResponseCustomToolCall:` + - `Optional description` - A call to a custom tool created by the model. + A description of the function. Used by the model to determine whether or not to call the function. - - `class BetaResponseCustomToolCallOutputItem:` + - `Optional outputSchema` - The output of a custom tool call from your code, being sent back to the model. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `String id` + - `class BetaFileSearchTool:` - The unique ID of the custom tool call output item. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `Status status` + - `JsonValue; type "file_search"constant` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the file search tool. Always `file_search`. - - `IN_PROGRESS("in_progress")` + - `FILE_SEARCH("file_search")` - - `COMPLETED("completed")` + - `List vectorStoreIds` - - `INCOMPLETE("incomplete")` + The IDs of the vector stores to search. - - `Optional createdBy` + - `Optional filters` - The identifier of the actor that created the item. + A filter to apply. - - `boolean parallelToolCalls` + - `class ComparisonFilter:` - Whether to allow the model to run tool calls in parallel. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `Optional temperature` + - `String key` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + The key to compare against the value. - - `ToolChoice toolChoice` + - `Type type` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `enum BetaToolChoiceOptions:` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Controls which (if any) tool is called by the model. + - `EQ("eq")` - `none` means the model will not call any tool and instead generates a message. + - `NE("ne")` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `GT("gt")` - `required` means the model must call one or more tools. + - `GTE("gte")` - - `NONE("none")` + - `LT("lt")` - - `AUTO("auto")` + - `LTE("lte")` - - `REQUIRED("required")` + - `IN("in")` - - `class BetaToolChoiceAllowed:` + - `NIN("nin")` - Constrains the tools available to the model to a pre-defined set. + - `Value value` - - `Mode mode` + The value to compare against the attribute key; supports string, number, or boolean types. - Constrains the tools available to the model to a pre-defined set. + - `String` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `double` - `required` requires the model to call one or more of the allowed tools. + - `boolean` - - `AUTO("auto")` + - `List` - - `REQUIRED("required")` + - `String` - - `List tools` + - `double` - A list of tool definitions that the model should be allowed to call. + - `class CompoundFilter:` - For the Responses API, the list of tool definitions might look like: + Combine multiple filters using `and` or `or`. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `List filters` - - `JsonValue; type "allowed_tools"constant` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Allowed tool configuration type. Always `allowed_tools`. + - `class ComparisonFilter:` - - `ALLOWED_TOOLS("allowed_tools")` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `class BetaToolChoiceTypes:` + - `String key` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + The key to compare against the value. - `Type type` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Allowed values are: + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `EQ("eq")` - - `FILE_SEARCH("file_search")` + - `NE("ne")` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `GT("gt")` - - `COMPUTER("computer")` + - `GTE("gte")` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `LT("lt")` - - `COMPUTER_USE("computer_use")` + - `LTE("lte")` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `IN("in")` - - `IMAGE_GENERATION("image_generation")` + - `NIN("nin")` - - `CODE_INTERPRETER("code_interpreter")` + - `Value value` - - `class BetaToolChoiceFunction:` + The value to compare against the attribute key; supports string, number, or boolean types. - Use this option to force the model to call a specific function. + - `String` - - `String name` + - `double` - The name of the function to call. + - `boolean` - - `JsonValue; type "function"constant` + - `List` - For function calling, the type is always `function`. + - `String` - - `FUNCTION("function")` + - `double` - - `class BetaToolChoiceMcp:` + - `JsonValue` - Use this option to force the model to call a specific tool on a remote MCP server. + - `Type type` - - `String serverLabel` + Type of operation: `and` or `or`. - The label of the MCP server to use. + - `AND("and")` - - `JsonValue; type "mcp"constant` + - `OR("or")` - For MCP tools, the type is always `mcp`. + - `Optional maxNumResults` - - `MCP("mcp")` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `Optional name` + - `Optional rankingOptions` - The name of the tool to call on the server. + Ranking options for search. - - `class BetaToolChoiceCustom:` + - `Optional hybridSearch` - Use this option to force the model to call a specific custom tool. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `String name` + - `double embeddingWeight` - The name of the custom tool to call. + The weight of the embedding in the reciprocal ranking fusion. - - `JsonValue; type "custom"constant` + - `double textWeight` - For custom tool calling, the type is always `custom`. + The weight of the text in the reciprocal ranking fusion. - - `CUSTOM("custom")` + - `Optional ranker` - - `JsonValue;` + The ranker to use for the file search. - - `JsonValue; type "programmatic_tool_calling"constant` + - `AUTO("auto")` - The tool to call. Always `programmatic_tool_calling`. + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional scoreThreshold` - - `class BetaToolChoiceApplyPatch:` + 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. - Forces the model to call the apply_patch tool when executing a tool call. + - `class BetaComputerTool:` - - `JsonValue; type "apply_patch"constant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The tool to call. Always `apply_patch`. + - `JsonValue; type "computer"constant` - - `APPLY_PATCH("apply_patch")` + The type of the computer tool. Always `computer`. - - `class BetaToolChoiceShell:` + - `COMPUTER("computer")` - Forces the model to call the shell tool when a tool call is required. + - `class BetaComputerUsePreviewTool:` - - `JsonValue; type "shell"constant` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The tool to call. Always `shell`. + - `long displayHeight` - - `SHELL("shell")` + The height of the computer display. - - `List tools` + - `long displayWidth` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The width of the computer display. - We support the following categories of tools: + - `Environment environment` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The type of computer environment to control. - - `class BetaFunctionTool:` + - `WINDOWS("windows")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `MAC("mac")` - - `class BetaFileSearchTool:` + - `LINUX("linux")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `UBUNTU("ubuntu")` - - `class BetaComputerTool:` + - `BROWSER("browser")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JsonValue; type "computer_use_preview"constant` - - `class BetaComputerUsePreviewTool:` + The type of the computer use tool. Always `computer_use_preview`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - `class BetaWebSearchTool:` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Mcp` - - - `CodeInterpreter` - - - `JsonValue;` - - - `ImageGeneration` + - `Type type` - - `JsonValue;` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `class BetaFunctionShellTool:` + - `WEB_SEARCH("web_search")` - A tool that allows the model to execute shell commands. + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `class BetaCustomTool:` + - `Optional filters` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Filters for the search. - - `class BetaNamespaceTool:` + - `Optional> allowedDomains` - Groups function/custom tools under a shared namespace. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `class BetaToolSearchTool:` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Hosted or BYOT tool search configuration for deferred tools. + - `Optional searchContextSize` - - `class BetaWebSearchPreviewTool:` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `LOW("low")` - - `class BetaApplyPatchTool:` + - `MEDIUM("medium")` - Allows the assistant to create, delete, or update files using unified diffs. + - `HIGH("high")` - - `Optional topP` + - `Optional userLocation` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The approximate location of the user. - We generally recommend altering this or `temperature` but not both. + - `Optional city` - - `Optional background` + Free text input for the city of the user, e.g. `San Francisco`. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `Optional country` - - `Optional completedAt` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `Optional region` - - `Optional conversation` + Free text input for the region of the user, e.g. `California`. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `Optional timezone` - - `String id` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique ID of the conversation that this response was associated with. + - `Optional type` - - `Optional maxOutputTokens` + The type of location approximation. Always `approximate`. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `APPROXIMATE("approximate")` - - `Optional maxToolCalls` + - `Mcp` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `String serverLabel` - - `Optional moderation` + A label for this MCP server, used to identify it in tool calls. - Moderation results for the response input and output, if moderated completions were requested. + - `JsonValue; type "mcp"constant` - - `Input input` + The type of the MCP tool. Always `mcp`. - Moderation for the response input. + - `MCP("mcp")` - - `class ModerationResult:` + - `Optional> allowedCallers` - A moderation result produced for the response input or output. + The tool invocation context(s). - - `Categories categories` + - `DIRECT("direct")` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `PROGRAMMATIC("programmatic")` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `Optional allowedTools` - Which modalities of input are reflected by the score for each category. + List of allowed tool names or a filter object. - - `TEXT("text")` + - `List` - - `IMAGE("image")` + - `class McpToolFilter:` - - `CategoryScores categoryScores` + A filter object to specify which tools are allowed. - A dictionary of moderation categories to scores. + - `Optional readOnly` - - `boolean flagged` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A boolean indicating whether the content was flagged by any category. + - `Optional> toolNames` - - `String model` + List of allowed tool names. - The moderation model that produced this result. + - `Optional authorization` - - `JsonValue; type "moderation_result"constant` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The object type, which was always `moderation_result` for successful moderation results. + - `Optional connectorId` - - `MODERATION_RESULT("moderation_result")` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `class Error:` + Currently supported `connector_id` values are: - An error produced while attempting moderation for the response input or output. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `String code` + - `CONNECTOR_DROPBOX("connector_dropbox")` - The error code. + - `CONNECTOR_GMAIL("connector_gmail")` - - `String message` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - The error message. + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `JsonValue; type "error"constant` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - The object type, which was always `error` for moderation failures. + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - - `ERROR("error")` + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `Output output` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - Moderation for the response output. + - `Optional deferLoading` - - `class ModerationResult:` + Whether this MCP tool is deferred and discovered via tool search. - A moderation result produced for the response input or output. + - `Optional headers` - - `Categories categories` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `Optional requireApproval` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + Specify which of the MCP server's tools require approval. - Which modalities of input are reflected by the score for each category. + - `class McpToolApprovalFilter:` - - `TEXT("text")` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `IMAGE("image")` + - `Optional always` - - `CategoryScores categoryScores` + A filter object to specify which tools are allowed. - A dictionary of moderation categories to scores. + - `Optional readOnly` - - `boolean flagged` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A boolean indicating whether the content was flagged by any category. + - `Optional> toolNames` - - `String model` + List of allowed tool names. - The moderation model that produced this result. + - `Optional never` - - `JsonValue; type "moderation_result"constant` + A filter object to specify which tools are allowed. - The object type, which was always `moderation_result` for successful moderation results. + - `Optional readOnly` - - `MODERATION_RESULT("moderation_result")` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `class Error:` + - `Optional> toolNames` - An error produced while attempting moderation for the response input or output. + List of allowed tool names. - - `String code` + - `enum McpToolApprovalSetting:` - The error code. + 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. - - `String message` + - `ALWAYS("always")` - The error message. + - `NEVER("never")` - - `JsonValue; type "error"constant` + - `Optional serverDescription` - The object type, which was always `error` for moderation failures. + Optional description of the MCP server, used to provide more context. - - `ERROR("error")` + - `Optional serverUrl` - - `Optional previousResponseId` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `Optional tunnelId` - - `Optional prompt` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `CodeInterpreter` - - `String id` + - `Container container` - The unique identifier of the prompt template to use. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `Optional variables` + - `String` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `class CodeInterpreterToolAuto:` - - `String` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `class BetaResponseInputText:` + - `JsonValue; type "auto"constant` - A text input to the model. + Always `auto`. - - `class BetaResponseInputImage:` + - `AUTO("auto")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Optional> fileIds` - - `class BetaResponseInputFile:` + An optional list of uploaded files to make available to your code. - A file input to the model. + - `Optional memoryLimit` - - `Optional version` + The memory limit for the code interpreter container. - Optional version of the prompt template. + - `_1G("1g")` - - `Optional promptCacheKey` + - `_4G("4g")` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `_16G("16g")` - - `Optional promptCacheOptions` + - `_64G("64g")` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `Optional networkPolicy` - - `Mode mode` + Network access policy for the container. - Whether implicit prompt-cache breakpoints were enabled. + - `class BetaContainerNetworkPolicyDisabled:` - - `IMPLICIT("implicit")` + - `JsonValue; type "disabled"constant` - - `EXPLICIT("explicit")` + Disable outbound network access. Always `disabled`. - - `Ttl ttl` + - `DISABLED("disabled")` - The minimum lifetime applied to each cache breakpoint. + - `class BetaContainerNetworkPolicyAllowlist:` - - `_30M("30m")` + - `List allowedDomains` - - `Optional promptCacheRetention` + A list of allowed domains when type is `allowlist`. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `JsonValue; type "allowlist"constant` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + Allow outbound network access only to specified domains. Always `allowlist`. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `ALLOWLIST("allowlist")` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `Optional> domainSecrets` - - `IN_MEMORY("in_memory")` + Optional domain-scoped secrets for allowlisted domains. - - `_24H("24h")` + - `String domain` - - `Optional reasoning` + The domain associated with the secret. - **gpt-5 and o-series models only** + - `String name` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The name of the secret to inject for the domain. - - `Optional context` + - `String value` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The secret value to inject for the domain. - - `AUTO("auto")` + - `JsonValue; type "code_interpreter"constant` - - `CURRENT_TURN("current_turn")` + The type of the code interpreter tool. Always `code_interpreter`. - - `ALL_TURNS("all_turns")` + - `CODE_INTERPRETER("code_interpreter")` - - `Optional effort` + - `Optional> allowedCallers` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The tool invocation context(s). - - `NONE("none")` + - `DIRECT("direct")` - - `MINIMAL("minimal")` + - `PROGRAMMATIC("programmatic")` - - `LOW("low")` + - `JsonValue;` - - `MEDIUM("medium")` + - `JsonValue; type "programmatic_tool_calling"constant` - - `HIGH("high")` + The type of the tool. Always `programmatic_tool_calling`. - - `XHIGH("xhigh")` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `MAX("max")` + - `ImageGeneration` - - `Optional generateSummary` + - `JsonValue; type "image_generation"constant` - **Deprecated:** use `summary` instead. + The type of the image generation tool. Always `image_generation`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `IMAGE_GENERATION("image_generation")` - - `AUTO("auto")` + - `Optional action` - - `CONCISE("concise")` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `DETAILED("detailed")` + - `GENERATE("generate")` - - `Optional mode` + - `EDIT("edit")` - Controls the reasoning execution mode for the request. + - `AUTO("auto")` - When returned on a response, this is the effective execution mode. + - `Optional background` - - `STANDARD("standard")` + 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. - - `PRO("pro")` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `Optional summary` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `TRANSPARENT("transparent")` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `OPAQUE("opaque")` - `AUTO("auto")` - - `CONCISE("concise")` - - - `DETAILED("detailed")` + - `Optional inputFidelity` - - `Optional safetyIdentifier` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `HIGH("high")` - - `Optional serviceTier` + - `LOW("low")` - Specifies the processing type used for serving the request. + - `Optional inputImageMask` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `Optional fileId` - - `AUTO("auto")` + File ID for the mask image. - - `DEFAULT("default")` + - `Optional imageUrl` - - `FLEX("flex")` + Base64-encoded mask image. - - `SCALE("scale")` + - `Optional model` - - `PRIORITY("priority")` + The image generation model to use. Default: `gpt-image-1`. - - `Optional status` + - `GPT_IMAGE_1("gpt-image-1")` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `COMPLETED("completed")` + - `GPT_IMAGE_2("gpt-image-2")` - - `FAILED("failed")` + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `IN_PROGRESS("in_progress")` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - - `CANCELLED("cancelled")` + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `QUEUED("queued")` + - `Optional moderation` - - `INCOMPLETE("incomplete")` + Moderation level for the generated image. Default: `auto`. - - `Optional text` + - `AUTO("auto")` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `LOW("low")` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `Optional outputCompression` - - `Optional format` + Compression level for the output image. Default: 100. - An object specifying the format that the model must output. + - `Optional outputFormat` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The default format is `{ "type": "text" }` with no additional options. + - `PNG("png")` - **Not recommended for gpt-4o and newer models:** + - `WEBP("webp")` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `JPEG("jpeg")` - - `JsonValue;` + - `Optional partialImages` - - `JsonValue; type "text"constant` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of response format being defined. Always `text`. + - `Optional quality` - - `TEXT("text")` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `LOW("low")` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `MEDIUM("medium")` - - `String name` + - `HIGH("high")` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `AUTO("auto")` - - `Schema schema` + - `Optional size` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow 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; type "json_schema"constant` + - `_1024X1024("1024x1024")` - The type of response format being defined. Always `json_schema`. + - `_1024X1536("1024x1536")` - - `JSON_SCHEMA("json_schema")` + - `_1536X1024("1536x1024")` - - `Optional description` + - `AUTO("auto")` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `JsonValue;` - - `Optional strict` + - `JsonValue; type "local_shell"constant` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The type of the local shell tool. Always `local_shell`. - - `JsonValue;` + - `LOCAL_SHELL("local_shell")` - - `JsonValue; type "json_object"constant` + - `class BetaFunctionShellTool:` - The type of response format being defined. Always `json_object`. + A tool that allows the model to execute shell commands. - - `JSON_OBJECT("json_object")` + - `JsonValue; type "shell"constant` - - `Optional verbosity` + The type of the shell tool. Always `shell`. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `SHELL("shell")` - - `LOW("low")` + - `Optional> allowedCallers` - - `MEDIUM("medium")` + The tool invocation context(s). - - `HIGH("high")` + - `DIRECT("direct")` - - `Optional topLogprobs` + - `PROGRAMMATIC("programmatic")` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `Optional environment` - - `Optional truncation` + - `class BetaContainerAuto:` - The truncation strategy to use for the model response. + - `JsonValue; type "container_auto"constant` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + Automatically creates a container for this request - - `AUTO("auto")` + - `CONTAINER_AUTO("container_auto")` - - `DISABLED("disabled")` + - `Optional> fileIds` - - `Optional usage` + An optional list of uploaded files to make available to your code. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `Optional memoryLimit` - - `long inputTokens` + The memory limit for the container. - The number of input tokens. + - `_1G("1g")` - - `InputTokensDetails inputTokensDetails` + - `_4G("4g")` - A detailed breakdown of the input tokens. + - `_16G("16g")` - - `long cacheWriteTokens` + - `_64G("64g")` - The number of input tokens that were written to the cache. + - `Optional networkPolicy` - - `long cachedTokens` + Network access policy for the container. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `class BetaContainerNetworkPolicyDisabled:` - - `long outputTokens` + - `class BetaContainerNetworkPolicyAllowlist:` - The number of output tokens. + - `Optional> skills` - - `OutputTokensDetails outputTokensDetails` + An optional list of skills referenced by id or inline data. - A detailed breakdown of the output tokens. + - `class BetaSkillReference:` - - `long reasoningTokens` + - `String skillId` - The number of reasoning tokens. + The ID of the referenced skill. - - `long totalTokens` + - `JsonValue; type "skill_reference"constant` - The total number of tokens used. + References a skill created with the /v1/skills endpoint. - - `Optional user` + - `SKILL_REFERENCE("skill_reference")` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `Optional version` - - `long sequenceNumber` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The sequence number for this event. + - `class BetaInlineSkill:` - - `JsonValue; type "response.completed"constant` + - `String description` - The type of the event. Always `response.completed`. + The description of the skill. - - `RESPONSE_COMPLETED("response.completed")` + - `String name` - - `Optional agent` + The name of the skill. - The agent that owns this multi-agent streaming event. + - `BetaInlineSkillSource source` - - `String agentName` + Inline skill payload - The canonical name of the agent that produced this item. + - `String data` - - `class BetaResponseContentPartAddedEvent:` + Base64-encoded skill zip bundle. - Emitted when a new content part is added. + - `JsonValue; mediaType "application/zip"constant` - - `long contentIndex` + The media type of the inline skill payload. Must be `application/zip`. - The index of the content part that was added. + - `APPLICATION_ZIP("application/zip")` - - `String itemId` + - `JsonValue; type "base64"constant` - The ID of the output item that the content part was added to. + The type of the inline skill source. Must be `base64`. - - `long outputIndex` + - `BASE64("base64")` - The index of the output item that the content part was added to. + - `JsonValue; type "inline"constant` - - `Part part` + Defines an inline skill for this request. - The content part that was added. + - `INLINE("inline")` - - `class BetaResponseOutputText:` + - `class BetaLocalEnvironment:` - A text output from the model. + - `JsonValue; type "local"constant` - - `class BetaResponseOutputRefusal:` + Use a local computer environment. - A refusal from the model. + - `LOCAL("local")` - - `class ReasoningText:` + - `Optional> skills` - Reasoning text from the model. + An optional list of skills. - - `String text` + - `String description` - The reasoning text from the model. + The description of the skill. - - `JsonValue; type "reasoning_text"constant` + - `String name` - The type of the reasoning text. Always `reasoning_text`. + The name of the skill. - - `REASONING_TEXT("reasoning_text")` + - `String path` - - `long sequenceNumber` + The path to the directory containing the skill. - The sequence number of this event. + - `class BetaContainerReference:` - - `JsonValue; type "response.content_part.added"constant` + - `String containerId` - The type of the event. Always `response.content_part.added`. + The ID of the referenced container. - - `RESPONSE_CONTENT_PART_ADDED("response.content_part.added")` + - `JsonValue; type "container_reference"constant` - - `Optional agent` + References a container created with the /v1/containers endpoint - The agent that owns this multi-agent streaming event. + - `CONTAINER_REFERENCE("container_reference")` - - `String agentName` + - `class BetaCustomTool:` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `class BetaResponseContentPartDoneEvent:` + - `String name` - Emitted when a content part is done. + The name of the custom tool, used to identify it in tool calls. - - `long contentIndex` + - `JsonValue; type "custom"constant` - The index of the content part that is done. + The type of the custom tool. Always `custom`. - - `String itemId` + - `CUSTOM("custom")` - The ID of the output item that the content part was added to. + - `Optional> allowedCallers` - - `long outputIndex` + The tool invocation context(s). - The index of the output item that the content part was added to. + - `DIRECT("direct")` - - `Part part` + - `PROGRAMMATIC("programmatic")` - The content part that is done. + - `Optional deferLoading` - - `class BetaResponseOutputText:` + Whether this tool should be deferred and discovered via tool search. - A text output from the model. + - `Optional description` - - `class BetaResponseOutputRefusal:` + Optional description of the custom tool, used to provide more context. - A refusal from the model. + - `Optional format` - - `class ReasoningText:` + The input format for the custom tool. Default is unconstrained text. - Reasoning text from the model. + - `JsonValue;` - - `String text` + - `JsonValue; type "text"constant` - The reasoning text from the model. + Unconstrained text format. Always `text`. - - `JsonValue; type "reasoning_text"constant` + - `TEXT("text")` - The type of the reasoning text. Always `reasoning_text`. + - `class Grammar:` - - `REASONING_TEXT("reasoning_text")` + A grammar defined by the user. - - `long sequenceNumber` + - `String definition` - The sequence number of this event. + The grammar definition. - - `JsonValue; type "response.content_part.done"constant` + - `Syntax syntax` - The type of the event. Always `response.content_part.done`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `RESPONSE_CONTENT_PART_DONE("response.content_part.done")` + - `LARK("lark")` - - `Optional agent` + - `REGEX("regex")` - The agent that owns this multi-agent streaming event. + - `JsonValue; type "grammar"constant` - - `String agentName` + Grammar format. Always `grammar`. - The canonical name of the agent that produced this item. + - `GRAMMAR("grammar")` - - `class BetaResponseCreatedEvent:` + - `class BetaNamespaceTool:` - An event that is emitted when a response is created. + Groups function/custom tools under a shared namespace. - - `BetaResponse response` + - `String description` - The response that was created. + A description of the namespace shown to the model. - - `long sequenceNumber` + - `String name` - The sequence number for this event. + The namespace name used in tool calls (for example, `crm`). - - `JsonValue; type "response.created"constant` + - `List tools` - The type of the event. Always `response.created`. + The function/custom tools available inside this namespace. - - `RESPONSE_CREATED("response.created")` + - `class Function:` - - `Optional agent` + - `String name` - The agent that owns this multi-agent streaming event. + - `JsonValue; type "function"constant` - - `String agentName` + - `FUNCTION("function")` - The canonical name of the agent that produced this item. + - `Optional> allowedCallers` - - `class BetaResponseErrorEvent:` + The tool invocation context(s). - Emitted when an error occurs. + - `DIRECT("direct")` - - `Optional code` + - `PROGRAMMATIC("programmatic")` - The error code. + - `Optional deferLoading` - - `String message` + Whether this function should be deferred and discovered via tool search. - The error message. + - `Optional description` - - `Optional param` + - `Optional outputSchema` - The error parameter. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `long sequenceNumber` + - `Optional parameters` - The sequence number of this event. + - `Optional strict` - - `JsonValue; type "error"constant` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - The type of the event. Always `error`. + - `class BetaCustomTool:` - - `ERROR("error")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional agent` + - `JsonValue; type "namespace"constant` - The agent that owns this multi-agent streaming event. + The type of the tool. Always `namespace`. - - `String agentName` + - `NAMESPACE("namespace")` - The canonical name of the agent that produced this item. + - `class BetaToolSearchTool:` - - `class BetaResponseFileSearchCallCompletedEvent:` + Hosted or BYOT tool search configuration for deferred tools. - Emitted when a file search call is completed (results found). + - `JsonValue; type "tool_search"constant` - - `String itemId` + The type of the tool. Always `tool_search`. - The ID of the output item that the file search call is initiated. + - `TOOL_SEARCH("tool_search")` - - `long outputIndex` + - `Optional description` - The index of the output item that the file search call is initiated. + Description shown to the model for a client-executed tool search tool. - - `long sequenceNumber` + - `Optional execution` - The sequence number of this event. + Whether tool search is executed by the server or by the client. - - `JsonValue; type "response.file_search_call.completed"constant` + - `SERVER("server")` - The type of the event. Always `response.file_search_call.completed`. + - `CLIENT("client")` - - `RESPONSE_FILE_SEARCH_CALL_COMPLETED("response.file_search_call.completed")` + - `Optional parameters` - - `Optional agent` + Parameter schema for a client-executed tool search tool. - The agent that owns this multi-agent streaming event. + - `class BetaWebSearchPreviewTool:` - - `String agentName` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The canonical name of the agent that produced this item. + - `Type type` - - `class BetaResponseFileSearchCallInProgressEvent:` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Emitted when a file search call is initiated. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `String itemId` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - The ID of the output item that the file search call is initiated. + - `Optional> searchContentTypes` - - `long outputIndex` + - `TEXT("text")` - The index of the output item that the file search call is initiated. + - `IMAGE("image")` - - `long sequenceNumber` + - `Optional searchContextSize` - The sequence number of this event. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `JsonValue; type "response.file_search_call.in_progress"constant` + - `LOW("low")` - The type of the event. Always `response.file_search_call.in_progress`. + - `MEDIUM("medium")` - - `RESPONSE_FILE_SEARCH_CALL_IN_PROGRESS("response.file_search_call.in_progress")` + - `HIGH("high")` - - `Optional agent` + - `Optional userLocation` - The agent that owns this multi-agent streaming event. + The user's location. - - `String agentName` + - `JsonValue; type "approximate"constant` - The canonical name of the agent that produced this item. + The type of location approximation. Always `approximate`. - - `class BetaResponseFileSearchCallSearchingEvent:` + - `APPROXIMATE("approximate")` - Emitted when a file search is currently searching. + - `Optional city` - - `String itemId` + Free text input for the city of the user, e.g. `San Francisco`. - The ID of the output item that the file search call is initiated. + - `Optional country` - - `long outputIndex` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The index of the output item that the file search call is searching. + - `Optional region` - - `long sequenceNumber` + Free text input for the region of the user, e.g. `California`. - The sequence number of this event. + - `Optional timezone` - - `JsonValue; type "response.file_search_call.searching"constant` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the event. Always `response.file_search_call.searching`. + - `class BetaApplyPatchTool:` - - `RESPONSE_FILE_SEARCH_CALL_SEARCHING("response.file_search_call.searching")` + Allows the assistant to create, delete, or update files using unified diffs. - - `Optional agent` + - `JsonValue; type "apply_patch"constant` - The agent that owns this multi-agent streaming event. + The type of the tool. Always `apply_patch`. - - `String agentName` + - `APPLY_PATCH("apply_patch")` - The canonical name of the agent that produced this item. + - `Optional> allowedCallers` - - `class BetaResponseFunctionCallArgumentsDeltaEvent:` + The tool invocation context(s). - Emitted when there is a partial function-call arguments delta. + - `DIRECT("direct")` - - `String delta` + - `PROGRAMMATIC("programmatic")` - The function-call arguments delta that is added. +### Beta Tool Choice Allowed - - `String itemId` +- `class BetaToolChoiceAllowed:` - The ID of the output item that the function-call arguments delta is added to. + Constrains the tools available to the model to a pre-defined set. - - `long outputIndex` + - `Mode mode` - The index of the output item that the function-call arguments delta is added to. + Constrains the tools available to the model to a pre-defined set. - - `long sequenceNumber` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The sequence number of this event. + `required` requires the model to call one or more of the allowed tools. - - `JsonValue; type "response.function_call_arguments.delta"constant` + - `AUTO("auto")` - The type of the event. Always `response.function_call_arguments.delta`. + - `REQUIRED("required")` - - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DELTA("response.function_call_arguments.delta")` + - `List tools` - - `Optional agent` + A list of tool definitions that the model should be allowed to call. - The agent that owns this multi-agent streaming event. + For the Responses API, the list of tool definitions might look like: - - `String agentName` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The canonical name of the agent that produced this item. + - `JsonValue; type "allowed_tools"constant` - - `class BetaResponseFunctionCallArgumentsDoneEvent:` + Allowed tool configuration type. Always `allowed_tools`. - Emitted when function-call arguments are finalized. + - `ALLOWED_TOOLS("allowed_tools")` - - `String arguments` +### Beta Tool Choice Apply Patch - The function-call arguments. +- `class BetaToolChoiceApplyPatch:` - - `String itemId` + Forces the model to call the apply_patch tool when executing a tool call. - The ID of the item. + - `JsonValue; type "apply_patch"constant` - - `String name` + The tool to call. Always `apply_patch`. - The name of the function that was called. + - `APPLY_PATCH("apply_patch")` - - `long outputIndex` +### Beta Tool Choice Custom - The index of the output item. +- `class BetaToolChoiceCustom:` - - `long sequenceNumber` + Use this option to force the model to call a specific custom tool. - The sequence number of this event. + - `String name` - - `JsonValue; type "response.function_call_arguments.done"constant` + The name of the custom tool to call. - - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DONE("response.function_call_arguments.done")` + - `JsonValue; type "custom"constant` - - `Optional agent` + For custom tool calling, the type is always `custom`. - The agent that owns this multi-agent streaming event. + - `CUSTOM("custom")` - - `String agentName` +### Beta Tool Choice Function - The canonical name of the agent that produced this item. +- `class BetaToolChoiceFunction:` - - `class BetaResponseInProgressEvent:` + Use this option to force the model to call a specific function. - Emitted when the response is in progress. + - `String name` - - `BetaResponse response` + The name of the function to call. - The response that is in progress. + - `JsonValue; type "function"constant` - - `long sequenceNumber` + For function calling, the type is always `function`. - The sequence number of this event. + - `FUNCTION("function")` - - `JsonValue; type "response.in_progress"constant` +### Beta Tool Choice Mcp - The type of the event. Always `response.in_progress`. +- `class BetaToolChoiceMcp:` - - `RESPONSE_IN_PROGRESS("response.in_progress")` + Use this option to force the model to call a specific tool on a remote MCP server. - - `Optional agent` + - `String serverLabel` - The agent that owns this multi-agent streaming event. + The label of the MCP server to use. - - `String agentName` + - `JsonValue; type "mcp"constant` - The canonical name of the agent that produced this item. + For MCP tools, the type is always `mcp`. - - `class BetaResponseFailedEvent:` + - `MCP("mcp")` - An event that is emitted when a response fails. + - `Optional name` - - `BetaResponse response` + The name of the tool to call on the server. - The response that failed. +### Beta Tool Choice Options - - `long sequenceNumber` +- `enum BetaToolChoiceOptions:` - The sequence number of this event. + Controls which (if any) tool is called by the model. - - `JsonValue; type "response.failed"constant` + `none` means the model will not call any tool and instead generates a message. - The type of the event. Always `response.failed`. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `RESPONSE_FAILED("response.failed")` + `required` means the model must call one or more tools. - - `Optional agent` + - `NONE("none")` - The agent that owns this multi-agent streaming event. + - `AUTO("auto")` - - `String agentName` + - `REQUIRED("required")` - The canonical name of the agent that produced this item. +### Beta Tool Choice Shell - - `class BetaResponseIncompleteEvent:` +- `class BetaToolChoiceShell:` - An event that is emitted when a response finishes as incomplete. + Forces the model to call the shell tool when a tool call is required. - - `BetaResponse response` + - `JsonValue; type "shell"constant` - The response that was incomplete. + The tool to call. Always `shell`. - - `long sequenceNumber` + - `SHELL("shell")` - The sequence number of this event. +### Beta Tool Choice Types - - `JsonValue; type "response.incomplete"constant` +- `class BetaToolChoiceTypes:` - The type of the event. Always `response.incomplete`. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `RESPONSE_INCOMPLETE("response.incomplete")` + - `Type type` - - `Optional agent` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The agent that owns this multi-agent streaming event. + Allowed values are: - - `String agentName` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The canonical name of the agent that produced this item. + - `FILE_SEARCH("file_search")` - - `class BetaResponseOutputItemAddedEvent:` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - Emitted when a new output item is added. + - `COMPUTER("computer")` - - `BetaResponseOutputItem item` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - The output item that was added. + - `COMPUTER_USE("computer_use")` - - `class BetaResponseOutputMessage:` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - An output message from the model. + - `IMAGE_GENERATION("image_generation")` - - `class BetaResponseFileSearchToolCall:` + - `CODE_INTERPRETER("code_interpreter")` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. +### Beta Tool Search Tool - - `class BetaResponseFunctionToolCall:` +- `class BetaToolSearchTool:` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Hosted or BYOT tool search configuration for deferred tools. - - `class BetaResponseFunctionToolCallOutputItem:` + - `JsonValue; type "tool_search"constant` - - `AgentMessage` + The type of the tool. Always `tool_search`. - - `MultiAgentCall` + - `TOOL_SEARCH("tool_search")` - - `MultiAgentCallOutput` + - `Optional description` - - `class BetaResponseFunctionWebSearch:` + Description shown to the model for a client-executed tool search tool. - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Optional execution` - - `class BetaResponseComputerToolCall:` + Whether tool search is executed by the server or by the client. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `SERVER("server")` - - `class BetaResponseComputerToolCallOutputItem:` + - `CLIENT("client")` - - `class BetaResponseReasoningItem:` + - `Optional parameters` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Parameter schema for a client-executed tool search tool. - - `Program` +### Beta Web Search Preview Tool - - `ProgramOutput` +- `class BetaWebSearchPreviewTool:` - - `class BetaResponseToolSearchCall:` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `class BetaResponseToolSearchOutputItem:` + - `Type type` - - `AdditionalTools` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `class BetaResponseCompactionItem:` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `ImageGenerationCall` + - `Optional> searchContentTypes` - - `class BetaResponseCodeInterpreterToolCall:` + - `TEXT("text")` - A tool call to run code. + - `IMAGE("image")` - - `LocalShellCall` + - `Optional searchContextSize` - - `LocalShellCallOutput` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `class BetaResponseFunctionShellToolCall:` + - `LOW("low")` - A tool call that executes one or more shell commands in a managed environment. + - `MEDIUM("medium")` - - `class BetaResponseFunctionShellToolCallOutput:` + - `HIGH("high")` - The output of a shell tool call that was emitted. + - `Optional userLocation` - - `class BetaResponseApplyPatchToolCall:` + The user's location. - A tool call that applies file diffs by creating, deleting, or updating files. + - `JsonValue; type "approximate"constant` - - `class BetaResponseApplyPatchToolCallOutput:` + The type of location approximation. Always `approximate`. - The output emitted by an apply patch tool call. + - `APPROXIMATE("approximate")` - - `McpCall` + - `Optional city` - - `McpListTools` + Free text input for the city of the user, e.g. `San Francisco`. - - `McpApprovalRequest` + - `Optional country` - - `McpApprovalResponse` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `class BetaResponseCustomToolCall:` + - `Optional region` - A call to a custom tool created by the model. + Free text input for the region of the user, e.g. `California`. - - `class BetaResponseCustomToolCallOutputItem:` + - `Optional timezone` - The output of a custom tool call from your code, being sent back to the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `long outputIndex` +### Beta Web Search Tool - The index of the output item that was added. +- `class BetaWebSearchTool:` - - `long sequenceNumber` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The sequence number of this event. + - `Type type` - - `JsonValue; type "response.output_item.added"constant` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The type of the event. Always `response.output_item.added`. + - `WEB_SEARCH("web_search")` - - `RESPONSE_OUTPUT_ITEM_ADDED("response.output_item.added")` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - - `Optional agent` + - `Optional filters` - The agent that owns this multi-agent streaming event. + Filters for the search. - - `String agentName` + - `Optional> allowedDomains` - The canonical name of the agent that produced this item. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `class BetaResponseOutputItemDoneEvent:` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Emitted when an output item is marked done. + - `Optional searchContextSize` - - `BetaResponseOutputItem item` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The output item that was marked done. + - `LOW("low")` - - `long outputIndex` + - `MEDIUM("medium")` - The index of the output item that was marked done. + - `HIGH("high")` - - `long sequenceNumber` + - `Optional userLocation` - The sequence number of this event. + The approximate location of the user. - - `JsonValue; type "response.output_item.done"constant` + - `Optional city` - The type of the event. Always `response.output_item.done`. + Free text input for the city of the user, e.g. `San Francisco`. - - `RESPONSE_OUTPUT_ITEM_DONE("response.output_item.done")` + - `Optional country` - - `Optional agent` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The agent that owns this multi-agent streaming event. + - `Optional region` - - `String agentName` + Free text input for the region of the user, e.g. `California`. - The canonical name of the agent that produced this item. + - `Optional timezone` - - `class BetaResponseReasoningSummaryPartAddedEvent:` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Emitted when a new reasoning summary part is added. + - `Optional type` - - `String itemId` + The type of location approximation. Always `approximate`. - The ID of the item this summary part is associated with. + - `APPROXIMATE("approximate")` - - `long outputIndex` +# Input Items - The index of the output item this summary part is associated with. +## List input items - - `Part part` +`InputItemListPage beta().responses().inputItems().list(InputItemListParamsparams = InputItemListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - The summary part that was added. +**get** `/responses/{response_id}/input_items?beta=true` - - `String text` +Returns a list of input items for a given response. - The text of the summary part. +### Parameters - - `JsonValue; type "summary_text"constant` +- `InputItemListParams params` - The type of the summary part. Always `summary_text`. + - `Optional responseId` - - `SUMMARY_TEXT("summary_text")` + - `Optional after` - - `long sequenceNumber` + An item ID to list items after, used in pagination. - The sequence number of this event. + - `Optional> include` - - `long summaryIndex` + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - The index of the summary part within the reasoning summary. + - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` - - `JsonValue; type "response.reasoning_summary_part.added"constant` + - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` - The type of the event. Always `response.reasoning_summary_part.added`. + - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` - - `RESPONSE_REASONING_SUMMARY_PART_ADDED("response.reasoning_summary_part.added")` + - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` - - `Optional agent` + - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` - The agent that owns this multi-agent streaming event. + - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` - - `String agentName` + - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` - The canonical name of the agent that produced this item. + - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` - - `class BetaResponseReasoningSummaryPartDoneEvent:` + - `Optional limit` - Emitted when a reasoning summary part is completed. + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. - - `String itemId` + - `Optional order` - The ID of the item this summary part is associated with. + The order to return the input items in. Default is `desc`. - - `long outputIndex` + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. - The index of the output item this summary part is associated with. + - `ASC("asc")` - - `Part part` + - `DESC("desc")` - The completed summary part. + - `Optional> betas` - - `String text` + - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` - The text of the summary part. +### Returns - - `JsonValue; type "summary_text"constant` +- `class BetaResponseItem: A class that can be one of several variants.union` - The type of the summary part. Always `summary_text`. + Content item used to generate a response. - - `SUMMARY_TEXT("summary_text")` + - `class BetaResponseInputMessageItem:` - - `long sequenceNumber` + - `String id` - The sequence number of this event. + The unique ID of the message input. - - `long summaryIndex` + - `List content` - The index of the summary part within the reasoning summary. + A list of one or many input items to the model, containing different content + types. - - `JsonValue; type "response.reasoning_summary_part.done"constant` + - `class BetaResponseInputText:` - The type of the event. Always `response.reasoning_summary_part.done`. + A text input to the model. - - `RESPONSE_REASONING_SUMMARY_PART_DONE("response.reasoning_summary_part.done")` + - `String text` - - `Optional agent` + The text input to the model. - The agent that owns this multi-agent streaming event. + - `JsonValue; type "input_text"constant` - - `String agentName` + The type of the input item. Always `input_text`. - The canonical name of the agent that produced this item. + - `INPUT_TEXT("input_text")` - - `Optional status` + - `Optional promptCacheBreakpoint` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `INCOMPLETE("incomplete")` + - `JsonValue; mode "explicit"constant` - - `class BetaResponseReasoningSummaryTextDeltaEvent:` + The breakpoint mode. Always `explicit`. - Emitted when a delta is added to a reasoning summary text. + - `EXPLICIT("explicit")` - - `String delta` + - `class BetaResponseInputImage:` - The text delta that was added to the summary. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `String itemId` + - `Detail detail` - The ID of the item this summary text delta is associated with. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `long outputIndex` + - `LOW("low")` - The index of the output item this summary text delta is associated with. + - `HIGH("high")` - - `long sequenceNumber` + - `AUTO("auto")` - The sequence number of this event. + - `ORIGINAL("original")` - - `long summaryIndex` + - `JsonValue; type "input_image"constant` - The index of the summary part within the reasoning summary. + The type of the input item. Always `input_image`. - - `JsonValue; type "response.reasoning_summary_text.delta"constant` + - `INPUT_IMAGE("input_image")` - The type of the event. Always `response.reasoning_summary_text.delta`. + - `Optional fileId` - - `RESPONSE_REASONING_SUMMARY_TEXT_DELTA("response.reasoning_summary_text.delta")` + The ID of the file to be sent to the model. - - `Optional agent` + - `Optional imageUrl` - The agent that owns this multi-agent streaming event. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `String agentName` + - `Optional promptCacheBreakpoint` - The canonical name of the agent that produced this item. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `class BetaResponseReasoningSummaryTextDoneEvent:` + - `JsonValue; mode "explicit"constant` - Emitted when a reasoning summary text is completed. + The breakpoint mode. Always `explicit`. - - `String itemId` + - `EXPLICIT("explicit")` - The ID of the item this summary text is associated with. + - `class BetaResponseInputFile:` - - `long outputIndex` + A file input to the model. - The index of the output item this summary text is associated with. + - `JsonValue; type "input_file"constant` - - `long sequenceNumber` + The type of the input item. Always `input_file`. - The sequence number of this event. + - `INPUT_FILE("input_file")` - - `long summaryIndex` + - `Optional detail` - The index of the summary part within the reasoning summary. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `String text` + - `AUTO("auto")` - The full text of the completed reasoning summary. + - `LOW("low")` - - `JsonValue; type "response.reasoning_summary_text.done"constant` + - `HIGH("high")` - The type of the event. Always `response.reasoning_summary_text.done`. + - `Optional fileData` - - `RESPONSE_REASONING_SUMMARY_TEXT_DONE("response.reasoning_summary_text.done")` + The content of the file to be sent to the model. - - `Optional agent` + - `Optional fileId` - The agent that owns this multi-agent streaming event. + The ID of the file to be sent to the model. - - `String agentName` + - `Optional fileUrl` - The canonical name of the agent that produced this item. + The URL of the file to be sent to the model. - - `class BetaResponseReasoningTextDeltaEvent:` + - `Optional filename` - Emitted when a delta is added to a reasoning text. + The name of the file to be sent to the model. - - `long contentIndex` + - `Optional promptCacheBreakpoint` - The index of the reasoning content part this delta is associated with. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String delta` + - `JsonValue; mode "explicit"constant` - The text delta that was added to the reasoning content. + The breakpoint mode. Always `explicit`. - - `String itemId` + - `EXPLICIT("explicit")` - The ID of the item this reasoning text delta is associated with. + - `Role role` - - `long outputIndex` + The role of the message input. One of `user`, `system`, or `developer`. - The index of the output item this reasoning text delta is associated with. + - `USER("user")` - - `long sequenceNumber` + - `SYSTEM("system")` - The sequence number of this event. + - `DEVELOPER("developer")` - - `JsonValue; type "response.reasoning_text.delta"constant` + - `JsonValue; type "message"constant` - The type of the event. Always `response.reasoning_text.delta`. + The type of the message input. Always set to `message`. - - `RESPONSE_REASONING_TEXT_DELTA("response.reasoning_text.delta")` + - `MESSAGE("message")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseReasoningTextDoneEvent:` + - `Optional status` - Emitted when a reasoning text is completed. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `long contentIndex` + - `IN_PROGRESS("in_progress")` - The index of the reasoning content part. + - `COMPLETED("completed")` - - `String itemId` + - `INCOMPLETE("incomplete")` - The ID of the item this reasoning text is associated with. + - `class BetaResponseOutputMessage:` - - `long outputIndex` + An output message from the model. - The index of the output item this reasoning text is associated with. + - `String id` - - `long sequenceNumber` + The unique ID of the output message. - The sequence number of this event. + - `List content` - - `String text` + The content of the output message. - The full text of the completed reasoning content. + - `class BetaResponseOutputText:` - - `JsonValue; type "response.reasoning_text.done"constant` + A text output from the model. - The type of the event. Always `response.reasoning_text.done`. + - `List annotations` - - `RESPONSE_REASONING_TEXT_DONE("response.reasoning_text.done")` + The annotations of the text output. - - `Optional agent` + - `class FileCitation:` - The agent that owns this multi-agent streaming event. + A citation to a file. - - `String agentName` + - `String fileId` - The canonical name of the agent that produced this item. + The ID of the file. - - `class BetaResponseRefusalDeltaEvent:` + - `String filename` - Emitted when there is a partial refusal text. + The filename of the file cited. - - `long contentIndex` + - `long index` - The index of the content part that the refusal text is added to. + The index of the file in the list of files. - - `String delta` + - `JsonValue; type "file_citation"constant` - The refusal text that is added. + The type of the file citation. Always `file_citation`. - - `String itemId` + - `FILE_CITATION("file_citation")` + + - `class UrlCitation:` + + A citation for a web resource used to generate a model response. - The ID of the output item that the refusal text is added to. + - `long endIndex` - - `long outputIndex` + The index of the last character of the URL citation in the message. - The index of the output item that the refusal text is added to. + - `long startIndex` - - `long sequenceNumber` + The index of the first character of the URL citation in the message. - The sequence number of this event. + - `String title` - - `JsonValue; type "response.refusal.delta"constant` + The title of the web resource. - The type of the event. Always `response.refusal.delta`. + - `JsonValue; type "url_citation"constant` - - `RESPONSE_REFUSAL_DELTA("response.refusal.delta")` + The type of the URL citation. Always `url_citation`. - - `Optional agent` + - `URL_CITATION("url_citation")` - The agent that owns this multi-agent streaming event. + - `String url` - - `String agentName` + The URL of the web resource. - The canonical name of the agent that produced this item. + - `class ContainerFileCitation:` - - `class BetaResponseRefusalDoneEvent:` + A citation for a container file used to generate a model response. - Emitted when refusal text is finalized. + - `String containerId` - - `long contentIndex` + The ID of the container file. - The index of the content part that the refusal text is finalized. + - `long endIndex` - - `String itemId` + The index of the last character of the container file citation in the message. - The ID of the output item that the refusal text is finalized. + - `String fileId` - - `long outputIndex` + The ID of the file. - The index of the output item that the refusal text is finalized. + - `String filename` - - `String refusal` + The filename of the container file cited. - The refusal text that is finalized. + - `long startIndex` - - `long sequenceNumber` + The index of the first character of the container file citation in the message. - The sequence number of this event. + - `JsonValue; type "container_file_citation"constant` - - `JsonValue; type "response.refusal.done"constant` + The type of the container file citation. Always `container_file_citation`. - The type of the event. Always `response.refusal.done`. + - `CONTAINER_FILE_CITATION("container_file_citation")` - - `RESPONSE_REFUSAL_DONE("response.refusal.done")` + - `class FilePath:` - - `Optional agent` + A path to a file. - The agent that owns this multi-agent streaming event. + - `String fileId` - - `String agentName` + The ID of the file. - The canonical name of the agent that produced this item. + - `long index` - - `class BetaResponseTextDeltaEvent:` + The index of the file in the list of files. - Emitted when there is an additional text delta. + - `JsonValue; type "file_path"constant` - - `long contentIndex` + The type of the file path. Always `file_path`. - The index of the content part that the text delta was added to. + - `FILE_PATH("file_path")` - - `String delta` + - `String text` - The text delta that was added. + The text output from the model. - - `String itemId` + - `JsonValue; type "output_text"constant` - The ID of the output item that the text delta was added to. + The type of the output text. Always `output_text`. - - `List logprobs` + - `OUTPUT_TEXT("output_text")` - The log probabilities of the tokens in the delta. + - `Optional> logprobs` - `String token` - A possible text token. + - `List bytes` - `double logprob` - The log probability of this token. + - `List topLogprobs` - - `Optional> topLogprobs` + - `String token` - The log probabilities of up to 20 of the most likely tokens. + - `List bytes` - - `Optional token` + - `double logprob` - A possible text token. + - `class BetaResponseOutputRefusal:` - - `Optional logprob` + A refusal from the model. - The log probability of this token. + - `String refusal` - - `long outputIndex` + The refusal explanation from the model. - The index of the output item that the text delta was added to. + - `JsonValue; type "refusal"constant` - - `long sequenceNumber` + The type of the refusal. Always `refusal`. - The sequence number for this event. + - `REFUSAL("refusal")` - - `JsonValue; type "response.output_text.delta"constant` + - `JsonValue; role "assistant"constant` - The type of the event. Always `response.output_text.delta`. + The role of the output message. Always `assistant`. - - `RESPONSE_OUTPUT_TEXT_DELTA("response.output_text.delta")` + - `ASSISTANT("assistant")` - - `Optional agent` + - `Status status` - The agent that owns this multi-agent streaming event. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `String agentName` + - `IN_PROGRESS("in_progress")` - The canonical name of the agent that produced this item. + - `COMPLETED("completed")` - - `class BetaResponseTextDoneEvent:` + - `INCOMPLETE("incomplete")` - Emitted when text content is finalized. + - `JsonValue; type "message"constant` - - `long contentIndex` + The type of the output message. Always `message`. - The index of the content part that the text content is finalized. + - `MESSAGE("message")` - - `String itemId` + - `Optional agent` - The ID of the output item that the text content is finalized. + The agent that produced this item. - - `List logprobs` + - `String agentName` - The log probabilities of the tokens in the delta. + The canonical name of the agent that produced this item. - - `String token` + - `Optional phase` - A possible text token. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `double logprob` + - `COMMENTARY("commentary")` - The log probability of this token. + - `FINAL_ANSWER("final_answer")` - - `Optional> topLogprobs` + - `class BetaResponseFileSearchToolCall:` - The log probabilities of up to 20 of the most likely tokens. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `Optional token` + - `String id` - A possible text token. + The unique ID of the file search tool call. - - `Optional logprob` + - `List queries` - The log probability of this token. + The queries used to search for files. - - `long outputIndex` + - `Status status` - The index of the output item that the text content is finalized. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `long sequenceNumber` + - `IN_PROGRESS("in_progress")` - The sequence number for this event. + - `SEARCHING("searching")` - - `String text` + - `COMPLETED("completed")` - The text content that is finalized. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "response.output_text.done"constant` + - `FAILED("failed")` - The type of the event. Always `response.output_text.done`. + - `JsonValue; type "file_search_call"constant` - - `RESPONSE_OUTPUT_TEXT_DONE("response.output_text.done")` + The type of the file search tool call. Always `file_search_call`. + + - `FILE_SEARCH_CALL("file_search_call")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseWebSearchCallCompletedEvent:` + - `Optional> results` - Emitted when a web search call is completed. + The results of the file search tool call. - - `String itemId` + - `Optional attributes` - Unique ID for the output item associated with the web search call. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `long outputIndex` + - `String` - The index of the output item that the web search call is associated with. + - `double` - - `long sequenceNumber` + - `boolean` - The sequence number of the web search call being processed. + - `Optional fileId` - - `JsonValue; type "response.web_search_call.completed"constant` + The unique ID of the file. - The type of the event. Always `response.web_search_call.completed`. + - `Optional filename` - - `RESPONSE_WEB_SEARCH_CALL_COMPLETED("response.web_search_call.completed")` + The name of the file. - - `Optional agent` + - `Optional score` - The agent that owns this multi-agent streaming event. + The relevance score of the file - a value between 0 and 1. - - `String agentName` + - `Optional text` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - - `class BetaResponseWebSearchCallInProgressEvent:` + - `class BetaResponseComputerToolCall:` - Emitted when a web search call is initiated. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `String itemId` + - `String id` - Unique ID for the output item associated with the web search call. + The unique ID of the computer call. - - `long outputIndex` + - `String callId` - The index of the output item that the web search call is associated with. + An identifier used when responding to the tool call with output. - - `long sequenceNumber` + - `List pendingSafetyChecks` - The sequence number of the web search call being processed. + The pending safety checks for the computer call. - - `JsonValue; type "response.web_search_call.in_progress"constant` + - `String id` - The type of the event. Always `response.web_search_call.in_progress`. + The ID of the pending safety check. - - `RESPONSE_WEB_SEARCH_CALL_IN_PROGRESS("response.web_search_call.in_progress")` + - `Optional code` - - `Optional agent` + The type of the pending safety check. - The agent that owns this multi-agent streaming event. + - `Optional message` - - `String agentName` + Details about the pending safety check. - The canonical name of the agent that produced this item. + - `Status status` - - `class BetaResponseWebSearchCallSearchingEvent:` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Emitted when a web search call is executing. + - `IN_PROGRESS("in_progress")` - - `String itemId` + - `COMPLETED("completed")` - Unique ID for the output item associated with the web search call. + - `INCOMPLETE("incomplete")` - - `long outputIndex` + - `Type type` - The index of the output item that the web search call is associated with. + The type of the computer call. Always `computer_call`. - - `long sequenceNumber` + - `COMPUTER_CALL("computer_call")` - The sequence number of the web search call being processed. + - `Optional action` - - `JsonValue; type "response.web_search_call.searching"constant` + A click action. - The type of the event. Always `response.web_search_call.searching`. + - `Click` - - `RESPONSE_WEB_SEARCH_CALL_SEARCHING("response.web_search_call.searching")` + - `Button button` - - `Optional agent` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The agent that owns this multi-agent streaming event. + - `LEFT("left")` - - `String agentName` + - `RIGHT("right")` - The canonical name of the agent that produced this item. + - `WHEEL("wheel")` - - `class BetaResponseImageGenCallCompletedEvent:` + - `BACK("back")` - Emitted when an image generation tool call has completed and the final image is available. + - `FORWARD("forward")` - - `String itemId` + - `JsonValue; type "click"constant` - The unique identifier of the image generation item being processed. + Specifies the event type. For a click action, this property is always `click`. - - `long outputIndex` + - `CLICK("click")` - The index of the output item in the response's output array. + - `long x` - - `long sequenceNumber` + The x-coordinate where the click occurred. - The sequence number of this event. + - `long y` - - `JsonValue; type "response.image_generation_call.completed"constant` + The y-coordinate where the click occurred. - The type of the event. Always 'response.image_generation_call.completed'. + - `Optional> keys` - - `RESPONSE_IMAGE_GENERATION_CALL_COMPLETED("response.image_generation_call.completed")` + The keys being held while clicking. - - `Optional agent` + - `DoubleClick` - The agent that owns this multi-agent streaming event. + - `Optional> keys` - - `String agentName` + The keys being held while double-clicking. - The canonical name of the agent that produced this item. + - `JsonValue; type "double_click"constant` - - `class BetaResponseImageGenCallGeneratingEvent:` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `DOUBLE_CLICK("double_click")` - - `String itemId` + - `long x` - The unique identifier of the image generation item being processed. + The x-coordinate where the double click occurred. - - `long outputIndex` + - `long y` - The index of the output item in the response's output array. + The y-coordinate where the double click occurred. - - `long sequenceNumber` + - `Drag` - The sequence number of the image generation item being processed. + - `List path` - - `JsonValue; type "response.image_generation_call.generating"constant` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The type of the event. Always 'response.image_generation_call.generating'. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `RESPONSE_IMAGE_GENERATION_CALL_GENERATING("response.image_generation_call.generating")` + - `long x` - - `Optional agent` + The x-coordinate. - The agent that owns this multi-agent streaming event. + - `long y` - - `String agentName` + The y-coordinate. - The canonical name of the agent that produced this item. + - `JsonValue; type "drag"constant` - - `class BetaResponseImageGenCallInProgressEvent:` + Specifies the event type. For a drag action, this property is always set to `drag`. - Emitted when an image generation tool call is in progress. + - `DRAG("drag")` - - `String itemId` + - `Optional> keys` - The unique identifier of the image generation item being processed. + The keys being held while dragging the mouse. - - `long outputIndex` + - `Keypress` - The index of the output item in the response's output array. + - `List keys` - - `long sequenceNumber` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The sequence number of the image generation item being processed. + - `JsonValue; type "keypress"constant` - - `JsonValue; type "response.image_generation_call.in_progress"constant` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `KEYPRESS("keypress")` - - `RESPONSE_IMAGE_GENERATION_CALL_IN_PROGRESS("response.image_generation_call.in_progress")` + - `Move` - - `Optional agent` + - `JsonValue; type "move"constant` - The agent that owns this multi-agent streaming event. + Specifies the event type. For a move action, this property is always set to `move`. - - `String agentName` + - `MOVE("move")` - The canonical name of the agent that produced this item. + - `long x` - - `class BetaResponseImageGenCallPartialImageEvent:` + The x-coordinate to move to. - Emitted when a partial image is available during image generation streaming. + - `long y` - - `String itemId` + The y-coordinate to move to. - The unique identifier of the image generation item being processed. + - `Optional> keys` - - `long outputIndex` + The keys being held while moving the mouse. - The index of the output item in the response's output array. + - `JsonValue;` - - `String partialImageB64` + - `JsonValue; type "screenshot"constant` - Base64-encoded partial image data, suitable for rendering as an image. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `long partialImageIndex` + - `SCREENSHOT("screenshot")` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `Scroll` - - `long sequenceNumber` + - `long scrollX` - The sequence number of the image generation item being processed. + The horizontal scroll distance. - - `JsonValue; type "response.image_generation_call.partial_image"constant` + - `long scrollY` - The type of the event. Always 'response.image_generation_call.partial_image'. + The vertical scroll distance. - - `RESPONSE_IMAGE_GENERATION_CALL_PARTIAL_IMAGE("response.image_generation_call.partial_image")` + - `JsonValue; type "scroll"constant` - - `Optional agent` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The agent that owns this multi-agent streaming event. + - `SCROLL("scroll")` - - `String agentName` + - `long x` - The canonical name of the agent that produced this item. + The x-coordinate where the scroll occurred. - - `class BetaResponseMcpCallArgumentsDeltaEvent:` + - `long y` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + The y-coordinate where the scroll occurred. - - `String delta` + - `Optional> keys` - A JSON string containing the partial update to the arguments for the MCP tool call. + The keys being held while scrolling. - - `String itemId` + - `Type` - The unique identifier of the MCP tool call item being processed. + - `String text` - - `long outputIndex` + The text to type. - The index of the output item in the response's output array. + - `JsonValue; type "type"constant` - - `long sequenceNumber` + Specifies the event type. For a type action, this property is always set to `type`. - The sequence number of this event. + - `TYPE("type")` - - `JsonValue; type "response.mcp_call_arguments.delta"constant` + - `JsonValue;` - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `JsonValue; type "wait"constant` - - `RESPONSE_MCP_CALL_ARGUMENTS_DELTA("response.mcp_call_arguments.delta")` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `Optional agent` + - `WAIT("wait")` - The agent that owns this multi-agent streaming event. + - `Optional> actions` - - `String agentName` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The canonical name of the agent that produced this item. + - `Click` - - `class BetaResponseMcpCallArgumentsDoneEvent:` + - `DoubleClick` - Emitted when the arguments for an MCP tool call are finalized. + - `Drag` - - `String arguments` + - `Keypress` - A JSON string containing the finalized arguments for the MCP tool call. + - `Move` - - `String itemId` + - `JsonValue;` - The unique identifier of the MCP tool call item being processed. + - `Scroll` - - `long outputIndex` + - `Type` - The index of the output item in the response's output array. + - `JsonValue;` - - `long sequenceNumber` + - `Optional agent` - The sequence number of this event. + The agent that produced this item. - - `JsonValue; type "response.mcp_call_arguments.done"constant` + - `String agentName` - The type of the event. Always 'response.mcp_call_arguments.done'. + The canonical name of the agent that produced this item. - - `RESPONSE_MCP_CALL_ARGUMENTS_DONE("response.mcp_call_arguments.done")` + - `class BetaResponseComputerToolCallOutputItem:` - - `Optional agent` + - `String id` - The agent that owns this multi-agent streaming event. + The unique ID of the computer call tool output. - - `String agentName` + - `String callId` - The canonical name of the agent that produced this item. + The ID of the computer tool call that produced the output. - - `class BetaResponseMcpCallCompletedEvent:` + - `BetaResponseComputerToolCallOutputScreenshot output` - Emitted when an MCP tool call has completed successfully. + A computer screenshot image used with the computer use tool. - - `String itemId` + - `JsonValue; type "computer_screenshot"constant` - The ID of the MCP tool call item that completed. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `long outputIndex` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The index of the output item that completed. + - `Optional fileId` - - `long sequenceNumber` + The identifier of an uploaded file that contains the screenshot. - The sequence number of this event. + - `Optional imageUrl` - - `JsonValue; type "response.mcp_call.completed"constant` + The URL of the screenshot image. - The type of the event. Always 'response.mcp_call.completed'. + - `Status status` - - `RESPONSE_MCP_CALL_COMPLETED("response.mcp_call.completed")` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `Optional agent` + - `COMPLETED("completed")` - The agent that owns this multi-agent streaming event. + - `INCOMPLETE("incomplete")` - - `String agentName` + - `FAILED("failed")` - The canonical name of the agent that produced this item. + - `IN_PROGRESS("in_progress")` - - `class BetaResponseMcpCallFailedEvent:` + - `JsonValue; type "computer_call_output"constant` - Emitted when an MCP tool call has failed. + The type of the computer tool call output. Always `computer_call_output`. - - `String itemId` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - The ID of the MCP tool call item that failed. + - `Optional> acknowledgedSafetyChecks` - - `long outputIndex` + The safety checks reported by the API that have been acknowledged by the + developer. - The index of the output item that failed. + - `String id` - - `long sequenceNumber` + The ID of the pending safety check. - The sequence number of this event. + - `Optional code` - - `JsonValue; type "response.mcp_call.failed"constant` + The type of the pending safety check. - The type of the event. Always 'response.mcp_call.failed'. + - `Optional message` - - `RESPONSE_MCP_CALL_FAILED("response.mcp_call.failed")` + Details about the pending safety check. - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseMcpCallInProgressEvent:` - - Emitted when an MCP tool call is in progress. - - - `String itemId` - - The unique identifier of the MCP tool call item being processed. + - `Optional createdBy` - - `long outputIndex` + The identifier of the actor that created the item. - The index of the output item in the response's output array. + - `class BetaResponseFunctionWebSearch:` - - `long sequenceNumber` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The sequence number of this event. + - `String id` - - `JsonValue; type "response.mcp_call.in_progress"constant` + The unique ID of the web search tool call. - The type of the event. Always 'response.mcp_call.in_progress'. + - `Action action` - - `RESPONSE_MCP_CALL_IN_PROGRESS("response.mcp_call.in_progress")` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `Optional agent` + - `class Search:` - The agent that owns this multi-agent streaming event. + Action type "search" - Performs a web search query. - - `String agentName` + - `JsonValue; type "search"constant` - The canonical name of the agent that produced this item. + The action type. - - `class BetaResponseMcpListToolsCompletedEvent:` + - `SEARCH("search")` - Emitted when the list of available MCP tools has been successfully retrieved. + - `Optional> queries` - - `String itemId` + The search queries. - The ID of the MCP tool call item that produced this output. + - `Optional query` - - `long outputIndex` + The search query. - The index of the output item that was processed. + - `Optional> sources` - - `long sequenceNumber` + The sources used in the search. - The sequence number of this event. + - `JsonValue; type "url"constant` - - `JsonValue; type "response.mcp_list_tools.completed"constant` + The type of source. Always `url`. - The type of the event. Always 'response.mcp_list_tools.completed'. + - `URL("url")` - - `RESPONSE_MCP_LIST_TOOLS_COMPLETED("response.mcp_list_tools.completed")` + - `String url` - - `Optional agent` + The URL of the source. - The agent that owns this multi-agent streaming event. + - `class OpenPage:` - - `String agentName` + Action type "open_page" - Opens a specific URL from search results. - The canonical name of the agent that produced this item. + - `JsonValue; type "open_page"constant` - - `class BetaResponseMcpListToolsFailedEvent:` + The action type. - Emitted when the attempt to list available MCP tools has failed. + - `OPEN_PAGE("open_page")` - - `String itemId` + - `Optional url` - The ID of the MCP tool call item that failed. + The URL opened by the model. - - `long outputIndex` + - `class FindInPage:` - The index of the output item that failed. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `long sequenceNumber` + - `String pattern` - The sequence number of this event. + The pattern or text to search for within the page. - - `JsonValue; type "response.mcp_list_tools.failed"constant` + - `JsonValue; type "find_in_page"constant` - The type of the event. Always 'response.mcp_list_tools.failed'. + The action type. - - `RESPONSE_MCP_LIST_TOOLS_FAILED("response.mcp_list_tools.failed")` + - `FIND_IN_PAGE("find_in_page")` - - `Optional agent` + - `String url` - The agent that owns this multi-agent streaming event. + The URL of the page searched for the pattern. - - `String agentName` + - `Status status` - The canonical name of the agent that produced this item. + The status of the web search tool call. - - `class BetaResponseMcpListToolsInProgressEvent:` + - `IN_PROGRESS("in_progress")` - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `SEARCHING("searching")` - - `String itemId` + - `COMPLETED("completed")` - The ID of the MCP tool call item that is being processed. + - `FAILED("failed")` - - `long outputIndex` + - `JsonValue; type "web_search_call"constant` - The index of the output item that is being processed. + The type of the web search tool call. Always `web_search_call`. - - `long sequenceNumber` + - `WEB_SEARCH_CALL("web_search_call")` - The sequence number of this event. + - `Optional agent` - - `JsonValue; type "response.mcp_list_tools.in_progress"constant` + The agent that produced this item. - The type of the event. Always 'response.mcp_list_tools.in_progress'. + - `String agentName` - - `RESPONSE_MCP_LIST_TOOLS_IN_PROGRESS("response.mcp_list_tools.in_progress")` + The canonical name of the agent that produced this item. - - `Optional agent` + - `class BetaResponseFunctionToolCallItem:` - The agent that owns this multi-agent streaming event. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The unique ID of the function tool call. - - `class BetaResponseOutputTextAnnotationAddedEvent:` + - `Status status` - Emitted when an annotation is added to output text content. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `JsonValue annotation` + - `IN_PROGRESS("in_progress")` - The annotation object being added. (See annotation schema for details.) + - `COMPLETED("completed")` - - `long annotationIndex` + - `INCOMPLETE("incomplete")` - The index of the annotation within the content part. + - `Optional createdBy` - - `long contentIndex` + The identifier of the actor that created the item. - The index of the content part within the output item. + - `class BetaResponseFunctionToolCallOutputItem:` - - `String itemId` + - `String id` - The unique identifier of the item to which the annotation is being added. + The unique ID of the function call tool output. - - `long outputIndex` + - `String callId` - The index of the output item in the response's output array. + The unique ID of the function tool call generated by the model. - - `long sequenceNumber` + - `Output output` - The sequence number of this event. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `JsonValue; type "response.output_text.annotation.added"constant` + - `String` - The type of the event. Always 'response.output_text.annotation.added'. + - `List` - - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` + - `class BetaResponseInputText:` - - `Optional agent` + A text input to the model. - The agent that owns this multi-agent streaming event. + - `class BetaResponseInputImage:` - - `String agentName` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The canonical name of the agent that produced this item. + - `class BetaResponseInputFile:` - - `class BetaResponseQueuedEvent:` + A file input to the model. - Emitted when a response is queued and waiting to be processed. + - `Status status` - - `BetaResponse response` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The full response object that is queued. + - `IN_PROGRESS("in_progress")` - - `long sequenceNumber` + - `COMPLETED("completed")` - The sequence number for this event. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "response.queued"constant` + - `JsonValue; type "function_call_output"constant` - The type of the event. Always 'response.queued'. + The type of the function tool call output. Always `function_call_output`. - - `RESPONSE_QUEUED("response.queued")` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseCustomToolCallInputDeltaEvent:` + - `Optional caller` - Event representing a delta (partial update) to the input of a custom tool call. + The execution context that produced this tool call. - - `String delta` + - `JsonValue;` - The incremental input data (delta) for the custom tool call. + - `JsonValue; type "direct"constant` - - `String itemId` + The caller type. Always `direct`. - Unique identifier for the API item associated with this event. + - `DIRECT("direct")` - - `long outputIndex` + - `class Program:` - The index of the output this delta applies to. + - `String callerId` - - `long sequenceNumber` + The call ID of the program item that produced this tool call. - The sequence number of this event. + - `JsonValue; type "program"constant` - - `JsonValue; type "response.custom_tool_call_input.delta"constant` + The caller type. Always `program`. - The event type identifier. + - `PROGRAM("program")` - - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DELTA("response.custom_tool_call_input.delta")` + - `Optional createdBy` - - `Optional agent` + The identifier of the actor that created the item. - The agent that owns this multi-agent streaming event. + - `AgentMessage` - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The unique ID of the agent message. - - `class BetaResponseCustomToolCallInputDoneEvent:` + - `String author` - Event indicating that input for a custom tool call is complete. + The sending agent identity. - - `String input` + - `List content` - The complete input data for the custom tool call. + Encrypted content sent between agents. - - `String itemId` + - `class BetaResponseInputText:` - Unique identifier for the API item associated with this event. + A text input to the model. - - `long outputIndex` + - `class BetaResponseOutputText:` - The index of the output this event applies to. + A text output from the model. - - `long sequenceNumber` + - `class Text:` - The sequence number of this event. + A text content. - - `JsonValue; type "response.custom_tool_call_input.done"constant` + - `String text` - The event type identifier. + - `JsonValue; type "text"constant` - - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DONE("response.custom_tool_call_input.done")` + - `TEXT("text")` - - `Optional agent` + - `class SummaryText:` - The agent that owns this multi-agent streaming event. + A summary text from the model. - - `String agentName` + - `String text` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. -### Beta Response Text Config + - `JsonValue; type "summary_text"constant` -- `class BetaResponseTextConfig:` + The type of the object. Always `summary_text`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `SUMMARY_TEXT("summary_text")` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `class ReasoningText:` - - `Optional format` + Reasoning text from the model. - An object specifying the format that the model must output. + - `String text` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The reasoning text from the model. - The default format is `{ "type": "text" }` with no additional options. + - `JsonValue; type "reasoning_text"constant` - **Not recommended for gpt-4o and newer models:** + The type of the reasoning text. Always `reasoning_text`. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `REASONING_TEXT("reasoning_text")` - - `JsonValue;` + - `class BetaResponseOutputRefusal:` - - `JsonValue; type "text"constant` + A refusal from the model. - The type of response format being defined. Always `text`. + - `class BetaResponseInputImage:` - - `TEXT("text")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `class ComputerScreenshot:` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A screenshot of a computer. - - `String name` + - `Detail detail` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Schema schema` + - `LOW("low")` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `HIGH("high")` - - `JsonValue; type "json_schema"constant` + - `AUTO("auto")` - The type of response format being defined. Always `json_schema`. + - `ORIGINAL("original")` - - `JSON_SCHEMA("json_schema")` + - `Optional fileId` - - `Optional description` + The identifier of an uploaded file that contains the screenshot. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Optional imageUrl` - - `Optional strict` + The URL of the screenshot image. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `JsonValue; type "computer_screenshot"constant` - - `JsonValue;` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `JsonValue; type "json_object"constant` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The type of response format being defined. Always `json_object`. + - `Optional promptCacheBreakpoint` - - `JSON_OBJECT("json_object")` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `Optional verbosity` + - `JsonValue; mode "explicit"constant` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The breakpoint mode. Always `explicit`. - - `LOW("low")` + - `EXPLICIT("explicit")` - - `MEDIUM("medium")` + - `class BetaResponseInputFile:` - - `HIGH("high")` + A file input to the model. -### Beta Response Text Delta Event + - `class EncryptedContent:` -- `class BetaResponseTextDeltaEvent:` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - Emitted when there is an additional text delta. + - `String encryptedContent` - - `long contentIndex` + Opaque encrypted content. - The index of the content part that the text delta was added to. + - `JsonValue; type "encrypted_content"constant` - - `String delta` + The type of the input item. Always `encrypted_content`. - The text delta that was added. + - `ENCRYPTED_CONTENT("encrypted_content")` - - `String itemId` + - `String recipient` - The ID of the output item that the text delta was added to. + The destination agent identity. - - `List logprobs` + - `JsonValue; type "agent_message"constant` - The log probabilities of the tokens in the delta. + The type of the item. Always `agent_message`. - - `String token` + - `AGENT_MESSAGE("agent_message")` - A possible text token. + - `Optional agent` - - `double logprob` + The agent that produced this item. - The log probability of this token. + - `String agentName` - - `Optional> topLogprobs` + The canonical name of the agent that produced this item. - The log probabilities of up to 20 of the most likely tokens. + - `MultiAgentCall` - - `Optional token` + - `String id` - A possible text token. + The unique ID of the multi-agent call item. - - `Optional logprob` + - `Action action` - The log probability of this token. + The multi-agent action to execute. - - `long outputIndex` + - `SPAWN_AGENT("spawn_agent")` - The index of the output item that the text delta was added to. + - `INTERRUPT_AGENT("interrupt_agent")` - - `long sequenceNumber` + - `LIST_AGENTS("list_agents")` - The sequence number for this event. + - `SEND_MESSAGE("send_message")` - - `JsonValue; type "response.output_text.delta"constant` + - `FOLLOWUP_TASK("followup_task")` - The type of the event. Always `response.output_text.delta`. + - `WAIT_AGENT("wait_agent")` - - `RESPONSE_OUTPUT_TEXT_DELTA("response.output_text.delta")` + - `String arguments` - - `Optional agent` + The JSON string of arguments generated for the action. - The agent that owns this multi-agent streaming event. + - `String callId` - - `String agentName` + The unique ID linking this call to its output. - The canonical name of the agent that produced this item. + - `JsonValue; type "multi_agent_call"constant` -### Beta Response Text Done Event + The type of the multi-agent call. Always `multi_agent_call`. -- `class BetaResponseTextDoneEvent:` + - `MULTI_AGENT_CALL("multi_agent_call")` - Emitted when text content is finalized. + - `Optional agent` - - `long contentIndex` + The agent that produced this item. - The index of the content part that the text content is finalized. + - `String agentName` - - `String itemId` + The canonical name of the agent that produced this item. - The ID of the output item that the text content is finalized. + - `MultiAgentCallOutput` - - `List logprobs` + - `String id` - The log probabilities of the tokens in the delta. + The unique ID of the multi-agent call output item. - - `String token` + - `Action action` - A possible text token. + The multi-agent action that produced this result. - - `double logprob` + - `SPAWN_AGENT("spawn_agent")` - The log probability of this token. + - `INTERRUPT_AGENT("interrupt_agent")` - - `Optional> topLogprobs` + - `LIST_AGENTS("list_agents")` - The log probabilities of up to 20 of the most likely tokens. + - `SEND_MESSAGE("send_message")` - - `Optional token` + - `FOLLOWUP_TASK("followup_task")` - A possible text token. + - `WAIT_AGENT("wait_agent")` - - `Optional logprob` + - `String callId` - The log probability of this token. + The unique ID of the multi-agent call. - - `long outputIndex` + - `List output` - The index of the output item that the text content is finalized. + Text output returned by the multi-agent action. - - `long sequenceNumber` + - `List annotations` - The sequence number for this event. + The annotations of the text output. - `String text` - The text content that is finalized. + The text output from the model. - - `JsonValue; type "response.output_text.done"constant` + - `JsonValue; type "output_text"constant` - The type of the event. Always `response.output_text.done`. + The type of the output text. Always `output_text`. - - `RESPONSE_OUTPUT_TEXT_DONE("response.output_text.done")` + - `Optional> logprobs` + + - `JsonValue; type "multi_agent_call_output"constant` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. -### Beta Response Tool Search Call - -- `class BetaResponseToolSearchCall:` + - `class BetaResponseToolSearchCall:` - `String id` @@ -124544,9 +137230,7 @@ public final class Main { The identifier of the actor that created the item. -### Beta Response Tool Search Output Item - -- `class BetaResponseToolSearchOutputItem:` + - `class BetaResponseToolSearchOutputItem:` - `String id` @@ -124685,7 +137369,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -124742,7 +137430,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -125655,1082 +138347,826 @@ public final class Main { The identifier of the actor that created the item. -### Beta Response Tool Search Output Item Param - -- `class BetaResponseToolSearchOutputItemParam:` - - - `List tools` - - The loaded tool definitions returned by the tool search output. - - - `class BetaFunctionTool:` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `String name` - - The name of the function to call. - - - `Optional parameters` + - `AdditionalTools` - A JSON schema object describing the parameters of the function. + - `String id` - - `Optional strict` + The unique ID of the additional tools item. - Whether strict parameter validation is enforced for this function tool. + - `Role role` - - `JsonValue; type "function"constant` + The role that provided the additional tools. - The type of the function tool. Always `function`. + - `UNKNOWN("unknown")` - - `FUNCTION("function")` + - `USER("user")` - - `Optional> allowedCallers` + - `ASSISTANT("assistant")` - The tool invocation context(s). + - `SYSTEM("system")` - - `DIRECT("direct")` + - `CRITIC("critic")` - - `PROGRAMMATIC("programmatic")` + - `DISCRIMINATOR("discriminator")` - - `Optional deferLoading` + - `DEVELOPER("developer")` - Whether this function is deferred and loaded via tool search. + - `TOOL("tool")` - - `Optional description` + - `List tools` - A description of the function. Used by the model to determine whether or not to call the function. + The additional tool definitions made available at this item. - - `Optional outputSchema` + - `class BetaFunctionTool:` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `class BetaFileSearchTool:` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `JsonValue; type "file_search"constant` - - The type of the file search tool. Always `file_search`. - - - `FILE_SEARCH("file_search")` - - - `List vectorStoreIds` - - The IDs of the vector stores to search. - - - `Optional 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` - - - `class CompoundFilter:` - - Combine multiple filters using `and` or `or`. - - - `List 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. - - - `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` - - - `JsonValue` - - - `Type type` - - Type of operation: `and` or `or`. - - - `AND("and")` - - - `OR("or")` - - - `Optional maxNumResults` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `Optional rankingOptions` - - Ranking options for search. - - - `Optional 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` - - The ranker to use for the file search. - - - `AUTO("auto")` - - - `DEFAULT_2024_11_15("default-2024-11-15")` - - - `Optional 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 BetaComputerTool:` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `JsonValue; type "computer"constant` - - The type of the computer tool. Always `computer`. - - - `COMPUTER("computer")` - - `class BetaComputerUsePreviewTool:` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `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 BetaWebSearchTool:` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Type 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 for the search. - - - `Optional> allowedDomains` + - `Mcp` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `CodeInterpreter` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `JsonValue;` - - `Optional searchContextSize` + - `ImageGeneration` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `JsonValue;` - - `LOW("low")` + - `class BetaFunctionShellTool:` - - `MEDIUM("medium")` + A tool that allows the model to execute shell commands. - - `HIGH("high")` + - `class BetaCustomTool:` - - `Optional userLocation` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The approximate location of the user. + - `class BetaNamespaceTool:` - - `Optional city` + Groups function/custom tools under a shared namespace. - Free text input for the city of the user, e.g. `San Francisco`. + - `class BetaToolSearchTool:` - - `Optional country` + Hosted or BYOT tool search configuration for deferred tools. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `class BetaWebSearchPreviewTool:` - - `Optional region` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Free text input for the region of the user, e.g. `California`. + - `class BetaApplyPatchTool:` - - `Optional timezone` + Allows the assistant to create, delete, or update files using unified diffs. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `JsonValue; type "additional_tools"constant` - - `Optional type` + The type of the item. Always `additional_tools`. - The type of location approximation. Always `approximate`. + - `ADDITIONAL_TOOLS("additional_tools")` - - `APPROXIMATE("approximate")` + - `Optional agent` - - `Mcp` + The agent that produced this item. - - `String serverLabel` + - `String agentName` - A label for this MCP server, used to identify it in tool calls. + The canonical name of the agent that produced this item. - - `JsonValue; type "mcp"constant` + - `class BetaResponseReasoningItem:` - The type of the MCP tool. Always `mcp`. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `MCP("mcp")` + - `String id` - - `Optional> allowedCallers` + The unique identifier of the reasoning content. - The tool invocation context(s). + - `List summary` - - `DIRECT("direct")` + Reasoning summary content. - - `PROGRAMMATIC("programmatic")` + - `String text` - - `Optional allowedTools` + A summary of the reasoning output from the model so far. - List of allowed tool names or a filter object. + - `JsonValue; type "summary_text"constant` - - `List` + The type of the object. Always `summary_text`. - - `class McpToolFilter:` + - `SUMMARY_TEXT("summary_text")` - A filter object to specify which tools are allowed. + - `JsonValue; type "reasoning"constant` - - `Optional readOnly` + The type of the object. Always `reasoning`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `REASONING("reasoning")` - - `Optional> toolNames` + - `Optional agent` - List of allowed tool names. + The agent that produced this item. - - `Optional authorization` + - `String agentName` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The canonical name of the agent that produced this item. - - `Optional connectorId` + - `Optional> content` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + Reasoning text content. - Currently supported `connector_id` values are: + - `String text` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The reasoning text from the model. - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `JsonValue; type "reasoning_text"constant` - - `CONNECTOR_GMAIL("connector_gmail")` + The type of the reasoning text. Always `reasoning_text`. - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `REASONING_TEXT("reasoning_text")` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `Optional encryptedContent` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `Optional status` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `IN_PROGRESS("in_progress")` - - `Optional deferLoading` + - `COMPLETED("completed")` - Whether this MCP tool is deferred and discovered via tool search. + - `INCOMPLETE("incomplete")` - - `Optional headers` + - `Program` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `String id` - - `Optional requireApproval` + The unique ID of the program item. - Specify which of the MCP server's tools require approval. + - `String callId` - - `class McpToolApprovalFilter:` + The stable call ID of the program item. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `String code` - - `Optional always` + The JavaScript source executed by programmatic tool calling. - A filter object to specify which tools are allowed. + - `String fingerprint` - - `Optional readOnly` + Opaque program replay fingerprint that must be round-tripped. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `JsonValue; type "program"constant` - - `Optional> toolNames` + The type of the item. Always `program`. - List of allowed tool names. + - `PROGRAM("program")` - - `Optional never` + - `Optional agent` - A filter object to specify which tools are allowed. + The agent that produced this item. - - `Optional readOnly` + - `String agentName` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The canonical name of the agent that produced this item. - - `Optional> toolNames` + - `ProgramOutput` - List of allowed tool names. + - `String id` - - `enum McpToolApprovalSetting:` + The unique ID of the program output item. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `String callId` - - `ALWAYS("always")` + The call ID of the program item. - - `NEVER("never")` + - `String result` - - `Optional serverDescription` + The result produced by the program item. - Optional description of the MCP server, used to provide more context. + - `Status status` - - `Optional serverUrl` + The terminal status of the program output item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `COMPLETED("completed")` - - `Optional tunnelId` + - `INCOMPLETE("incomplete")` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `JsonValue; type "program_output"constant` - - `CodeInterpreter` + The type of the item. Always `program_output`. - - `Container container` + - `PROGRAM_OUTPUT("program_output")` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `Optional agent` - - `String` + The agent that produced this item. - - `class CodeInterpreterToolAuto:` + - `String agentName` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The canonical name of the agent that produced this item. - - `JsonValue; type "auto"constant` + - `class BetaResponseCompactionItem:` - Always `auto`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `AUTO("auto")` + - `String id` - - `Optional> fileIds` + The unique ID of the compaction item. - An optional list of uploaded files to make available to your code. + - `String encryptedContent` - - `Optional memoryLimit` + The encrypted content that was produced by compaction. - The memory limit for the code interpreter container. + - `JsonValue; type "compaction"constant` - - `_1G("1g")` + The type of the item. Always `compaction`. - - `_4G("4g")` + - `COMPACTION("compaction")` - - `_16G("16g")` + - `Optional agent` - - `_64G("64g")` + The agent that produced this item. - - `Optional networkPolicy` + - `String agentName` - Network access policy for the container. + The canonical name of the agent that produced this item. - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional createdBy` - - `JsonValue; type "disabled"constant` + The identifier of the actor that created the item. - Disable outbound network access. Always `disabled`. + - `ImageGenerationCall` - - `DISABLED("disabled")` + - `String id` - - `class BetaContainerNetworkPolicyAllowlist:` + The unique ID of the image generation call. - - `List allowedDomains` + - `Optional result` - A list of allowed domains when type is `allowlist`. + The generated image encoded in base64. - - `JsonValue; type "allowlist"constant` + - `Status status` - Allow outbound network access only to specified domains. Always `allowlist`. + The status of the image generation call. - - `ALLOWLIST("allowlist")` + - `IN_PROGRESS("in_progress")` - - `Optional> domainSecrets` + - `COMPLETED("completed")` - Optional domain-scoped secrets for allowlisted domains. + - `GENERATING("generating")` - - `String domain` + - `FAILED("failed")` - The domain associated with the secret. + - `JsonValue; type "image_generation_call"constant` - - `String name` + The type of the image generation call. Always `image_generation_call`. - The name of the secret to inject for the domain. + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `String value` + - `Optional agent` - The secret value to inject for the domain. + The agent that produced this item. - - `JsonValue; type "code_interpreter"constant` + - `String agentName` - The type of the code interpreter tool. Always `code_interpreter`. + The canonical name of the agent that produced this item. - - `CODE_INTERPRETER("code_interpreter")` + - `class BetaResponseCodeInterpreterToolCall:` - - `Optional> allowedCallers` + A tool call to run code. - The tool invocation context(s). + - `String id` - - `DIRECT("direct")` + The unique ID of the code interpreter tool call. - - `PROGRAMMATIC("programmatic")` + - `Optional code` - - `JsonValue;` + The code to run, or null if not available. - - `JsonValue; type "programmatic_tool_calling"constant` + - `String containerId` - The type of the tool. Always `programmatic_tool_calling`. + The ID of the container used to run the code. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional> outputs` - - `ImageGeneration` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `JsonValue; type "image_generation"constant` + - `class Logs:` - The type of the image generation tool. Always `image_generation`. + The logs output from the code interpreter. - - `IMAGE_GENERATION("image_generation")` + - `String logs` - - `Optional action` + The logs output from the code interpreter. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `JsonValue; type "logs"constant` - - `GENERATE("generate")` + The type of the output. Always `logs`. - - `EDIT("edit")` + - `LOGS("logs")` - - `AUTO("auto")` + - `class Image:` - - `Optional background` + The image output from the code interpreter. - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + - `JsonValue; type "image"constant` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + The type of the output. Always `image`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `IMAGE("image")` - - `TRANSPARENT("transparent")` + - `String url` - - `OPAQUE("opaque")` + The URL of the image output from the code interpreter. - - `AUTO("auto")` + - `Status status` - - `Optional inputFidelity` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `IN_PROGRESS("in_progress")` - - `HIGH("high")` + - `COMPLETED("completed")` - - `LOW("low")` + - `INCOMPLETE("incomplete")` - - `Optional inputImageMask` + - `INTERPRETING("interpreting")` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `FAILED("failed")` - - `Optional fileId` + - `JsonValue; type "code_interpreter_call"constant` - File ID for the mask image. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `Optional imageUrl` + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - Base64-encoded mask image. + - `Optional agent` - - `Optional model` + The agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `String agentName` - - `GPT_IMAGE_1("gpt-image-1")` + The canonical name of the agent that produced this item. - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `LocalShellCall` - - `GPT_IMAGE_2("gpt-image-2")` + - `String id` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The unique ID of the local shell call. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `Action action` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + Execute a shell command on the server. - - `Optional moderation` + - `List command` - Moderation level for the generated image. Default: `auto`. + The command to run. - - `AUTO("auto")` + - `Env env` - - `LOW("low")` + Environment variables to set for the command. - - `Optional outputCompression` + - `JsonValue; type "exec"constant` - Compression level for the output image. Default: 100. + The type of the local shell action. Always `exec`. - - `Optional outputFormat` + - `EXEC("exec")` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `Optional timeoutMs` - - `PNG("png")` + Optional timeout in milliseconds for the command. - - `WEBP("webp")` + - `Optional user` - - `JPEG("jpeg")` + Optional user to run the command as. - - `Optional partialImages` + - `Optional workingDirectory` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Optional working directory to run the command in. - - `Optional quality` + - `String callId` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The unique ID of the local shell tool call generated by the model. - - `LOW("low")` + - `Status status` - - `MEDIUM("medium")` + The status of the local shell call. - - `HIGH("high")` + - `IN_PROGRESS("in_progress")` - - `AUTO("auto")` + - `COMPLETED("completed")` - - `Optional size` + - `INCOMPLETE("incomplete")` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `JsonValue; type "local_shell_call"constant` - - `_1024X1024("1024x1024")` + The type of the local shell call. Always `local_shell_call`. - - `_1024X1536("1024x1536")` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `_1536X1024("1536x1024")` + - `Optional agent` - - `AUTO("auto")` + The agent that produced this item. - - `JsonValue;` + - `String agentName` - - `JsonValue; type "local_shell"constant` + The canonical name of the agent that produced this item. - The type of the local shell tool. Always `local_shell`. + - `LocalShellCallOutput` - - `LOCAL_SHELL("local_shell")` + - `String id` - - `class BetaFunctionShellTool:` + The unique ID of the local shell tool call generated by the model. - A tool that allows the model to execute shell commands. + - `String output` - - `JsonValue; type "shell"constant` + A JSON string of the output of the local shell tool call. - The type of the shell tool. Always `shell`. + - `JsonValue; type "local_shell_call_output"constant` - - `SHELL("shell")` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `Optional> allowedCallers` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - The tool invocation context(s). + - `Optional agent` - - `DIRECT("direct")` + The agent that produced this item. - - `PROGRAMMATIC("programmatic")` + - `String agentName` - - `Optional environment` + The canonical name of the agent that produced this item. - - `class BetaContainerAuto:` + - `Optional status` - - `JsonValue; type "container_auto"constant` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Automatically creates a container for this request + - `IN_PROGRESS("in_progress")` - - `CONTAINER_AUTO("container_auto")` + - `COMPLETED("completed")` - - `Optional> fileIds` + - `INCOMPLETE("incomplete")` - An optional list of uploaded files to make available to your code. + - `class BetaResponseFunctionShellToolCall:` - - `Optional memoryLimit` + A tool call that executes one or more shell commands in a managed environment. - The memory limit for the container. + - `String id` - - `_1G("1g")` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `_4G("4g")` + - `Action action` - - `_16G("16g")` + The shell commands and limits that describe how to run the tool call. - - `_64G("64g")` + - `List commands` - - `Optional networkPolicy` + - `Optional maxOutputLength` - Network access policy for the container. + Optional maximum number of characters to return from each command. - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional timeoutMs` - - `class BetaContainerNetworkPolicyAllowlist:` + Optional timeout in milliseconds for the commands. - - `Optional> skills` + - `String callId` - An optional list of skills referenced by id or inline data. + The unique ID of the shell tool call generated by the model. - - `class BetaSkillReference:` + - `Optional environment` - - `String skillId` + Represents the use of a local environment to perform shell actions. - The ID of the referenced skill. + - `class BetaResponseLocalEnvironment:` - - `JsonValue; type "skill_reference"constant` + Represents the use of a local environment to perform shell actions. - References a skill created with the /v1/skills endpoint. + - `JsonValue; type "local"constant` - - `SKILL_REFERENCE("skill_reference")` + The environment type. Always `local`. - - `Optional version` + - `LOCAL("local")` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `class BetaResponseContainerReference:` - - `class BetaInlineSkill:` + Represents a container created with /v1/containers. - - `String description` + - `String containerId` - The description of the skill. + - `JsonValue; type "container_reference"constant` - - `String name` + The environment type. Always `container_reference`. - The name of the skill. + - `CONTAINER_REFERENCE("container_reference")` - - `BetaInlineSkillSource source` + - `Status status` - Inline skill payload + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `String data` + - `IN_PROGRESS("in_progress")` - Base64-encoded skill zip bundle. + - `COMPLETED("completed")` - - `JsonValue; mediaType "application/zip"constant` + - `INCOMPLETE("incomplete")` - The media type of the inline skill payload. Must be `application/zip`. + - `JsonValue; type "shell_call"constant` - - `APPLICATION_ZIP("application/zip")` + The type of the item. Always `shell_call`. - - `JsonValue; type "base64"constant` + - `SHELL_CALL("shell_call")` - The type of the inline skill source. Must be `base64`. + - `Optional agent` - - `BASE64("base64")` + The agent that produced this item. - - `JsonValue; type "inline"constant` + - `String agentName` - Defines an inline skill for this request. + The canonical name of the agent that produced this item. - - `INLINE("inline")` + - `Optional caller` - - `class BetaLocalEnvironment:` + The execution context that produced this tool call. - - `JsonValue; type "local"constant` + - `JsonValue;` - Use a local computer environment. + - `JsonValue; type "direct"constant` - - `LOCAL("local")` + - `DIRECT("direct")` - - `Optional> skills` + - `class Program:` - An optional list of skills. + - `String callerId` - - `String description` + The call ID of the program item that produced this tool call. - The description of the skill. + - `JsonValue; type "program"constant` - - `String name` + - `PROGRAM("program")` - The name of the skill. + - `Optional createdBy` - - `String path` + The ID of the entity that created this tool call. - The path to the directory containing the skill. + - `class BetaResponseFunctionShellToolCallOutput:` - - `class BetaContainerReference:` + The output of a shell tool call that was emitted. - - `String containerId` + - `String id` - The ID of the referenced container. + The unique ID of the shell call output. Populated when this item is returned via API. - - `JsonValue; type "container_reference"constant` + - `String callId` - References a container created with the /v1/containers endpoint + The unique ID of the shell tool call generated by the model. - - `CONTAINER_REFERENCE("container_reference")` + - `Optional maxOutputLength` - - `class BetaCustomTool:` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `List output` - - `String name` + An array of shell call output contents - The name of the custom tool, used to identify it in tool calls. + - `Outcome outcome` - - `JsonValue; type "custom"constant` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The type of the custom tool. Always `custom`. + - `JsonValue;` - - `CUSTOM("custom")` + - `JsonValue; type "timeout"constant` - - `Optional> allowedCallers` + The outcome type. Always `timeout`. - The tool invocation context(s). + - `TIMEOUT("timeout")` - - `DIRECT("direct")` + - `class Exit:` - - `PROGRAMMATIC("programmatic")` + Indicates that the shell commands finished and returned an exit code. - - `Optional deferLoading` + - `long exitCode` - Whether this tool should be deferred and discovered via tool search. + Exit code from the shell process. - - `Optional description` + - `JsonValue; type "exit"constant` - Optional description of the custom tool, used to provide more context. + The outcome type. Always `exit`. - - `Optional format` + - `EXIT("exit")` - The input format for the custom tool. Default is unconstrained text. + - `String stderr` - - `JsonValue;` + The standard error output that was captured. - - `JsonValue; type "text"constant` + - `String stdout` - Unconstrained text format. Always `text`. + The standard output that was captured. - - `TEXT("text")` + - `Optional createdBy` - - `class Grammar:` + The identifier of the actor that created the item. - A grammar defined by the user. + - `Status status` - - `String definition` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The grammar definition. + - `IN_PROGRESS("in_progress")` - - `Syntax syntax` + - `COMPLETED("completed")` - The syntax of the grammar definition. One of `lark` or `regex`. + - `INCOMPLETE("incomplete")` - - `LARK("lark")` + - `JsonValue; type "shell_call_output"constant` - - `REGEX("regex")` + The type of the shell call output. Always `shell_call_output`. - - `JsonValue; type "grammar"constant` + - `SHELL_CALL_OUTPUT("shell_call_output")` - Grammar format. Always `grammar`. + - `Optional agent` - - `GRAMMAR("grammar")` + The agent that produced this item. - - `class BetaNamespaceTool:` + - `String agentName` - Groups function/custom tools under a shared namespace. + The canonical name of the agent that produced this item. - - `String description` + - `Optional caller` - A description of the namespace shown to the model. + The execution context that produced this tool call. - - `String name` + - `JsonValue;` - The namespace name used in tool calls (for example, `crm`). + - `JsonValue; type "direct"constant` - - `List tools` + - `DIRECT("direct")` - The function/custom tools available inside this namespace. + - `class Program:` - - `class Function:` + - `String callerId` - - `String name` + The call ID of the program item that produced this tool call. - - `JsonValue; type "function"constant` + - `JsonValue; type "program"constant` - - `FUNCTION("function")` + - `PROGRAM("program")` - - `Optional> allowedCallers` + - `Optional createdBy` - The tool invocation context(s). + The identifier of the actor that created the item. - - `DIRECT("direct")` + - `class BetaResponseApplyPatchToolCall:` - - `PROGRAMMATIC("programmatic")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `Optional deferLoading` + - `String id` - Whether this function should be deferred and discovered via tool search. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `Optional description` + - `String callId` - - `Optional outputSchema` + The unique ID of the apply patch tool call generated by the model. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `Operation operation` - - `Optional parameters` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `Optional strict` + - `class CreateFile:` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + Instruction describing how to create a file via the apply_patch tool. - - `class BetaCustomTool:` + - `String diff` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Diff to apply. - - `JsonValue; type "namespace"constant` + - `String path` - The type of the tool. Always `namespace`. + Path of the file to create. - - `NAMESPACE("namespace")` + - `JsonValue; type "create_file"constant` - - `class BetaToolSearchTool:` + Create a new file with the provided diff. - Hosted or BYOT tool search configuration for deferred tools. + - `CREATE_FILE("create_file")` - - `JsonValue; type "tool_search"constant` + - `class DeleteFile:` - The type of the tool. Always `tool_search`. + Instruction describing how to delete a file via the apply_patch tool. - - `TOOL_SEARCH("tool_search")` + - `String path` - - `Optional description` + Path of the file to delete. - Description shown to the model for a client-executed tool search tool. + - `JsonValue; type "delete_file"constant` - - `Optional execution` + Delete the specified file. - Whether tool search is executed by the server or by the client. + - `DELETE_FILE("delete_file")` - - `SERVER("server")` + - `class UpdateFile:` - - `CLIENT("client")` + Instruction describing how to update a file via the apply_patch tool. - - `Optional parameters` + - `String diff` - Parameter schema for a client-executed tool search tool. + Diff to apply. - - `class BetaWebSearchPreviewTool:` + - `String path` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Path of the file to update. - - `Type type` + - `JsonValue; type "update_file"constant` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Update an existing file with the provided diff. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `UPDATE_FILE("update_file")` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `Status status` - - `Optional> searchContentTypes` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `TEXT("text")` + - `IN_PROGRESS("in_progress")` - - `IMAGE("image")` + - `COMPLETED("completed")` - - `Optional searchContextSize` + - `JsonValue; type "apply_patch_call"constant` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the item. Always `apply_patch_call`. - - `LOW("low")` + - `APPLY_PATCH_CALL("apply_patch_call")` - - `MEDIUM("medium")` + - `Optional agent` - - `HIGH("high")` + The agent that produced this item. - - `Optional userLocation` + - `String agentName` - The user's location. + The canonical name of the agent that produced this item. - - `JsonValue; type "approximate"constant` + - `Optional caller` - The type of location approximation. Always `approximate`. + The execution context that produced this tool call. - - `APPROXIMATE("approximate")` + - `JsonValue;` - - `Optional city` + - `JsonValue; type "direct"constant` - Free text input for the city of the user, e.g. `San Francisco`. + - `DIRECT("direct")` - - `Optional country` + - `class Program:` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `String callerId` - - `Optional region` + The call ID of the program item that produced this tool call. - Free text input for the region of the user, e.g. `California`. + - `JsonValue; type "program"constant` - - `Optional timezone` + - `PROGRAM("program")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `Optional createdBy` - - `class BetaApplyPatchTool:` + The ID of the entity that created this tool call. - Allows the assistant to create, delete, or update files using unified diffs. + - `class BetaResponseApplyPatchToolCallOutput:` - - `JsonValue; type "apply_patch"constant` + The output emitted by an apply patch tool call. - The type of the tool. Always `apply_patch`. + - `String id` - - `APPLY_PATCH("apply_patch")` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `Optional> allowedCallers` + - `String callId` - The tool invocation context(s). + The unique ID of the apply patch tool call generated by the model. - - `DIRECT("direct")` + - `Status status` - - `PROGRAMMATIC("programmatic")` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `JsonValue; type "tool_search_output"constant` + - `COMPLETED("completed")` - The item type. Always `tool_search_output`. + - `FAILED("failed")` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `JsonValue; type "apply_patch_call_output"constant` - - `Optional id` + The type of the item. Always `apply_patch_call_output`. - The unique ID of this tool search output. + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - `Optional agent` @@ -126740,270 +139176,325 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional callId` + - `Optional caller` - The unique ID of the tool search call generated by the model. + The execution context that produced this tool call. - - `Optional execution` + - `JsonValue;` - Whether tool search was executed by the server or by the client. + - `JsonValue; type "direct"constant` - - `SERVER("server")` + - `DIRECT("direct")` - - `CLIENT("client")` + - `class Program:` - - `Optional status` + - `String callerId` - The status of the tool search output. + The call ID of the program item that produced this tool call. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "program"constant` - - `COMPLETED("completed")` + - `PROGRAM("program")` - - `INCOMPLETE("incomplete")` + - `Optional createdBy` -### Beta Response Usage + The ID of the entity that created this tool call output. -- `class BetaResponseUsage:` + - `Optional output` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + Optional textual output returned by the apply patch tool. - - `long inputTokens` + - `McpListTools` - The number of input tokens. + - `String id` - - `InputTokensDetails inputTokensDetails` + The unique ID of the list. - A detailed breakdown of the input tokens. + - `String serverLabel` - - `long cacheWriteTokens` + The label of the MCP server. - The number of input tokens that were written to the cache. + - `List tools` - - `long cachedTokens` + The tools available on the server. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `JsonValue inputSchema` - - `long outputTokens` + The JSON schema describing the tool's input. - The number of output tokens. + - `String name` - - `OutputTokensDetails outputTokensDetails` + The name of the tool. - A detailed breakdown of the output tokens. + - `Optional annotations` - - `long reasoningTokens` + Additional annotations about the tool. - The number of reasoning tokens. + - `Optional description` - - `long totalTokens` + The description of the tool. - The total number of tokens used. + - `JsonValue; type "mcp_list_tools"constant` -### Beta Response Web Search Call Completed Event + The type of the item. Always `mcp_list_tools`. -- `class BetaResponseWebSearchCallCompletedEvent:` + - `MCP_LIST_TOOLS("mcp_list_tools")` - Emitted when a web search call is completed. + - `Optional agent` - - `String itemId` + The agent that produced this item. - Unique ID for the output item associated with the web search call. + - `String agentName` - - `long outputIndex` + The canonical name of the agent that produced this item. - The index of the output item that the web search call is associated with. + - `Optional error` - - `long sequenceNumber` + Error message if the server could not list tools. - The sequence number of the web search call being processed. + - `McpApprovalRequest` - - `JsonValue; type "response.web_search_call.completed"constant` + - `String id` - The type of the event. Always `response.web_search_call.completed`. + The unique ID of the approval request. - - `RESPONSE_WEB_SEARCH_CALL_COMPLETED("response.web_search_call.completed")` + - `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")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. -### Beta Response Web Search Call In Progress Event - -- `class BetaResponseWebSearchCallInProgressEvent:` - - Emitted when a web search call is initiated. + - `McpApprovalResponse` - - `String itemId` + - `String id` - Unique ID for the output item associated with the web search call. + The unique ID of the approval response - - `long outputIndex` + - `String approvalRequestId` - The index of the output item that the web search call is associated with. + The ID of the approval request being answered. - - `long sequenceNumber` + - `boolean approve` - The sequence number of the web search call being processed. + Whether the request was approved. - - `JsonValue; type "response.web_search_call.in_progress"constant` + - `JsonValue; type "mcp_approval_response"constant` - The type of the event. Always `response.web_search_call.in_progress`. + The type of the item. Always `mcp_approval_response`. - - `RESPONSE_WEB_SEARCH_CALL_IN_PROGRESS("response.web_search_call.in_progress")` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. -### Beta Response Web Search Call Searching Event + - `Optional reason` -- `class BetaResponseWebSearchCallSearchingEvent:` + Optional reason for the decision. - Emitted when a web search call is executing. + - `McpCall` - - `String itemId` + - `String id` - Unique ID for the output item associated with the web search call. + The unique ID of the tool call. - - `long outputIndex` + - `String arguments` - The index of the output item that the web search call is associated with. + A JSON string of the arguments passed to the tool. - - `long sequenceNumber` + - `String name` - The sequence number of the web search call being processed. + The name of the tool that was run. - - `JsonValue; type "response.web_search_call.searching"constant` + - `String serverLabel` - The type of the event. Always `response.web_search_call.searching`. + The label of the MCP server running the tool. - - `RESPONSE_WEB_SEARCH_CALL_SEARCHING("response.web_search_call.searching")` + - `JsonValue; type "mcp_call"constant` + + The type of the item. Always `mcp_call`. + + - `MCP_CALL("mcp_call")` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. -### Beta Responses Client Event + - `Optional approvalRequestId` -- `class BetaResponsesClientEvent: A class that can be one of several variants.union` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - Client events accepted by the Responses WebSocket server. + - `Optional error` - - `ResponseCreate` + The error from the tool call, if any. - - `JsonValue; type "response.create"constant` + - `Optional output` - The type of the client event. Always `response.create`. + The output from the tool call. - - `RESPONSE_CREATE("response.create")` + - `Optional status` - - `Optional background` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `IN_PROGRESS("in_progress")` - - `Optional> contextManagement` + - `COMPLETED("completed")` - Context management configuration for this request. + - `INCOMPLETE("incomplete")` - - `String type` + - `CALLING("calling")` - The context management entry type. Currently only 'compaction' is supported. + - `FAILED("failed")` - - `Optional compactThreshold` + - `class BetaResponseCustomToolCallItem:` - Token threshold at which compaction should be triggered for this entry. + A call to a custom tool created by the model. - - `Optional conversation` + - `String id` - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + The unique ID of the custom tool call item. - - `String` + - `Status status` - - `class BetaResponseConversationParam:` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The conversation that this response belongs to. + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseCustomToolCallOutputItem:` + + The output of a custom tool call from your code, being sent back to the model. - `String id` - The unique ID of the conversation. + The unique ID of the custom tool call output item. - - `Optional> include` + - `Status status` - Specify additional output data to include in the model response. Currently supported values are: + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `IN_PROGRESS("in_progress")` - - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` + - `COMPLETED("completed")` - - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` + - `INCOMPLETE("incomplete")` - - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` + - `Optional createdBy` - - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` + The identifier of the actor that created the item. - - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` +### Example - - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` +```java +package com.openai.example; - - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.responses.inputitems.InputItemListPage; +import com.openai.models.beta.responses.inputitems.InputItemListParams; - - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` +public final class Main { + private Main() {} - - `Optional input` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - Text, image, or file inputs to the model, used to generate a response. + InputItemListPage page = client.beta().responses().inputItems().list("response_id"); + } +} +``` - Learn more: +#### Response - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) +```json +{ + "data": [ + { + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } + } + ], + "role": "user", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "status": "in_progress" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `String` +## Domain Types - - `List` +### Beta Response Item List - - `class BetaEasyInputMessage:` +- `class BetaResponseItemList:` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + A list of Response items. - - `Content content` + - `List data` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + A list of items used to generate this response. - - `String` + - `class BetaResponseInputMessageItem:` - - `List` + - `String id` + + The unique ID of the message input. + + - `List content` + + A list of one or many input items to the model, containing different content + types. - `class BetaResponseInputText:` @@ -127117,60 +139608,20 @@ public final class Main { - `Role role` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The role of the message input. One of `user`, `system`, or `developer`. - `USER("user")` - - `ASSISTANT("assistant")` - - `SYSTEM("system")` - `DEVELOPER("developer")` - - `Optional 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")` - - - `Optional type` + - `JsonValue; type "message"constant` - The type of the message input. Always `message`. + The type of the message input. Always set to `message`. - `MESSAGE("message")` - - `Message` - - - `List content` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText:` - - A text input to the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `Role role` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `USER("user")` - - - `SYSTEM("system")` - - - `DEVELOPER("developer")` - - `Optional agent` The agent that produced this item. @@ -127190,12 +139641,6 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `Optional type` - - The type of the message input. Always set to `message`. - - - `MESSAGE("message")` - - `class BetaResponseOutputMessage:` An output message from the model. @@ -127391,6 +139836,8 @@ public final class Main { - `COMMENTARY("commentary")` + - `FINAL_ANSWER("final_answer")` + - `class BetaResponseFileSearchToolCall:` The results of a file search tool call. See the @@ -127721,7 +140168,11 @@ public final class Main { The canonical name of the agent that produced this item. - - `ComputerCallOutput` + - `class BetaResponseComputerToolCallOutputItem:` + + - `String id` + + The unique ID of the computer call tool output. - `String callId` @@ -127746,19 +140197,29 @@ public final class Main { The URL of the screenshot image. + - `Status status` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `FAILED("failed")` + + - `IN_PROGRESS("in_progress")` + - `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 id` - - The ID of the computer tool call output. - - `Optional> acknowledgedSafetyChecks` - The safety checks reported by the API that have been acknowledged by the developer. + The safety checks reported by the API that have been acknowledged by the + developer. - `String id` @@ -127780,15 +140241,9 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional 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")` + - `Optional createdBy` - - `INCOMPLETE("incomplete")` + The identifier of the actor that created the item. - `class BetaResponseFunctionWebSearch:` @@ -127894,66 +140349,16 @@ public final class Main { The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCall:` + - `class BetaResponseFunctionToolCallItem:` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `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 id` + - `String id` The unique ID of the function tool call. - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional namespace` - - The namespace of the function to run. - - - `Optional status` + - `Status status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -127964,7 +140369,15 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `FunctionCallOutput` + - `Optional createdBy` + + The identifier of the actor that created the item. + + - `class BetaResponseFunctionToolCallOutputItem:` + + - `String id` + + The unique ID of the function call tool output. - `String callId` @@ -127972,191 +140385,189 @@ public final class Main { - `Output output` - Text, image, or file output of the function tool call. + The output from the function call generated by your code. + Can be a string or an list of output content. - `String` - - `List` + - `List` - - `class BetaResponseInputTextContent:` + - `class BetaResponseInputText:` A text input to the model. - - `String text` - - The text input to the model. - - - `JsonValue; type "input_text"constant` + - `class BetaResponseInputImage:` - The type of the input item. Always `input_text`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `INPUT_TEXT("input_text")` + - `class BetaResponseInputFile:` - - `Optional promptCacheBreakpoint` + A file input to the model. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Status status` - - `JsonValue; mode "explicit"constant` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The breakpoint mode. Always `explicit`. + - `IN_PROGRESS("in_progress")` - - `EXPLICIT("explicit")` + - `COMPLETED("completed")` - - `class BetaResponseInputImageContent:` + - `INCOMPLETE("incomplete")` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `JsonValue; type "function_call_output"constant` - - `JsonValue; type "input_image"constant` + The type of the function tool call output. Always `function_call_output`. - The type of the input item. Always `input_image`. + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `INPUT_IMAGE("input_image")` + - `Optional agent` - - `Optional detail` + The agent that produced this item. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `String agentName` - - `LOW("low")` + The canonical name of the agent that produced this item. - - `HIGH("high")` + - `Optional caller` - - `AUTO("auto")` + The execution context that produced this tool call. - - `ORIGINAL("original")` + - `JsonValue;` - - `Optional fileId` + - `JsonValue; type "direct"constant` - The ID of the file to be sent to the model. + The caller type. Always `direct`. - - `Optional imageUrl` + - `DIRECT("direct")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `class Program:` - - `Optional promptCacheBreakpoint` + - `String callerId` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The call ID of the program item that produced this tool call. - - `JsonValue; mode "explicit"constant` + - `JsonValue; type "program"constant` - The breakpoint mode. Always `explicit`. + The caller type. Always `program`. - - `EXPLICIT("explicit")` + - `PROGRAM("program")` - - `class BetaResponseInputFileContent:` + - `Optional createdBy` - A file input to the model. + The identifier of the actor that created the item. - - `JsonValue; type "input_file"constant` + - `AgentMessage` - The type of the input item. Always `input_file`. + - `String id` - - `INPUT_FILE("input_file")` + The unique ID of the agent message. - - `Optional detail` + - `String author` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The sending agent identity. - - `AUTO("auto")` + - `List content` - - `LOW("low")` + Encrypted content sent between agents. - - `HIGH("high")` + - `class BetaResponseInputText:` - - `Optional fileData` + A text input to the model. - The base64-encoded data of the file to be sent to the model. + - `class BetaResponseOutputText:` - - `Optional fileId` + A text output from the model. - The ID of the file to be sent to the model. + - `class Text:` - - `Optional fileUrl` + A text content. - The URL of the file to be sent to the model. + - `String text` - - `Optional filename` + - `JsonValue; type "text"constant` - The name of the file to be sent to the model. + - `TEXT("text")` - - `Optional promptCacheBreakpoint` + - `class SummaryText:` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A summary text from the model. - - `JsonValue; mode "explicit"constant` + - `String text` - The breakpoint mode. Always `explicit`. + A summary of the reasoning output from the model so far. - - `EXPLICIT("explicit")` + - `JsonValue; type "summary_text"constant` - - `JsonValue; type "function_call_output"constant` + The type of the object. Always `summary_text`. - The type of the function tool call output. Always `function_call_output`. + - `SUMMARY_TEXT("summary_text")` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `class ReasoningText:` - - `Optional id` + Reasoning text from the model. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `String text` - - `Optional agent` + The reasoning text from the model. - The agent that produced this item. + - `JsonValue; type "reasoning_text"constant` - - `String agentName` + The type of the reasoning text. Always `reasoning_text`. - The canonical name of the agent that produced this item. + - `REASONING_TEXT("reasoning_text")` - - `Optional caller` + - `class BetaResponseOutputRefusal:` - The execution context that produced this tool call. + A refusal from the model. - - `JsonValue;` + - `class BetaResponseInputImage:` - - `JsonValue; type "direct"constant` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The caller type. Always `direct`. + - `class ComputerScreenshot:` - - `DIRECT("direct")` + A screenshot of a computer. - - `class Program:` + - `Detail detail` - - `String callerId` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The call ID of the program item that produced this tool call. + - `LOW("low")` - - `JsonValue; type "program"constant` + - `HIGH("high")` - The caller type. Always `program`. + - `AUTO("auto")` - - `PROGRAM("program")` + - `ORIGINAL("original")` - - `Optional status` + - `Optional fileId` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The identifier of an uploaded file that contains the screenshot. - - `IN_PROGRESS("in_progress")` + - `Optional imageUrl` - - `COMPLETED("completed")` + The URL of the screenshot image. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "computer_screenshot"constant` - - `AgentMessage` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `String author` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - The sending agent identity. + - `Optional promptCacheBreakpoint` - - `List content` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Plaintext, image, or encrypted content sent between agents. + - `JsonValue; mode "explicit"constant` - - `class BetaResponseInputTextContent:` + The breakpoint mode. Always `explicit`. - A text input to the model. + - `EXPLICIT("explicit")` - - `class BetaResponseInputImageContent:` + - `class BetaResponseInputFile:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A file input to the model. - `class EncryptedContent:` @@ -128178,14 +140589,10 @@ public final class Main { - `JsonValue; type "agent_message"constant` - The item type. Always `agent_message`. + The type of the item. Always `agent_message`. - `AGENT_MESSAGE("agent_message")` - - `Optional id` - - The unique ID of this agent message item. - - `Optional agent` The agent that produced this item. @@ -128196,9 +140603,13 @@ public final class Main { - `MultiAgentCall` + - `String id` + + The unique ID of the multi-agent call item. + - `Action action` - The multi-agent action that was executed. + The multi-agent action to execute. - `SPAWN_AGENT("spawn_agent")` @@ -128214,7 +140625,7 @@ public final class Main { - `String arguments` - The action arguments as a JSON string. + The JSON string of arguments generated for the action. - `String callId` @@ -128222,14 +140633,10 @@ public final class Main { - `JsonValue; type "multi_agent_call"constant` - The item type. Always `multi_agent_call`. + The type of the multi-agent call. Always `multi_agent_call`. - `MULTI_AGENT_CALL("multi_agent_call")` - - `Optional id` - - The unique ID of this multi-agent call. - - `Optional agent` The agent that produced this item. @@ -128240,6 +140647,10 @@ public final class Main { - `MultiAgentCallOutput` + - `String id` + + The unique ID of the multi-agent call output item. + - `Action action` The multi-agent action that produced this result. @@ -128260,105 +140671,75 @@ public final class Main { The unique ID of the multi-agent call. - - `List output` + - `List output` Text output returned by the multi-agent action. - - `String text` - - The text content. - - - `JsonValue; type "output_text"constant` - - The content type. Always `output_text`. - - - `OUTPUT_TEXT("output_text")` - - - `Optional annotations` - - Citations associated with the text content. - - - `List` - - - `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 citation type. Always `file_citation`. + - `List annotations` - - `FILE_CITATION("file_citation")` + The annotations of the text output. - - `List` + - `String text` - - `long endIndex` + The text output from the model. - The index of the last character of the citation in the message. + - `JsonValue; type "output_text"constant` - - `long startIndex` + The type of the output text. Always `output_text`. - The index of the first character of the citation in the message. + - `Optional> logprobs` - - `String title` + - `JsonValue; type "multi_agent_call_output"constant` - The title of the cited resource. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `JsonValue; type "url_citation"constant` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - The citation type. Always `url_citation`. + - `Optional agent` - - `URL_CITATION("url_citation")` + The agent that produced this item. - - `String url` + - `String agentName` - The URL of the cited resource. + The canonical name of the agent that produced this item. - - `List` + - `class BetaResponseToolSearchCall:` - - `String containerId` + - `String id` - The ID of the container. + The unique ID of the tool search call item. - - `long endIndex` + - `JsonValue arguments` - The index of the last character of the citation in the message. + Arguments used for the tool search call. - - `String fileId` + - `Optional callId` - The ID of the container file. + The unique ID of the tool search call generated by the model. - - `String filename` + - `Execution execution` - The filename of the container file cited. + Whether tool search was executed by the server or by the client. - - `long startIndex` + - `SERVER("server")` - The index of the first character of the citation in the message. + - `CLIENT("client")` - - `JsonValue; type "container_file_citation"constant` + - `Status status` - The citation type. Always `container_file_citation`. + The status of the tool search call item that was recorded. - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "multi_agent_call_output"constant` + - `COMPLETED("completed")` - The item type. Always `multi_agent_call_output`. + - `INCOMPLETE("incomplete")` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `JsonValue; type "tool_search_call"constant` - - `Optional id` + The type of the item. Always `tool_search_call`. - The unique ID of this multi-agent call output. + - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional agent` @@ -128368,35 +140749,21 @@ public final class Main { The canonical name of the agent that produced this item. - - `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 id` - - The unique ID of this tool search call. + - `Optional createdBy` - - `Optional agent` + The identifier of the actor that created the item. - The agent that produced this item. + - `class BetaResponseToolSearchOutputItem:` - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - `Optional callId` The unique ID of the tool search call generated by the model. - - `Optional execution` + - `Execution execution` Whether tool search was executed by the server or by the client. @@ -128404,9 +140771,9 @@ public final class Main { - `CLIENT("client")` - - `Optional status` + - `Status status` - The status of the tool search call. + The status of the tool search output item that was recorded. - `IN_PROGRESS("in_progress")` @@ -128414,11 +140781,9 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseToolSearchOutputItemParam:` - - `List tools` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `class BetaFunctionTool:` @@ -128527,7 +140892,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `class CompoundFilter:` @@ -128584,7 +140953,11 @@ public final class Main { - `boolean` - - `List` + - `List` + + - `String` + + - `double` - `JsonValue` @@ -129481,14 +141854,10 @@ public final class Main { - `JsonValue; type "tool_search_output"constant` - The item type. Always `tool_search_output`. + The type of the item. Always `tool_search_output`. - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `Optional id` - - The unique ID of this tool search output. - - `Optional agent` The agent that produced this item. @@ -129497,39 +141866,39 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional callId` - - The unique ID of the tool search call generated by the model. + - `Optional createdBy` - - `Optional execution` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `AdditionalTools` - - `SERVER("server")` + - `String id` - - `CLIENT("client")` + The unique ID of the additional tools item. - - `Optional status` + - `Role role` - The status of the tool search output. + The role that provided the additional tools. - - `IN_PROGRESS("in_progress")` + - `UNKNOWN("unknown")` - - `COMPLETED("completed")` + - `USER("user")` - - `INCOMPLETE("incomplete")` + - `ASSISTANT("assistant")` - - `AdditionalTools` + - `SYSTEM("system")` - - `JsonValue; role "developer"constant` + - `CRITIC("critic")` - The role that provided the additional tools. Only `developer` is supported. + - `DISCRIMINATOR("discriminator")` - `DEVELOPER("developer")` + - `TOOL("tool")` + - `List tools` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `class BetaFunctionTool:` @@ -129588,14 +141957,10 @@ public final class Main { - `JsonValue; type "additional_tools"constant` - The item type. Always `additional_tools`. + The type of the item. Always `additional_tools`. - `ADDITIONAL_TOOLS("additional_tools")` - - `Optional id` - - The unique ID of this additional tools item. - - `Optional agent` The agent that produced this item. @@ -129673,13 +142038,85 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `class BetaResponseCompactionItemParam:` + - `Program` + + - `String id` + + The unique ID of the program item. + + - `String callId` + + The stable call ID of the program item. + + - `String code` + + The JavaScript source executed by programmatic tool calling. + + - `String fingerprint` + + Opaque program replay fingerprint that must be round-tripped. + + - `JsonValue; type "program"constant` + + The type of the item. Always `program`. + + - `PROGRAM("program")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `ProgramOutput` + + - `String id` + + The unique ID of the program output item. + + - `String callId` + + The call ID of the program item. + + - `String result` + + The result produced by the program item. + + - `Status status` + + The terminal status of the program output item. + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "program_output"constant` + + The type of the item. Always `program_output`. + + - `PROGRAM_OUTPUT("program_output")` + + - `Optional agent` + + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem:` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `String id` + + The unique ID of the compaction item. + - `String encryptedContent` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `JsonValue; type "compaction"constant` @@ -129687,10 +142124,6 @@ public final class Main { - `COMPACTION("compaction")` - - `Optional id` - - The ID of the compaction item. - - `Optional agent` The agent that produced this item. @@ -129699,6 +142132,10 @@ public final class Main { The canonical name of the agent that produced this item. + - `Optional createdBy` + + The identifier of the actor that created the item. + - `ImageGenerationCall` - `String id` @@ -129910,7 +142347,13 @@ public final class Main { - `INCOMPLETE("incomplete")` - - `ShellCall` + - `class BetaResponseFunctionShellToolCall:` + + A tool call that executes one or more shell commands in a managed environment. + + - `String id` + + The unique ID of the shell tool call. Populated when this item is returned via API. - `Action action` @@ -129918,30 +142361,60 @@ public final class Main { - `List commands` - Ordered shell commands for the execution environment to run. - - `Optional maxOutputLength` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - `Optional timeoutMs` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `String callId` The unique ID of the shell tool call generated by the model. + - `Optional environment` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment:` + + Represents the use of a local environment to perform shell actions. + + - `JsonValue; type "local"constant` + + The environment type. Always `local`. + + - `LOCAL("local")` + + - `class BetaResponseContainerReference:` + + Represents a container created with /v1/containers. + + - `String containerId` + + - `JsonValue; type "container_reference"constant` + + The environment type. Always `container_reference`. + + - `CONTAINER_REFERENCE("container_reference")` + + - `Status status` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + - `JsonValue; type "shell_call"constant` The type of the item. Always `shell_call`. - `SHELL_CALL("shell_call")` - - `Optional id` - - The unique ID of the shell tool call. Populated when this item is returned via API. - - `Optional agent` The agent that produced this item. @@ -129958,8 +142431,6 @@ public final class Main { - `JsonValue; type "direct"constant` - The caller type. Always `direct`. - - `DIRECT("direct")` - `class Program:` @@ -129970,41 +142441,35 @@ public final class Main { - `JsonValue; type "program"constant` - The caller type. Always `program`. - - `PROGRAM("program")` - - `Optional environment` - - The environment to execute the shell commands in. - - - `class BetaLocalEnvironment:` - - - `class BetaContainerReference:` - - - `Optional status` + - `Optional createdBy` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The ID of the entity that created this tool call. - - `IN_PROGRESS("in_progress")` + - `class BetaResponseFunctionShellToolCallOutput:` - - `COMPLETED("completed")` + The output of a shell tool call that was emitted. - - `INCOMPLETE("incomplete")` + - `String id` - - `ShellCallOutput` + The unique ID of the shell call output. Populated when this item is returned via API. - `String callId` The unique ID of the shell tool call generated by the model. - - `List output` + - `Optional maxOutputLength` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `List output` + + An array of shell call output contents - `Outcome outcome` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `JsonValue;` @@ -130020,7 +142485,7 @@ public final class Main { - `long exitCode` - The exit code returned by the shell process. + Exit code from the shell process. - `JsonValue; type "exit"constant` @@ -130030,21 +142495,31 @@ public final class Main { - `String stderr` - Captured stderr output for the shell call. + The standard error output that was captured. - `String stdout` - Captured stdout output for the shell call. + The standard output that was captured. - - `JsonValue; type "shell_call_output"constant` + - `Optional createdBy` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Status status` - - `Optional id` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `IN_PROGRESS("in_progress")` + + - `COMPLETED("completed")` + + - `INCOMPLETE("incomplete")` + + - `JsonValue; type "shell_call_output"constant` + + The type of the shell call output. Always `shell_call_output`. + + - `SHELL_CALL_OUTPUT("shell_call_output")` - `Optional agent` @@ -130062,8 +142537,6 @@ public final class Main { - `JsonValue; type "direct"constant` - The caller type. Always `direct`. - - `DIRECT("direct")` - `class Program:` @@ -130074,25 +142547,19 @@ public final class Main { - `JsonValue; type "program"constant` - The caller type. Always `program`. - - `PROGRAM("program")` - - `Optional maxOutputLength` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `Optional status` + - `Optional createdBy` - The status of the shell call output. + The identifier of the actor that created the item. - - `IN_PROGRESS("in_progress")` + - `class BetaResponseApplyPatchToolCall:` - - `COMPLETED("completed")` + A tool call that applies file diffs by creating, deleting, or updating files. - - `INCOMPLETE("incomplete")` + - `String id` - - `ApplyPatchCall` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `String callId` @@ -130100,55 +142567,55 @@ public final class Main { - `Operation operation` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `class CreateFile:` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `String diff` - Unified diff content to apply when creating the file. + Diff to apply. - `String path` - Path of the file to create relative to the workspace root. + Path of the file to create. - `JsonValue; type "create_file"constant` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `CREATE_FILE("create_file")` - `class DeleteFile:` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `String path` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `JsonValue; type "delete_file"constant` - The operation type. Always `delete_file`. + Delete the specified file. - `DELETE_FILE("delete_file")` - `class UpdateFile:` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `String diff` - Unified diff content to apply to the existing file. + Diff to apply. - `String path` - Path of the file to update relative to the workspace root. + Path of the file to update. - `JsonValue; type "update_file"constant` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `UPDATE_FILE("update_file")` @@ -130166,10 +142633,6 @@ public final class Main { - `APPLY_PATCH_CALL("apply_patch_call")` - - `Optional id` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `Optional agent` The agent that produced this item. @@ -130186,8 +142649,6 @@ public final class Main { - `JsonValue; type "direct"constant` - The caller type. Always `direct`. - - `DIRECT("direct")` - `class Program:` @@ -130198,11 +142659,19 @@ public final class Main { - `JsonValue; type "program"constant` - The caller type. Always `program`. - - `PROGRAM("program")` - - `ApplyPatchCallOutput` + - `Optional createdBy` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput:` + + The output emitted by an apply patch tool call. + + - `String id` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `String callId` @@ -130222,10 +142691,6 @@ public final class Main { - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `Optional id` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `Optional agent` The agent that produced this item. @@ -130242,8 +142707,6 @@ public final class Main { - `JsonValue; type "direct"constant` - The caller type. Always `direct`. - - `DIRECT("direct")` - `class Program:` @@ -130254,13 +142717,15 @@ public final class Main { - `JsonValue; type "program"constant` - The caller type. Always `program`. - - `PROGRAM("program")` + - `Optional createdBy` + + The ID of the entity that created this tool call output. + - `Optional output` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. - `McpListTools` @@ -130344,6 +142809,10 @@ public final class Main { - `McpApprovalResponse` + - `String id` + + The unique ID of the approval response + - `String approvalRequestId` The ID of the approval request being answered. @@ -130358,10 +142827,6 @@ public final class Main { - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - - `Optional id` - - The unique ID of the approval response - - `Optional agent` The agent that produced this item. @@ -130433,1582 +142898,1108 @@ public final class Main { - `FAILED("failed")` - - `class BetaResponseCustomToolCallOutput:` - - 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` - - - `class BetaResponseInputText:` - - A text input to the model. - - - `class BetaResponseInputImage:` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `class BetaResponseInputFile:` - - A file input to the model. - - - `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 id` - - The unique ID of the custom tool call output in the OpenAI platform. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - The caller type. Always `direct`. - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - The caller type. Always `program`. - - - `PROGRAM("program")` - - - `class BetaResponseCustomToolCall:` - - 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 id` - - The unique ID of the custom tool call in the OpenAI platform. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional caller` - - The execution context that produced this tool call. - - - `JsonValue;` - - - `JsonValue; type "direct"constant` - - - `DIRECT("direct")` - - - `class Program:` - - - `String callerId` - - The call ID of the program item that produced this tool call. - - - `JsonValue; type "program"constant` - - - `PROGRAM("program")` - - - `Optional namespace` - - The namespace of the custom tool being called. - - - `CompactionTrigger` - - - `JsonValue; type "compaction_trigger"constant` - - The type of the item. Always `compaction_trigger`. - - - `COMPACTION_TRIGGER("compaction_trigger")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ItemReference` - - - `String id` - - The ID of the item to reference. - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional type` - - The type of item to reference. Always `item_reference`. - - - `ITEM_REFERENCE("item_reference")` - - - `Program` - - - `String id` - - The unique ID of this program item. - - - `String callId` - - The stable call ID of the program item. - - - `String code` - - The JavaScript source executed by programmatic tool calling. - - - `String fingerprint` - - Opaque program replay fingerprint that must be round-tripped. - - - `JsonValue; type "program"constant` - - The item type. Always `program`. - - - `PROGRAM("program")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `ProgramOutput` - - - `String id` - - The unique ID of this program output item. - - - `String callId` - - The call ID of the program item. - - - `String result` - - The result produced by the program item. - - - `Status status` - - The terminal status of the program output. - - - `COMPLETED("completed")` - - - `INCOMPLETE("incomplete")` - - - `JsonValue; type "program_output"constant` - - The item type. Always `program_output`. - - - `PROGRAM_OUTPUT("program_output")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `Optional instructions` - - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - - - `Optional maxOutputTokens` - - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - - `Optional maxToolCalls` - - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - - `Optional 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. - - - `Optional model` - - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. - - - `GPT_5_6_SOL("gpt-5.6-sol")` - - - `GPT_5_6_TERRA("gpt-5.6-terra")` - - - `GPT_5_6_LUNA("gpt-5.6-luna")` - - - `GPT_5_4("gpt-5.4")` - - - `GPT_5_4_MINI("gpt-5.4-mini")` - - - `GPT_5_4_NANO("gpt-5.4-nano")` - - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - - - `GPT_5_2("gpt-5.2")` - - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - - - `GPT_5_2_PRO("gpt-5.2-pro")` - - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - - - `GPT_5_1("gpt-5.1")` - - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - - - `GPT_5_1_CODEX("gpt-5.1-codex")` - - - `GPT_5_1_MINI("gpt-5.1-mini")` - - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - - - `GPT_5("gpt-5")` - - - `GPT_5_MINI("gpt-5-mini")` - - - `GPT_5_NANO("gpt-5-nano")` - - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - - - `GPT_4_1("gpt-4.1")` - - - `GPT_4_1_MINI("gpt-4.1-mini")` - - - `GPT_4_1_NANO("gpt-4.1-nano")` - - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - - - `O4_MINI("o4-mini")` - - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - - - `O3("o3")` - - - `O3_2025_04_16("o3-2025-04-16")` - - - `O3_MINI("o3-mini")` - - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - - `O1("o1")` - - - `O1_2024_12_17("o1-2024-12-17")` - - - `O1_PREVIEW("o1-preview")` - - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - - - `O1_MINI("o1-mini")` - - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - - - `GPT_4O("gpt-4o")` - - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - - - `CODEX_MINI_LATEST("codex-mini-latest")` - - - `GPT_4O_MINI("gpt-4o-mini")` + - `class BetaResponseCustomToolCallItem:` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + A call to a custom tool created by the model. - - `GPT_4_TURBO("gpt-4-turbo")` + - `String id` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + The unique ID of the custom tool call item. - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + - `Status status` - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `IN_PROGRESS("in_progress")` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + - `COMPLETED("completed")` - - `GPT_4("gpt-4")` + - `INCOMPLETE("incomplete")` - - `GPT_4_0314("gpt-4-0314")` + - `Optional createdBy` - - `GPT_4_0613("gpt-4-0613")` + The identifier of the actor that created the item. - - `GPT_4_32K("gpt-4-32k")` + - `class BetaResponseCustomToolCallOutputItem:` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + The output of a custom tool call from your code, being sent back to the model. - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `String id` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + The unique ID of the custom tool call output item. - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `Status status` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + - `IN_PROGRESS("in_progress")` - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `COMPLETED("completed")` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + - `INCOMPLETE("incomplete")` - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + - `Optional createdBy` - - `O1_PRO("o1-pro")` + The identifier of the actor that created the item. - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - `String firstId` - - `O3_PRO("o3-pro")` + The ID of the first item in the list. - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + - `boolean hasMore` - - `O3_DEEP_RESEARCH("o3-deep-research")` + Whether there are more items available. - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + - `String lastId` - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` + The ID of the last item in the list. - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` + - `JsonValue; object_ "list"constant` - - `COMPUTER_USE_PREVIEW("computer-use-preview")` + The type of object returned, must be `list`. - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` + - `LIST("list")` - - `GPT_5_CODEX("gpt-5-codex")` +# Input Tokens - - `GPT_5_PRO("gpt-5-pro")` +## Get input token counts - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` +`InputTokenCountResponse beta().responses().inputTokens().count(InputTokenCountParamsparams = InputTokenCountParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` +**post** `/responses/input_tokens?beta=true` - - `Optional moderation` +Returns input token counts of the request. - Configuration for running moderation on the input and output of this response. +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - - `String model` +### Parameters - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. +- `InputTokenCountParams params` - - `Optional policy` + - `Optional> betas` - The policy to apply to moderated response input and output. + - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` - - `Optional input` + - `Optional conversation` - The moderation policy for the response input. + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - - `Mode mode` + - `String` - - `SCORE("score")` + - `class BetaResponseConversationParam:` - - `BLOCK("block")` + The conversation that this response belongs to. - - `Optional output` + - `String id` - The moderation policy for the response output. + The unique ID of the conversation. - - `Mode mode` + - `Optional input` - - `SCORE("score")` + Text, image, or file inputs to the model, used to generate a response - - `BLOCK("block")` + - `String` - - `Optional multiAgent` + - `List` - Configuration for server-hosted multi-agent execution. + - `class BetaEasyInputMessage:` - - `boolean enabled` + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - Whether to enable server-hosted multi-agent execution for this response. + - `Content content` - - `Optional maxConcurrentSubagents` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + - `String` - - `Optional parallelToolCalls` + - `List` - Whether to allow the model to run tool calls in parallel. + - `class BetaResponseInputText:` - - `Optional previousResponseId` + A text input to the model. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `String text` - - `Optional prompt` + The text input to the model. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `JsonValue; type "input_text"constant` - - `String id` + The type of the input item. Always `input_text`. - The unique identifier of the prompt template to use. + - `INPUT_TEXT("input_text")` - - `Optional variables` + - `Optional promptCacheBreakpoint` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `String` + - `JsonValue; mode "explicit"constant` - - `class BetaResponseInputText:` + The breakpoint mode. Always `explicit`. - A text input to the model. + - `EXPLICIT("explicit")` - `class BetaResponseInputImage:` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `class BetaResponseInputFile:` - - A file input to the model. - - - `Optional version` + - `Detail detail` - Optional version of the prompt template. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Optional promptCacheKey` + - `LOW("low")` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `HIGH("high")` - - `Optional promptCacheOptions` + - `AUTO("auto")` - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. + - `ORIGINAL("original")` - - `Optional mode` + - `JsonValue; type "input_image"constant` - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + The type of the input item. Always `input_image`. - - `IMPLICIT("implicit")` + - `INPUT_IMAGE("input_image")` - - `EXPLICIT("explicit")` + - `Optional fileId` - - `Optional ttl` + The ID of the file to be sent to the model. - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + - `Optional imageUrl` - - `_30M("30m")` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `Optional promptCacheRetention` + - `Optional promptCacheBreakpoint` - Deprecated. Use `prompt_cache_options.ttl` instead. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `JsonValue; mode "explicit"constant` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The breakpoint mode. Always `explicit`. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `EXPLICIT("explicit")` - - `IN_MEMORY("in_memory")` + - `class BetaResponseInputFile:` - - `_24H("24h")` + A file input to the model. - - `Optional reasoning` + - `JsonValue; type "input_file"constant` - **gpt-5 and o-series models only** + The type of the input item. Always `input_file`. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `INPUT_FILE("input_file")` - - `Optional context` + - `Optional detail` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `AUTO("auto")` - - `CURRENT_TURN("current_turn")` + - `LOW("low")` - - `ALL_TURNS("all_turns")` + - `HIGH("high")` - - `Optional effort` + - `Optional fileData` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The content of the file to be sent to the model. - - `NONE("none")` + - `Optional fileId` - - `MINIMAL("minimal")` + The ID of the file to be sent to the model. - - `LOW("low")` + - `Optional fileUrl` - - `MEDIUM("medium")` + The URL of the file to be sent to the model. - - `HIGH("high")` + - `Optional filename` - - `XHIGH("xhigh")` + The name of the file to be sent to the model. - - `MAX("max")` + - `Optional promptCacheBreakpoint` - - `Optional generateSummary` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - **Deprecated:** use `summary` instead. + - `JsonValue; mode "explicit"constant` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The breakpoint mode. Always `explicit`. - - `AUTO("auto")` + - `EXPLICIT("explicit")` - - `CONCISE("concise")` + - `Role role` - - `DETAILED("detailed")` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `Optional mode` + - `USER("user")` - Controls the reasoning execution mode for the request. + - `ASSISTANT("assistant")` - When returned on a response, this is the effective execution mode. + - `SYSTEM("system")` - - `STANDARD("standard")` + - `DEVELOPER("developer")` - - `PRO("pro")` + - `Optional phase` - - `Optional summary` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `COMMENTARY("commentary")` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `FINAL_ANSWER("final_answer")` - - `AUTO("auto")` + - `Optional type` - - `CONCISE("concise")` + The type of the message input. Always `message`. - - `DETAILED("detailed")` + - `MESSAGE("message")` - - `Optional safetyIdentifier` + - `Message` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `List content` - - `Optional serviceTier` + A list of one or many input items to the model, containing different content + types. - Specifies the processing type used for serving the request. + - `class BetaResponseInputText:` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + A text input to the model. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `class BetaResponseInputImage:` - - `AUTO("auto")` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `DEFAULT("default")` + - `class BetaResponseInputFile:` - - `FLEX("flex")` + A file input to the model. - - `SCALE("scale")` + - `Role role` - - `PRIORITY("priority")` + The role of the message input. One of `user`, `system`, or `developer`. - - `Optional store` + - `USER("user")` - Whether to store the generated model response for later retrieval via - API. + - `SYSTEM("system")` - - `Optional stream` + - `DEVELOPER("developer")` - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + - `Optional agent` - - `Optional streamOptions` + The agent that produced this item. - Options for streaming responses. Only set this when you set `stream: true`. + - `String agentName` - - `Optional includeObfuscation` + The canonical name of the agent that produced this item. - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. + - `Optional status` - - `Optional temperature` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `IN_PROGRESS("in_progress")` - - `Optional text` + - `COMPLETED("completed")` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `INCOMPLETE("incomplete")` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `Optional type` - - `Optional format` + The type of the message input. Always set to `message`. - An object specifying the format that the model must output. + - `MESSAGE("message")` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `class BetaResponseOutputMessage:` - The default format is `{ "type": "text" }` with no additional options. + An output message from the model. - **Not recommended for gpt-4o and newer models:** + - `String id` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The unique ID of the output message. - - `JsonValue;` + - `List content` - - `JsonValue; type "text"constant` + The content of the output message. - The type of response format being defined. Always `text`. + - `class BetaResponseOutputText:` - - `TEXT("text")` + A text output from the model. - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `List annotations` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The annotations of the text output. - - `String name` + - `class FileCitation:` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + A citation to a file. - - `Schema schema` + - `String fileId` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The ID of the file. - - `JsonValue; type "json_schema"constant` + - `String filename` - The type of response format being defined. Always `json_schema`. + The filename of the file cited. - - `JSON_SCHEMA("json_schema")` + - `long index` - - `Optional description` + The index of the file in the list of files. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `JsonValue; type "file_citation"constant` - - `Optional strict` + The type of the file citation. Always `file_citation`. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `FILE_CITATION("file_citation")` - - `JsonValue;` + - `class UrlCitation:` - - `JsonValue; type "json_object"constant` + A citation for a web resource used to generate a model response. - The type of response format being defined. Always `json_object`. + - `long endIndex` - - `JSON_OBJECT("json_object")` + The index of the last character of the URL citation in the message. - - `Optional verbosity` + - `long startIndex` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The index of the first character of the URL citation in the message. - - `LOW("low")` + - `String title` - - `MEDIUM("medium")` + The title of the web resource. - - `HIGH("high")` + - `JsonValue; type "url_citation"constant` - - `Optional toolChoice` + The type of the URL citation. Always `url_citation`. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `URL_CITATION("url_citation")` - - `enum BetaToolChoiceOptions:` + - `String url` - Controls which (if any) tool is called by the model. + The URL of the web resource. - `none` means the model will not call any tool and instead generates a message. + - `class ContainerFileCitation:` - `auto` means the model can pick between generating a message or calling one or - more tools. + A citation for a container file used to generate a model response. - `required` means the model must call one or more tools. + - `String containerId` - - `NONE("none")` + The ID of the container file. - - `AUTO("auto")` + - `long endIndex` - - `REQUIRED("required")` + The index of the last character of the container file citation in the message. - - `class BetaToolChoiceAllowed:` + - `String fileId` - Constrains the tools available to the model to a pre-defined set. + The ID of the file. - - `Mode mode` + - `String filename` - Constrains the tools available to the model to a pre-defined set. + The filename of the container file cited. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `long startIndex` - `required` requires the model to call one or more of the allowed tools. + The index of the first character of the container file citation in the message. - - `AUTO("auto")` + - `JsonValue; type "container_file_citation"constant` - - `REQUIRED("required")` + The type of the container file citation. Always `container_file_citation`. - - `List tools` + - `CONTAINER_FILE_CITATION("container_file_citation")` - A list of tool definitions that the model should be allowed to call. + - `class FilePath:` - For the Responses API, the list of tool definitions might look like: + A path to a file. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `String fileId` - - `JsonValue; type "allowed_tools"constant` + The ID of the file. - Allowed tool configuration type. Always `allowed_tools`. + - `long index` - - `ALLOWED_TOOLS("allowed_tools")` + The index of the file in the list of files. - - `class BetaToolChoiceTypes:` + - `JsonValue; type "file_path"constant` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + The type of the file path. Always `file_path`. - - `Type type` + - `FILE_PATH("file_path")` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `String text` - Allowed values are: + The text output from the model. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `JsonValue; type "output_text"constant` - - `FILE_SEARCH("file_search")` + The type of the output text. Always `output_text`. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `OUTPUT_TEXT("output_text")` - - `COMPUTER("computer")` + - `Optional> logprobs` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `String token` - - `COMPUTER_USE("computer_use")` + - `List bytes` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `double logprob` - - `IMAGE_GENERATION("image_generation")` + - `List topLogprobs` - - `CODE_INTERPRETER("code_interpreter")` + - `String token` - - `class BetaToolChoiceFunction:` + - `List bytes` - Use this option to force the model to call a specific function. + - `double logprob` - - `String name` + - `class BetaResponseOutputRefusal:` - The name of the function to call. + A refusal from the model. - - `JsonValue; type "function"constant` + - `String refusal` - For function calling, the type is always `function`. + The refusal explanation from the model. - - `FUNCTION("function")` + - `JsonValue; type "refusal"constant` - - `class BetaToolChoiceMcp:` + The type of the refusal. Always `refusal`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `REFUSAL("refusal")` - - `String serverLabel` + - `JsonValue; role "assistant"constant` - The label of the MCP server to use. + The role of the output message. Always `assistant`. - - `JsonValue; type "mcp"constant` + - `ASSISTANT("assistant")` - For MCP tools, the type is always `mcp`. + - `Status status` - - `MCP("mcp")` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `Optional name` + - `IN_PROGRESS("in_progress")` - The name of the tool to call on the server. + - `COMPLETED("completed")` - - `class BetaToolChoiceCustom:` + - `INCOMPLETE("incomplete")` - Use this option to force the model to call a specific custom tool. + - `JsonValue; type "message"constant` - - `String name` + The type of the output message. Always `message`. - The name of the custom tool to call. + - `MESSAGE("message")` - - `JsonValue; type "custom"constant` + - `Optional agent` - For custom tool calling, the type is always `custom`. + The agent that produced this item. - - `CUSTOM("custom")` + - `String agentName` - - `JsonValue;` + The canonical name of the agent that produced this item. - - `JsonValue; type "programmatic_tool_calling"constant` + - `Optional phase` - The tool to call. Always `programmatic_tool_calling`. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `COMMENTARY("commentary")` - - `class BetaToolChoiceApplyPatch:` + - `FINAL_ANSWER("final_answer")` - Forces the model to call the apply_patch tool when executing a tool call. + - `class BetaResponseFileSearchToolCall:` - - `JsonValue; type "apply_patch"constant` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - The tool to call. Always `apply_patch`. + - `String id` - - `APPLY_PATCH("apply_patch")` + The unique ID of the file search tool call. - - `class BetaToolChoiceShell:` + - `List queries` - Forces the model to call the shell tool when a tool call is required. + The queries used to search for files. - - `JsonValue; type "shell"constant` + - `Status status` - The tool to call. Always `shell`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `SHELL("shell")` + - `IN_PROGRESS("in_progress")` - - `Optional> tools` + - `SEARCHING("searching")` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `COMPLETED("completed")` - We support the following categories of tools: + - `INCOMPLETE("incomplete")` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `FAILED("failed")` - - `class BetaFunctionTool:` + - `JsonValue; type "file_search_call"constant` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The type of the file search tool call. Always `file_search_call`. - - `class BetaFileSearchTool:` + - `FILE_SEARCH_CALL("file_search_call")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `Optional agent` - - `class BetaComputerTool:` + The agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String agentName` - - `class BetaComputerUsePreviewTool:` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional> results` - - `class BetaWebSearchTool:` + The results of the file search tool call. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional attributes` - - `Mcp` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `CodeInterpreter` + - `String` - - `JsonValue;` + - `double` - - `ImageGeneration` + - `boolean` - - `JsonValue;` + - `Optional fileId` - - `class BetaFunctionShellTool:` + The unique ID of the file. - A tool that allows the model to execute shell commands. + - `Optional filename` - - `class BetaCustomTool:` + The name of the file. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `Optional score` - - `class BetaNamespaceTool:` + The relevance score of the file - a value between 0 and 1. - Groups function/custom tools under a shared namespace. + - `Optional text` - - `class BetaToolSearchTool:` + The text that was retrieved from the file. - Hosted or BYOT tool search configuration for deferred tools. + - `class BetaResponseComputerToolCall:` - - `class BetaWebSearchPreviewTool:` + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String id` - - `class BetaApplyPatchTool:` + The unique ID of the computer call. - Allows the assistant to create, delete, or update files using unified diffs. + - `String callId` - - `Optional topLogprobs` + An identifier used when responding to the tool call with output. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `List pendingSafetyChecks` - - `Optional topP` + The pending safety checks for the computer call. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `String id` - We generally recommend altering this or `temperature` but not both. + The ID of the pending safety check. - - `Optional truncation` + - `Optional code` - The truncation strategy to use for the model response. + The type of the pending safety check. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `Optional message` - - `AUTO("auto")` + Details about the pending safety check. - - `DISABLED("disabled")` + - `Status status` - - `Optional user` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `IN_PROGRESS("in_progress")` - - `ResponseInject` + - `COMPLETED("completed")` - - `List input` + - `INCOMPLETE("incomplete")` - Input items to inject into the active response. + - `Type type` - - `class BetaEasyInputMessage:` + The type of the computer call. Always `computer_call`. - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `COMPUTER_CALL("computer_call")` - - `Message` + - `Optional action` - - `class BetaResponseOutputMessage:` + A click action. - An output message from the model. + - `Click` - - `class BetaResponseFileSearchToolCall:` + - `Button button` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `class BetaResponseComputerToolCall:` + - `LEFT("left")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `RIGHT("right")` - - `ComputerCallOutput` + - `WHEEL("wheel")` - - `class BetaResponseFunctionWebSearch:` + - `BACK("back")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `FORWARD("forward")` - - `class BetaResponseFunctionToolCall:` + - `JsonValue; type "click"constant` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Specifies the event type. For a click action, this property is always `click`. - - `FunctionCallOutput` + - `CLICK("click")` - - `AgentMessage` + - `long x` - - `MultiAgentCall` + The x-coordinate where the click occurred. - - `MultiAgentCallOutput` + - `long y` - - `ToolSearchCall` + The y-coordinate where the click occurred. - - `class BetaResponseToolSearchOutputItemParam:` + - `Optional> keys` - - `AdditionalTools` + The keys being held while clicking. - - `class BetaResponseReasoningItem:` + - `DoubleClick` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `Optional> keys` - - `class BetaResponseCompactionItemParam:` + The keys being held while double-clicking. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `JsonValue; type "double_click"constant` - - `ImageGenerationCall` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `class BetaResponseCodeInterpreterToolCall:` + - `DOUBLE_CLICK("double_click")` - A tool call to run code. + - `long x` - - `LocalShellCall` + The x-coordinate where the double click occurred. - - `LocalShellCallOutput` + - `long y` - - `ShellCall` + The y-coordinate where the double click occurred. - - `ShellCallOutput` + - `Drag` - - `ApplyPatchCall` + - `List path` - - `ApplyPatchCallOutput` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `McpListTools` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `McpApprovalRequest` + - `long x` - - `McpApprovalResponse` + The x-coordinate. - - `McpCall` + - `long y` - - `class BetaResponseCustomToolCallOutput:` + The y-coordinate. - The output of a custom tool call from your code, being sent back to the model. + - `JsonValue; type "drag"constant` - - `class BetaResponseCustomToolCall:` + Specifies the event type. For a drag action, this property is always set to `drag`. - A call to a custom tool created by the model. + - `DRAG("drag")` - - `CompactionTrigger` + - `Optional> keys` - - `ItemReference` + The keys being held while dragging the mouse. - - `Program` + - `Keypress` - - `ProgramOutput` + - `List keys` - - `String responseId` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The ID of the active response that should receive the input. + - `JsonValue; type "keypress"constant` - - `JsonValue; type "response.inject"constant` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The event discriminator. Always `response.inject`. + - `KEYPRESS("keypress")` - - `RESPONSE_INJECT("response.inject")` + - `Move` -### Beta Responses Server Event + - `JsonValue; type "move"constant` -- `class BetaResponsesServerEvent: A class that can be one of several variants.union` + Specifies the event type. For a move action, this property is always set to `move`. - Server events emitted by the Responses WebSocket server. + - `MOVE("move")` - - `class BetaResponseAudioDeltaEvent:` + - `long x` - Emitted when there is a partial audio response. + The x-coordinate to move to. - - `String delta` + - `long y` - A chunk of Base64 encoded response audio bytes. + The y-coordinate to move to. - - `long sequenceNumber` + - `Optional> keys` - A sequence number for this chunk of the stream response. + The keys being held while moving the mouse. - - `JsonValue; type "response.audio.delta"constant` + - `JsonValue;` - The type of the event. Always `response.audio.delta`. + - `JsonValue; type "screenshot"constant` - - `RESPONSE_AUDIO_DELTA("response.audio.delta")` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `Optional agent` + - `SCREENSHOT("screenshot")` - The agent that owns this multi-agent streaming event. + - `Scroll` - - `String agentName` + - `long scrollX` - The canonical name of the agent that produced this item. + The horizontal scroll distance. - - `class BetaResponseAudioDoneEvent:` + - `long scrollY` - Emitted when the audio response is complete. + The vertical scroll distance. - - `long sequenceNumber` + - `JsonValue; type "scroll"constant` - The sequence number of the delta. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `JsonValue; type "response.audio.done"constant` + - `SCROLL("scroll")` - The type of the event. Always `response.audio.done`. + - `long x` - - `RESPONSE_AUDIO_DONE("response.audio.done")` + The x-coordinate where the scroll occurred. - - `Optional agent` + - `long y` - The agent that owns this multi-agent streaming event. + The y-coordinate where the scroll occurred. - - `String agentName` + - `Optional> keys` - The canonical name of the agent that produced this item. + The keys being held while scrolling. - - `class BetaResponseAudioTranscriptDeltaEvent:` + - `Type` - Emitted when there is a partial transcript of audio. + - `String text` - - `String delta` + The text to type. - The partial transcript of the audio response. + - `JsonValue; type "type"constant` - - `long sequenceNumber` + Specifies the event type. For a type action, this property is always set to `type`. - The sequence number of this event. + - `TYPE("type")` - - `JsonValue; type "response.audio.transcript.delta"constant` + - `JsonValue;` - The type of the event. Always `response.audio.transcript.delta`. + - `JsonValue; type "wait"constant` - - `RESPONSE_AUDIO_TRANSCRIPT_DELTA("response.audio.transcript.delta")` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `Optional agent` + - `WAIT("wait")` - The agent that owns this multi-agent streaming event. + - `Optional> actions` - - `String agentName` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The canonical name of the agent that produced this item. + - `Click` - - `class BetaResponseAudioTranscriptDoneEvent:` + - `DoubleClick` - Emitted when the full audio transcript is completed. + - `Drag` - - `long sequenceNumber` + - `Keypress` - The sequence number of this event. + - `Move` - - `JsonValue; type "response.audio.transcript.done"constant` + - `JsonValue;` - The type of the event. Always `response.audio.transcript.done`. + - `Scroll` - - `RESPONSE_AUDIO_TRANSCRIPT_DONE("response.audio.transcript.done")` + - `Type` + + - `JsonValue;` - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterCallCodeDeltaEvent:` - - Emitted when a partial code snippet is streamed by the code interpreter. - - - `String delta` - - The partial code snippet being streamed by the code interpreter. - - - `String itemId` - - The unique identifier of the code interpreter tool call item. + - `ComputerCallOutput` - - `long outputIndex` + - `String callId` - The index of the output item in the response for which the code is being streamed. + The ID of the computer tool call that produced the output. - - `long sequenceNumber` + - `BetaResponseComputerToolCallOutputScreenshot output` - The sequence number of this event, used to order streaming events. + A computer screenshot image used with the computer use tool. - - `JsonValue; type "response.code_interpreter_call_code.delta"constant` + - `JsonValue; type "computer_screenshot"constant` - The type of the event. Always `response.code_interpreter_call_code.delta`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DELTA("response.code_interpreter_call_code.delta")` + - `COMPUTER_SCREENSHOT("computer_screenshot")` - - `Optional agent` + - `Optional fileId` - The agent that owns this multi-agent streaming event. + The identifier of an uploaded file that contains the screenshot. - - `String agentName` + - `Optional imageUrl` - The canonical name of the agent that produced this item. + The URL of the screenshot image. - - `class BetaResponseCodeInterpreterCallCodeDoneEvent:` + - `JsonValue; type "computer_call_output"constant` - Emitted when the code snippet is finalized by the code interpreter. + The type of the computer tool call output. Always `computer_call_output`. - - `String code` + - `COMPUTER_CALL_OUTPUT("computer_call_output")` - The final code snippet output by the code interpreter. + - `Optional id` - - `String itemId` + The ID of the computer tool call output. - The unique identifier of the code interpreter tool call item. + - `Optional> acknowledgedSafetyChecks` - - `long outputIndex` + The safety checks reported by the API that have been acknowledged by the developer. - The index of the output item in the response for which the code is finalized. + - `String id` - - `long sequenceNumber` + The ID of the pending safety check. - The sequence number of this event, used to order streaming events. + - `Optional code` - - `JsonValue; type "response.code_interpreter_call_code.done"constant` + The type of the pending safety check. - The type of the event. Always `response.code_interpreter_call_code.done`. + - `Optional message` - - `RESPONSE_CODE_INTERPRETER_CALL_CODE_DONE("response.code_interpreter_call_code.done")` + Details about the pending safety check. - `Optional agent` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - - `class BetaResponseCodeInterpreterCallCompletedEvent:` + - `Optional status` - Emitted when the code interpreter call is completed. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `String itemId` + - `IN_PROGRESS("in_progress")` - The unique identifier of the code interpreter tool call item. + - `COMPLETED("completed")` - - `long outputIndex` + - `INCOMPLETE("incomplete")` - The index of the output item in the response for which the code interpreter call is completed. + - `class BetaResponseFunctionWebSearch:` - - `long sequenceNumber` + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - The sequence number of this event, used to order streaming events. + - `String id` - - `JsonValue; type "response.code_interpreter_call.completed"constant` + 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). - The type of the event. Always `response.code_interpreter_call.completed`. + - `class Search:` - - `RESPONSE_CODE_INTERPRETER_CALL_COMPLETED("response.code_interpreter_call.completed")` + Action type "search" - Performs a web search query. - - `Optional agent` + - `JsonValue; type "search"constant` - The agent that owns this multi-agent streaming event. + The action type. - - `String agentName` + - `SEARCH("search")` - The canonical name of the agent that produced this item. + - `Optional> queries` - - `class BetaResponseCodeInterpreterCallInProgressEvent:` + The search queries. - Emitted when a code interpreter call is in progress. + - `Optional query` - - `String itemId` + The search query. - The unique identifier of the code interpreter tool call item. + - `Optional> sources` - - `long outputIndex` + The sources used in the search. - The index of the output item in the response for which the code interpreter call is in progress. + - `JsonValue; type "url"constant` - - `long sequenceNumber` + The type of source. Always `url`. - The sequence number of this event, used to order streaming events. + - `URL("url")` - - `JsonValue; type "response.code_interpreter_call.in_progress"constant` + - `String url` - The type of the event. Always `response.code_interpreter_call.in_progress`. + The URL of the source. - - `RESPONSE_CODE_INTERPRETER_CALL_IN_PROGRESS("response.code_interpreter_call.in_progress")` + - `class OpenPage:` - - `Optional agent` + Action type "open_page" - Opens a specific URL from search results. - The agent that owns this multi-agent streaming event. + - `JsonValue; type "open_page"constant` - - `String agentName` + The action type. - The canonical name of the agent that produced this item. + - `OPEN_PAGE("open_page")` - - `class BetaResponseCodeInterpreterCallInterpretingEvent:` + - `Optional url` - Emitted when the code interpreter is actively interpreting the code snippet. + The URL opened by the model. - - `String itemId` + - `class FindInPage:` - The unique identifier of the code interpreter tool call item. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `long outputIndex` + - `String pattern` - The index of the output item in the response for which the code interpreter is interpreting code. + The pattern or text to search for within the page. - - `long sequenceNumber` + - `JsonValue; type "find_in_page"constant` - The sequence number of this event, used to order streaming events. + The action type. - - `JsonValue; type "response.code_interpreter_call.interpreting"constant` + - `FIND_IN_PAGE("find_in_page")` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `String url` - - `RESPONSE_CODE_INTERPRETER_CALL_INTERPRETING("response.code_interpreter_call.interpreting")` + The URL of the page searched for the pattern. - - `Optional agent` + - `Status status` - The agent that owns this multi-agent streaming event. + The status of the web search tool call. - - `String agentName` + - `IN_PROGRESS("in_progress")` - The canonical name of the agent that produced this item. + - `SEARCHING("searching")` - - `class BetaResponseCompletedEvent:` + - `COMPLETED("completed")` - Emitted when the model response is complete. + - `FAILED("failed")` - - `BetaResponse response` + - `JsonValue; type "web_search_call"constant` - Properties of the completed response. + The type of the web search tool call. Always `web_search_call`. - - `String id` + - `WEB_SEARCH_CALL("web_search_call")` - Unique identifier for this Response. + - `Optional agent` - - `double createdAt` + The agent that produced this item. - Unix timestamp (in seconds) of when this Response was created. + - `String agentName` - - `Optional error` + The canonical name of the agent that produced this item. - An error object returned when the model fails to generate a Response. + - `class BetaResponseFunctionToolCall:` - - `Code code` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The error code for the response. + - `String arguments` - - `SERVER_ERROR("server_error")` + A JSON string of the arguments to pass to the function. - - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` + - `String callId` - - `INVALID_PROMPT("invalid_prompt")` + The unique ID of the function tool call generated by the model. - - `BIO_POLICY("bio_policy")` + - `String name` - - `VECTOR_STORE_TIMEOUT("vector_store_timeout")` + The name of the function to run. - - `INVALID_IMAGE("invalid_image")` + - `JsonValue; type "function_call"constant` - - `INVALID_IMAGE_FORMAT("invalid_image_format")` + The type of the function tool call. Always `function_call`. - - `INVALID_BASE64_IMAGE("invalid_base64_image")` + - `FUNCTION_CALL("function_call")` - - `INVALID_IMAGE_URL("invalid_image_url")` + - `Optional id` - - `IMAGE_TOO_LARGE("image_too_large")` + The unique ID of the function tool call. - - `IMAGE_TOO_SMALL("image_too_small")` + - `Optional agent` - - `IMAGE_PARSE_ERROR("image_parse_error")` + The agent that produced this item. - - `IMAGE_CONTENT_POLICY_VIOLATION("image_content_policy_violation")` + - `String agentName` - - `INVALID_IMAGE_MODE("invalid_image_mode")` + The canonical name of the agent that produced this item. - - `IMAGE_FILE_TOO_LARGE("image_file_too_large")` + - `Optional caller` - - `UNSUPPORTED_IMAGE_MEDIA_TYPE("unsupported_image_media_type")` + The execution context that produced this tool call. - - `EMPTY_IMAGE_FILE("empty_image_file")` + - `JsonValue;` - - `FAILED_TO_DOWNLOAD_IMAGE("failed_to_download_image")` + - `JsonValue; type "direct"constant` - - `IMAGE_FILE_NOT_FOUND("image_file_not_found")` + - `DIRECT("direct")` - - `String message` + - `class Program:` - A human-readable description of the error. + - `String callerId` - - `Optional incompleteDetails` + The call ID of the program item that produced this tool call. - Details about why the response is incomplete. + - `JsonValue; type "program"constant` - - `Optional reason` + - `PROGRAM("program")` - The reason why the response is incomplete. + - `Optional namespace` - - `MAX_OUTPUT_TOKENS("max_output_tokens")` + The namespace of the function to run. - - `CONTENT_FILTER("content_filter")` + - `Optional status` - - `Optional instructions` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A system (or developer) message inserted into the model's context. + - `IN_PROGRESS("in_progress")` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `COMPLETED("completed")` - - `String` + - `INCOMPLETE("incomplete")` - - `List` + - `FunctionCallOutput` - - `class BetaEasyInputMessage:` + - `String callId` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The unique ID of the function tool call generated by the model. - - `Content content` + - `Output output` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + Text, image, or file output of the function tool call. - `String` - - `List` + - `List` - - `class BetaResponseInputText:` + - `class BetaResponseInputTextContent:` A text input to the model. @@ -132032,11 +144023,17 @@ public final class Main { - `EXPLICIT("explicit")` - - `class BetaResponseInputImage:` + - `class BetaResponseInputImageContent:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `Detail detail` + - `JsonValue; type "input_image"constant` + + The type of the input item. Always `input_image`. + + - `INPUT_IMAGE("input_image")` + + - `Optional detail` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. @@ -132048,12 +144045,6 @@ public final class Main { - `ORIGINAL("original")` - - `JsonValue; type "input_image"constant` - - The type of the input item. Always `input_image`. - - - `INPUT_IMAGE("input_image")` - - `Optional fileId` The ID of the file to be sent to the model. @@ -132072,7 +144063,7 @@ public final class Main { - `EXPLICIT("explicit")` - - `class BetaResponseInputFile:` + - `class BetaResponseInputFileContent:` A file input to the model. @@ -132094,7 +144085,7 @@ public final class Main { - `Optional fileData` - The content of the file to be sent to the model. + The base64-encoded data of the file to be sent to the model. - `Optional fileId` @@ -132118,61 +144109,103 @@ public final class Main { - `EXPLICIT("explicit")` - - `Role role` + - `JsonValue; type "function_call_output"constant` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The type of the function tool call output. Always `function_call_output`. - - `USER("user")` + - `FUNCTION_CALL_OUTPUT("function_call_output")` - - `ASSISTANT("assistant")` + - `Optional id` - - `SYSTEM("system")` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `DEVELOPER("developer")` + - `Optional agent` - - `Optional phase` + The agent that produced this item. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `String agentName` - - `COMMENTARY("commentary")` + The canonical name of the agent that produced this item. - - `Optional type` + - `Optional caller` - The type of the message input. Always `message`. + The execution context that produced this tool call. - - `MESSAGE("message")` + - `JsonValue;` - - `Message` + - `JsonValue; type "direct"constant` - - `List content` + The caller type. Always `direct`. - A list of one or many input items to the model, containing different content - types. + - `DIRECT("direct")` - - `class BetaResponseInputText:` + - `class Program:` + + - `String callerId` + + The call ID of the program item that produced this tool call. + + - `JsonValue; type "program"constant` + + The caller type. Always `program`. + + - `PROGRAM("program")` + + - `Optional 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")` + + - `AgentMessage` + + - `String author` + + The sending agent identity. + + - `List content` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent:` A text input to the model. - - `class BetaResponseInputImage:` + - `class BetaResponseInputImageContent:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `class BetaResponseInputFile:` + - `class EncryptedContent:` - A file input to the model. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `Role role` + - `String encryptedContent` - The role of the message input. One of `user`, `system`, or `developer`. + Opaque encrypted content. - - `USER("user")` + - `JsonValue; type "encrypted_content"constant` - - `SYSTEM("system")` + The type of the input item. Always `encrypted_content`. - - `DEVELOPER("developer")` + - `ENCRYPTED_CONTENT("encrypted_content")` + + - `String recipient` + + The destination agent identity. + + - `JsonValue; type "agent_message"constant` + + The item type. Always `agent_message`. + + - `AGENT_MESSAGE("agent_message")` + + - `Optional id` + + The unique ID of this agent message item. - `Optional agent` @@ -132182,46 +144215,91 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional status` + - `MultiAgentCall` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Action action` - - `IN_PROGRESS("in_progress")` + The multi-agent action that was executed. - - `COMPLETED("completed")` + - `SPAWN_AGENT("spawn_agent")` - - `INCOMPLETE("incomplete")` + - `INTERRUPT_AGENT("interrupt_agent")` - - `Optional type` + - `LIST_AGENTS("list_agents")` - The type of the message input. Always set to `message`. + - `SEND_MESSAGE("send_message")` - - `MESSAGE("message")` + - `FOLLOWUP_TASK("followup_task")` - - `class BetaResponseOutputMessage:` + - `WAIT_AGENT("wait_agent")` - An output message from the model. + - `String arguments` - - `String id` + The action arguments as a JSON string. - The unique ID of the output message. + - `String callId` - - `List content` + The unique ID linking this call to its output. - The content of the output message. + - `JsonValue; type "multi_agent_call"constant` - - `class BetaResponseOutputText:` + The item type. Always `multi_agent_call`. - A text output from the model. + - `MULTI_AGENT_CALL("multi_agent_call")` - - `List annotations` + - `Optional id` - The annotations of the text output. + The unique ID of this multi-agent call. - - `class FileCitation:` + - `Optional agent` - A citation to a file. + The agent that produced this item. + + - `String agentName` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput` + + - `Action action` + + The multi-agent action that produced this result. + + - `SPAWN_AGENT("spawn_agent")` + + - `INTERRUPT_AGENT("interrupt_agent")` + + - `LIST_AGENTS("list_agents")` + + - `SEND_MESSAGE("send_message")` + + - `FOLLOWUP_TASK("followup_task")` + + - `WAIT_AGENT("wait_agent")` + + - `String callId` + + The unique ID of the multi-agent call. + + - `List output` + + Text output returned by the multi-agent action. + + - `String text` + + The text content. + + - `JsonValue; type "output_text"constant` + + The content type. Always `output_text`. + + - `OUTPUT_TEXT("output_text")` + + - `Optional annotations` + + Citations associated with the text content. + + - `List` - `String fileId` @@ -132237,51 +144315,47 @@ public final class Main { - `JsonValue; type "file_citation"constant` - The type of the file citation. Always `file_citation`. + The citation type. Always `file_citation`. - `FILE_CITATION("file_citation")` - - `class UrlCitation:` - - A citation for a web resource used to generate a model response. + - `List` - `long endIndex` - The index of the last character of the URL citation in the message. + The index of the last character of the citation in the message. - `long startIndex` - The index of the first character of the URL citation in the message. + The index of the first character of the citation in the message. - `String title` - The title of the web resource. + The title of the cited resource. - `JsonValue; type "url_citation"constant` - The type of the URL citation. Always `url_citation`. + The citation type. Always `url_citation`. - `URL_CITATION("url_citation")` - `String url` - The URL of the web resource. - - - `class ContainerFileCitation:` + The URL of the cited resource. - A citation for a container file used to generate a model response. + - `List` - `String containerId` - The ID of the container file. + The ID of the container. - `long endIndex` - The index of the last character of the container file citation in the message. + The index of the last character of the citation in the message. - `String fileId` - The ID of the file. + The ID of the container file. - `String filename` @@ -132289,164 +144363,184 @@ public final class Main { - `long startIndex` - The index of the first character of the container file citation in the message. + The index of the first character of the citation in the message. - `JsonValue; type "container_file_citation"constant` - The type of the container file citation. Always `container_file_citation`. + The citation type. Always `container_file_citation`. - `CONTAINER_FILE_CITATION("container_file_citation")` - - `class FilePath:` + - `JsonValue; type "multi_agent_call_output"constant` - A path to a file. + The item type. Always `multi_agent_call_output`. - - `String fileId` + - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - The ID of the file. + - `Optional id` - - `long index` + The unique ID of this multi-agent call output. - The index of the file in the list of files. + - `Optional agent` - - `JsonValue; type "file_path"constant` + The agent that produced this item. - The type of the file path. Always `file_path`. + - `String agentName` - - `FILE_PATH("file_path")` + The canonical name of the agent that produced this item. - - `String text` + - `ToolSearchCall` - The text output from the model. + - `JsonValue arguments` - - `JsonValue; type "output_text"constant` + The arguments supplied to the tool search call. - The type of the output text. Always `output_text`. + - `JsonValue; type "tool_search_call"constant` - - `OUTPUT_TEXT("output_text")` + The item type. Always `tool_search_call`. - - `Optional> logprobs` + - `TOOL_SEARCH_CALL("tool_search_call")` - - `String token` + - `Optional id` - - `List bytes` + The unique ID of this tool search call. - - `double logprob` + - `Optional agent` - - `List topLogprobs` + The agent that produced this item. - - `String token` + - `String agentName` - - `List bytes` + The canonical name of the agent that produced this item. - - `double logprob` + - `Optional callId` - - `class BetaResponseOutputRefusal:` + The unique ID of the tool search call generated by the model. - A refusal from the model. + - `Optional execution` - - `String refusal` + Whether tool search was executed by the server or by the client. - The refusal explanation from the model. + - `SERVER("server")` - - `JsonValue; type "refusal"constant` + - `CLIENT("client")` - The type of the refusal. Always `refusal`. + - `Optional status` - - `REFUSAL("refusal")` + The status of the tool search call. - - `JsonValue; role "assistant"constant` + - `IN_PROGRESS("in_progress")` - The role of the output message. Always `assistant`. + - `COMPLETED("completed")` - - `ASSISTANT("assistant")` + - `INCOMPLETE("incomplete")` - - `Status status` + - `class BetaResponseToolSearchOutputItemParam:` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `List tools` - - `IN_PROGRESS("in_progress")` + The loaded tool definitions returned by the tool search output. - - `COMPLETED("completed")` + - `class BetaFunctionTool:` - - `INCOMPLETE("incomplete")` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `JsonValue; type "message"constant` + - `String name` - The type of the output message. Always `message`. + The name of the function to call. - - `MESSAGE("message")` + - `Optional parameters` - - `Optional agent` + A JSON schema object describing the parameters of the function. - The agent that produced this item. + - `Optional strict` - - `String agentName` + Whether strict parameter validation is enforced for this function tool. - The canonical name of the agent that produced this item. + - `JsonValue; type "function"constant` - - `Optional phase` + The type of the function tool. Always `function`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `FUNCTION("function")` - - `COMMENTARY("commentary")` + - `Optional> allowedCallers` - - `class BetaResponseFileSearchToolCall:` + The tool invocation context(s). - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `DIRECT("direct")` - - `String id` + - `PROGRAMMATIC("programmatic")` - The unique ID of the file search tool call. + - `Optional deferLoading` - - `List queries` + Whether this function is deferred and loaded via tool search. - The queries used to search for files. + - `Optional description` - - `Status status` + A description of the function. Used by the model to determine whether or not to call the function. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `Optional outputSchema` - - `IN_PROGRESS("in_progress")` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `SEARCHING("searching")` + - `class BetaFileSearchTool:` - - `COMPLETED("completed")` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `INCOMPLETE("incomplete")` + - `JsonValue; type "file_search"constant` - - `FAILED("failed")` + The type of the file search tool. Always `file_search`. - - `JsonValue; type "file_search_call"constant` + - `FILE_SEARCH("file_search")` - The type of the file search tool call. Always `file_search_call`. + - `List vectorStoreIds` - - `FILE_SEARCH_CALL("file_search_call")` + The IDs of the vector stores to search. - - `Optional agent` + - `Optional filters` - The agent that produced this item. + A filter to apply. - - `String agentName` + - `class ComparisonFilter:` - The canonical name of the agent that produced this item. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `Optional> results` + - `String key` - The results of the file search tool call. + The key to compare against the value. - - `Optional attributes` + - `Type type` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + 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` @@ -132454,938 +144548,1082 @@ public final class Main { - `boolean` - - `Optional fileId` + - `List` - The unique ID of the file. + - `String` - - `Optional filename` + - `double` - The name of the file. + - `class CompoundFilter:` - - `Optional score` + Combine multiple filters using `and` or `or`. - The relevance score of the file - a value between 0 and 1. + - `List filters` - - `Optional text` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The text that was retrieved from the file. + - `class ComparisonFilter:` - - `class BetaResponseComputerToolCall:` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `String key` - - `String id` + The key to compare against the value. - The unique ID of the computer call. + - `Type type` - - `String callId` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - An identifier used when responding to the tool call with output. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `List pendingSafetyChecks` + - `EQ("eq")` - The pending safety checks for the computer call. + - `NE("ne")` - - `String id` + - `GT("gt")` - The ID of the pending safety check. + - `GTE("gte")` - - `Optional code` + - `LT("lt")` - The type of the pending safety check. + - `LTE("lte")` - - `Optional message` + - `IN("in")` - Details about the pending safety check. + - `NIN("nin")` - - `Status status` + - `Value value` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The value to compare against the attribute key; supports string, number, or boolean types. - - `IN_PROGRESS("in_progress")` + - `String` - - `COMPLETED("completed")` + - `double` - - `INCOMPLETE("incomplete")` + - `boolean` + + - `List` + + - `String` + + - `double` + + - `JsonValue` - `Type type` - The type of the computer call. Always `computer_call`. + Type of operation: `and` or `or`. - - `COMPUTER_CALL("computer_call")` + - `AND("and")` - - `Optional action` + - `OR("or")` - A click action. + - `Optional maxNumResults` - - `Click` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `Button button` + - `Optional rankingOptions` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Ranking options for search. - - `LEFT("left")` + - `Optional hybridSearch` - - `RIGHT("right")` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `WHEEL("wheel")` + - `double embeddingWeight` - - `BACK("back")` + The weight of the embedding in the reciprocal ranking fusion. - - `FORWARD("forward")` + - `double textWeight` - - `JsonValue; type "click"constant` + The weight of the text in the reciprocal ranking fusion. - Specifies the event type. For a click action, this property is always `click`. + - `Optional ranker` - - `CLICK("click")` + The ranker to use for the file search. - - `long x` + - `AUTO("auto")` - The x-coordinate where the click occurred. + - `DEFAULT_2024_11_15("default-2024-11-15")` - - `long y` + - `Optional scoreThreshold` - The y-coordinate where the click occurred. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `Optional> keys` + - `class BetaComputerTool:` - The keys being held while clicking. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `DoubleClick` + - `JsonValue; type "computer"constant` - - `Optional> keys` + The type of the computer tool. Always `computer`. - The keys being held while double-clicking. + - `COMPUTER("computer")` - - `JsonValue; type "double_click"constant` + - `class BetaComputerUsePreviewTool:` - Specifies the event type. For a double click action, this property is always set to `double_click`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `DOUBLE_CLICK("double_click")` + - `long displayHeight` - - `long x` + The height of the computer display. - The x-coordinate where the double click occurred. + - `long displayWidth` - - `long y` + The width of the computer display. - The y-coordinate where the double click occurred. + - `Environment environment` - - `Drag` + The type of computer environment to control. - - `List path` + - `WINDOWS("windows")` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `MAC("mac")` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `LINUX("linux")` - - `long x` + - `UBUNTU("ubuntu")` - The x-coordinate. + - `BROWSER("browser")` - - `long y` + - `JsonValue; type "computer_use_preview"constant` - The y-coordinate. + The type of the computer use tool. Always `computer_use_preview`. - - `JsonValue; type "drag"constant` + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `class BetaWebSearchTool:` - - `DRAG("drag")` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `Optional> keys` + - `Type type` - The keys being held while dragging the mouse. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `Keypress` + - `WEB_SEARCH("web_search")` - - `List keys` + - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `Optional filters` - - `JsonValue; type "keypress"constant` + Filters for the search. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `Optional> allowedDomains` - - `KEYPRESS("keypress")` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `Move` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `JsonValue; type "move"constant` + - `Optional searchContextSize` - Specifies the event type. For a move action, this property is always set to `move`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `MOVE("move")` + - `LOW("low")` - - `long x` + - `MEDIUM("medium")` - The x-coordinate to move to. + - `HIGH("high")` - - `long y` + - `Optional userLocation` - The y-coordinate to move to. + The approximate location of the user. - - `Optional> keys` + - `Optional city` - The keys being held while moving the mouse. + Free text input for the city of the user, e.g. `San Francisco`. - - `JsonValue;` + - `Optional country` - - `JsonValue; type "screenshot"constant` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `Optional region` - - `SCREENSHOT("screenshot")` + Free text input for the region of the user, e.g. `California`. - - `Scroll` + - `Optional timezone` - - `long scrollX` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The horizontal scroll distance. + - `Optional type` - - `long scrollY` + The type of location approximation. Always `approximate`. - The vertical scroll distance. + - `APPROXIMATE("approximate")` - - `JsonValue; type "scroll"constant` + - `Mcp` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `String serverLabel` - - `SCROLL("scroll")` + A label for this MCP server, used to identify it in tool calls. - - `long x` + - `JsonValue; type "mcp"constant` - The x-coordinate where the scroll occurred. + The type of the MCP tool. Always `mcp`. - - `long y` + - `MCP("mcp")` - The y-coordinate where the scroll occurred. + - `Optional> allowedCallers` - - `Optional> keys` + The tool invocation context(s). - The keys being held while scrolling. + - `DIRECT("direct")` - - `Type` + - `PROGRAMMATIC("programmatic")` - - `String text` + - `Optional allowedTools` - The text to type. + List of allowed tool names or a filter object. - - `JsonValue; type "type"constant` + - `List` - Specifies the event type. For a type action, this property is always set to `type`. + - `class McpToolFilter:` - - `TYPE("type")` + A filter object to specify which tools are allowed. - - `JsonValue;` + - `Optional readOnly` - - `JsonValue; type "wait"constant` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `Optional> toolNames` - - `WAIT("wait")` + List of allowed tool names. - - `Optional> actions` + - `Optional authorization` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + 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. - - `Click` + - `Optional connectorId` - - `DoubleClick` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - `Drag` + Currently supported `connector_id` values are: - - `Keypress` + - 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` - - `Move` + - `CONNECTOR_DROPBOX("connector_dropbox")` - - `JsonValue;` + - `CONNECTOR_GMAIL("connector_gmail")` - - `Scroll` + - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - - `Type` + - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - - `JsonValue;` + - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - - `Optional agent` + - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - The agent that produced this item. + - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - - `String agentName` + - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - The canonical name of the agent that produced this item. + - `Optional deferLoading` - - `ComputerCallOutput` + Whether this MCP tool is deferred and discovered via tool search. - - `String callId` + - `Optional headers` - The ID of the computer tool call that produced the output. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `Optional requireApproval` - A computer screenshot image used with the computer use tool. + Specify which of the MCP server's tools require approval. - - `JsonValue; type "computer_screenshot"constant` + - `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` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> toolNames` + + List of allowed tool names. + + - `Optional never` + + A filter object to specify which tools are allowed. + + - `Optional readOnly` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `Optional> 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 serverDescription` + + Optional description of the MCP server, used to provide more context. + + - `Optional serverUrl` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `Optional tunnelId` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter` + + - `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> fileIds` + + An optional list of uploaded files to make available to your code. + + - `Optional memoryLimit` + + The memory limit for the code interpreter container. + + - `_1G("1g")` + + - `_4G("4g")` + + - `_16G("16g")` + + - `_64G("64g")` + + - `Optional networkPolicy` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled:` + + - `JsonValue; type "disabled"constant` + + Disable outbound network access. Always `disabled`. + + - `DISABLED("disabled")` + + - `class BetaContainerNetworkPolicyAllowlist:` + + - `List allowedDomains` + + A list of allowed domains when type is `allowlist`. + + - `JsonValue; type "allowlist"constant` + + Allow outbound network access only to specified domains. Always `allowlist`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `ALLOWLIST("allowlist")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `Optional> domainSecrets` - - `Optional fileId` + Optional domain-scoped secrets for allowlisted domains. - The identifier of an uploaded file that contains the screenshot. + - `String domain` - - `Optional imageUrl` + The domain associated with the secret. - The URL of the screenshot image. + - `String name` - - `JsonValue; type "computer_call_output"constant` + The name of the secret to inject for the domain. - The type of the computer tool call output. Always `computer_call_output`. + - `String value` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + The secret value to inject for the domain. - - `Optional id` + - `JsonValue; type "code_interpreter"constant` - The ID of the computer tool call output. + The type of the code interpreter tool. Always `code_interpreter`. - - `Optional> acknowledgedSafetyChecks` + - `CODE_INTERPRETER("code_interpreter")` - The safety checks reported by the API that have been acknowledged by the developer. + - `Optional> allowedCallers` - - `String id` + The tool invocation context(s). - The ID of the pending safety check. + - `DIRECT("direct")` - - `Optional code` + - `PROGRAMMATIC("programmatic")` - The type of the pending safety check. + - `JsonValue;` - - `Optional message` + - `JsonValue; type "programmatic_tool_calling"constant` - Details about the pending safety check. + The type of the tool. Always `programmatic_tool_calling`. - - `Optional agent` + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - The agent that produced this item. + - `ImageGeneration` - - `String agentName` + - `JsonValue; type "image_generation"constant` - The canonical name of the agent that produced this item. + The type of the image generation tool. Always `image_generation`. - - `Optional status` + - `IMAGE_GENERATION("image_generation")` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `Optional action` - - `IN_PROGRESS("in_progress")` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `COMPLETED("completed")` + - `GENERATE("generate")` - - `INCOMPLETE("incomplete")` + - `EDIT("edit")` - - `class BetaResponseFunctionWebSearch:` + - `AUTO("auto")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `Optional background` - - `String id` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - The unique ID of the web search tool call. + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `Action action` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - 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). + - `TRANSPARENT("transparent")` - - `class Search:` + - `OPAQUE("opaque")` - Action type "search" - Performs a web search query. + - `AUTO("auto")` - - `JsonValue; type "search"constant` + - `Optional inputFidelity` - The action type. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `SEARCH("search")` + - `HIGH("high")` - - `Optional> queries` + - `LOW("low")` - The search queries. + - `Optional inputImageMask` - - `Optional query` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The search query. + - `Optional fileId` - - `Optional> sources` + File ID for the mask image. - The sources used in the search. + - `Optional imageUrl` - - `JsonValue; type "url"constant` + Base64-encoded mask image. - The type of source. Always `url`. + - `Optional model` - - `URL("url")` + The image generation model to use. Default: `gpt-image-1`. - - `String url` + - `GPT_IMAGE_1("gpt-image-1")` - The URL of the source. + - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - - `class OpenPage:` + - `GPT_IMAGE_2("gpt-image-2")` - Action type "open_page" - Opens a specific URL from search results. + - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - - `JsonValue; type "open_page"constant` + - `GPT_IMAGE_1_5("gpt-image-1.5")` - The action type. + - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - - `OPEN_PAGE("open_page")` + - `Optional moderation` - - `Optional url` + Moderation level for the generated image. Default: `auto`. - The URL opened by the model. + - `AUTO("auto")` - - `class FindInPage:` + - `LOW("low")` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `Optional outputCompression` - - `String pattern` + Compression level for the output image. Default: 100. - The pattern or text to search for within the page. + - `Optional outputFormat` - - `JsonValue; type "find_in_page"constant` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The action type. + - `PNG("png")` - - `FIND_IN_PAGE("find_in_page")` + - `WEBP("webp")` - - `String url` + - `JPEG("jpeg")` - The URL of the page searched for the pattern. + - `Optional partialImages` - - `Status status` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The status of the web search tool call. + - `Optional quality` - - `IN_PROGRESS("in_progress")` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `SEARCHING("searching")` + - `LOW("low")` - - `COMPLETED("completed")` + - `MEDIUM("medium")` - - `FAILED("failed")` + - `HIGH("high")` - - `JsonValue; type "web_search_call"constant` + - `AUTO("auto")` - The type of the web search tool call. Always `web_search_call`. + - `Optional size` - - `WEB_SEARCH_CALL("web_search_call")` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `Optional agent` + - `_1024X1024("1024x1024")` - The agent that produced this item. + - `_1024X1536("1024x1536")` - - `String agentName` + - `_1536X1024("1536x1024")` - The canonical name of the agent that produced this item. + - `AUTO("auto")` - - `class BetaResponseFunctionToolCall:` + - `JsonValue;` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `JsonValue; type "local_shell"constant` - - `String arguments` + The type of the local shell tool. Always `local_shell`. - A JSON string of the arguments to pass to the function. + - `LOCAL_SHELL("local_shell")` - - `String callId` + - `class BetaFunctionShellTool:` - The unique ID of the function tool call generated by the model. + A tool that allows the model to execute shell commands. - - `String name` + - `JsonValue; type "shell"constant` - The name of the function to run. + The type of the shell tool. Always `shell`. - - `JsonValue; type "function_call"constant` + - `SHELL("shell")` - The type of the function tool call. Always `function_call`. + - `Optional> allowedCallers` - - `FUNCTION_CALL("function_call")` + The tool invocation context(s). - - `Optional id` + - `DIRECT("direct")` - The unique ID of the function tool call. + - `PROGRAMMATIC("programmatic")` - - `Optional agent` + - `Optional environment` - The agent that produced this item. + - `class BetaContainerAuto:` - - `String agentName` + - `JsonValue; type "container_auto"constant` - The canonical name of the agent that produced this item. + Automatically creates a container for this request - - `Optional caller` + - `CONTAINER_AUTO("container_auto")` - The execution context that produced this tool call. + - `Optional> fileIds` - - `JsonValue;` + An optional list of uploaded files to make available to your code. - - `JsonValue; type "direct"constant` + - `Optional memoryLimit` - - `DIRECT("direct")` + The memory limit for the container. - - `class Program:` + - `_1G("1g")` - - `String callerId` + - `_4G("4g")` - The call ID of the program item that produced this tool call. + - `_16G("16g")` - - `JsonValue; type "program"constant` + - `_64G("64g")` - - `PROGRAM("program")` + - `Optional networkPolicy` - - `Optional namespace` + Network access policy for the container. - The namespace of the function to run. + - `class BetaContainerNetworkPolicyDisabled:` - - `Optional status` + - `class BetaContainerNetworkPolicyAllowlist:` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional> skills` - - `IN_PROGRESS("in_progress")` + An optional list of skills referenced by id or inline data. - - `COMPLETED("completed")` + - `class BetaSkillReference:` - - `INCOMPLETE("incomplete")` + - `String skillId` - - `FunctionCallOutput` + The ID of the referenced skill. - - `String callId` + - `JsonValue; type "skill_reference"constant` - The unique ID of the function tool call generated by the model. + References a skill created with the /v1/skills endpoint. - - `Output output` + - `SKILL_REFERENCE("skill_reference")` - Text, image, or file output of the function tool call. + - `Optional version` - - `String` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `List` + - `class BetaInlineSkill:` - - `class BetaResponseInputTextContent:` + - `String description` - A text input to the model. + The description of the skill. - - `String text` + - `String name` - The text input to the model. + The name of the skill. - - `JsonValue; type "input_text"constant` + - `BetaInlineSkillSource source` - The type of the input item. Always `input_text`. + Inline skill payload - - `INPUT_TEXT("input_text")` + - `String data` - - `Optional promptCacheBreakpoint` + Base64-encoded skill zip bundle. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; mediaType "application/zip"constant` - - `JsonValue; mode "explicit"constant` + The media type of the inline skill payload. Must be `application/zip`. - The breakpoint mode. Always `explicit`. + - `APPLICATION_ZIP("application/zip")` - - `EXPLICIT("explicit")` + - `JsonValue; type "base64"constant` - - `class BetaResponseInputImageContent:` + The type of the inline skill source. Must be `base64`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `BASE64("base64")` - - `JsonValue; type "input_image"constant` + - `JsonValue; type "inline"constant` - The type of the input item. Always `input_image`. + Defines an inline skill for this request. - - `INPUT_IMAGE("input_image")` + - `INLINE("inline")` - - `Optional detail` + - `class BetaLocalEnvironment:` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `JsonValue; type "local"constant` - - `LOW("low")` + Use a local computer environment. - - `HIGH("high")` + - `LOCAL("local")` - - `AUTO("auto")` + - `Optional> skills` - - `ORIGINAL("original")` + An optional list of skills. - - `Optional fileId` + - `String description` - The ID of the file to be sent to the model. + The description of the skill. - - `Optional imageUrl` + - `String name` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The name of the skill. - - `Optional promptCacheBreakpoint` + - `String path` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The path to the directory containing the skill. - - `JsonValue; mode "explicit"constant` + - `class BetaContainerReference:` - The breakpoint mode. Always `explicit`. + - `String containerId` - - `EXPLICIT("explicit")` + The ID of the referenced container. - - `class BetaResponseInputFileContent:` + - `JsonValue; type "container_reference"constant` - A file input to the model. + References a container created with the /v1/containers endpoint - - `JsonValue; type "input_file"constant` + - `CONTAINER_REFERENCE("container_reference")` - The type of the input item. Always `input_file`. + - `class BetaCustomTool:` - - `INPUT_FILE("input_file")` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `Optional detail` + - `String name` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The name of the custom tool, used to identify it in tool calls. - - `AUTO("auto")` + - `JsonValue; type "custom"constant` - - `LOW("low")` + The type of the custom tool. Always `custom`. - - `HIGH("high")` + - `CUSTOM("custom")` - - `Optional fileData` + - `Optional> allowedCallers` - The base64-encoded data of the file to be sent to the model. + The tool invocation context(s). - - `Optional fileId` + - `DIRECT("direct")` - The ID of the file to be sent to the model. + - `PROGRAMMATIC("programmatic")` - - `Optional fileUrl` + - `Optional deferLoading` - The URL of the file to be sent to the model. + Whether this tool should be deferred and discovered via tool search. - - `Optional filename` + - `Optional description` - The name of the file to be sent to the model. + Optional description of the custom tool, used to provide more context. - - `Optional promptCacheBreakpoint` + - `Optional format` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The input format for the custom tool. Default is unconstrained text. - - `JsonValue; mode "explicit"constant` + - `JsonValue;` - The breakpoint mode. Always `explicit`. + - `JsonValue; type "text"constant` - - `EXPLICIT("explicit")` + Unconstrained text format. Always `text`. - - `JsonValue; type "function_call_output"constant` + - `TEXT("text")` - The type of the function tool call output. Always `function_call_output`. + - `class Grammar:` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + A grammar defined by the user. - - `Optional id` + - `String definition` - The unique ID of the function tool call output. Populated when this item is returned via API. + The grammar definition. - - `Optional agent` + - `Syntax syntax` - The agent that produced this item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `String agentName` + - `LARK("lark")` - The canonical name of the agent that produced this item. + - `REGEX("regex")` - - `Optional caller` + - `JsonValue; type "grammar"constant` - The execution context that produced this tool call. + Grammar format. Always `grammar`. - - `JsonValue;` + - `GRAMMAR("grammar")` - - `JsonValue; type "direct"constant` + - `class BetaNamespaceTool:` - The caller type. Always `direct`. + Groups function/custom tools under a shared namespace. - - `DIRECT("direct")` + - `String description` - - `class Program:` + A description of the namespace shown to the model. - - `String callerId` + - `String name` - The call ID of the program item that produced this tool call. + The namespace name used in tool calls (for example, `crm`). - - `JsonValue; type "program"constant` + - `List tools` - The caller type. Always `program`. + The function/custom tools available inside this namespace. - - `PROGRAM("program")` + - `class Function:` - - `Optional status` + - `String name` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `JsonValue; type "function"constant` - - `IN_PROGRESS("in_progress")` + - `FUNCTION("function")` - - `COMPLETED("completed")` + - `Optional> allowedCallers` - - `INCOMPLETE("incomplete")` + The tool invocation context(s). - - `AgentMessage` + - `DIRECT("direct")` - - `String author` + - `PROGRAMMATIC("programmatic")` - The sending agent identity. + - `Optional deferLoading` - - `List content` + Whether this function should be deferred and discovered via tool search. - Plaintext, image, or encrypted content sent between agents. + - `Optional description` - - `class BetaResponseInputTextContent:` + - `Optional outputSchema` - A text input to the model. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `class BetaResponseInputImageContent:` + - `Optional parameters` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `Optional strict` - - `class EncryptedContent:` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `class BetaCustomTool:` - - `String encryptedContent` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - Opaque encrypted content. + - `JsonValue; type "namespace"constant` - - `JsonValue; type "encrypted_content"constant` + The type of the tool. Always `namespace`. - The type of the input item. Always `encrypted_content`. + - `NAMESPACE("namespace")` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `class BetaToolSearchTool:` - - `String recipient` + Hosted or BYOT tool search configuration for deferred tools. - The destination agent identity. + - `JsonValue; type "tool_search"constant` - - `JsonValue; type "agent_message"constant` + The type of the tool. Always `tool_search`. - The item type. Always `agent_message`. + - `TOOL_SEARCH("tool_search")` - - `AGENT_MESSAGE("agent_message")` + - `Optional description` - - `Optional id` + Description shown to the model for a client-executed tool search tool. - The unique ID of this agent message item. + - `Optional execution` - - `Optional agent` + Whether tool search is executed by the server or by the client. - The agent that produced this item. + - `SERVER("server")` - - `String agentName` + - `CLIENT("client")` - The canonical name of the agent that produced this item. + - `Optional parameters` - - `MultiAgentCall` + Parameter schema for a client-executed tool search tool. - - `Action action` + - `class BetaWebSearchPreviewTool:` - The multi-agent action that was executed. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `SPAWN_AGENT("spawn_agent")` + - `Type type` - - `INTERRUPT_AGENT("interrupt_agent")` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `LIST_AGENTS("list_agents")` + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `SEND_MESSAGE("send_message")` + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `FOLLOWUP_TASK("followup_task")` + - `Optional> searchContentTypes` - - `WAIT_AGENT("wait_agent")` + - `TEXT("text")` - - `String arguments` + - `IMAGE("image")` - The action arguments as a JSON string. + - `Optional searchContextSize` - - `String callId` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The unique ID linking this call to its output. + - `LOW("low")` - - `JsonValue; type "multi_agent_call"constant` + - `MEDIUM("medium")` - The item type. Always `multi_agent_call`. + - `HIGH("high")` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `Optional userLocation` - - `Optional id` + The user's location. - The unique ID of this multi-agent call. + - `JsonValue; type "approximate"constant` - - `Optional agent` + The type of location approximation. Always `approximate`. - The agent that produced this item. + - `APPROXIMATE("approximate")` - - `String agentName` + - `Optional city` - The canonical name of the agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `MultiAgentCallOutput` + - `Optional country` - - `Action action` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The multi-agent action that produced this result. + - `Optional region` - - `SPAWN_AGENT("spawn_agent")` + Free text input for the region of the user, e.g. `California`. - - `INTERRUPT_AGENT("interrupt_agent")` + - `Optional timezone` - - `LIST_AGENTS("list_agents")` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `SEND_MESSAGE("send_message")` + - `class BetaApplyPatchTool:` - - `FOLLOWUP_TASK("followup_task")` + Allows the assistant to create, delete, or update files using unified diffs. - - `WAIT_AGENT("wait_agent")` + - `JsonValue; type "apply_patch"constant` - - `String callId` + The type of the tool. Always `apply_patch`. - The unique ID of the multi-agent call. + - `APPLY_PATCH("apply_patch")` - - `List output` + - `Optional> allowedCallers` - Text output returned by the multi-agent action. + The tool invocation context(s). - - `String text` + - `DIRECT("direct")` - The text content. + - `PROGRAMMATIC("programmatic")` - - `JsonValue; type "output_text"constant` + - `JsonValue; type "tool_search_output"constant` - The content type. Always `output_text`. + The item type. Always `tool_search_output`. - - `OUTPUT_TEXT("output_text")` + - `TOOL_SEARCH_OUTPUT("tool_search_output")` - - `Optional annotations` + - `Optional id` - Citations associated with the text content. + The unique ID of this tool search output. - - `List` + - `Optional agent` - - `String fileId` + The agent that produced this item. - The ID of the file. + - `String agentName` - - `String filename` + The canonical name of the agent that produced this item. - The filename of the file cited. + - `Optional callId` - - `long index` + The unique ID of the tool search call generated by the model. - The index of the file in the list of files. + - `Optional execution` - - `JsonValue; type "file_citation"constant` + Whether tool search was executed by the server or by the client. - The citation type. Always `file_citation`. + - `SERVER("server")` - - `FILE_CITATION("file_citation")` + - `CLIENT("client")` - - `List` + - `Optional status` - - `long endIndex` + The status of the tool search output. - The index of the last character of the citation in the message. + - `IN_PROGRESS("in_progress")` - - `long startIndex` + - `COMPLETED("completed")` - The index of the first character of the citation in the message. + - `INCOMPLETE("incomplete")` - - `String title` + - `AdditionalTools` - The title of the cited resource. + - `JsonValue; role "developer"constant` - - `JsonValue; type "url_citation"constant` + The role that provided the additional tools. Only `developer` is supported. - The citation type. Always `url_citation`. + - `DEVELOPER("developer")` - - `URL_CITATION("url_citation")` + - `List tools` - - `String url` + A list of additional tools made available at this item. - The URL of the cited resource. + - `class BetaFunctionTool:` - - `List` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `String containerId` + - `class BetaFileSearchTool:` - The ID of the container. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `long endIndex` + - `class BetaComputerTool:` - The index of the last character of the citation in the message. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String fileId` + - `class BetaComputerUsePreviewTool:` - The ID of the container file. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `String filename` + - `class BetaWebSearchTool:` - The filename of the container file cited. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `long startIndex` + - `Mcp` - The index of the first character of the citation in the message. + - `CodeInterpreter` - - `JsonValue; type "container_file_citation"constant` + - `JsonValue;` - The citation type. Always `container_file_citation`. + - `ImageGeneration` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `JsonValue;` - - `JsonValue; type "multi_agent_call_output"constant` + - `class BetaFunctionShellTool:` - The item type. Always `multi_agent_call_output`. + A tool that allows the model to execute shell commands. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `class BetaCustomTool:` - - `Optional id` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The unique ID of this multi-agent call output. + - `class BetaNamespaceTool:` - - `Optional agent` + Groups function/custom tools under a shared namespace. - The agent that produced this item. + - `class BetaToolSearchTool:` - - `String agentName` + Hosted or BYOT tool search configuration for deferred tools. - The canonical name of the agent that produced this item. + - `class BetaWebSearchPreviewTool:` - - `ToolSearchCall` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `JsonValue arguments` + - `class BetaApplyPatchTool:` - The arguments supplied to the tool search call. + Allows the assistant to create, delete, or update files using unified diffs. - - `JsonValue; type "tool_search_call"constant` + - `JsonValue; type "additional_tools"constant` - The item type. Always `tool_search_call`. + The item type. Always `additional_tools`. - - `TOOL_SEARCH_CALL("tool_search_call")` + - `ADDITIONAL_TOOLS("additional_tools")` - `Optional id` - The unique ID of this tool search call. + The unique ID of this additional tools item. - `Optional agent` @@ -133395,1102 +145633,1059 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional callId` + - `class BetaResponseReasoningItem:` - The unique ID of the tool search call generated by the model. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `Optional execution` + - `String id` - Whether tool search was executed by the server or by the client. + The unique identifier of the reasoning content. - - `SERVER("server")` + - `List summary` - - `CLIENT("client")` + Reasoning summary content. - - `Optional status` + - `String text` - The status of the tool search call. + A summary of the reasoning output from the model so far. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "summary_text"constant` - - `COMPLETED("completed")` + The type of the object. Always `summary_text`. - - `INCOMPLETE("incomplete")` + - `SUMMARY_TEXT("summary_text")` - - `class BetaResponseToolSearchOutputItemParam:` + - `JsonValue; type "reasoning"constant` - - `List tools` + The type of the object. Always `reasoning`. - The loaded tool definitions returned by the tool search output. + - `REASONING("reasoning")` - - `class BetaFunctionTool:` + - `Optional agent` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The agent that produced this item. - - `String name` + - `String agentName` - The name of the function to call. + The canonical name of the agent that produced this item. - - `Optional parameters` + - `Optional> content` - A JSON schema object describing the parameters of the function. + Reasoning text content. - - `Optional strict` + - `String text` - Whether strict parameter validation is enforced for this function tool. + The reasoning text from the model. - - `JsonValue; type "function"constant` + - `JsonValue; type "reasoning_text"constant` - The type of the function tool. Always `function`. + The type of the reasoning text. Always `reasoning_text`. - - `FUNCTION("function")` + - `REASONING_TEXT("reasoning_text")` - - `Optional> allowedCallers` + - `Optional encryptedContent` - The tool invocation context(s). + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `DIRECT("direct")` + - `Optional status` - - `PROGRAMMATIC("programmatic")` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Optional deferLoading` + - `IN_PROGRESS("in_progress")` - Whether this function is deferred and loaded via tool search. + - `COMPLETED("completed")` - - `Optional description` + - `INCOMPLETE("incomplete")` - A description of the function. Used by the model to determine whether or not to call the function. + - `class BetaResponseCompactionItemParam:` - - `Optional outputSchema` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `String encryptedContent` - - `class BetaFileSearchTool:` + The encrypted content of the compaction summary. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `JsonValue; type "compaction"constant` - - `JsonValue; type "file_search"constant` + The type of the item. Always `compaction`. - The type of the file search tool. Always `file_search`. + - `COMPACTION("compaction")` - - `FILE_SEARCH("file_search")` + - `Optional id` - - `List vectorStoreIds` + The ID of the compaction item. - The IDs of the vector stores to search. + - `Optional agent` - - `Optional filters` + The agent that produced this item. - A filter to apply. + - `String agentName` - - `class ComparisonFilter:` + The canonical name of the agent that produced this item. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `ImageGenerationCall` - - `String key` + - `String id` - The key to compare against the value. + The unique ID of the image generation call. - - `Type type` + - `Optional result` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The generated image encoded in base64. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `Status status` - - `EQ("eq")` + The status of the image generation call. - - `NE("ne")` + - `IN_PROGRESS("in_progress")` - - `GT("gt")` + - `COMPLETED("completed")` - - `GTE("gte")` + - `GENERATING("generating")` - - `LT("lt")` + - `FAILED("failed")` - - `LTE("lte")` + - `JsonValue; type "image_generation_call"constant` - - `IN("in")` + The type of the image generation call. Always `image_generation_call`. - - `NIN("nin")` + - `IMAGE_GENERATION_CALL("image_generation_call")` - - `Value value` + - `Optional agent` - The value to compare against the attribute key; supports string, number, or boolean types. + The agent that produced this item. - - `String` + - `String agentName` - - `double` + The canonical name of the agent that produced this item. - - `boolean` + - `class BetaResponseCodeInterpreterToolCall:` - - `List` + A tool call to run code. - - `class CompoundFilter:` + - `String id` - Combine multiple filters using `and` or `or`. + The unique ID of the code interpreter tool call. - - `List filters` + - `Optional code` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The code to run, or null if not available. - - `class ComparisonFilter:` + - `String containerId` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The ID of the container used to run the code. - - `String key` + - `Optional> outputs` - The key to compare against the value. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `Type type` + - `class Logs:` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The logs output from the code interpreter. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `String logs` - - `EQ("eq")` + The logs output from the code interpreter. - - `NE("ne")` + - `JsonValue; type "logs"constant` - - `GT("gt")` + The type of the output. Always `logs`. - - `GTE("gte")` + - `LOGS("logs")` - - `LT("lt")` + - `class Image:` - - `LTE("lte")` + The image output from the code interpreter. - - `IN("in")` + - `JsonValue; type "image"constant` - - `NIN("nin")` + The type of the output. Always `image`. - - `Value value` + - `IMAGE("image")` - The value to compare against the attribute key; supports string, number, or boolean types. + - `String url` - - `String` + The URL of the image output from the code interpreter. - - `double` + - `Status status` - - `boolean` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `List` + - `IN_PROGRESS("in_progress")` - - `JsonValue` + - `COMPLETED("completed")` - - `Type type` + - `INCOMPLETE("incomplete")` - Type of operation: `and` or `or`. + - `INTERPRETING("interpreting")` - - `AND("and")` + - `FAILED("failed")` - - `OR("or")` + - `JsonValue; type "code_interpreter_call"constant` - - `Optional maxNumResults` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `CODE_INTERPRETER_CALL("code_interpreter_call")` - - `Optional rankingOptions` + - `Optional agent` - Ranking options for search. + The agent that produced this item. - - `Optional hybridSearch` + - `String agentName` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The canonical name of the agent that produced this item. - - `double embeddingWeight` + - `LocalShellCall` - The weight of the embedding in the reciprocal ranking fusion. + - `String id` - - `double textWeight` + The unique ID of the local shell call. - The weight of the text in the reciprocal ranking fusion. + - `Action action` - - `Optional ranker` + Execute a shell command on the server. - The ranker to use for the file search. + - `List command` - - `AUTO("auto")` + The command to run. - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `Env env` - - `Optional scoreThreshold` + Environment variables to set for the command. - 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. + - `JsonValue; type "exec"constant` - - `class BetaComputerTool:` + The type of the local shell action. Always `exec`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `EXEC("exec")` - - `JsonValue; type "computer"constant` + - `Optional timeoutMs` - The type of the computer tool. Always `computer`. + Optional timeout in milliseconds for the command. - - `COMPUTER("computer")` + - `Optional user` - - `class BetaComputerUsePreviewTool:` + Optional user to run the command as. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional workingDirectory` - - `long displayHeight` + Optional working directory to run the command in. - The height of the computer display. + - `String callId` - - `long displayWidth` + The unique ID of the local shell tool call generated by the model. - The width of the computer display. + - `Status status` - - `Environment environment` + The status of the local shell call. - The type of computer environment to control. + - `IN_PROGRESS("in_progress")` - - `WINDOWS("windows")` + - `COMPLETED("completed")` - - `MAC("mac")` + - `INCOMPLETE("incomplete")` - - `LINUX("linux")` + - `JsonValue; type "local_shell_call"constant` - - `UBUNTU("ubuntu")` + The type of the local shell call. Always `local_shell_call`. - - `BROWSER("browser")` + - `LOCAL_SHELL_CALL("local_shell_call")` - - `JsonValue; type "computer_use_preview"constant` + - `Optional agent` - The type of the computer use tool. Always `computer_use_preview`. + The agent that produced this item. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `String agentName` - - `class BetaWebSearchTool:` + The canonical name of the agent that produced this item. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `LocalShellCallOutput` - - `Type type` + - `String id` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The unique ID of the local shell tool call generated by the model. - - `WEB_SEARCH("web_search")` + - `String output` - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + A JSON string of the output of the local shell tool call. - - `Optional filters` + - `JsonValue; type "local_shell_call_output"constant` - Filters for the search. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `Optional> allowedDomains` + - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Optional agent` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The agent that produced this item. - - `Optional searchContextSize` + - `String agentName` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The canonical name of the agent that produced this item. - - `LOW("low")` + - `Optional status` - - `MEDIUM("medium")` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `HIGH("high")` + - `IN_PROGRESS("in_progress")` - - `Optional userLocation` + - `COMPLETED("completed")` - The approximate location of the user. + - `INCOMPLETE("incomplete")` - - `Optional city` + - `ShellCall` - Free text input for the city of the user, e.g. `San Francisco`. + - `Action action` - - `Optional country` + The shell commands and limits that describe how to run the tool call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `List commands` - - `Optional region` + Ordered shell commands for the execution environment to run. - Free text input for the region of the user, e.g. `California`. + - `Optional maxOutputLength` - - `Optional timezone` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `Optional timeoutMs` - - `Optional type` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The type of location approximation. Always `approximate`. + - `String callId` - - `APPROXIMATE("approximate")` + The unique ID of the shell tool call generated by the model. - - `Mcp` + - `JsonValue; type "shell_call"constant` - - `String serverLabel` + The type of the item. Always `shell_call`. - A label for this MCP server, used to identify it in tool calls. + - `SHELL_CALL("shell_call")` - - `JsonValue; type "mcp"constant` + - `Optional id` - The type of the MCP tool. Always `mcp`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `MCP("mcp")` + - `Optional agent` - - `Optional> allowedCallers` + The agent that produced this item. - The tool invocation context(s). + - `String agentName` - - `DIRECT("direct")` + The canonical name of the agent that produced this item. + + - `Optional caller` - - `PROGRAMMATIC("programmatic")` + The execution context that produced this tool call. - - `Optional allowedTools` + - `JsonValue;` - List of allowed tool names or a filter object. + - `JsonValue; type "direct"constant` - - `List` + The caller type. Always `direct`. - - `class McpToolFilter:` + - `DIRECT("direct")` - A filter object to specify which tools are allowed. + - `class Program:` - - `Optional readOnly` + - `String callerId` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The call ID of the program item that produced this tool call. - - `Optional> toolNames` + - `JsonValue; type "program"constant` - List of allowed tool names. + The caller type. Always `program`. - - `Optional authorization` + - `PROGRAM("program")` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `Optional environment` - - `Optional connectorId` + The environment to execute the shell commands in. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `class BetaLocalEnvironment:` - Currently supported `connector_id` values are: + - `class BetaContainerReference:` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `Optional status` - - `CONNECTOR_DROPBOX("connector_dropbox")` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `CONNECTOR_GMAIL("connector_gmail")` + - `IN_PROGRESS("in_progress")` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `COMPLETED("completed")` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `INCOMPLETE("incomplete")` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `ShellCallOutput` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `String callId` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + The unique ID of the shell tool call generated by the model. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `List output` - - `Optional deferLoading` + Captured chunks of stdout and stderr output, along with their associated outcomes. - Whether this MCP tool is deferred and discovered via tool search. + - `Outcome outcome` - - `Optional headers` + The exit or timeout outcome associated with this shell call. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `JsonValue;` - - `Optional requireApproval` + - `JsonValue; type "timeout"constant` - Specify which of the MCP server's tools require approval. + The outcome type. Always `timeout`. - - `class McpToolApprovalFilter:` + - `TIMEOUT("timeout")` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `class Exit:` - - `Optional always` + Indicates that the shell commands finished and returned an exit code. - A filter object to specify which tools are allowed. + - `long exitCode` - - `Optional readOnly` + The exit code returned by the shell process. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `JsonValue; type "exit"constant` - - `Optional> toolNames` + The outcome type. Always `exit`. - List of allowed tool names. + - `EXIT("exit")` - - `Optional never` + - `String stderr` - A filter object to specify which tools are allowed. + Captured stderr output for the shell call. - - `Optional readOnly` + - `String stdout` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Captured stdout output for the shell call. - - `Optional> toolNames` + - `JsonValue; type "shell_call_output"constant` - List of allowed tool names. + The type of the item. Always `shell_call_output`. - - `enum McpToolApprovalSetting:` + - `SHELL_CALL_OUTPUT("shell_call_output")` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `Optional id` - - `ALWAYS("always")` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `NEVER("never")` + - `Optional agent` - - `Optional serverDescription` + The agent that produced this item. - Optional description of the MCP server, used to provide more context. + - `String agentName` - - `Optional serverUrl` + The canonical name of the agent that produced this item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `Optional caller` - - `Optional tunnelId` + The execution context that produced this tool call. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `JsonValue;` - - `CodeInterpreter` + - `JsonValue; type "direct"constant` - - `Container container` + The caller type. Always `direct`. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `DIRECT("direct")` - - `String` + - `class Program:` - - `class CodeInterpreterToolAuto:` + - `String callerId` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The call ID of the program item that produced this tool call. - - `JsonValue; type "auto"constant` + - `JsonValue; type "program"constant` - Always `auto`. + The caller type. Always `program`. - - `AUTO("auto")` + - `PROGRAM("program")` - - `Optional> fileIds` + - `Optional maxOutputLength` - An optional list of uploaded files to make available to your code. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `Optional memoryLimit` + - `Optional status` - The memory limit for the code interpreter container. + The status of the shell call output. - - `_1G("1g")` + - `IN_PROGRESS("in_progress")` - - `_4G("4g")` + - `COMPLETED("completed")` - - `_16G("16g")` + - `INCOMPLETE("incomplete")` - - `_64G("64g")` + - `ApplyPatchCall` - - `Optional networkPolicy` + - `String callId` - Network access policy for the container. + The unique ID of the apply patch tool call generated by the model. - - `class BetaContainerNetworkPolicyDisabled:` + - `Operation operation` - - `JsonValue; type "disabled"constant` + The specific create, delete, or update instruction for the apply_patch tool call. - Disable outbound network access. Always `disabled`. + - `class CreateFile:` - - `DISABLED("disabled")` + Instruction for creating a new file via the apply_patch tool. - - `class BetaContainerNetworkPolicyAllowlist:` + - `String diff` - - `List allowedDomains` + Unified diff content to apply when creating the file. - A list of allowed domains when type is `allowlist`. + - `String path` - - `JsonValue; type "allowlist"constant` + Path of the file to create relative to the workspace root. - Allow outbound network access only to specified domains. Always `allowlist`. + - `JsonValue; type "create_file"constant` - - `ALLOWLIST("allowlist")` + The operation type. Always `create_file`. - - `Optional> domainSecrets` + - `CREATE_FILE("create_file")` - Optional domain-scoped secrets for allowlisted domains. + - `class DeleteFile:` - - `String domain` + Instruction for deleting an existing file via the apply_patch tool. - The domain associated with the secret. + - `String path` - - `String name` + Path of the file to delete relative to the workspace root. - The name of the secret to inject for the domain. + - `JsonValue; type "delete_file"constant` - - `String value` + The operation type. Always `delete_file`. - The secret value to inject for the domain. + - `DELETE_FILE("delete_file")` - - `JsonValue; type "code_interpreter"constant` + - `class UpdateFile:` - The type of the code interpreter tool. Always `code_interpreter`. + Instruction for updating an existing file via the apply_patch tool. - - `CODE_INTERPRETER("code_interpreter")` + - `String diff` - - `Optional> allowedCallers` + Unified diff content to apply to the existing file. - The tool invocation context(s). + - `String path` - - `DIRECT("direct")` + Path of the file to update relative to the workspace root. - - `PROGRAMMATIC("programmatic")` + - `JsonValue; type "update_file"constant` - - `JsonValue;` + The operation type. Always `update_file`. - - `JsonValue; type "programmatic_tool_calling"constant` + - `UPDATE_FILE("update_file")` - The type of the tool. Always `programmatic_tool_calling`. + - `Status status` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `ImageGeneration` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "image_generation"constant` + - `COMPLETED("completed")` - The type of the image generation tool. Always `image_generation`. + - `JsonValue; type "apply_patch_call"constant` - - `IMAGE_GENERATION("image_generation")` + The type of the item. Always `apply_patch_call`. - - `Optional action` + - `APPLY_PATCH_CALL("apply_patch_call")` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `Optional id` - - `GENERATE("generate")` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `EDIT("edit")` + - `Optional agent` - - `AUTO("auto")` + The agent that produced this item. - - `Optional background` + - `String agentName` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The canonical name of the agent that produced this item. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `Optional caller` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The execution context that produced this tool call. - - `TRANSPARENT("transparent")` + - `JsonValue;` - - `OPAQUE("opaque")` + - `JsonValue; type "direct"constant` - - `AUTO("auto")` + The caller type. Always `direct`. - - `Optional inputFidelity` + - `DIRECT("direct")` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `class Program:` - - `HIGH("high")` + - `String callerId` - - `LOW("low")` + The call ID of the program item that produced this tool call. - - `Optional inputImageMask` + - `JsonValue; type "program"constant` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The caller type. Always `program`. - - `Optional fileId` + - `PROGRAM("program")` - File ID for the mask image. + - `ApplyPatchCallOutput` - - `Optional imageUrl` + - `String callId` - Base64-encoded mask image. + The unique ID of the apply patch tool call generated by the model. - - `Optional model` + - `Status status` - The image generation model to use. Default: `gpt-image-1`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `GPT_IMAGE_1("gpt-image-1")` + - `COMPLETED("completed")` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `FAILED("failed")` - - `GPT_IMAGE_2("gpt-image-2")` + - `JsonValue; type "apply_patch_call_output"constant` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The type of the item. Always `apply_patch_call_output`. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `Optional id` - - `Optional moderation` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Moderation level for the generated image. Default: `auto`. + - `Optional agent` - - `AUTO("auto")` + The agent that produced this item. - - `LOW("low")` + - `String agentName` - - `Optional outputCompression` + The canonical name of the agent that produced this item. - Compression level for the output image. Default: 100. + - `Optional caller` - - `Optional outputFormat` + The execution context that produced this tool call. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `JsonValue;` - - `PNG("png")` + - `JsonValue; type "direct"constant` - - `WEBP("webp")` + The caller type. Always `direct`. - - `JPEG("jpeg")` + - `DIRECT("direct")` - - `Optional partialImages` + - `class Program:` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `String callerId` - - `Optional quality` + The call ID of the program item that produced this tool call. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `JsonValue; type "program"constant` - - `LOW("low")` + The caller type. Always `program`. - - `MEDIUM("medium")` + - `PROGRAM("program")` - - `HIGH("high")` + - `Optional output` - - `AUTO("auto")` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `Optional size` + - `McpListTools` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `String id` - - `_1024X1024("1024x1024")` + The unique ID of the list. - - `_1024X1536("1024x1536")` + - `String serverLabel` - - `_1536X1024("1536x1024")` + The label of the MCP server. - - `AUTO("auto")` + - `List tools` - - `JsonValue;` + The tools available on the server. - - `JsonValue; type "local_shell"constant` + - `JsonValue inputSchema` - The type of the local shell tool. Always `local_shell`. + The JSON schema describing the tool's input. - - `LOCAL_SHELL("local_shell")` + - `String name` - - `class BetaFunctionShellTool:` + The name of the tool. - A tool that allows the model to execute shell commands. + - `Optional annotations` - - `JsonValue; type "shell"constant` + Additional annotations about the tool. - The type of the shell tool. Always `shell`. + - `Optional description` - - `SHELL("shell")` + The description of the tool. - - `Optional> allowedCallers` + - `JsonValue; type "mcp_list_tools"constant` - The tool invocation context(s). + The type of the item. Always `mcp_list_tools`. - - `DIRECT("direct")` + - `MCP_LIST_TOOLS("mcp_list_tools")` - - `PROGRAMMATIC("programmatic")` + - `Optional agent` - - `Optional environment` + The agent that produced this item. - - `class BetaContainerAuto:` + - `String agentName` - - `JsonValue; type "container_auto"constant` + The canonical name of the agent that produced this item. - Automatically creates a container for this request + - `Optional error` - - `CONTAINER_AUTO("container_auto")` + Error message if the server could not list tools. - - `Optional> fileIds` + - `McpApprovalRequest` - An optional list of uploaded files to make available to your code. + - `String id` - - `Optional memoryLimit` + The unique ID of the approval request. - The memory limit for the container. + - `String arguments` - - `_1G("1g")` + A JSON string of arguments for the tool. - - `_4G("4g")` + - `String name` - - `_16G("16g")` + The name of the tool to run. - - `_64G("64g")` + - `String serverLabel` - - `Optional networkPolicy` + The label of the MCP server making the request. - Network access policy for the container. + - `JsonValue; type "mcp_approval_request"constant` - - `class BetaContainerNetworkPolicyDisabled:` + The type of the item. Always `mcp_approval_request`. - - `class BetaContainerNetworkPolicyAllowlist:` + - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - - `Optional> skills` + - `Optional agent` - An optional list of skills referenced by id or inline data. + The agent that produced this item. - - `class BetaSkillReference:` + - `String agentName` - - `String skillId` + The canonical name of the agent that produced this item. - The ID of the referenced skill. + - `McpApprovalResponse` - - `JsonValue; type "skill_reference"constant` + - `String approvalRequestId` - References a skill created with the /v1/skills endpoint. + The ID of the approval request being answered. - - `SKILL_REFERENCE("skill_reference")` + - `boolean approve` - - `Optional version` + Whether the request was approved. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `JsonValue; type "mcp_approval_response"constant` - - `class BetaInlineSkill:` + The type of the item. Always `mcp_approval_response`. - - `String description` + - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - The description of the skill. + - `Optional id` - - `String name` + The unique ID of the approval response - The name of the skill. + - `Optional agent` - - `BetaInlineSkillSource source` + The agent that produced this item. - Inline skill payload + - `String agentName` - - `String data` + The canonical name of the agent that produced this item. - Base64-encoded skill zip bundle. + - `Optional reason` - - `JsonValue; mediaType "application/zip"constant` + Optional reason for the decision. - The media type of the inline skill payload. Must be `application/zip`. + - `McpCall` - - `APPLICATION_ZIP("application/zip")` + - `String id` - - `JsonValue; type "base64"constant` + The unique ID of the tool call. - The type of the inline skill source. Must be `base64`. + - `String arguments` - - `BASE64("base64")` + A JSON string of the arguments passed to the tool. - - `JsonValue; type "inline"constant` + - `String name` - Defines an inline skill for this request. + The name of the tool that was run. - - `INLINE("inline")` + - `String serverLabel` - - `class BetaLocalEnvironment:` + The label of the MCP server running the tool. - - `JsonValue; type "local"constant` + - `JsonValue; type "mcp_call"constant` - Use a local computer environment. + The type of the item. Always `mcp_call`. - - `LOCAL("local")` + - `MCP_CALL("mcp_call")` - - `Optional> skills` + - `Optional agent` - An optional list of skills. + The agent that produced this item. - - `String description` + - `String agentName` - The description of the skill. + The canonical name of the agent that produced this item. - - `String name` + - `Optional approvalRequestId` - The name of the skill. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `String path` + - `Optional error` - The path to the directory containing the skill. + The error from the tool call, if any. - - `class BetaContainerReference:` + - `Optional output` - - `String containerId` + The output from the tool call. - The ID of the referenced container. + - `Optional status` - - `JsonValue; type "container_reference"constant` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - References a container created with the /v1/containers endpoint + - `IN_PROGRESS("in_progress")` - - `CONTAINER_REFERENCE("container_reference")` + - `COMPLETED("completed")` - - `class BetaCustomTool:` + - `INCOMPLETE("incomplete")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `CALLING("calling")` - - `String name` + - `FAILED("failed")` - The name of the custom tool, used to identify it in tool calls. + - `class BetaResponseCustomToolCallOutput:` - - `JsonValue; type "custom"constant` + The output of a custom tool call from your code, being sent back to the model. - The type of the custom tool. Always `custom`. + - `String callId` - - `CUSTOM("custom")` + The call ID, used to map this custom tool call output to a custom tool call. - - `Optional> allowedCallers` + - `Output output` - The tool invocation context(s). + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `DIRECT("direct")` + - `String` - - `PROGRAMMATIC("programmatic")` + - `List` - - `Optional deferLoading` + - `class BetaResponseInputText:` - Whether this tool should be deferred and discovered via tool search. + A text input to the model. - - `Optional description` + - `class BetaResponseInputImage:` - Optional description of the custom tool, used to provide more context. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `Optional format` + - `class BetaResponseInputFile:` - The input format for the custom tool. Default is unconstrained text. + A file input to the model. - - `JsonValue;` + - `JsonValue; type "custom_tool_call_output"constant` - - `JsonValue; type "text"constant` + The type of the custom tool call output. Always `custom_tool_call_output`. - Unconstrained text format. Always `text`. + - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - - `TEXT("text")` + - `Optional id` - - `class Grammar:` + The unique ID of the custom tool call output in the OpenAI platform. - A grammar defined by the user. + - `Optional agent` - - `String definition` + The agent that produced this item. - The grammar definition. + - `String agentName` - - `Syntax syntax` + The canonical name of the agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `Optional caller` - - `LARK("lark")` + The execution context that produced this tool call. - - `REGEX("regex")` + - `JsonValue;` - - `JsonValue; type "grammar"constant` + - `JsonValue; type "direct"constant` - Grammar format. Always `grammar`. + The caller type. Always `direct`. - - `GRAMMAR("grammar")` + - `DIRECT("direct")` - - `class BetaNamespaceTool:` + - `class Program:` - Groups function/custom tools under a shared namespace. + - `String callerId` - - `String description` + The call ID of the program item that produced this tool call. - A description of the namespace shown to the model. + - `JsonValue; type "program"constant` - - `String name` + The caller type. Always `program`. - The namespace name used in tool calls (for example, `crm`). + - `PROGRAM("program")` - - `List tools` + - `class BetaResponseCustomToolCall:` - The function/custom tools available inside this namespace. + A call to a custom tool created by the model. - - `class Function:` + - `String callId` - - `String name` + An identifier used to map this custom tool call to a tool call output. - - `JsonValue; type "function"constant` + - `String input` - - `FUNCTION("function")` + The input for the custom tool call generated by the model. - - `Optional> allowedCallers` + - `String name` - The tool invocation context(s). + The name of the custom tool being called. - - `DIRECT("direct")` + - `JsonValue; type "custom_tool_call"constant` - - `PROGRAMMATIC("programmatic")` + The type of the custom tool call. Always `custom_tool_call`. - - `Optional deferLoading` + - `CUSTOM_TOOL_CALL("custom_tool_call")` - Whether this function should be deferred and discovered via tool search. + - `Optional id` - - `Optional description` + The unique ID of the custom tool call in the OpenAI platform. - - `Optional outputSchema` + - `Optional agent` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The agent that produced this item. - - `Optional parameters` + - `String agentName` - - `Optional strict` + The canonical name of the agent that produced this item. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `Optional caller` - - `class BetaCustomTool:` + The execution context that produced this tool call. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `JsonValue;` - - `JsonValue; type "namespace"constant` + - `JsonValue; type "direct"constant` - The type of the tool. Always `namespace`. + - `DIRECT("direct")` - - `NAMESPACE("namespace")` + - `class Program:` - - `class BetaToolSearchTool:` + - `String callerId` - Hosted or BYOT tool search configuration for deferred tools. + The call ID of the program item that produced this tool call. - - `JsonValue; type "tool_search"constant` + - `JsonValue; type "program"constant` - The type of the tool. Always `tool_search`. + - `PROGRAM("program")` - - `TOOL_SEARCH("tool_search")` + - `Optional namespace` - - `Optional description` + The namespace of the custom tool being called. - Description shown to the model for a client-executed tool search tool. + - `CompactionTrigger` - - `Optional execution` + - `JsonValue; type "compaction_trigger"constant` - Whether tool search is executed by the server or by the client. + The type of the item. Always `compaction_trigger`. - - `SERVER("server")` + - `COMPACTION_TRIGGER("compaction_trigger")` - - `CLIENT("client")` + - `Optional agent` - - `Optional parameters` + The agent that produced this item. - Parameter schema for a client-executed tool search tool. + - `String agentName` - - `class BetaWebSearchPreviewTool:` + The canonical name of the agent that produced this item. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `ItemReference` - - `Type type` + - `String id` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The ID of the item to reference. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `Optional agent` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The agent that produced this item. - - `Optional> searchContentTypes` + - `String agentName` - - `TEXT("text")` + The canonical name of the agent that produced this item. - - `IMAGE("image")` + - `Optional type` - - `Optional searchContextSize` + The type of item to reference. Always `item_reference`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `ITEM_REFERENCE("item_reference")` - - `LOW("low")` + - `Program` - - `MEDIUM("medium")` + - `String id` - - `HIGH("high")` + The unique ID of this program item. - - `Optional userLocation` + - `String callId` - The user's location. + The stable call ID of the program item. - - `JsonValue; type "approximate"constant` + - `String code` - The type of location approximation. Always `approximate`. + The JavaScript source executed by programmatic tool calling. - - `APPROXIMATE("approximate")` + - `String fingerprint` - - `Optional city` + Opaque program replay fingerprint that must be round-tripped. - Free text input for the city of the user, e.g. `San Francisco`. + - `JsonValue; type "program"constant` - - `Optional country` + The item type. Always `program`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `PROGRAM("program")` - - `Optional region` + - `Optional agent` - Free text input for the region of the user, e.g. `California`. + The agent that produced this item. - - `Optional timezone` + - `String agentName` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The canonical name of the agent that produced this item. - - `class BetaApplyPatchTool:` + - `ProgramOutput` - Allows the assistant to create, delete, or update files using unified diffs. + - `String id` - - `JsonValue; type "apply_patch"constant` + The unique ID of this program output item. - The type of the tool. Always `apply_patch`. + - `String callId` - - `APPLY_PATCH("apply_patch")` + The call ID of the program item. - - `Optional> allowedCallers` + - `String result` - The tool invocation context(s). + The result produced by the program item. - - `DIRECT("direct")` + - `Status status` - - `PROGRAMMATIC("programmatic")` + The terminal status of the program output. - - `JsonValue; type "tool_search_output"constant` + - `COMPLETED("completed")` - The item type. Always `tool_search_output`. + - `INCOMPLETE("incomplete")` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `JsonValue; type "program_output"constant` - - `Optional id` + The item type. Always `program_output`. - The unique ID of this tool search output. + - `PROGRAM_OUTPUT("program_output")` - `Optional agent` @@ -134500,10380 +146695,11269 @@ public final class Main { The canonical name of the agent that produced this item. - - `Optional callId` - - The unique ID of the tool search call generated by the model. - - - `Optional execution` - - Whether tool search was executed by the server or by the client. + - `Optional instructions` - - `SERVER("server")` + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - - `CLIENT("client")` + - `Optional model` - - `Optional status` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - The status of the tool search output. + - `Optional parallelToolCalls` - - `IN_PROGRESS("in_progress")` + Whether to allow the model to run tool calls in parallel. - - `COMPLETED("completed")` + - `Optional personality` - - `INCOMPLETE("incomplete")` + A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - - `AdditionalTools` + - `FRIENDLY("friendly")` - - `JsonValue; role "developer"constant` + - `PRAGMATIC("pragmatic")` - The role that provided the additional tools. Only `developer` is supported. + - `Optional previousResponseId` - - `DEVELOPER("developer")` + The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `List tools` + - `Optional reasoning` - A list of additional tools made available at this item. + **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `class BetaFunctionTool:` + - `Optional context` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `class BetaFileSearchTool:` + - `AUTO("auto")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `CURRENT_TURN("current_turn")` - - `class BetaComputerTool:` + - `ALL_TURNS("all_turns")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional effort` - - `class BetaComputerUsePreviewTool:` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `NONE("none")` - - `class BetaWebSearchTool:` + - `MINIMAL("minimal")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `LOW("low")` - - `Mcp` + - `MEDIUM("medium")` - - `CodeInterpreter` + - `HIGH("high")` - - `JsonValue;` + - `XHIGH("xhigh")` - - `ImageGeneration` + - `MAX("max")` - - `JsonValue;` + - `Optional generateSummary` - - `class BetaFunctionShellTool:` + **Deprecated:** use `summary` instead. - A tool that allows the model to execute shell commands. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `class BetaCustomTool:` + - `AUTO("auto")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `CONCISE("concise")` - - `class BetaNamespaceTool:` + - `DETAILED("detailed")` - Groups function/custom tools under a shared namespace. + - `Optional mode` - - `class BetaToolSearchTool:` + Controls the reasoning execution mode for the request. - Hosted or BYOT tool search configuration for deferred tools. + When returned on a response, this is the effective execution mode. - - `class BetaWebSearchPreviewTool:` + - `STANDARD("standard")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `PRO("pro")` - - `class BetaApplyPatchTool:` + - `Optional summary` - Allows the assistant to create, delete, or update files using unified diffs. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `JsonValue; type "additional_tools"constant` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The item type. Always `additional_tools`. + - `AUTO("auto")` - - `ADDITIONAL_TOOLS("additional_tools")` + - `CONCISE("concise")` - - `Optional id` + - `DETAILED("detailed")` - The unique ID of this additional tools item. + - `Optional text` - - `Optional agent` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The agent that produced this item. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `String agentName` + - `Optional format` - The canonical name of the agent that produced this item. + An object specifying the format that the model must output. - - `class BetaResponseReasoningItem:` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The default format is `{ "type": "text" }` with no additional options. - - `String id` + **Not recommended for gpt-4o and newer models:** - The unique identifier of the reasoning content. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `List summary` + - `JsonValue;` - Reasoning summary content. + - `JsonValue; type "text"constant` - - `String text` + The type of response format being defined. Always `text`. - A summary of the reasoning output from the model so far. + - `TEXT("text")` - - `JsonValue; type "summary_text"constant` + - `class BetaResponseFormatTextJsonSchemaConfig:` - The type of the object. Always `summary_text`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `SUMMARY_TEXT("summary_text")` + - `String name` - - `JsonValue; type "reasoning"constant` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The type of the object. Always `reasoning`. + - `Schema schema` - - `REASONING("reasoning")` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `Optional agent` + - `JsonValue; type "json_schema"constant` - The agent that produced this item. + The type of response format being defined. Always `json_schema`. - - `String agentName` + - `JSON_SCHEMA("json_schema")` - The canonical name of the agent that produced this item. + - `Optional description` - - `Optional> content` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Reasoning text content. + - `Optional strict` - - `String text` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The reasoning text from the model. + - `JsonValue;` - - `JsonValue; type "reasoning_text"constant` + - `JsonValue; type "json_object"constant` - The type of the reasoning text. Always `reasoning_text`. + The type of response format being defined. Always `json_object`. - - `REASONING_TEXT("reasoning_text")` + - `JSON_OBJECT("json_object")` - - `Optional encryptedContent` + - `Optional verbosity` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `Optional status` + - `LOW("low")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `MEDIUM("medium")` - - `IN_PROGRESS("in_progress")` + - `HIGH("high")` - - `COMPLETED("completed")` + - `Optional toolChoice` - - `INCOMPLETE("incomplete")` + Controls which tool the model should use, if any. - - `class BetaResponseCompactionItemParam:` + - `enum BetaToolChoiceOptions:` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Controls which (if any) tool is called by the model. - - `String encryptedContent` + `none` means the model will not call any tool and instead generates a message. - The encrypted content of the compaction summary. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `JsonValue; type "compaction"constant` + `required` means the model must call one or more tools. - The type of the item. Always `compaction`. + - `NONE("none")` - - `COMPACTION("compaction")` + - `AUTO("auto")` - - `Optional id` + - `REQUIRED("required")` - The ID of the compaction item. + - `class BetaToolChoiceAllowed:` - - `Optional agent` + Constrains the tools available to the model to a pre-defined set. - The agent that produced this item. + - `Mode mode` - - `String agentName` + Constrains the tools available to the model to a pre-defined set. - The canonical name of the agent that produced this item. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `ImageGenerationCall` + `required` requires the model to call one or more of the allowed tools. - - `String id` + - `AUTO("auto")` - The unique ID of the image generation call. + - `REQUIRED("required")` - - `Optional result` + - `List tools` - The generated image encoded in base64. + A list of tool definitions that the model should be allowed to call. - - `Status status` + For the Responses API, the list of tool definitions might look like: - The status of the image generation call. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "allowed_tools"constant` - - `COMPLETED("completed")` + Allowed tool configuration type. Always `allowed_tools`. - - `GENERATING("generating")` + - `ALLOWED_TOOLS("allowed_tools")` - - `FAILED("failed")` + - `class BetaToolChoiceTypes:` - - `JsonValue; type "image_generation_call"constant` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - The type of the image generation call. Always `image_generation_call`. + - `Type type` - - `IMAGE_GENERATION_CALL("image_generation_call")` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `Optional agent` + Allowed values are: - The agent that produced this item. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `String agentName` + - `FILE_SEARCH("file_search")` - The canonical name of the agent that produced this item. + - `WEB_SEARCH_PREVIEW("web_search_preview")` - - `class BetaResponseCodeInterpreterToolCall:` + - `COMPUTER("computer")` - A tool call to run code. + - `COMPUTER_USE_PREVIEW("computer_use_preview")` - - `String id` + - `COMPUTER_USE("computer_use")` - The unique ID of the code interpreter tool call. + - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - - `Optional code` + - `IMAGE_GENERATION("image_generation")` - The code to run, or null if not available. + - `CODE_INTERPRETER("code_interpreter")` - - `String containerId` + - `class BetaToolChoiceFunction:` - The ID of the container used to run the code. + Use this option to force the model to call a specific function. - - `Optional> outputs` + - `String name` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The name of the function to call. - - `class Logs:` + - `JsonValue; type "function"constant` - The logs output from the code interpreter. + For function calling, the type is always `function`. - - `String logs` + - `FUNCTION("function")` - The logs output from the code interpreter. + - `class BetaToolChoiceMcp:` - - `JsonValue; type "logs"constant` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the output. Always `logs`. + - `String serverLabel` - - `LOGS("logs")` + The label of the MCP server to use. - - `class Image:` + - `JsonValue; type "mcp"constant` - The image output from the code interpreter. + For MCP tools, the type is always `mcp`. - - `JsonValue; type "image"constant` + - `MCP("mcp")` - The type of the output. Always `image`. + - `Optional name` - - `IMAGE("image")` + The name of the tool to call on the server. - - `String url` + - `class BetaToolChoiceCustom:` - The URL of the image output from the code interpreter. + Use this option to force the model to call a specific custom tool. - - `Status status` + - `String name` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The name of the custom tool to call. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "custom"constant` - - `COMPLETED("completed")` + For custom tool calling, the type is always `custom`. - - `INCOMPLETE("incomplete")` + - `CUSTOM("custom")` - - `INTERPRETING("interpreting")` + - `JsonValue;` - - `FAILED("failed")` + - `JsonValue; type "programmatic_tool_calling"constant` - - `JsonValue; type "code_interpreter_call"constant` + The tool to call. Always `programmatic_tool_calling`. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `class BetaToolChoiceApplyPatch:` - - `Optional agent` + Forces the model to call the apply_patch tool when executing a tool call. - The agent that produced this item. + - `JsonValue; type "apply_patch"constant` - - `String agentName` + The tool to call. Always `apply_patch`. - The canonical name of the agent that produced this item. + - `APPLY_PATCH("apply_patch")` - - `LocalShellCall` + - `class BetaToolChoiceShell:` - - `String id` + Forces the model to call the shell tool when a tool call is required. - The unique ID of the local shell call. + - `JsonValue; type "shell"constant` - - `Action action` + The tool to call. Always `shell`. - Execute a shell command on the server. + - `SHELL("shell")` - - `List command` + - `Optional> tools` - The command to run. + An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. - - `Env env` + - `class BetaFunctionTool:` - Environment variables to set for the command. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `JsonValue; type "exec"constant` + - `class BetaFileSearchTool:` - The type of the local shell action. Always `exec`. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `EXEC("exec")` + - `class BetaComputerTool:` - - `Optional timeoutMs` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Optional timeout in milliseconds for the command. + - `class BetaComputerUsePreviewTool:` - - `Optional user` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Optional user to run the command as. + - `class BetaWebSearchTool:` - - `Optional workingDirectory` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Optional working directory to run the command in. + - `Mcp` - - `String callId` + - `CodeInterpreter` - The unique ID of the local shell tool call generated by the model. + - `JsonValue;` - - `Status status` + - `ImageGeneration` - The status of the local shell call. + - `JsonValue;` - - `IN_PROGRESS("in_progress")` + - `class BetaFunctionShellTool:` - - `COMPLETED("completed")` + A tool that allows the model to execute shell commands. - - `INCOMPLETE("incomplete")` + - `class BetaCustomTool:` - - `JsonValue; type "local_shell_call"constant` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - The type of the local shell call. Always `local_shell_call`. + - `class BetaNamespaceTool:` - - `LOCAL_SHELL_CALL("local_shell_call")` + Groups function/custom tools under a shared namespace. - - `Optional agent` + - `class BetaToolSearchTool:` - The agent that produced this item. + Hosted or BYOT tool search configuration for deferred tools. - - `String agentName` + - `class BetaWebSearchPreviewTool:` - The canonical name of the agent that produced this item. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `LocalShellCallOutput` + - `class BetaApplyPatchTool:` - - `String id` + Allows the assistant to create, delete, or update files using unified diffs. - The unique ID of the local shell tool call generated by the model. + - `Optional truncation` - - `String output` + The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error. - A JSON string of the output of the local shell tool call. + - `AUTO("auto")` - - `JsonValue; type "local_shell_call_output"constant` + - `DISABLED("disabled")` - The type of the local shell tool call output. Always `local_shell_call_output`. +### Returns - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` +- `class InputTokenCountResponse:` - - `Optional agent` + - `long inputTokens` - The agent that produced this item. + - `JsonValue; object_ "response.input_tokens"constant` - - `String agentName` + - `RESPONSE_INPUT_TOKENS("response.input_tokens")` - The canonical name of the agent that produced this item. +### Example - - `Optional status` +```java +package com.openai.example; - The status of the item. One of `in_progress`, `completed`, or `incomplete`. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.responses.inputtokens.InputTokenCountParams; +import com.openai.models.beta.responses.inputtokens.InputTokenCountResponse; - - `IN_PROGRESS("in_progress")` +public final class Main { + private Main() {} - - `COMPLETED("completed")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `INCOMPLETE("incomplete")` + InputTokenCountResponse response = client.beta().responses().inputTokens().count(); + } +} +``` - - `ShellCall` +#### Response - - `Action action` +```json +{ + "input_tokens": 123, + "object": "response.input_tokens" +} +``` - The shell commands and limits that describe how to run the tool call. +### Example - - `List commands` +```java +package com.openai.example; - Ordered shell commands for the execution environment to run. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.responses.inputtokens.InputTokenCountParams; +import com.openai.models.responses.inputtokens.InputTokenCountResponse; - - `Optional maxOutputLength` +public final class Main { + private Main() {} - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `Optional timeoutMs` + InputTokenCountParams params = InputTokenCountParams.builder() + .model("gpt-5") + .input("Tell me a joke.") + .build(); - Maximum wall-clock time in milliseconds to allow the shell commands to run. + InputTokenCountResponse response = client.responses().inputTokens().count(params); + } +} +``` - - `String callId` +#### Response - The unique ID of the shell tool call generated by the model. +```json +{ + "object": "response.input_tokens", + "input_tokens": 11 +} +``` - - `JsonValue; type "shell_call"constant` +# ChatKit - The type of the item. Always `shell_call`. +## Domain Types - - `SHELL_CALL("shell_call")` +### ChatKit Workflow - - `Optional id` +- `class ChatKitWorkflow:` - The unique ID of the shell tool call. Populated when this item is returned via API. + Workflow metadata and state returned for the session. - - `Optional agent` + - `String id` - The agent that produced this item. + Identifier of the workflow backing the session. - - `String agentName` + - `Optional stateVariables` - The canonical name of the agent that produced this item. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `Optional caller` + - `String` - The execution context that produced this tool call. + - `boolean` - - `JsonValue;` + - `double` - - `JsonValue; type "direct"constant` + - `Tracing tracing` - The caller type. Always `direct`. + Tracing settings applied to the workflow. - - `DIRECT("direct")` + - `boolean enabled` - - `class Program:` + Indicates whether tracing is enabled. - - `String callerId` + - `Optional version` - The call ID of the program item that produced this tool call. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `JsonValue; type "program"constant` +# Sessions - The caller type. Always `program`. +## Cancel chat session - - `PROGRAM("program")` +`ChatSession beta().chatkit().sessions().cancel(SessionCancelParamsparams = SessionCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `Optional environment` +**post** `/chatkit/sessions/{session_id}/cancel` - The environment to execute the shell commands in. +Cancel an active ChatKit session and return its most recent metadata. - - `class BetaLocalEnvironment:` +Cancelling prevents new requests from using the issued client secret. - - `class BetaContainerReference:` +### Parameters - - `Optional status` +- `SessionCancelParams params` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `Optional sessionId` - - `IN_PROGRESS("in_progress")` +### Returns - - `COMPLETED("completed")` +- `class ChatSession:` - - `INCOMPLETE("incomplete")` + Represents a ChatKit session and its resolved configuration. - - `ShellCallOutput` + - `String id` - - `String callId` + Identifier for the ChatKit session. - The unique ID of the shell tool call generated by the model. + - `ChatSessionChatKitConfiguration chatkitConfiguration` - - `List output` + Resolved ChatKit feature configuration for the session. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `ChatSessionAutomaticThreadTitling automaticThreadTitling` - - `Outcome outcome` + Automatic thread titling preferences. - The exit or timeout outcome associated with this shell call. + - `boolean enabled` - - `JsonValue;` + Whether automatic thread titling is enabled. - - `JsonValue; type "timeout"constant` + - `ChatSessionFileUpload fileUpload` - The outcome type. Always `timeout`. + Upload settings for the session. - - `TIMEOUT("timeout")` + - `boolean enabled` - - `class Exit:` + Indicates if uploads are enabled for the session. - Indicates that the shell commands finished and returned an exit code. + - `Optional maxFileSize` - - `long exitCode` + Maximum upload size in megabytes. - The exit code returned by the shell process. + - `Optional maxFiles` - - `JsonValue; type "exit"constant` + Maximum number of uploads allowed during the session. - The outcome type. Always `exit`. + - `ChatSessionHistory history` - - `EXIT("exit")` + History retention configuration. - - `String stderr` + - `boolean enabled` - Captured stderr output for the shell call. + Indicates if chat history is persisted for the session. - - `String stdout` + - `Optional recentThreads` - Captured stdout output for the shell call. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `JsonValue; type "shell_call_output"constant` + - `String clientSecret` - The type of the item. Always `shell_call_output`. + Ephemeral client secret that authenticates session requests. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `long expiresAt` - - `Optional id` + Unix timestamp (in seconds) for when the session expires. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `long maxRequestsPer1Minute` - - `Optional agent` + Convenience copy of the per-minute request limit. - The agent that produced this item. + - `JsonValue; object_ "chatkit.session"constant` - - `String agentName` + Type discriminator that is always `chatkit.session`. - The canonical name of the agent that produced this item. + - `CHATKIT_SESSION("chatkit.session")` - - `Optional caller` + - `ChatSessionRateLimits rateLimits` - The execution context that produced this tool call. + Resolved rate limit values. - - `JsonValue;` + - `long maxRequestsPer1Minute` - - `JsonValue; type "direct"constant` + Maximum allowed requests per one-minute window. - The caller type. Always `direct`. + - `ChatSessionStatus status` - - `DIRECT("direct")` + Current lifecycle state of the session. - - `class Program:` + - `ACTIVE("active")` - - `String callerId` + - `EXPIRED("expired")` - The call ID of the program item that produced this tool call. + - `CANCELLED("cancelled")` - - `JsonValue; type "program"constant` + - `String user` - The caller type. Always `program`. + User identifier associated with the session. - - `PROGRAM("program")` + - `ChatKitWorkflow workflow` - - `Optional maxOutputLength` + Workflow metadata for the session. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `String id` - - `Optional status` + Identifier of the workflow backing the session. - The status of the shell call output. + - `Optional stateVariables` - - `IN_PROGRESS("in_progress")` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `COMPLETED("completed")` + - `String` - - `INCOMPLETE("incomplete")` + - `boolean` - - `ApplyPatchCall` + - `double` - - `String callId` + - `Tracing tracing` - The unique ID of the apply patch tool call generated by the model. + Tracing settings applied to the workflow. - - `Operation operation` + - `boolean enabled` - The specific create, delete, or update instruction for the apply_patch tool call. + Indicates whether tracing is enabled. - - `class CreateFile:` + - `Optional version` - Instruction for creating a new file via the apply_patch tool. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `String diff` +### Example - Unified diff content to apply when creating the file. +```java +package com.openai.example; - - `String path` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.sessions.SessionCancelParams; +import com.openai.models.beta.chatkit.threads.ChatSession; - Path of the file to create relative to the workspace root. +public final class Main { + private Main() {} - - `JsonValue; type "create_file"constant` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The operation type. Always `create_file`. + ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123"); + } +} +``` - - `CREATE_FILE("create_file")` +#### Response - - `class DeleteFile:` +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - Instruction for deleting an existing file via the apply_patch tool. +### Example - - `String path` +```java +package com.openai.example; - Path of the file to delete relative to the workspace root. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.sessions.SessionCancelParams; +import com.openai.models.beta.chatkit.threads.ChatSession; - - `JsonValue; type "delete_file"constant` +public final class Main { + private Main() {} - The operation type. Always `delete_file`. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `DELETE_FILE("delete_file")` + ChatSession chatSession = client.beta().chatkit().sessions().cancel("cksess_123"); + } +} +``` - - `class UpdateFile:` +#### Response - Instruction for updating an existing file via the apply_patch tool. +```json +{ + "id": "cksess_123", + "object": "chatkit.session", + "workflow": { + "id": "workflow_alpha", + "version": "1" + }, + "scope": { + "customer_id": "cust_456" + }, + "max_requests_per_1_minute": 30, + "ttl_seconds": 900, + "status": "cancelled", + "cancelled_at": 1712345678 +} +``` - - `String diff` +## Create ChatKit session - Unified diff content to apply to the existing file. +`ChatSession beta().chatkit().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `String path` +**post** `/chatkit/sessions` - Path of the file to update relative to the workspace root. +Create a ChatKit session. - - `JsonValue; type "update_file"constant` +### Parameters - The operation type. Always `update_file`. +- `SessionCreateParams params` - - `UPDATE_FILE("update_file")` + - `String user` - - `Status status` + A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `ChatSessionWorkflowParam workflow` - - `IN_PROGRESS("in_progress")` + Workflow that powers the session. - - `COMPLETED("completed")` + - `Optional chatkitConfiguration` - - `JsonValue; type "apply_patch_call"constant` + Optional overrides for ChatKit runtime configuration features - The type of the item. Always `apply_patch_call`. + - `Optional expiresAfter` - - `APPLY_PATCH_CALL("apply_patch_call")` + Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - - `Optional id` + - `Optional rateLimits` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Optional override for per-minute request limits. When omitted, defaults to 10. - - `Optional agent` +### Returns - The agent that produced this item. +- `class ChatSession:` - - `String agentName` + Represents a ChatKit session and its resolved configuration. - The canonical name of the agent that produced this item. + - `String id` - - `Optional caller` + Identifier for the ChatKit session. - The execution context that produced this tool call. + - `ChatSessionChatKitConfiguration chatkitConfiguration` - - `JsonValue;` + Resolved ChatKit feature configuration for the session. - - `JsonValue; type "direct"constant` + - `ChatSessionAutomaticThreadTitling automaticThreadTitling` - The caller type. Always `direct`. + Automatic thread titling preferences. - - `DIRECT("direct")` + - `boolean enabled` - - `class Program:` + Whether automatic thread titling is enabled. - - `String callerId` + - `ChatSessionFileUpload fileUpload` - The call ID of the program item that produced this tool call. + Upload settings for the session. - - `JsonValue; type "program"constant` + - `boolean enabled` - The caller type. Always `program`. + Indicates if uploads are enabled for the session. - - `PROGRAM("program")` + - `Optional maxFileSize` - - `ApplyPatchCallOutput` + Maximum upload size in megabytes. - - `String callId` + - `Optional maxFiles` - The unique ID of the apply patch tool call generated by the model. + Maximum number of uploads allowed during the session. - - `Status status` + - `ChatSessionHistory history` - The status of the apply patch tool call output. One of `completed` or `failed`. + History retention configuration. - - `COMPLETED("completed")` + - `boolean enabled` - - `FAILED("failed")` + Indicates if chat history is persisted for the session. - - `JsonValue; type "apply_patch_call_output"constant` + - `Optional recentThreads` - The type of the item. Always `apply_patch_call_output`. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `String clientSecret` - - `Optional id` + Ephemeral client secret that authenticates session requests. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `long expiresAt` - - `Optional agent` + Unix timestamp (in seconds) for when the session expires. - The agent that produced this item. + - `long maxRequestsPer1Minute` - - `String agentName` + Convenience copy of the per-minute request limit. - The canonical name of the agent that produced this item. + - `JsonValue; object_ "chatkit.session"constant` - - `Optional caller` + Type discriminator that is always `chatkit.session`. - The execution context that produced this tool call. + - `CHATKIT_SESSION("chatkit.session")` - - `JsonValue;` + - `ChatSessionRateLimits rateLimits` - - `JsonValue; type "direct"constant` + Resolved rate limit values. - The caller type. Always `direct`. + - `long maxRequestsPer1Minute` - - `DIRECT("direct")` + Maximum allowed requests per one-minute window. - - `class Program:` + - `ChatSessionStatus status` - - `String callerId` + Current lifecycle state of the session. - The call ID of the program item that produced this tool call. + - `ACTIVE("active")` - - `JsonValue; type "program"constant` + - `EXPIRED("expired")` - The caller type. Always `program`. + - `CANCELLED("cancelled")` - - `PROGRAM("program")` + - `String user` - - `Optional output` + User identifier associated with the session. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `ChatKitWorkflow workflow` - - `McpListTools` + Workflow metadata for the session. - `String id` - The unique ID of the list. + Identifier of the workflow backing the session. - - `String serverLabel` + - `Optional stateVariables` - The label of the MCP server. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `List tools` + - `String` - The tools available on the server. + - `boolean` - - `JsonValue inputSchema` + - `double` - The JSON schema describing the tool's input. + - `Tracing tracing` - - `String name` + Tracing settings applied to the workflow. - The name of the tool. + - `boolean enabled` - - `Optional annotations` + Indicates whether tracing is enabled. - Additional annotations about the tool. + - `Optional version` - - `Optional description` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - The description of the tool. +### Example - - `JsonValue; type "mcp_list_tools"constant` +```java +package com.openai.example; - The type of the item. Always `mcp_list_tools`. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.sessions.SessionCreateParams; +import com.openai.models.beta.chatkit.threads.ChatSession; +import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam; - - `MCP_LIST_TOOLS("mcp_list_tools")` +public final class Main { + private Main() {} - - `Optional agent` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The agent that produced this item. + SessionCreateParams params = SessionCreateParams.builder() + .user("x") + .workflow(ChatSessionWorkflowParam.builder() + .id("id") + .build()) + .build(); + ChatSession chatSession = client.beta().chatkit().sessions().create(params); + } +} +``` - - `String agentName` +#### Response - The canonical name of the agent that produced this item. +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - - `Optional error` +### Example - Error message if the server could not list tools. +```java +package com.openai.example; - - `McpApprovalRequest` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.sessions.SessionCreateParams; +import com.openai.models.beta.chatkit.threads.ChatSession; +import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam; - - `String id` +public final class Main { + private Main() {} - The unique ID of the approval request. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `String arguments` + SessionCreateParams params = SessionCreateParams.builder() + .user("user") + .workflow(ChatSessionWorkflowParam.builder() + .id("id") + .build()) + .build(); + ChatSession chatSession = client.beta().chatkit().sessions().create(params); + } +} +``` - A JSON string of arguments for the tool. +#### Response - - `String name` +```json +{ + "client_secret": "chatkit_token_123", + "expires_at": 1735689600, + "workflow": { + "id": "workflow_alpha", + "version": "2024-10-01" + }, + "scope": { + "project": "alpha", + "environment": "staging" + }, + "max_requests_per_1_minute": 60, + "max_requests_per_session": 500, + "status": "active" +} +``` - The name of the tool to run. +# Threads - - `String serverLabel` +## List ChatKit thread items - The label of the MCP server making the request. +`ThreadListItemsPage beta().chatkit().threads().listItems(ThreadListItemsParamsparams = ThreadListItemsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `JsonValue; type "mcp_approval_request"constant` +**get** `/chatkit/threads/{thread_id}/items` - The type of the item. Always `mcp_approval_request`. +List items that belong to a ChatKit thread. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` +### Parameters - - `Optional agent` +- `ThreadListItemsParams params` - The agent that produced this item. + - `Optional threadId` - - `String agentName` + - `Optional after` - The canonical name of the agent that produced this item. + List items created after this thread item ID. Defaults to null for the first page. - - `McpApprovalResponse` + - `Optional before` - - `String approvalRequestId` + List items created before this thread item ID. Defaults to null for the newest results. - The ID of the approval request being answered. + - `Optional limit` - - `boolean approve` + Maximum number of thread items to return. Defaults to 20. - Whether the request was approved. + - `Optional order` - - `JsonValue; type "mcp_approval_response"constant` + Sort order for results by creation time. Defaults to `desc`. - The type of the item. Always `mcp_approval_response`. + - `ASC("asc")` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `DESC("desc")` - - `Optional id` +### Returns - The unique ID of the approval response +- `class Data: A class that can be one of several variants.union` - - `Optional agent` + User-authored messages within a thread. - The agent that produced this item. + - `class ChatKitThreadUserMessageItem:` - - `String agentName` + User-authored messages within a thread. - The canonical name of the agent that produced this item. + - `String id` - - `Optional reason` + Identifier of the thread item. - Optional reason for the decision. + - `List attachments` - - `McpCall` + Attachments associated with the user message. Defaults to an empty list. - `String id` - The unique ID of the tool call. + Identifier for the attachment. - - `String arguments` + - `String mimeType` - A JSON string of the arguments passed to the tool. + MIME type of the attachment. - `String name` - The name of the tool that was run. - - - `String serverLabel` + Original display name for the attachment. - The label of the MCP server running the tool. + - `Optional previewUrl` - - `JsonValue; type "mcp_call"constant` + Preview URL for rendering the attachment inline. - The type of the item. Always `mcp_call`. + - `Type type` - - `MCP_CALL("mcp_call")` + Attachment discriminator. - - `Optional agent` + - `IMAGE("image")` - The agent that produced this item. + - `FILE("file")` - - `String agentName` + - `List content` - The canonical name of the agent that produced this item. + Ordered content elements supplied by the user. - - `Optional approvalRequestId` + - `class InputText:` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + Text block that a user contributed to the thread. - - `Optional error` + - `String text` - The error from the tool call, if any. + Plain-text content supplied by the user. - - `Optional output` + - `JsonValue; type "input_text"constant` - The output from the tool call. + Type discriminator that is always `input_text`. - - `Optional status` + - `INPUT_TEXT("input_text")` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `class QuotedText:` - - `IN_PROGRESS("in_progress")` + Quoted snippet that the user referenced in their message. - - `COMPLETED("completed")` + - `String text` - - `INCOMPLETE("incomplete")` + Quoted text content. - - `CALLING("calling")` + - `JsonValue; type "quoted_text"constant` - - `FAILED("failed")` + Type discriminator that is always `quoted_text`. - - `class BetaResponseCustomToolCallOutput:` + - `QUOTED_TEXT("quoted_text")` - The output of a custom tool call from your code, being sent back to the model. + - `long createdAt` - - `String callId` + Unix timestamp (in seconds) for when the item was created. - The call ID, used to map this custom tool call output to a custom tool call. + - `Optional inferenceOptions` - - `Output output` + Inference overrides applied to the message. Defaults to null when unset. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `Optional model` - - `String` + Model name that generated the response. Defaults to null when using the session default. - - `List` + - `Optional toolChoice` - - `class BetaResponseInputText:` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - A text input to the model. + - `String id` - - `class BetaResponseInputImage:` + Identifier of the requested tool. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `JsonValue; object_ "chatkit.thread_item"constant` - - `class BetaResponseInputFile:` + Type discriminator that is always `chatkit.thread_item`. - A file input to the model. + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `JsonValue; type "custom_tool_call_output"constant` + - `String threadId` - The type of the custom tool call output. Always `custom_tool_call_output`. + Identifier of the parent thread. - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + - `JsonValue; type "chatkit.user_message"constant` - - `Optional id` + - `CHATKIT_USER_MESSAGE("chatkit.user_message")` - The unique ID of the custom tool call output in the OpenAI platform. + - `class ChatKitThreadAssistantMessageItem:` - - `Optional agent` + Assistant-authored message within a thread. - The agent that produced this item. + - `String id` - - `String agentName` + Identifier of the thread item. - The canonical name of the agent that produced this item. + - `List content` - - `Optional caller` + Ordered assistant response segments. - The execution context that produced this tool call. + - `List annotations` - - `JsonValue;` + Ordered list of annotations attached to the response text. - - `JsonValue; type "direct"constant` + - `class File:` - The caller type. Always `direct`. + Annotation that references an uploaded file. - - `DIRECT("direct")` + - `Source source` - - `class Program:` + File attachment referenced by the annotation. - - `String callerId` + - `String filename` - The call ID of the program item that produced this tool call. + Filename referenced by the annotation. - - `JsonValue; type "program"constant` + - `JsonValue; type "file"constant` - The caller type. Always `program`. + Type discriminator that is always `file`. - - `PROGRAM("program")` + - `FILE("file")` - - `class BetaResponseCustomToolCall:` + - `JsonValue; type "file"constant` - A call to a custom tool created by the model. + Type discriminator that is always `file` for this annotation. - - `String callId` + - `FILE("file")` - An identifier used to map this custom tool call to a tool call output. + - `class Url:` - - `String input` + Annotation that references a URL. - The input for the custom tool call generated by the model. + - `Source source` - - `String name` + URL referenced by the annotation. - The name of the custom tool being called. + - `JsonValue; type "url"constant` - - `JsonValue; type "custom_tool_call"constant` + Type discriminator that is always `url`. - The type of the custom tool call. Always `custom_tool_call`. + - `URL("url")` - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `String url` - - `Optional id` + URL referenced by the annotation. - The unique ID of the custom tool call in the OpenAI platform. + - `JsonValue; type "url"constant` - - `Optional agent` + Type discriminator that is always `url` for this annotation. - The agent that produced this item. + - `URL("url")` - - `String agentName` + - `String text` - The canonical name of the agent that produced this item. + Assistant generated text. - - `Optional caller` + - `JsonValue; type "output_text"constant` - The execution context that produced this tool call. + Type discriminator that is always `output_text`. - - `JsonValue;` + - `OUTPUT_TEXT("output_text")` - - `JsonValue; type "direct"constant` + - `long createdAt` - - `DIRECT("direct")` + Unix timestamp (in seconds) for when the item was created. - - `class Program:` + - `JsonValue; object_ "chatkit.thread_item"constant` - - `String callerId` + Type discriminator that is always `chatkit.thread_item`. - The call ID of the program item that produced this tool call. + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `JsonValue; type "program"constant` + - `String threadId` - - `PROGRAM("program")` + Identifier of the parent thread. - - `Optional namespace` + - `JsonValue; type "chatkit.assistant_message"constant` - The namespace of the custom tool being called. + Type discriminator that is always `chatkit.assistant_message`. - - `CompactionTrigger` + - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")` - - `JsonValue; type "compaction_trigger"constant` + - `class ChatKitWidgetItem:` - The type of the item. Always `compaction_trigger`. + Thread item that renders a widget payload. - - `COMPACTION_TRIGGER("compaction_trigger")` + - `String id` - - `Optional agent` + Identifier of the thread item. - The agent that produced this item. + - `long createdAt` - - `String agentName` + Unix timestamp (in seconds) for when the item was created. - The canonical name of the agent that produced this item. + - `JsonValue; object_ "chatkit.thread_item"constant` - - `ItemReference` + Type discriminator that is always `chatkit.thread_item`. - - `String id` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - The ID of the item to reference. + - `String threadId` - - `Optional agent` + Identifier of the parent thread. - The agent that produced this item. + - `JsonValue; type "chatkit.widget"constant` - - `String agentName` + Type discriminator that is always `chatkit.widget`. - The canonical name of the agent that produced this item. + - `CHATKIT_WIDGET("chatkit.widget")` - - `Optional type` + - `String widget` - The type of item to reference. Always `item_reference`. + Serialized widget payload rendered in the UI. - - `ITEM_REFERENCE("item_reference")` + - `class ChatKitClientToolCall:` - - `Program` + Record of a client side tool invocation initiated by the assistant. - `String id` - The unique ID of this program item. + Identifier of the thread item. + + - `String arguments` + + JSON-encoded arguments that were sent to the tool. - `String callId` - The stable call ID of the program item. + Identifier for the client tool call. - - `String code` + - `long createdAt` - The JavaScript source executed by programmatic tool calling. + Unix timestamp (in seconds) for when the item was created. - - `String fingerprint` + - `String name` - Opaque program replay fingerprint that must be round-tripped. + Tool name that was invoked. - - `JsonValue; type "program"constant` + - `JsonValue; object_ "chatkit.thread_item"constant` - The item type. Always `program`. + Type discriminator that is always `chatkit.thread_item`. - - `PROGRAM("program")` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `Optional agent` + - `Optional output` - The agent that produced this item. + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `String agentName` + - `Status status` - The canonical name of the agent that produced this item. + Execution status for the tool call. - - `ProgramOutput` + - `IN_PROGRESS("in_progress")` - - `String id` + - `COMPLETED("completed")` - The unique ID of this program output item. + - `String threadId` - - `String callId` + Identifier of the parent thread. - The call ID of the program item. + - `JsonValue; type "chatkit.client_tool_call"constant` - - `String result` + Type discriminator that is always `chatkit.client_tool_call`. - The result produced by the program item. + - `CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")` - - `Status status` + - `class ChatKitTask:` - The terminal status of the program output. + Task emitted by the workflow to show progress and status updates. - - `COMPLETED("completed")` + - `String id` - - `INCOMPLETE("incomplete")` + Identifier of the thread item. - - `JsonValue; type "program_output"constant` + - `long createdAt` - The item type. Always `program_output`. + Unix timestamp (in seconds) for when the item was created. - - `PROGRAM_OUTPUT("program_output")` + - `Optional heading` - - `Optional agent` + Optional heading for the task. Defaults to null when not provided. - The agent that produced this item. + - `JsonValue; object_ "chatkit.thread_item"constant` - - `String agentName` + Type discriminator that is always `chatkit.thread_item`. - The canonical name of the agent that produced this item. + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `Optional metadata` + - `Optional summary` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Optional summary that describes the task. Defaults to null when omitted. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `TaskType taskType` - - `Model model` + Subtype for the task. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `CUSTOM("custom")` - - `GPT_5_6_SOL("gpt-5.6-sol")` + - `THOUGHT("thought")` - - `GPT_5_6_TERRA("gpt-5.6-terra")` + - `String threadId` - - `GPT_5_6_LUNA("gpt-5.6-luna")` + Identifier of the parent thread. - - `GPT_5_4("gpt-5.4")` + - `JsonValue; type "chatkit.task"constant` - - `GPT_5_4_MINI("gpt-5.4-mini")` + Type discriminator that is always `chatkit.task`. - - `GPT_5_4_NANO("gpt-5.4-nano")` + - `CHATKIT_TASK("chatkit.task")` - - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` + - `class ChatKitTaskGroup:` - - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` + Collection of workflow tasks grouped together in the thread. - - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` + - `String id` - - `GPT_5_2("gpt-5.2")` + Identifier of the thread item. - - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` + - `long createdAt` - - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` + Unix timestamp (in seconds) for when the item was created. - - `GPT_5_2_PRO("gpt-5.2-pro")` + - `JsonValue; object_ "chatkit.thread_item"constant` - - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` + Type discriminator that is always `chatkit.thread_item`. - - `GPT_5_1("gpt-5.1")` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` + - `List tasks` - - `GPT_5_1_CODEX("gpt-5.1-codex")` + Tasks included in the group. - - `GPT_5_1_MINI("gpt-5.1-mini")` + - `Optional heading` - - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` + Optional heading for the grouped task. Defaults to null when not provided. - - `GPT_5("gpt-5")` + - `Optional summary` - - `GPT_5_MINI("gpt-5-mini")` + Optional summary that describes the grouped task. Defaults to null when omitted. - - `GPT_5_NANO("gpt-5-nano")` + - `Type type` - - `GPT_5_2025_08_07("gpt-5-2025-08-07")` + Subtype for the grouped task. - - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` + - `CUSTOM("custom")` - - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` + - `THOUGHT("thought")` - - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` + - `String threadId` - - `GPT_4_1("gpt-4.1")` + Identifier of the parent thread. - - `GPT_4_1_MINI("gpt-4.1-mini")` + - `JsonValue; type "chatkit.task_group"constant` - - `GPT_4_1_NANO("gpt-4.1-nano")` + Type discriminator that is always `chatkit.task_group`. - - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` + - `CHATKIT_TASK_GROUP("chatkit.task_group")` - - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` +### Example - - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` +```java +package com.openai.example; - - `O4_MINI("o4-mini")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.threads.ThreadListItemsPage; +import com.openai.models.beta.chatkit.threads.ThreadListItemsParams; - - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` +public final class Main { + private Main() {} - - `O3("o3")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `O3_2025_04_16("o3-2025-04-16")` + ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123"); + } +} +``` - - `O3_MINI("o3-mini")` +#### Response - - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` +```json +{ + "data": [ + { + "id": "id", + "attachments": [ + { + "id": "id", + "mime_type": "mime_type", + "name": "name", + "preview_url": "https://example.com", + "type": "image" + } + ], + "content": [ + { + "text": "text", + "type": "input_text" + } + ], + "created_at": 0, + "inference_options": { + "model": "model", + "tool_choice": { + "id": "id" + } + }, + "object": "chatkit.thread_item", + "thread_id": "thread_id", + "type": "chatkit.user_message" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `O1("o1")` +### Example - - `O1_2024_12_17("o1-2024-12-17")` +```java +package com.openai.example; - - `O1_PREVIEW("o1-preview")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.threads.ThreadListItemsPage; +import com.openai.models.beta.chatkit.threads.ThreadListItemsParams; - - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` +public final class Main { + private Main() {} - - `O1_MINI("o1-mini")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` + ThreadListItemsPage page = client.beta().chatkit().threads().listItems("cthr_123"); + } +} +``` - - `GPT_4O("gpt-4o")` +#### Response - - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` +```json +{ + "data": [ + { + "id": "cthi_user_001", + "object": "chatkit.thread_item", + "type": "user_message", + "content": [ + { + "type": "input_text", + "text": "I need help debugging an onboarding issue." + } + ], + "attachments": [] + }, + { + "id": "cthi_assistant_002", + "object": "chatkit.thread_item", + "type": "assistant_message", + "content": [ + { + "type": "output_text", + "text": "Let's start by confirming the workflow version you deployed." + } + ] + } + ], + "has_more": false, + "object": "list" +} +``` - - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` +## Retrieve ChatKit thread - - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` +`ChatKitThread beta().chatkit().threads().retrieve(ThreadRetrieveParamsparams = ThreadRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` +**get** `/chatkit/threads/{thread_id}` - - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` +Retrieve a ChatKit thread by its identifier. - - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` +### Parameters - - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` +- `ThreadRetrieveParams params` - - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` + - `Optional threadId` - - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` +### Returns - - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` +- `class ChatKitThread:` - - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` + Represents a ChatKit thread and its current status. - - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` + - `String id` - - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` + Identifier of the thread. - - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` + - `long createdAt` - - `CODEX_MINI_LATEST("codex-mini-latest")` + Unix timestamp (in seconds) for when the thread was created. - - `GPT_4O_MINI("gpt-4o-mini")` + - `JsonValue; object_ "chatkit.thread"constant` - - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` + Type discriminator that is always `chatkit.thread`. - - `GPT_4_TURBO("gpt-4-turbo")` + - `CHATKIT_THREAD("chatkit.thread")` - - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` + - `Status status` - - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` + Current status for the thread. Defaults to `active` for newly created threads. - - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` + - `JsonValue;` - - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` + - `JsonValue; type "active"constant` - - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` + Status discriminator that is always `active`. - - `GPT_4("gpt-4")` + - `ACTIVE("active")` - - `GPT_4_0314("gpt-4-0314")` + - `class Locked:` - - `GPT_4_0613("gpt-4-0613")` + Indicates that a thread is locked and cannot accept new input. - - `GPT_4_32K("gpt-4-32k")` + - `Optional reason` - - `GPT_4_32K_0314("gpt-4-32k-0314")` + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `GPT_4_32K_0613("gpt-4-32k-0613")` + - `JsonValue; type "locked"constant` - - `GPT_3_5_TURBO("gpt-3.5-turbo")` + Status discriminator that is always `locked`. - - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` + - `LOCKED("locked")` - - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` + - `class Closed:` - - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` + Indicates that a thread has been closed. - - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` + - `Optional reason` - - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` + - `JsonValue; type "closed"constant` - - `O1_PRO("o1-pro")` + Status discriminator that is always `closed`. - - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` + - `CLOSED("closed")` - - `O3_PRO("o3-pro")` + - `Optional title` - - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `O3_DEEP_RESEARCH("o3-deep-research")` + - `String user` - - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` + Free-form string that identifies your end user who owns the thread. - - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` +### Example - - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` +```java +package com.openai.example; - - `COMPUTER_USE_PREVIEW("computer-use-preview")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.threads.ChatKitThread; +import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams; - - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` +public final class Main { + private Main() {} - - `GPT_5_CODEX("gpt-5-codex")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `GPT_5_PRO("gpt-5-pro")` + ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123"); + } +} +``` - - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` +#### Response - - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` +```json +{ + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" +} +``` - - `JsonValue; object_ "response"constant` +### Example - The object type of this resource - always set to `response`. +```java +package com.openai.example; - - `RESPONSE("response")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.threads.ChatKitThread; +import com.openai.models.beta.chatkit.threads.ThreadRetrieveParams; - - `List output` +public final class Main { + private Main() {} - An array of content items generated by the model. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + ChatKitThread chatkitThread = client.beta().chatkit().threads().retrieve("cthr_123"); + } +} +``` - - `class BetaResponseOutputMessage:` +#### Response - An output message from the model. +```json +{ + "id": "cthr_abc123", + "object": "chatkit.thread", + "title": "Customer escalation", + "items": { + "data": [ + { + "id": "cthi_user_001", + "object": "chatkit.thread_item", + "type": "user_message", + "content": [ + { + "type": "input_text", + "text": "I need help debugging an onboarding issue." + } + ], + "attachments": [] + }, + { + "id": "cthi_assistant_002", + "object": "chatkit.thread_item", + "type": "assistant_message", + "content": [ + { + "type": "output_text", + "text": "Let's start by confirming the workflow version you deployed." + } + ] + } + ], + "has_more": false + } +} +``` - - `class BetaResponseFileSearchToolCall:` +## Delete ChatKit thread - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. +`ThreadDeleteResponse beta().chatkit().threads().delete(ThreadDeleteParamsparams = ThreadDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `class BetaResponseFunctionToolCall:` +**delete** `/chatkit/threads/{thread_id}` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. +Delete a ChatKit thread along with its items and stored attachments. - - `class BetaResponseFunctionToolCallOutputItem:` +### Parameters - - `String id` +- `ThreadDeleteParams params` - The unique ID of the function call tool output. + - `Optional threadId` - - `String callId` +### Returns - The unique ID of the function tool call generated by the model. +- `class ThreadDeleteResponse:` - - `Output output` + Confirmation payload returned after deleting a thread. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `String id` - - `String` + Identifier of the deleted thread. - - `List` + - `boolean deleted` - - `class BetaResponseInputText:` + Indicates that the thread has been deleted. - A text input to the model. + - `JsonValue; object_ "chatkit.thread.deleted"constant` - - `class BetaResponseInputImage:` + Type discriminator that is always `chatkit.thread.deleted`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `CHATKIT_THREAD_DELETED("chatkit.thread.deleted")` - - `class BetaResponseInputFile:` +### Example - A file input to the model. +```java +package com.openai.example; - - `Status status` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.threads.ThreadDeleteParams; +import com.openai.models.beta.chatkit.threads.ThreadDeleteResponse; - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +public final class Main { + private Main() {} - - `IN_PROGRESS("in_progress")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `COMPLETED("completed")` + ThreadDeleteResponse thread = client.beta().chatkit().threads().delete("cthr_123"); + } +} +``` - - `INCOMPLETE("incomplete")` +#### Response - - `JsonValue; type "function_call_output"constant` +```json +{ + "id": "id", + "deleted": true, + "object": "chatkit.thread.deleted" +} +``` - The type of the function tool call output. Always `function_call_output`. +### Example - - `FUNCTION_CALL_OUTPUT("function_call_output")` +```java +package com.openai.example; - - `Optional agent` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chat_kit.threads.ThreadDeleteParams; +import com.openai.models.beta.chat_kit.threads.ThreadDeleteResponse; - The agent that produced this item. +public final class Main { + private Main() {} - - `String agentName` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The canonical name of the agent that produced this item. + ThreadDeleteResponse thread = client.beta().chat_kit().threads().delete("cthr_123"); + } +} +``` - - `Optional caller` +## List ChatKit threads - The execution context that produced this tool call. +`ThreadListPage beta().chatkit().threads().list(ThreadListParamsparams = ThreadListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `JsonValue;` +**get** `/chatkit/threads` - - `JsonValue; type "direct"constant` +List ChatKit threads with optional pagination and user filters. - The caller type. Always `direct`. +### Parameters - - `DIRECT("direct")` +- `ThreadListParams params` - - `class Program:` + - `Optional after` - - `String callerId` + List items created after this thread item ID. Defaults to null for the first page. - The call ID of the program item that produced this tool call. + - `Optional before` - - `JsonValue; type "program"constant` + List items created before this thread item ID. Defaults to null for the newest results. - The caller type. Always `program`. + - `Optional limit` - - `PROGRAM("program")` + Maximum number of thread items to return. Defaults to 20. - - `Optional createdBy` + - `Optional order` - The identifier of the actor that created the item. + Sort order for results by creation time. Defaults to `desc`. - - `AgentMessage` + - `ASC("asc")` - - `String id` + - `DESC("desc")` - The unique ID of the agent message. + - `Optional user` - - `String author` + Filter threads that belong to this user identifier. Defaults to null to return all users. - The sending agent identity. +### Returns - - `List content` +- `class ChatKitThread:` - Encrypted content sent between agents. + Represents a ChatKit thread and its current status. - - `class BetaResponseInputText:` + - `String id` - A text input to the model. + Identifier of the thread. - - `class BetaResponseOutputText:` + - `long createdAt` - A text output from the model. + Unix timestamp (in seconds) for when the thread was created. - - `class Text:` + - `JsonValue; object_ "chatkit.thread"constant` - A text content. + Type discriminator that is always `chatkit.thread`. - - `String text` + - `CHATKIT_THREAD("chatkit.thread")` - - `JsonValue; type "text"constant` + - `Status status` - - `TEXT("text")` + Current status for the thread. Defaults to `active` for newly created threads. - - `class SummaryText:` + - `JsonValue;` - A summary text from the model. + - `JsonValue; type "active"constant` - - `String text` + Status discriminator that is always `active`. - A summary of the reasoning output from the model so far. + - `ACTIVE("active")` - - `JsonValue; type "summary_text"constant` + - `class Locked:` - The type of the object. Always `summary_text`. + Indicates that a thread is locked and cannot accept new input. - - `SUMMARY_TEXT("summary_text")` + - `Optional reason` - - `class ReasoningText:` + Reason that the thread was locked. Defaults to null when no reason is recorded. - Reasoning text from the model. + - `JsonValue; type "locked"constant` - - `String text` + Status discriminator that is always `locked`. - The reasoning text from the model. + - `LOCKED("locked")` - - `JsonValue; type "reasoning_text"constant` + - `class Closed:` - The type of the reasoning text. Always `reasoning_text`. + Indicates that a thread has been closed. - - `REASONING_TEXT("reasoning_text")` + - `Optional reason` - - `class BetaResponseOutputRefusal:` + Reason that the thread was closed. Defaults to null when no reason is recorded. - A refusal from the model. + - `JsonValue; type "closed"constant` - - `class BetaResponseInputImage:` + Status discriminator that is always `closed`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `CLOSED("closed")` - - `class ComputerScreenshot:` + - `Optional title` - A screenshot of a computer. + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `Detail detail` + - `String user` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Free-form string that identifies your end user who owns the thread. - - `LOW("low")` +### Example - - `HIGH("high")` +```java +package com.openai.example; - - `AUTO("auto")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.threads.ThreadListPage; +import com.openai.models.beta.chatkit.threads.ThreadListParams; - - `ORIGINAL("original")` +public final class Main { + private Main() {} - - `Optional fileId` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The identifier of an uploaded file that contains the screenshot. + ThreadListPage page = client.beta().chatkit().threads().list(); + } +} +``` - - `Optional imageUrl` +#### Response - The URL of the screenshot image. +```json +{ + "data": [ + { + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `JsonValue; type "computer_screenshot"constant` +### Example - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. +```java +package com.openai.example; - - `COMPUTER_SCREENSHOT("computer_screenshot")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.chatkit.threads.ThreadListPage; +import com.openai.models.beta.chatkit.threads.ThreadListParams; - - `Optional promptCacheBreakpoint` +public final class Main { + private Main() {} - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `JsonValue; mode "explicit"constant` + ThreadListPage page = client.beta().chatkit().threads().list(); + } +} +``` - The breakpoint mode. Always `explicit`. +#### Response - - `EXPLICIT("explicit")` +```json +{ + "data": [ + { + "id": "cthr_abc123", + "object": "chatkit.thread", + "title": "Customer escalation" + }, + { + "id": "cthr_def456", + "object": "chatkit.thread", + "title": "Demo feedback" + } + ], + "has_more": false, + "object": "list" +} +``` - - `class BetaResponseInputFile:` +## Domain Types - A file input to the model. +### Chat Session - - `class EncryptedContent:` +- `class ChatSession:` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Represents a ChatKit session and its resolved configuration. - - `String encryptedContent` + - `String id` - Opaque encrypted content. + Identifier for the ChatKit session. - - `JsonValue; type "encrypted_content"constant` + - `ChatSessionChatKitConfiguration chatkitConfiguration` - The type of the input item. Always `encrypted_content`. + Resolved ChatKit feature configuration for the session. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `ChatSessionAutomaticThreadTitling automaticThreadTitling` - - `String recipient` + Automatic thread titling preferences. - The destination agent identity. + - `boolean enabled` - - `JsonValue; type "agent_message"constant` + Whether automatic thread titling is enabled. - The type of the item. Always `agent_message`. + - `ChatSessionFileUpload fileUpload` - - `AGENT_MESSAGE("agent_message")` + Upload settings for the session. - - `Optional agent` + - `boolean enabled` - The agent that produced this item. + Indicates if uploads are enabled for the session. - - `String agentName` + - `Optional maxFileSize` - The canonical name of the agent that produced this item. + Maximum upload size in megabytes. - - `MultiAgentCall` + - `Optional maxFiles` - - `String id` + Maximum number of uploads allowed during the session. - The unique ID of the multi-agent call item. + - `ChatSessionHistory history` - - `Action action` + History retention configuration. - The multi-agent action to execute. + - `boolean enabled` - - `SPAWN_AGENT("spawn_agent")` + Indicates if chat history is persisted for the session. - - `INTERRUPT_AGENT("interrupt_agent")` + - `Optional recentThreads` - - `LIST_AGENTS("list_agents")` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `SEND_MESSAGE("send_message")` + - `String clientSecret` - - `FOLLOWUP_TASK("followup_task")` + Ephemeral client secret that authenticates session requests. - - `WAIT_AGENT("wait_agent")` + - `long expiresAt` - - `String arguments` + Unix timestamp (in seconds) for when the session expires. - The JSON string of arguments generated for the action. + - `long maxRequestsPer1Minute` - - `String callId` + Convenience copy of the per-minute request limit. - The unique ID linking this call to its output. + - `JsonValue; object_ "chatkit.session"constant` - - `JsonValue; type "multi_agent_call"constant` + Type discriminator that is always `chatkit.session`. - The type of the multi-agent call. Always `multi_agent_call`. + - `CHATKIT_SESSION("chatkit.session")` - - `MULTI_AGENT_CALL("multi_agent_call")` + - `ChatSessionRateLimits rateLimits` - - `Optional agent` + Resolved rate limit values. - The agent that produced this item. + - `long maxRequestsPer1Minute` - - `String agentName` + Maximum allowed requests per one-minute window. - The canonical name of the agent that produced this item. + - `ChatSessionStatus status` - - `MultiAgentCallOutput` + Current lifecycle state of the session. - - `String id` + - `ACTIVE("active")` - The unique ID of the multi-agent call output item. + - `EXPIRED("expired")` - - `Action action` + - `CANCELLED("cancelled")` - The multi-agent action that produced this result. + - `String user` - - `SPAWN_AGENT("spawn_agent")` + User identifier associated with the session. - - `INTERRUPT_AGENT("interrupt_agent")` + - `ChatKitWorkflow workflow` - - `LIST_AGENTS("list_agents")` + Workflow metadata for the session. - - `SEND_MESSAGE("send_message")` + - `String id` - - `FOLLOWUP_TASK("followup_task")` + Identifier of the workflow backing the session. - - `WAIT_AGENT("wait_agent")` + - `Optional stateVariables` - - `String callId` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - The unique ID of the multi-agent call. + - `String` - - `List output` + - `boolean` - Text output returned by the multi-agent action. + - `double` - - `List annotations` + - `Tracing tracing` - The annotations of the text output. + Tracing settings applied to the workflow. - - `String text` + - `boolean enabled` - The text output from the model. + Indicates whether tracing is enabled. - - `JsonValue; type "output_text"constant` + - `Optional version` - The type of the output text. Always `output_text`. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `Optional> logprobs` +### Chat Session Automatic Thread Titling - - `JsonValue; type "multi_agent_call_output"constant` +- `class ChatSessionAutomaticThreadTitling:` - The type of the multi-agent result. Always `multi_agent_call_output`. + Automatic thread title preferences for the session. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `boolean enabled` - - `Optional agent` + Whether automatic thread titling is enabled. - The agent that produced this item. +### Chat Session ChatKit Configuration - - `String agentName` +- `class ChatSessionChatKitConfiguration:` - The canonical name of the agent that produced this item. + ChatKit configuration for the session. - - `class BetaResponseFunctionWebSearch:` + - `ChatSessionAutomaticThreadTitling automaticThreadTitling` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Automatic thread titling preferences. - - `class BetaResponseComputerToolCall:` + - `boolean enabled` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Whether automatic thread titling is enabled. - - `class BetaResponseComputerToolCallOutputItem:` + - `ChatSessionFileUpload fileUpload` - - `String id` + Upload settings for the session. - The unique ID of the computer call tool output. + - `boolean enabled` - - `String callId` + Indicates if uploads are enabled for the session. - The ID of the computer tool call that produced the output. + - `Optional maxFileSize` - - `BetaResponseComputerToolCallOutputScreenshot output` + Maximum upload size in megabytes. - A computer screenshot image used with the computer use tool. + - `Optional maxFiles` - - `Status status` + Maximum number of uploads allowed during the session. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `ChatSessionHistory history` - - `COMPLETED("completed")` + History retention configuration. - - `INCOMPLETE("incomplete")` + - `boolean enabled` - - `FAILED("failed")` + Indicates if chat history is persisted for the session. - - `IN_PROGRESS("in_progress")` + - `Optional recentThreads` - - `JsonValue; type "computer_call_output"constant` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - The type of the computer tool call output. Always `computer_call_output`. +### Chat Session ChatKit Configuration Param - - `COMPUTER_CALL_OUTPUT("computer_call_output")` +- `class ChatSessionChatKitConfigurationParam:` - - `Optional> acknowledgedSafetyChecks` + Optional per-session configuration settings for ChatKit behavior. - The safety checks reported by the API that have been acknowledged by the - developer. + - `Optional automaticThreadTitling` - - `String id` + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - The ID of the pending safety check. + - `Optional enabled` - - `Optional code` + Enable automatic thread title generation. Defaults to true. - The type of the pending safety check. + - `Optional fileUpload` - - `Optional message` + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - Details about the pending safety check. + - `Optional enabled` - - `Optional agent` + Enable uploads for this session. Defaults to false. - The agent that produced this item. + - `Optional maxFileSize` - - `String agentName` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - The canonical name of the agent that produced this item. + - `Optional maxFiles` - - `Optional createdBy` + Maximum number of files that can be uploaded to the session. Defaults to 10. - The identifier of the actor that created the item. + - `Optional history` - - `class BetaResponseReasoningItem:` + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `Optional enabled` - - `Program` + Enables chat users to access previous ChatKit threads. Defaults to true. - - `String id` + - `Optional recentThreads` - The unique ID of the program item. + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `String callId` +### Chat Session Expires After Param - The stable call ID of the program item. +- `class ChatSessionExpiresAfterParam:` - - `String code` + Controls when the session expires relative to an anchor timestamp. - The JavaScript source executed by programmatic tool calling. + - `JsonValue; anchor "created_at"constant` - - `String fingerprint` + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - Opaque program replay fingerprint that must be round-tripped. + - `CREATED_AT("created_at")` - - `JsonValue; type "program"constant` + - `long seconds` - The type of the item. Always `program`. + Number of seconds after the anchor when the session expires. - - `PROGRAM("program")` +### Chat Session File Upload - - `Optional agent` +- `class ChatSessionFileUpload:` - The agent that produced this item. + Upload permissions and limits applied to the session. - - `String agentName` + - `boolean enabled` - The canonical name of the agent that produced this item. + Indicates if uploads are enabled for the session. - - `ProgramOutput` + - `Optional maxFileSize` - - `String id` + Maximum upload size in megabytes. - The unique ID of the program output item. + - `Optional maxFiles` - - `String callId` + Maximum number of uploads allowed during the session. - The call ID of the program item. +### Chat Session History - - `String result` +- `class ChatSessionHistory:` - The result produced by the program item. + History retention preferences returned for the session. - - `Status status` + - `boolean enabled` - The terminal status of the program output item. + Indicates if chat history is persisted for the session. - - `COMPLETED("completed")` + - `Optional recentThreads` - - `INCOMPLETE("incomplete")` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `JsonValue; type "program_output"constant` +### Chat Session Rate Limits - The type of the item. Always `program_output`. +- `class ChatSessionRateLimits:` - - `PROGRAM_OUTPUT("program_output")` + Active per-minute request limit for the session. - - `Optional agent` + - `long maxRequestsPer1Minute` - The agent that produced this item. + Maximum allowed requests per one-minute window. - - `String agentName` +### Chat Session Rate Limits Param + +- `class ChatSessionRateLimitsParam:` - The canonical name of the agent that produced this item. + Controls request rate limits for the session. - - `class BetaResponseToolSearchCall:` + - `Optional maxRequestsPer1Minute` - - `String id` + Maximum number of requests allowed per minute for the session. Defaults to 10. - The unique ID of the tool search call item. +### Chat Session Status - - `JsonValue arguments` +- `enum ChatSessionStatus:` - Arguments used for the tool search call. + - `ACTIVE("active")` - - `Optional callId` + - `EXPIRED("expired")` - The unique ID of the tool search call generated by the model. + - `CANCELLED("cancelled")` - - `Execution execution` +### Chat Session Workflow Param - Whether tool search was executed by the server or by the client. +- `class ChatSessionWorkflowParam:` - - `SERVER("server")` + Workflow reference and overrides applied to the chat session. - - `CLIENT("client")` + - `String id` - - `Status status` + Identifier for the workflow invoked by the session. - The status of the tool search call item that was recorded. + - `Optional stateVariables` - - `IN_PROGRESS("in_progress")` + State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - - `COMPLETED("completed")` + - `String` - - `INCOMPLETE("incomplete")` + - `boolean` - - `JsonValue; type "tool_search_call"constant` + - `double` - The type of the item. Always `tool_search_call`. + - `Optional tracing` - - `TOOL_SEARCH_CALL("tool_search_call")` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - - `Optional agent` + - `Optional enabled` - The agent that produced this item. + Whether tracing is enabled during the session. Defaults to true. - - `String agentName` + - `Optional version` - The canonical name of the agent that produced this item. + Specific workflow version to run. Defaults to the latest deployed version. - - `Optional createdBy` +### ChatKit Attachment - The identifier of the actor that created the item. +- `class ChatKitAttachment:` - - `class BetaResponseToolSearchOutputItem:` + Attachment metadata included on thread items. - `String id` - The unique ID of the tool search output item. - - - `Optional callId` + Identifier for the attachment. - The unique ID of the tool search call generated by the model. + - `String mimeType` - - `Execution execution` + MIME type of the attachment. - Whether tool search was executed by the server or by the client. + - `String name` - - `SERVER("server")` + Original display name for the attachment. - - `CLIENT("client")` + - `Optional previewUrl` - - `Status status` + Preview URL for rendering the attachment inline. - The status of the tool search output item that was recorded. + - `Type type` - - `IN_PROGRESS("in_progress")` + Attachment discriminator. - - `COMPLETED("completed")` + - `IMAGE("image")` - - `INCOMPLETE("incomplete")` + - `FILE("file")` - - `List tools` +### ChatKit Response Output Text - The loaded tool definitions returned by tool search. +- `class ChatKitResponseOutputText:` - - `class BetaFunctionTool:` + Assistant response text accompanied by optional annotations. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `List annotations` - - `class BetaFileSearchTool:` + Ordered list of annotations attached to the response text. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `class File:` - - `class BetaComputerTool:` + Annotation that references an uploaded file. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Source source` - - `class BetaComputerUsePreviewTool:` + File attachment referenced by the annotation. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String filename` - - `class BetaWebSearchTool:` + Filename referenced by the annotation. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "file"constant` - - `Mcp` + Type discriminator that is always `file`. - - `CodeInterpreter` + - `FILE("file")` - - `JsonValue;` + - `JsonValue; type "file"constant` - - `ImageGeneration` + Type discriminator that is always `file` for this annotation. - - `JsonValue;` + - `FILE("file")` - - `class BetaFunctionShellTool:` + - `class Url:` - A tool that allows the model to execute shell commands. + Annotation that references a URL. - - `class BetaCustomTool:` + - `Source source` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + URL referenced by the annotation. - - `class BetaNamespaceTool:` + - `JsonValue; type "url"constant` - Groups function/custom tools under a shared namespace. + Type discriminator that is always `url`. - - `class BetaToolSearchTool:` + - `URL("url")` - Hosted or BYOT tool search configuration for deferred tools. + - `String url` - - `class BetaWebSearchPreviewTool:` + URL referenced by the annotation. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "url"constant` - - `class BetaApplyPatchTool:` + Type discriminator that is always `url` for this annotation. - Allows the assistant to create, delete, or update files using unified diffs. + - `URL("url")` - - `JsonValue; type "tool_search_output"constant` + - `String text` - The type of the item. Always `tool_search_output`. + Assistant generated text. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `JsonValue; type "output_text"constant` - - `Optional agent` + Type discriminator that is always `output_text`. - The agent that produced this item. + - `OUTPUT_TEXT("output_text")` - - `String agentName` +### ChatKit Thread - The canonical name of the agent that produced this item. +- `class ChatKitThread:` - - `Optional createdBy` + Represents a ChatKit thread and its current status. - The identifier of the actor that created the item. + - `String id` - - `AdditionalTools` + Identifier of the thread. - - `String id` + - `long createdAt` - The unique ID of the additional tools item. + Unix timestamp (in seconds) for when the thread was created. - - `Role role` + - `JsonValue; object_ "chatkit.thread"constant` - The role that provided the additional tools. + Type discriminator that is always `chatkit.thread`. - - `UNKNOWN("unknown")` + - `CHATKIT_THREAD("chatkit.thread")` - - `USER("user")` + - `Status status` - - `ASSISTANT("assistant")` + Current status for the thread. Defaults to `active` for newly created threads. - - `SYSTEM("system")` + - `JsonValue;` - - `CRITIC("critic")` + - `JsonValue; type "active"constant` - - `DISCRIMINATOR("discriminator")` + Status discriminator that is always `active`. - - `DEVELOPER("developer")` + - `ACTIVE("active")` - - `TOOL("tool")` + - `class Locked:` - - `List tools` + Indicates that a thread is locked and cannot accept new input. - The additional tool definitions made available at this item. + - `Optional reason` - - `class BetaFunctionTool:` + Reason that the thread was locked. Defaults to null when no reason is recorded. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `JsonValue; type "locked"constant` - - `class BetaFileSearchTool:` + Status discriminator that is always `locked`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `LOCKED("locked")` - - `class BetaComputerTool:` + - `class Closed:` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Indicates that a thread has been closed. - - `class BetaComputerUsePreviewTool:` + - `Optional reason` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `class BetaWebSearchTool:` + - `JsonValue; type "closed"constant` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Status discriminator that is always `closed`. - - `Mcp` + - `CLOSED("closed")` - - `CodeInterpreter` + - `Optional title` - - `JsonValue;` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `ImageGeneration` + - `String user` - - `JsonValue;` + Free-form string that identifies your end user who owns the thread. - - `class BetaFunctionShellTool:` +### ChatKit Thread Assistant Message Item - A tool that allows the model to execute shell commands. +- `class ChatKitThreadAssistantMessageItem:` - - `class BetaCustomTool:` + Assistant-authored message within a thread. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `String id` - - `class BetaNamespaceTool:` + Identifier of the thread item. - Groups function/custom tools under a shared namespace. + - `List content` - - `class BetaToolSearchTool:` + Ordered assistant response segments. - Hosted or BYOT tool search configuration for deferred tools. + - `List annotations` - - `class BetaWebSearchPreviewTool:` + Ordered list of annotations attached to the response text. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `class File:` - - `class BetaApplyPatchTool:` + Annotation that references an uploaded file. - Allows the assistant to create, delete, or update files using unified diffs. + - `Source source` - - `JsonValue; type "additional_tools"constant` + File attachment referenced by the annotation. - The type of the item. Always `additional_tools`. + - `String filename` - - `ADDITIONAL_TOOLS("additional_tools")` + Filename referenced by the annotation. - - `Optional agent` + - `JsonValue; type "file"constant` - The agent that produced this item. + Type discriminator that is always `file`. - - `String agentName` + - `FILE("file")` - The canonical name of the agent that produced this item. + - `JsonValue; type "file"constant` - - `class BetaResponseCompactionItem:` + Type discriminator that is always `file` for this annotation. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `FILE("file")` - - `String id` + - `class Url:` - The unique ID of the compaction item. + Annotation that references a URL. - - `String encryptedContent` + - `Source source` - The encrypted content that was produced by compaction. + URL referenced by the annotation. - - `JsonValue; type "compaction"constant` + - `JsonValue; type "url"constant` - The type of the item. Always `compaction`. + Type discriminator that is always `url`. - - `COMPACTION("compaction")` + - `URL("url")` - - `Optional agent` + - `String url` - The agent that produced this item. + URL referenced by the annotation. - - `String agentName` + - `JsonValue; type "url"constant` - The canonical name of the agent that produced this item. + Type discriminator that is always `url` for this annotation. - - `Optional createdBy` + - `URL("url")` - The identifier of the actor that created the item. + - `String text` - - `ImageGenerationCall` + Assistant generated text. - - `String id` + - `JsonValue; type "output_text"constant` - The unique ID of the image generation call. + Type discriminator that is always `output_text`. - - `Optional result` + - `OUTPUT_TEXT("output_text")` - The generated image encoded in base64. + - `long createdAt` - - `Status status` + Unix timestamp (in seconds) for when the item was created. - The status of the image generation call. + - `JsonValue; object_ "chatkit.thread_item"constant` - - `IN_PROGRESS("in_progress")` + Type discriminator that is always `chatkit.thread_item`. - - `COMPLETED("completed")` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `GENERATING("generating")` + - `String threadId` - - `FAILED("failed")` + Identifier of the parent thread. - - `JsonValue; type "image_generation_call"constant` + - `JsonValue; type "chatkit.assistant_message"constant` - The type of the image generation call. Always `image_generation_call`. + Type discriminator that is always `chatkit.assistant_message`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")` - - `Optional agent` +### ChatKit Thread Item List - The agent that produced this item. +- `class ChatKitThreadItemList:` - - `String agentName` + A paginated list of thread items rendered for the ChatKit API. - The canonical name of the agent that produced this item. + - `List data` - - `class BetaResponseCodeInterpreterToolCall:` + A list of items - A tool call to run code. + - `class ChatKitThreadUserMessageItem:` - - `LocalShellCall` + User-authored messages within a thread. - `String id` - The unique ID of the local shell call. + Identifier of the thread item. - - `Action action` + - `List attachments` - Execute a shell command on the server. + Attachments associated with the user message. Defaults to an empty list. - - `List command` + - `String id` - The command to run. + Identifier for the attachment. - - `Env env` + - `String mimeType` - Environment variables to set for the command. + MIME type of the attachment. - - `JsonValue; type "exec"constant` + - `String name` - The type of the local shell action. Always `exec`. + Original display name for the attachment. - - `EXEC("exec")` + - `Optional previewUrl` - - `Optional timeoutMs` + Preview URL for rendering the attachment inline. - Optional timeout in milliseconds for the command. + - `Type type` - - `Optional user` + Attachment discriminator. - Optional user to run the command as. + - `IMAGE("image")` - - `Optional workingDirectory` + - `FILE("file")` - Optional working directory to run the command in. + - `List content` - - `String callId` + Ordered content elements supplied by the user. - The unique ID of the local shell tool call generated by the model. + - `class InputText:` - - `Status status` + Text block that a user contributed to the thread. - The status of the local shell call. + - `String text` - - `IN_PROGRESS("in_progress")` + Plain-text content supplied by the user. - - `COMPLETED("completed")` + - `JsonValue; type "input_text"constant` - - `INCOMPLETE("incomplete")` + Type discriminator that is always `input_text`. - - `JsonValue; type "local_shell_call"constant` + - `INPUT_TEXT("input_text")` - The type of the local shell call. Always `local_shell_call`. + - `class QuotedText:` - - `LOCAL_SHELL_CALL("local_shell_call")` + Quoted snippet that the user referenced in their message. - - `Optional agent` + - `String text` - The agent that produced this item. + Quoted text content. - - `String agentName` + - `JsonValue; type "quoted_text"constant` - The canonical name of the agent that produced this item. + Type discriminator that is always `quoted_text`. - - `LocalShellCallOutput` + - `QUOTED_TEXT("quoted_text")` - - `String id` + - `long createdAt` - The unique ID of the local shell tool call generated by the model. + Unix timestamp (in seconds) for when the item was created. - - `String output` + - `Optional inferenceOptions` - A JSON string of the output of the local shell tool call. + Inference overrides applied to the message. Defaults to null when unset. - - `JsonValue; type "local_shell_call_output"constant` + - `Optional model` - The type of the local shell tool call output. Always `local_shell_call_output`. + Model name that generated the response. Defaults to null when using the session default. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `Optional toolChoice` - - `Optional agent` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - The agent that produced this item. + - `String id` - - `String agentName` + Identifier of the requested tool. - The canonical name of the agent that produced this item. + - `JsonValue; object_ "chatkit.thread_item"constant` - - `Optional status` + Type discriminator that is always `chatkit.thread_item`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `IN_PROGRESS("in_progress")` + - `String threadId` - - `COMPLETED("completed")` + Identifier of the parent thread. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "chatkit.user_message"constant` - - `class BetaResponseFunctionShellToolCall:` + - `CHATKIT_USER_MESSAGE("chatkit.user_message")` - A tool call that executes one or more shell commands in a managed environment. + - `class ChatKitThreadAssistantMessageItem:` + + Assistant-authored message within a thread. - `String id` - The unique ID of the shell tool call. Populated when this item is returned via API. + Identifier of the thread item. - - `Action action` + - `List content` - The shell commands and limits that describe how to run the tool call. + Ordered assistant response segments. - - `List commands` + - `List annotations` - - `Optional maxOutputLength` + Ordered list of annotations attached to the response text. - Optional maximum number of characters to return from each command. + - `class File:` - - `Optional timeoutMs` + Annotation that references an uploaded file. - Optional timeout in milliseconds for the commands. + - `Source source` - - `String callId` + File attachment referenced by the annotation. - The unique ID of the shell tool call generated by the model. + - `String filename` - - `Optional environment` + Filename referenced by the annotation. - Represents the use of a local environment to perform shell actions. + - `JsonValue; type "file"constant` - - `class BetaResponseLocalEnvironment:` + Type discriminator that is always `file`. - Represents the use of a local environment to perform shell actions. + - `FILE("file")` - - `JsonValue; type "local"constant` + - `JsonValue; type "file"constant` - The environment type. Always `local`. + Type discriminator that is always `file` for this annotation. - - `LOCAL("local")` + - `FILE("file")` - - `class BetaResponseContainerReference:` + - `class Url:` - Represents a container created with /v1/containers. + Annotation that references a URL. - - `String containerId` + - `Source source` - - `JsonValue; type "container_reference"constant` + URL referenced by the annotation. - The environment type. Always `container_reference`. + - `JsonValue; type "url"constant` - - `CONTAINER_REFERENCE("container_reference")` + Type discriminator that is always `url`. - - `Status status` + - `URL("url")` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `String url` - - `IN_PROGRESS("in_progress")` + URL referenced by the annotation. - - `COMPLETED("completed")` + - `JsonValue; type "url"constant` - - `INCOMPLETE("incomplete")` + Type discriminator that is always `url` for this annotation. - - `JsonValue; type "shell_call"constant` + - `URL("url")` - The type of the item. Always `shell_call`. + - `String text` - - `SHELL_CALL("shell_call")` + Assistant generated text. - - `Optional agent` + - `JsonValue; type "output_text"constant` - The agent that produced this item. + Type discriminator that is always `output_text`. - - `String agentName` + - `OUTPUT_TEXT("output_text")` - The canonical name of the agent that produced this item. + - `long createdAt` - - `Optional caller` + Unix timestamp (in seconds) for when the item was created. - The execution context that produced this tool call. + - `JsonValue; object_ "chatkit.thread_item"constant` - - `JsonValue;` + Type discriminator that is always `chatkit.thread_item`. - - `JsonValue; type "direct"constant` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `DIRECT("direct")` + - `String threadId` - - `class Program:` + Identifier of the parent thread. - - `String callerId` + - `JsonValue; type "chatkit.assistant_message"constant` - The call ID of the program item that produced this tool call. + Type discriminator that is always `chatkit.assistant_message`. - - `JsonValue; type "program"constant` + - `CHATKIT_ASSISTANT_MESSAGE("chatkit.assistant_message")` - - `PROGRAM("program")` + - `class ChatKitWidgetItem:` - - `Optional createdBy` + Thread item that renders a widget payload. - The ID of the entity that created this tool call. + - `String id` - - `class BetaResponseFunctionShellToolCallOutput:` + Identifier of the thread item. - The output of a shell tool call that was emitted. + - `long createdAt` - - `String id` + Unix timestamp (in seconds) for when the item was created. - The unique ID of the shell call output. Populated when this item is returned via API. + - `JsonValue; object_ "chatkit.thread_item"constant` - - `String callId` + Type discriminator that is always `chatkit.thread_item`. - The unique ID of the shell tool call generated by the model. + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `Optional maxOutputLength` + - `String threadId` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + Identifier of the parent thread. - - `List output` + - `JsonValue; type "chatkit.widget"constant` - An array of shell call output contents + Type discriminator that is always `chatkit.widget`. - - `Outcome outcome` + - `CHATKIT_WIDGET("chatkit.widget")` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `String widget` - - `JsonValue;` + Serialized widget payload rendered in the UI. - - `JsonValue; type "timeout"constant` + - `class ChatKitClientToolCall:` - The outcome type. Always `timeout`. + Record of a client side tool invocation initiated by the assistant. - - `TIMEOUT("timeout")` + - `String id` - - `class Exit:` + Identifier of the thread item. - Indicates that the shell commands finished and returned an exit code. + - `String arguments` - - `long exitCode` + JSON-encoded arguments that were sent to the tool. - Exit code from the shell process. + - `String callId` - - `JsonValue; type "exit"constant` + Identifier for the client tool call. - The outcome type. Always `exit`. + - `long createdAt` - - `EXIT("exit")` + Unix timestamp (in seconds) for when the item was created. - - `String stderr` + - `String name` - The standard error output that was captured. + Tool name that was invoked. - - `String stdout` + - `JsonValue; object_ "chatkit.thread_item"constant` - The standard output that was captured. + Type discriminator that is always `chatkit.thread_item`. - - `Optional createdBy` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - The identifier of the actor that created the item. + - `Optional output` + + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - `Status status` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Execution status for the tool call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - - `INCOMPLETE("incomplete")` + - `String threadId` - - `JsonValue; type "shell_call_output"constant` + Identifier of the parent thread. - The type of the shell call output. Always `shell_call_output`. + - `JsonValue; type "chatkit.client_tool_call"constant` - - `SHELL_CALL_OUTPUT("shell_call_output")` + Type discriminator that is always `chatkit.client_tool_call`. - - `Optional agent` + - `CHATKIT_CLIENT_TOOL_CALL("chatkit.client_tool_call")` - The agent that produced this item. + - `class ChatKitTask:` - - `String agentName` + Task emitted by the workflow to show progress and status updates. - The canonical name of the agent that produced this item. + - `String id` - - `Optional caller` + Identifier of the thread item. - The execution context that produced this tool call. + - `long createdAt` - - `JsonValue;` + Unix timestamp (in seconds) for when the item was created. - - `JsonValue; type "direct"constant` + - `Optional heading` - - `DIRECT("direct")` + Optional heading for the task. Defaults to null when not provided. - - `class Program:` + - `JsonValue; object_ "chatkit.thread_item"constant` - - `String callerId` + Type discriminator that is always `chatkit.thread_item`. - The call ID of the program item that produced this tool call. + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `JsonValue; type "program"constant` + - `Optional summary` - - `PROGRAM("program")` + Optional summary that describes the task. Defaults to null when omitted. - - `Optional createdBy` + - `TaskType taskType` - The identifier of the actor that created the item. + Subtype for the task. - - `class BetaResponseApplyPatchToolCall:` + - `CUSTOM("custom")` - A tool call that applies file diffs by creating, deleting, or updating files. + - `THOUGHT("thought")` - - `String id` + - `String threadId` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Identifier of the parent thread. - - `String callId` + - `JsonValue; type "chatkit.task"constant` - The unique ID of the apply patch tool call generated by the model. + Type discriminator that is always `chatkit.task`. - - `Operation operation` + - `CHATKIT_TASK("chatkit.task")` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `class ChatKitTaskGroup:` - - `class CreateFile:` + Collection of workflow tasks grouped together in the thread. - Instruction describing how to create a file via the apply_patch tool. + - `String id` - - `String diff` + Identifier of the thread item. - Diff to apply. + - `long createdAt` - - `String path` + Unix timestamp (in seconds) for when the item was created. - Path of the file to create. + - `JsonValue; object_ "chatkit.thread_item"constant` - - `JsonValue; type "create_file"constant` + Type discriminator that is always `chatkit.thread_item`. - Create a new file with the provided diff. + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `CREATE_FILE("create_file")` + - `List tasks` - - `class DeleteFile:` + Tasks included in the group. - Instruction describing how to delete a file via the apply_patch tool. + - `Optional heading` - - `String path` + Optional heading for the grouped task. Defaults to null when not provided. - Path of the file to delete. + - `Optional summary` - - `JsonValue; type "delete_file"constant` + Optional summary that describes the grouped task. Defaults to null when omitted. - Delete the specified file. + - `Type type` - - `DELETE_FILE("delete_file")` + Subtype for the grouped task. - - `class UpdateFile:` + - `CUSTOM("custom")` - Instruction describing how to update a file via the apply_patch tool. + - `THOUGHT("thought")` - - `String diff` + - `String threadId` - Diff to apply. + Identifier of the parent thread. - - `String path` + - `JsonValue; type "chatkit.task_group"constant` - Path of the file to update. + Type discriminator that is always `chatkit.task_group`. - - `JsonValue; type "update_file"constant` + - `CHATKIT_TASK_GROUP("chatkit.task_group")` - Update an existing file with the provided diff. + - `Optional firstId` - - `UPDATE_FILE("update_file")` + The ID of the first item in the list. - - `Status status` + - `boolean hasMore` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Whether there are more items available. - - `IN_PROGRESS("in_progress")` + - `Optional lastId` - - `COMPLETED("completed")` + The ID of the last item in the list. - - `JsonValue; type "apply_patch_call"constant` + - `JsonValue; object_ "list"constant` - The type of the item. Always `apply_patch_call`. + The type of object returned, must be `list`. - - `APPLY_PATCH_CALL("apply_patch_call")` + - `LIST("list")` - - `Optional agent` +### ChatKit Thread User Message Item - The agent that produced this item. +- `class ChatKitThreadUserMessageItem:` - - `String agentName` + User-authored messages within a thread. - The canonical name of the agent that produced this item. + - `String id` - - `Optional caller` + Identifier of the thread item. - The execution context that produced this tool call. + - `List attachments` - - `JsonValue;` + Attachments associated with the user message. Defaults to an empty list. - - `JsonValue; type "direct"constant` + - `String id` - - `DIRECT("direct")` + Identifier for the attachment. - - `class Program:` + - `String mimeType` - - `String callerId` + MIME type of the attachment. - The call ID of the program item that produced this tool call. + - `String name` - - `JsonValue; type "program"constant` + Original display name for the attachment. - - `PROGRAM("program")` + - `Optional previewUrl` - - `Optional createdBy` + Preview URL for rendering the attachment inline. - The ID of the entity that created this tool call. + - `Type type` - - `class BetaResponseApplyPatchToolCallOutput:` + Attachment discriminator. - The output emitted by an apply patch tool call. + - `IMAGE("image")` - - `String id` + - `FILE("file")` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `List content` - - `String callId` + Ordered content elements supplied by the user. - The unique ID of the apply patch tool call generated by the model. + - `class InputText:` - - `Status status` + Text block that a user contributed to the thread. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `String text` - - `COMPLETED("completed")` + Plain-text content supplied by the user. - - `FAILED("failed")` + - `JsonValue; type "input_text"constant` - - `JsonValue; type "apply_patch_call_output"constant` + Type discriminator that is always `input_text`. - The type of the item. Always `apply_patch_call_output`. + - `INPUT_TEXT("input_text")` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `class QuotedText:` - - `Optional agent` + Quoted snippet that the user referenced in their message. - The agent that produced this item. + - `String text` - - `String agentName` + Quoted text content. - The canonical name of the agent that produced this item. + - `JsonValue; type "quoted_text"constant` - - `Optional caller` + Type discriminator that is always `quoted_text`. - The execution context that produced this tool call. + - `QUOTED_TEXT("quoted_text")` - - `JsonValue;` + - `long createdAt` - - `JsonValue; type "direct"constant` + Unix timestamp (in seconds) for when the item was created. - - `DIRECT("direct")` + - `Optional inferenceOptions` - - `class Program:` + Inference overrides applied to the message. Defaults to null when unset. - - `String callerId` + - `Optional model` - The call ID of the program item that produced this tool call. + Model name that generated the response. Defaults to null when using the session default. - - `JsonValue; type "program"constant` + - `Optional toolChoice` - - `PROGRAM("program")` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `Optional createdBy` + - `String id` - The ID of the entity that created this tool call output. + Identifier of the requested tool. - - `Optional output` + - `JsonValue; object_ "chatkit.thread_item"constant` - Optional textual output returned by the apply patch tool. + Type discriminator that is always `chatkit.thread_item`. - - `McpCall` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - - `String id` + - `String threadId` - The unique ID of the tool call. + Identifier of the parent thread. - - `String arguments` + - `JsonValue; type "chatkit.user_message"constant` - A JSON string of the arguments passed to the tool. + - `CHATKIT_USER_MESSAGE("chatkit.user_message")` - - `String name` +### ChatKit Widget Item - The name of the tool that was run. +- `class ChatKitWidgetItem:` - - `String serverLabel` + Thread item that renders a widget payload. - The label of the MCP server running the tool. + - `String id` - - `JsonValue; type "mcp_call"constant` + Identifier of the thread item. - The type of the item. Always `mcp_call`. + - `long createdAt` - - `MCP_CALL("mcp_call")` + Unix timestamp (in seconds) for when the item was created. - - `Optional agent` + - `JsonValue; object_ "chatkit.thread_item"constant` - The agent that produced this item. + Type discriminator that is always `chatkit.thread_item`. - - `String agentName` + - `CHATKIT_THREAD_ITEM("chatkit.thread_item")` - The canonical name of the agent that produced this item. + - `String threadId` - - `Optional approvalRequestId` + Identifier of the parent thread. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `JsonValue; type "chatkit.widget"constant` - - `Optional error` + Type discriminator that is always `chatkit.widget`. - The error from the tool call, if any. + - `CHATKIT_WIDGET("chatkit.widget")` - - `Optional output` + - `String widget` - The output from the tool call. + Serialized widget payload rendered in the UI. - - `Optional status` +# Assistants - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. +## List assistants - - `IN_PROGRESS("in_progress")` +`AssistantListPage beta().assistants().list(AssistantListParamsparams = AssistantListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `COMPLETED("completed")` +**get** `/assistants` - - `INCOMPLETE("incomplete")` +Returns a list of assistants. - - `CALLING("calling")` +### Parameters - - `FAILED("failed")` +- `AssistantListParams params` - - `McpListTools` + - `Optional after` - - `String id` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - The unique ID of the list. + - `Optional before` - - `String serverLabel` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - The label of the MCP server. + - `Optional limit` - - `List tools` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The tools available on the server. + - `Optional order` - - `JsonValue inputSchema` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - The JSON schema describing the tool's input. + - `ASC("asc")` - - `String name` + - `DESC("desc")` - The name of the tool. +### Returns - - `Optional annotations` +- `class Assistant:` - Additional annotations about the tool. + Represents an `assistant` that can call the model and use tools. - - `Optional description` + - `String id` - The description of the tool. + The identifier, which can be referenced in API endpoints. - - `JsonValue; type "mcp_list_tools"constant` + - `long createdAt` - The type of the item. Always `mcp_list_tools`. + The Unix timestamp (in seconds) for when the assistant was created. - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `Optional description` - - `Optional agent` + The description of the assistant. The maximum length is 512 characters. - The agent that produced this item. + - `Optional instructions` - - `String agentName` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The canonical name of the agent that produced this item. + - `Optional metadata` - - `Optional error` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Error message if the server could not list tools. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `McpApprovalRequest` + - `String model` - - `String id` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - The unique ID of the approval request. + - `Optional name` - - `String arguments` + The name of the assistant. The maximum length is 256 characters. - A JSON string of arguments for the tool. + - `JsonValue; object_ "assistant"constant` - - `String name` + The object type, which is always `assistant`. - The name of the tool to run. + - `ASSISTANT("assistant")` - - `String serverLabel` + - `List tools` - The label of the MCP server making the request. + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `JsonValue; type "mcp_approval_request"constant` + - `class CodeInterpreterTool:` - The type of the item. Always `mcp_approval_request`. + - `JsonValue; type "code_interpreter"constant` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + The type of tool being defined: `code_interpreter` - - `Optional agent` + - `CODE_INTERPRETER("code_interpreter")` - The agent that produced this item. + - `class FileSearchTool:` - - `String agentName` + - `JsonValue; type "file_search"constant` - The canonical name of the agent that produced this item. + The type of tool being defined: `file_search` - - `McpApprovalResponse` + - `FILE_SEARCH("file_search")` - - `String id` + - `Optional fileSearch` - The unique ID of the approval response + Overrides for the file search tool. - - `String approvalRequestId` + - `Optional maxNumResults` - The ID of the approval request being answered. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `boolean approve` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Whether the request was approved. + - `Optional rankingOptions` - - `JsonValue; type "mcp_approval_response"constant` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The type of the item. Always `mcp_approval_response`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `double scoreThreshold` - - `Optional agent` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The agent that produced this item. + - `Optional ranker` - - `String agentName` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The canonical name of the agent that produced this item. + - `AUTO("auto")` - - `Optional reason` + - `DEFAULT_2024_08_21("default_2024_08_21")` - Optional reason for the decision. + - `class FunctionTool:` - - `class BetaResponseCustomToolCall:` + - `FunctionDefinition function` - A call to a custom tool created by the model. + - `String name` - - `class BetaResponseCustomToolCallOutputItem:` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The output of a custom tool call from your code, being sent back to the model. + - `Optional description` - - `String id` + A description of what the function does, used by the model to choose when and how to call the function. - The unique ID of the custom tool call output item. + - `Optional parameters` - - `Status status` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Omitting `parameters` defines a function with an empty parameter list. - - `IN_PROGRESS("in_progress")` + - `Optional strict` - - `COMPLETED("completed")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `INCOMPLETE("incomplete")` + - `JsonValue; type "function"constant` - - `Optional createdBy` + The type of tool being defined: `function` - The identifier of the actor that created the item. + - `FUNCTION("function")` - - `boolean parallelToolCalls` + - `Optional responseFormat` - Whether to allow the model to run tool calls in parallel. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `Optional temperature` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `ToolChoice toolChoice` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `JsonValue;` - - `enum BetaToolChoiceOptions:` + - `AUTO("auto")` - Controls which (if any) tool is called by the model. + - `class ResponseFormatText:` - `none` means the model will not call any tool and instead generates a message. + Default response format. Used to generate text responses. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `JsonValue; type "text"constant` - `required` means the model must call one or more tools. + The type of response format being defined. Always `text`. - - `NONE("none")` + - `TEXT("text")` - - `AUTO("auto")` + - `class ResponseFormatJsonObject:` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `REQUIRED("required")` + - `JsonValue; type "json_object"constant` - - `class BetaToolChoiceAllowed:` + The type of response format being defined. Always `json_object`. - Constrains the tools available to the model to a pre-defined set. + - `JSON_OBJECT("json_object")` - - `Mode mode` + - `class ResponseFormatJsonSchema:` - Constrains the tools available to the model to a pre-defined set. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `JsonSchema jsonSchema` - `required` requires the model to call one or more of the allowed tools. + Structured Outputs configuration options, including a JSON Schema. - - `AUTO("auto")` + - `String name` - - `REQUIRED("required")` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `List tools` + - `Optional description` - A list of tool definitions that the model should be allowed to call. + A description of what the response format is for, used by the model to + determine how to respond in the format. - For the Responses API, the list of tool definitions might look like: + - `Optional schema` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `JsonValue; type "allowed_tools"constant` + - `Optional strict` - Allowed tool configuration type. Always `allowed_tools`. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `ALLOWED_TOOLS("allowed_tools")` + - `JsonValue; type "json_schema"constant` - - `class BetaToolChoiceTypes:` + The type of response format being defined. Always `json_schema`. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `JSON_SCHEMA("json_schema")` - - `Type type` + - `Optional temperature` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - Allowed values are: + - `Optional toolResources` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `FILE_SEARCH("file_search")` + - `Optional codeInterpreter` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `Optional> fileIds` - - `COMPUTER("computer")` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `Optional fileSearch` - - `COMPUTER_USE("computer_use")` + - `Optional> vectorStoreIds` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `IMAGE_GENERATION("image_generation")` + - `Optional topP` - - `CODE_INTERPRETER("code_interpreter")` + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `class BetaToolChoiceFunction:` + We generally recommend altering this or temperature but not both. - Use this option to force the model to call a specific function. +### Example - - `String name` +```java +package com.openai.example; - The name of the function to call. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.assistants.AssistantListPage; +import com.openai.models.beta.assistants.AssistantListParams; - - `JsonValue; type "function"constant` +public final class Main { + private Main() {} - For function calling, the type is always `function`. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `FUNCTION("function")` + AssistantListPage page = client.beta().assistants().list(); + } +} +``` - - `class BetaToolChoiceMcp:` +#### Response - Use this option to force the model to call a specific tool on a remote MCP server. +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 + } + ], + "first_id": "asst_abc123", + "has_more": false, + "last_id": "asst_abc456", + "object": "list" +} +``` - - `String serverLabel` +## Create assistant - The label of the MCP server to use. +`Assistant beta().assistants().create(AssistantCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `JsonValue; type "mcp"constant` +**post** `/assistants` - For MCP tools, the type is always `mcp`. +Create an assistant with a model and instructions. - - `MCP("mcp")` +### Parameters - - `Optional name` +- `AssistantCreateParams params` - The name of the tool to call on the server. + - `ChatModel model` - - `class BetaToolChoiceCustom:` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - Use this option to force the model to call a specific custom tool. + - `Optional description` - - `String name` + The description of the assistant. The maximum length is 512 characters. - The name of the custom tool to call. + - `Optional instructions` - - `JsonValue; type "custom"constant` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - For custom tool calling, the type is always `custom`. + - `Optional metadata` - - `CUSTOM("custom")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `JsonValue;` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `JsonValue; type "programmatic_tool_calling"constant` + - `Optional name` - The tool to call. Always `programmatic_tool_calling`. + The name of the assistant. The maximum length is 256 characters. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `Optional reasoningEffort` - - `class BetaToolChoiceApplyPatch:` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - Forces the model to call the apply_patch tool when executing a tool call. + - `Optional responseFormat` - - `JsonValue; type "apply_patch"constant` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The tool to call. Always `apply_patch`. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `APPLY_PATCH("apply_patch")` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class BetaToolChoiceShell:` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - Forces the model to call the shell tool when a tool call is required. + - `Optional temperature` - - `JsonValue; type "shell"constant` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - The tool to call. Always `shell`. + - `Optional toolResources` - - `SHELL("shell")` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `List tools` + - `Optional codeInterpreter` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `Optional> fileIds` - We support the following categories of tools: + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `Optional fileSearch` - - `class BetaFunctionTool:` + - `Optional> vectorStoreIds` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `class BetaFileSearchTool:` + - `Optional> vectorStores` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `class BetaComputerTool:` + - `Optional chunkingStrategy` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `class BetaComputerUsePreviewTool:` + - `JsonValue;` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JsonValue; type "auto"constant` - - `class BetaWebSearchTool:` + Always `auto`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `AUTO("auto")` - - `Mcp` + - `class Static:` - - `CodeInterpreter` + - `InnerStatic static_` - - `JsonValue;` + - `long chunkOverlapTokens` - - `ImageGeneration` + The number of tokens that overlap between chunks. The default value is `400`. - - `JsonValue;` + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `class BetaFunctionShellTool:` + - `long maxChunkSizeTokens` - A tool that allows the model to execute shell commands. + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `class BetaCustomTool:` + - `JsonValue; type "static"constant` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + Always `static`. - - `class BetaNamespaceTool:` + - `STATIC("static")` - Groups function/custom tools under a shared namespace. + - `Optional> fileIds` - - `class BetaToolSearchTool:` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. - Hosted or BYOT tool search configuration for deferred tools. + - `Optional metadata` - - `class BetaWebSearchPreviewTool:` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class BetaApplyPatchTool:` + - `Optional> tools` - Allows the assistant to create, delete, or update files using unified diffs. + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `Optional topP` + - `class CodeInterpreterTool:` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `JsonValue; type "code_interpreter"constant` - We generally recommend altering this or `temperature` but not both. + The type of tool being defined: `code_interpreter` - - `Optional background` + - `CODE_INTERPRETER("code_interpreter")` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `class FileSearchTool:` - - `Optional completedAt` + - `JsonValue; type "file_search"constant` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The type of tool being defined: `file_search` - - `Optional conversation` + - `FILE_SEARCH("file_search")` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `Optional fileSearch` - - `String id` + Overrides for the file search tool. - The unique ID of the conversation that this response was associated with. + - `Optional maxNumResults` - - `Optional maxOutputTokens` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Optional maxToolCalls` + - `Optional rankingOptions` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `Optional moderation` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Moderation results for the response input and output, if moderated completions were requested. + - `double scoreThreshold` - - `Input input` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Moderation for the response input. + - `Optional ranker` - - `class ModerationResult:` + The ranker to use for the file search. If not specified will use the `auto` ranker. - A moderation result produced for the response input or output. + - `AUTO("auto")` - - `Categories categories` + - `DEFAULT_2024_08_21("default_2024_08_21")` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `class FunctionTool:` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + - `FunctionDefinition function` - Which modalities of input are reflected by the score for each category. + - `String name` - - `TEXT("text")` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `IMAGE("image")` + - `Optional description` - - `CategoryScores categoryScores` + A description of what the function does, used by the model to choose when and how to call the function. - A dictionary of moderation categories to scores. + - `Optional parameters` - - `boolean flagged` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - A boolean indicating whether the content was flagged by any category. + Omitting `parameters` defines a function with an empty parameter list. - - `String model` + - `Optional strict` - The moderation model that produced this result. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `JsonValue; type "moderation_result"constant` + - `JsonValue; type "function"constant` - The object type, which was always `moderation_result` for successful moderation results. + The type of tool being defined: `function` - - `MODERATION_RESULT("moderation_result")` + - `FUNCTION("function")` - - `class Error:` + - `Optional topP` - An error produced while attempting moderation for the response input or output. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `String code` + We generally recommend altering this or temperature but not both. - The error code. +### Returns - - `String message` +- `class Assistant:` - The error message. + Represents an `assistant` that can call the model and use tools. - - `JsonValue; type "error"constant` + - `String id` - The object type, which was always `error` for moderation failures. + The identifier, which can be referenced in API endpoints. - - `ERROR("error")` + - `long createdAt` - - `Output output` + The Unix timestamp (in seconds) for when the assistant was created. - Moderation for the response output. + - `Optional description` - - `class ModerationResult:` + The description of the assistant. The maximum length is 512 characters. - A moderation result produced for the response input or output. + - `Optional instructions` - - `Categories categories` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `Optional metadata` - - `CategoryAppliedInputTypes categoryAppliedInputTypes` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Which modalities of input are reflected by the score for each category. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `TEXT("text")` + - `String model` - - `IMAGE("image")` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - `CategoryScores categoryScores` + - `Optional name` - A dictionary of moderation categories to scores. + The name of the assistant. The maximum length is 256 characters. - - `boolean flagged` + - `JsonValue; object_ "assistant"constant` - A boolean indicating whether the content was flagged by any category. + The object type, which is always `assistant`. - - `String model` + - `ASSISTANT("assistant")` - The moderation model that produced this result. + - `List tools` - - `JsonValue; type "moderation_result"constant` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - The object type, which was always `moderation_result` for successful moderation results. + - `class CodeInterpreterTool:` - - `MODERATION_RESULT("moderation_result")` + - `JsonValue; type "code_interpreter"constant` - - `class Error:` + The type of tool being defined: `code_interpreter` - An error produced while attempting moderation for the response input or output. + - `CODE_INTERPRETER("code_interpreter")` - - `String code` + - `class FileSearchTool:` - The error code. + - `JsonValue; type "file_search"constant` - - `String message` + The type of tool being defined: `file_search` - The error message. + - `FILE_SEARCH("file_search")` - - `JsonValue; type "error"constant` + - `Optional fileSearch` - The object type, which was always `error` for moderation failures. + Overrides for the file search tool. - - `ERROR("error")` + - `Optional maxNumResults` - - `Optional previousResponseId` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Optional prompt` + - `Optional rankingOptions` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `String id` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The unique identifier of the prompt template to use. + - `double scoreThreshold` - - `Optional variables` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `Optional ranker` - - `String` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaResponseInputText:` + - `AUTO("auto")` - A text input to the model. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `class BetaResponseInputImage:` + - `class FunctionTool:` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `FunctionDefinition function` - - `class BetaResponseInputFile:` + - `String name` - A file input to the model. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `Optional version` + - `Optional description` - Optional version of the prompt template. + A description of what the function does, used by the model to choose when and how to call the function. - - `Optional promptCacheKey` + - `Optional parameters` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `Optional promptCacheOptions` + Omitting `parameters` defines a function with an empty parameter list. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `Optional strict` - - `Mode mode` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - Whether implicit prompt-cache breakpoints were enabled. + - `JsonValue; type "function"constant` - - `IMPLICIT("implicit")` + The type of tool being defined: `function` - - `EXPLICIT("explicit")` + - `FUNCTION("function")` - - `Ttl ttl` + - `Optional responseFormat` - The minimum lifetime applied to each cache breakpoint. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `_30M("30m")` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional promptCacheRetention` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Deprecated. Use `prompt_cache_options.ttl` instead. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `JsonValue;` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `AUTO("auto")` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `class ResponseFormatText:` - - `IN_MEMORY("in_memory")` + Default response format. Used to generate text responses. - - `_24H("24h")` + - `JsonValue; type "text"constant` - - `Optional reasoning` + The type of response format being defined. Always `text`. - **gpt-5 and o-series models only** + - `TEXT("text")` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `class ResponseFormatJsonObject:` - - `Optional context` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `JsonValue; type "json_object"constant` - - `AUTO("auto")` + The type of response format being defined. Always `json_object`. - - `CURRENT_TURN("current_turn")` + - `JSON_OBJECT("json_object")` - - `ALL_TURNS("all_turns")` + - `class ResponseFormatJsonSchema:` - - `Optional effort` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `JsonSchema jsonSchema` - - `NONE("none")` + Structured Outputs configuration options, including a JSON Schema. - - `MINIMAL("minimal")` + - `String name` - - `LOW("low")` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `MEDIUM("medium")` + - `Optional description` - - `HIGH("high")` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `XHIGH("xhigh")` + - `Optional schema` - - `MAX("max")` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `Optional generateSummary` + - `Optional strict` - **Deprecated:** use `summary` instead. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `JsonValue; type "json_schema"constant` - - `AUTO("auto")` + The type of response format being defined. Always `json_schema`. - - `CONCISE("concise")` + - `JSON_SCHEMA("json_schema")` - - `DETAILED("detailed")` + - `Optional temperature` - - `Optional mode` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - Controls the reasoning execution mode for the request. + - `Optional toolResources` - When returned on a response, this is the effective execution mode. + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `STANDARD("standard")` + - `Optional codeInterpreter` - - `PRO("pro")` + - `Optional> fileIds` - - `Optional summary` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `Optional fileSearch` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `Optional> vectorStoreIds` - - `AUTO("auto")` + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `CONCISE("concise")` + - `Optional topP` - - `DETAILED("detailed")` + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `Optional safetyIdentifier` + We generally recommend altering this or temperature but not both. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). +### Example - - `Optional serviceTier` +```java +package com.openai.example; - Specifies the processing type used for serving the request. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.ChatModel; +import com.openai.models.beta.assistants.Assistant; +import com.openai.models.beta.assistants.AssistantCreateParams; - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. +public final class Main { + private Main() {} - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `AUTO("auto")` + AssistantCreateParams params = AssistantCreateParams.builder() + .model(ChatModel.GPT_4O) + .build(); + Assistant assistant = client.beta().assistants().create(params); + } +} +``` - - `DEFAULT("default")` +#### Response - - `FLEX("flex")` +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - - `SCALE("scale")` +## Retrieve assistant - - `PRIORITY("priority")` +`Assistant beta().assistants().retrieve(AssistantRetrieveParamsparams = AssistantRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `Optional status` +**get** `/assistants/{assistant_id}` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. +Retrieves an assistant. - - `COMPLETED("completed")` +### Parameters - - `FAILED("failed")` +- `AssistantRetrieveParams params` - - `IN_PROGRESS("in_progress")` + - `Optional assistantId` - - `CANCELLED("cancelled")` +### Returns - - `QUEUED("queued")` +- `class Assistant:` - - `INCOMPLETE("incomplete")` + Represents an `assistant` that can call the model and use tools. - - `Optional text` + - `String id` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The identifier, which can be referenced in API endpoints. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `long createdAt` - - `Optional format` + The Unix timestamp (in seconds) for when the assistant was created. - An object specifying the format that the model must output. + - `Optional description` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The description of the assistant. The maximum length is 512 characters. - The default format is `{ "type": "text" }` with no additional options. + - `Optional instructions` - **Not recommended for gpt-4o and newer models:** + The system instructions that the assistant uses. The maximum length is 256,000 characters. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `Optional metadata` - - `JsonValue;` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `JsonValue; type "text"constant` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of response format being defined. Always `text`. + - `String model` - - `TEXT("text")` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - `class BetaResponseFormatTextJsonSchemaConfig:` + - `Optional name` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The name of the assistant. The maximum length is 256 characters. - - `String name` + - `JsonValue; object_ "assistant"constant` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The object type, which is always `assistant`. - - `Schema schema` + - `ASSISTANT("assistant")` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `List tools` - - `JsonValue; type "json_schema"constant` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - The type of response format being defined. Always `json_schema`. + - `class CodeInterpreterTool:` - - `JSON_SCHEMA("json_schema")` + - `JsonValue; type "code_interpreter"constant` - - `Optional description` + The type of tool being defined: `code_interpreter` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `CODE_INTERPRETER("code_interpreter")` - - `Optional strict` + - `class FileSearchTool:` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `JsonValue; type "file_search"constant` - - `JsonValue;` + The type of tool being defined: `file_search` - - `JsonValue; type "json_object"constant` + - `FILE_SEARCH("file_search")` - The type of response format being defined. Always `json_object`. + - `Optional fileSearch` - - `JSON_OBJECT("json_object")` + Overrides for the file search tool. - - `Optional verbosity` + - `Optional maxNumResults` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `LOW("low")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `MEDIUM("medium")` + - `Optional rankingOptions` - - `HIGH("high")` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `Optional topLogprobs` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `double scoreThreshold` - - `Optional truncation` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The truncation strategy to use for the model response. + - `Optional ranker` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The ranker to use for the file search. If not specified will use the `auto` ranker. - `AUTO("auto")` - - `DISABLED("disabled")` - - - `Optional usage` + - `DEFAULT_2024_08_21("default_2024_08_21")` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `class FunctionTool:` - - `long inputTokens` + - `FunctionDefinition function` - The number of input tokens. + - `String name` - - `InputTokensDetails inputTokensDetails` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - A detailed breakdown of the input tokens. + - `Optional description` - - `long cacheWriteTokens` + A description of what the function does, used by the model to choose when and how to call the function. - The number of input tokens that were written to the cache. + - `Optional parameters` - - `long cachedTokens` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + Omitting `parameters` defines a function with an empty parameter list. - - `long outputTokens` + - `Optional strict` - The number of output tokens. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `OutputTokensDetails outputTokensDetails` + - `JsonValue; type "function"constant` - A detailed breakdown of the output tokens. + The type of tool being defined: `function` - - `long reasoningTokens` + - `FUNCTION("function")` - The number of reasoning tokens. + - `Optional responseFormat` - - `long totalTokens` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The total number of tokens used. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional user` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `long sequenceNumber` + - `JsonValue;` - The sequence number for this event. + - `AUTO("auto")` - - `JsonValue; type "response.completed"constant` + - `class ResponseFormatText:` - The type of the event. Always `response.completed`. + Default response format. Used to generate text responses. - - `RESPONSE_COMPLETED("response.completed")` + - `JsonValue; type "text"constant` - - `Optional agent` + The type of response format being defined. Always `text`. - The agent that owns this multi-agent streaming event. + - `TEXT("text")` - - `String agentName` + - `class ResponseFormatJsonObject:` - The canonical name of the agent that produced this item. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `class BetaResponseContentPartAddedEvent:` + - `JsonValue; type "json_object"constant` - Emitted when a new content part is added. + The type of response format being defined. Always `json_object`. - - `long contentIndex` + - `JSON_OBJECT("json_object")` - The index of the content part that was added. + - `class ResponseFormatJsonSchema:` - - `String itemId` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The ID of the output item that the content part was added to. + - `JsonSchema jsonSchema` - - `long outputIndex` + Structured Outputs configuration options, including a JSON Schema. - The index of the output item that the content part was added to. + - `String name` - - `Part part` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The content part that was added. + - `Optional description` - - `class BetaResponseOutputText:` + A description of what the response format is for, used by the model to + determine how to respond in the format. - A text output from the model. + - `Optional schema` - - `class BetaResponseOutputRefusal:` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - A refusal from the model. + - `Optional strict` - - `class ReasoningText:` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - Reasoning text from the model. + - `JsonValue; type "json_schema"constant` - - `String text` + The type of response format being defined. Always `json_schema`. - The reasoning text from the model. + - `JSON_SCHEMA("json_schema")` - - `JsonValue; type "reasoning_text"constant` + - `Optional temperature` - The type of the reasoning text. Always `reasoning_text`. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `REASONING_TEXT("reasoning_text")` + - `Optional toolResources` - - `long sequenceNumber` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The sequence number of this event. + - `Optional codeInterpreter` - - `JsonValue; type "response.content_part.added"constant` + - `Optional> fileIds` - The type of the event. Always `response.content_part.added`. + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `RESPONSE_CONTENT_PART_ADDED("response.content_part.added")` + - `Optional fileSearch` - - `Optional agent` + - `Optional> vectorStoreIds` - The agent that owns this multi-agent streaming event. + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `String agentName` + - `Optional topP` - The canonical name of the agent that produced this item. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `class BetaResponseContentPartDoneEvent:` + We generally recommend altering this or temperature but not both. - Emitted when a content part is done. +### Example - - `long contentIndex` +```java +package com.openai.example; - The index of the content part that is done. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.assistants.Assistant; +import com.openai.models.beta.assistants.AssistantRetrieveParams; - - `String itemId` +public final class Main { + private Main() {} - The ID of the output item that the content part was added to. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `long outputIndex` + Assistant assistant = client.beta().assistants().retrieve("assistant_id"); + } +} +``` - The index of the output item that the content part was added to. +#### Response - - `Part part` +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - The content part that is done. +## Modify assistant - - `class BetaResponseOutputText:` +`Assistant beta().assistants().update(AssistantUpdateParamsparams = AssistantUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - A text output from the model. +**post** `/assistants/{assistant_id}` - - `class BetaResponseOutputRefusal:` +Modifies an assistant. - A refusal from the model. +### Parameters - - `class ReasoningText:` +- `AssistantUpdateParams params` - Reasoning text from the model. + - `Optional assistantId` - - `String text` + - `Optional description` - The reasoning text from the model. + The description of the assistant. The maximum length is 512 characters. - - `JsonValue; type "reasoning_text"constant` + - `Optional instructions` - The type of the reasoning text. Always `reasoning_text`. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `REASONING_TEXT("reasoning_text")` + - `Optional metadata` - - `long sequenceNumber` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The sequence number of this event. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `JsonValue; type "response.content_part.done"constant` + - `Optional model` - The type of the event. Always `response.content_part.done`. + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - `RESPONSE_CONTENT_PART_DONE("response.content_part.done")` + - `GPT_5("gpt-5")` - - `Optional agent` + - `GPT_5_MINI("gpt-5-mini")` - The agent that owns this multi-agent streaming event. + - `GPT_5_NANO("gpt-5-nano")` - - `String agentName` + - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - The canonical name of the agent that produced this item. + - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - - `class BetaResponseCreatedEvent:` + - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - An event that is emitted when a response is created. + - `GPT_4_1("gpt-4.1")` - - `BetaResponse response` + - `GPT_4_1_MINI("gpt-4.1-mini")` - The response that was created. + - `GPT_4_1_NANO("gpt-4.1-nano")` - - `long sequenceNumber` + - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - The sequence number for this event. + - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - - `JsonValue; type "response.created"constant` + - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - The type of the event. Always `response.created`. + - `O3_MINI("o3-mini")` - - `RESPONSE_CREATED("response.created")` + - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - - `Optional agent` + - `O1("o1")` - The agent that owns this multi-agent streaming event. + - `O1_2024_12_17("o1-2024-12-17")` - - `String agentName` + - `GPT_4O("gpt-4o")` - The canonical name of the agent that produced this item. + - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - - `class BetaResponseErrorEvent:` + - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - Emitted when an error occurs. + - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - - `Optional code` + - `GPT_4O_MINI("gpt-4o-mini")` - The error code. + - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - - `String message` + - `GPT_4_5_PREVIEW("gpt-4.5-preview")` - The error message. + - `GPT_4_5_PREVIEW_2025_02_27("gpt-4.5-preview-2025-02-27")` - - `Optional param` + - `GPT_4_TURBO("gpt-4-turbo")` - The error parameter. + - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - - `long sequenceNumber` + - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - The sequence number of this event. + - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - - `JsonValue; type "error"constant` + - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - The type of the event. Always `error`. + - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - - `ERROR("error")` + - `GPT_4("gpt-4")` - - `Optional agent` + - `GPT_4_0314("gpt-4-0314")` - The agent that owns this multi-agent streaming event. + - `GPT_4_0613("gpt-4-0613")` - - `String agentName` + - `GPT_4_32K("gpt-4-32k")` - The canonical name of the agent that produced this item. + - `GPT_4_32K_0314("gpt-4-32k-0314")` - - `class BetaResponseFileSearchCallCompletedEvent:` + - `GPT_4_32K_0613("gpt-4-32k-0613")` - Emitted when a file search call is completed (results found). + - `GPT_3_5_TURBO("gpt-3.5-turbo")` - - `String itemId` + - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - The ID of the output item that the file search call is initiated. + - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - - `long outputIndex` + - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - The index of the output item that the file search call is initiated. + - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - - `long sequenceNumber` + - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - The sequence number of this event. + - `Optional name` - - `JsonValue; type "response.file_search_call.completed"constant` + The name of the assistant. The maximum length is 256 characters. - The type of the event. Always `response.file_search_call.completed`. + - `Optional reasoningEffort` - - `RESPONSE_FILE_SEARCH_CALL_COMPLETED("response.file_search_call.completed")` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `Optional agent` + - `Optional responseFormat` - The agent that owns this multi-agent streaming event. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `String agentName` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The canonical name of the agent that produced this item. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class BetaResponseFileSearchCallInProgressEvent:` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - Emitted when a file search call is initiated. + - `Optional temperature` - - `String itemId` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - The ID of the output item that the file search call is initiated. + - `Optional toolResources` - - `long outputIndex` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The index of the output item that the file search call is initiated. + - `Optional codeInterpreter` - - `long sequenceNumber` + - `Optional> fileIds` - The sequence number of this event. + Overrides the list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `JsonValue; type "response.file_search_call.in_progress"constant` + - `Optional fileSearch` - The type of the event. Always `response.file_search_call.in_progress`. + - `Optional> vectorStoreIds` - - `RESPONSE_FILE_SEARCH_CALL_IN_PROGRESS("response.file_search_call.in_progress")` + Overrides the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `Optional agent` + - `Optional> tools` - The agent that owns this multi-agent streaming event. + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `String agentName` + - `class CodeInterpreterTool:` - The canonical name of the agent that produced this item. + - `JsonValue; type "code_interpreter"constant` - - `class BetaResponseFileSearchCallSearchingEvent:` + The type of tool being defined: `code_interpreter` - Emitted when a file search is currently searching. + - `CODE_INTERPRETER("code_interpreter")` - - `String itemId` + - `class FileSearchTool:` - The ID of the output item that the file search call is initiated. + - `JsonValue; type "file_search"constant` - - `long outputIndex` + The type of tool being defined: `file_search` - The index of the output item that the file search call is searching. + - `FILE_SEARCH("file_search")` - - `long sequenceNumber` + - `Optional fileSearch` - The sequence number of this event. + Overrides for the file search tool. - - `JsonValue; type "response.file_search_call.searching"constant` + - `Optional maxNumResults` - The type of the event. Always `response.file_search_call.searching`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `RESPONSE_FILE_SEARCH_CALL_SEARCHING("response.file_search_call.searching")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Optional agent` + - `Optional rankingOptions` - The agent that owns this multi-agent streaming event. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `String agentName` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The canonical name of the agent that produced this item. + - `double scoreThreshold` - - `class BetaResponseFunctionCallArgumentsDeltaEvent:` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Emitted when there is a partial function-call arguments delta. + - `Optional ranker` - - `String delta` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The function-call arguments delta that is added. + - `AUTO("auto")` - - `String itemId` + - `DEFAULT_2024_08_21("default_2024_08_21")` - The ID of the output item that the function-call arguments delta is added to. + - `class FunctionTool:` - - `long outputIndex` + - `FunctionDefinition function` - The index of the output item that the function-call arguments delta is added to. + - `String name` - - `long sequenceNumber` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The sequence number of this event. + - `Optional description` - - `JsonValue; type "response.function_call_arguments.delta"constant` + A description of what the function does, used by the model to choose when and how to call the function. - The type of the event. Always `response.function_call_arguments.delta`. + - `Optional parameters` - - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DELTA("response.function_call_arguments.delta")` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `Optional agent` + Omitting `parameters` defines a function with an empty parameter list. - The agent that owns this multi-agent streaming event. + - `Optional strict` - - `String agentName` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The canonical name of the agent that produced this item. + - `JsonValue; type "function"constant` - - `class BetaResponseFunctionCallArgumentsDoneEvent:` + The type of tool being defined: `function` - Emitted when function-call arguments are finalized. + - `FUNCTION("function")` - - `String arguments` + - `Optional topP` - The function-call arguments. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `String itemId` + We generally recommend altering this or temperature but not both. - The ID of the item. +### Returns - - `String name` +- `class Assistant:` - The name of the function that was called. + Represents an `assistant` that can call the model and use tools. - - `long outputIndex` + - `String id` - The index of the output item. + The identifier, which can be referenced in API endpoints. - - `long sequenceNumber` + - `long createdAt` - The sequence number of this event. + The Unix timestamp (in seconds) for when the assistant was created. - - `JsonValue; type "response.function_call_arguments.done"constant` + - `Optional description` - - `RESPONSE_FUNCTION_CALL_ARGUMENTS_DONE("response.function_call_arguments.done")` + The description of the assistant. The maximum length is 512 characters. - - `Optional agent` + - `Optional instructions` - The agent that owns this multi-agent streaming event. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `String agentName` + - `Optional metadata` - The canonical name of the agent that produced this item. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `class BetaResponseInProgressEvent:` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Emitted when the response is in progress. + - `String model` - - `BetaResponse response` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - The response that is in progress. + - `Optional name` - - `long sequenceNumber` + The name of the assistant. The maximum length is 256 characters. - The sequence number of this event. + - `JsonValue; object_ "assistant"constant` - - `JsonValue; type "response.in_progress"constant` + The object type, which is always `assistant`. - The type of the event. Always `response.in_progress`. + - `ASSISTANT("assistant")` - - `RESPONSE_IN_PROGRESS("response.in_progress")` + - `List tools` - - `Optional agent` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - The agent that owns this multi-agent streaming event. + - `class CodeInterpreterTool:` - - `String agentName` + - `JsonValue; type "code_interpreter"constant` - The canonical name of the agent that produced this item. + The type of tool being defined: `code_interpreter` - - `class BetaResponseFailedEvent:` + - `CODE_INTERPRETER("code_interpreter")` - An event that is emitted when a response fails. + - `class FileSearchTool:` - - `BetaResponse response` + - `JsonValue; type "file_search"constant` - The response that failed. + The type of tool being defined: `file_search` - - `long sequenceNumber` + - `FILE_SEARCH("file_search")` - The sequence number of this event. + - `Optional fileSearch` - - `JsonValue; type "response.failed"constant` + Overrides for the file search tool. - The type of the event. Always `response.failed`. + - `Optional maxNumResults` - - `RESPONSE_FAILED("response.failed")` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `Optional agent` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The agent that owns this multi-agent streaming event. + - `Optional rankingOptions` - - `String agentName` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The canonical name of the agent that produced this item. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaResponseIncompleteEvent:` + - `double scoreThreshold` - An event that is emitted when a response finishes as incomplete. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `BetaResponse response` + - `Optional ranker` - The response that was incomplete. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `long sequenceNumber` + - `AUTO("auto")` - The sequence number of this event. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `JsonValue; type "response.incomplete"constant` + - `class FunctionTool:` - The type of the event. Always `response.incomplete`. + - `FunctionDefinition function` - - `RESPONSE_INCOMPLETE("response.incomplete")` + - `String name` - - `Optional agent` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The agent that owns this multi-agent streaming event. + - `Optional description` - - `String agentName` + A description of what the function does, used by the model to choose when and how to call the function. - The canonical name of the agent that produced this item. + - `Optional parameters` - - `class BetaResponseOutputItemAddedEvent:` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - Emitted when a new output item is added. + Omitting `parameters` defines a function with an empty parameter list. - - `BetaResponseOutputItem item` + - `Optional strict` - The output item that was added. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `class BetaResponseOutputMessage:` + - `JsonValue; type "function"constant` - An output message from the model. + The type of tool being defined: `function` - - `class BetaResponseFileSearchToolCall:` + - `FUNCTION("function")` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `Optional responseFormat` - - `class BetaResponseFunctionToolCall:` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `class BetaResponseFunctionToolCallOutputItem:` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `AgentMessage` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `MultiAgentCall` + - `JsonValue;` - - `MultiAgentCallOutput` + - `AUTO("auto")` - - `class BetaResponseFunctionWebSearch:` + - `class ResponseFormatText:` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Default response format. Used to generate text responses. - - `class BetaResponseComputerToolCall:` + - `JsonValue; type "text"constant` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + The type of response format being defined. Always `text`. - - `class BetaResponseComputerToolCallOutputItem:` + - `TEXT("text")` - - `class BetaResponseReasoningItem:` + - `class ResponseFormatJsonObject:` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `Program` + - `JsonValue; type "json_object"constant` - - `ProgramOutput` + The type of response format being defined. Always `json_object`. - - `class BetaResponseToolSearchCall:` + - `JSON_OBJECT("json_object")` - - `class BetaResponseToolSearchOutputItem:` + - `class ResponseFormatJsonSchema:` - - `AdditionalTools` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `class BetaResponseCompactionItem:` + - `JsonSchema jsonSchema` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Structured Outputs configuration options, including a JSON Schema. - - `ImageGenerationCall` + - `String name` - - `class BetaResponseCodeInterpreterToolCall:` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - A tool call to run code. + - `Optional description` - - `LocalShellCall` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `LocalShellCallOutput` + - `Optional schema` - - `class BetaResponseFunctionShellToolCall:` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - A tool call that executes one or more shell commands in a managed environment. + - `Optional strict` - - `class BetaResponseFunctionShellToolCallOutput:` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The output of a shell tool call that was emitted. + - `JsonValue; type "json_schema"constant` - - `class BetaResponseApplyPatchToolCall:` + The type of response format being defined. Always `json_schema`. - A tool call that applies file diffs by creating, deleting, or updating files. + - `JSON_SCHEMA("json_schema")` - - `class BetaResponseApplyPatchToolCallOutput:` + - `Optional temperature` - The output emitted by an apply patch tool call. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `McpCall` + - `Optional toolResources` - - `McpListTools` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `McpApprovalRequest` + - `Optional codeInterpreter` - - `McpApprovalResponse` + - `Optional> fileIds` - - `class BetaResponseCustomToolCall:` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - A call to a custom tool created by the model. + - `Optional fileSearch` - - `class BetaResponseCustomToolCallOutputItem:` + - `Optional> vectorStoreIds` - The output of a custom tool call from your code, being sent back to the model. + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `long outputIndex` + - `Optional topP` - The index of the output item that was added. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `long sequenceNumber` + We generally recommend altering this or temperature but not both. - The sequence number of this event. +### Example - - `JsonValue; type "response.output_item.added"constant` +```java +package com.openai.example; - The type of the event. Always `response.output_item.added`. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.assistants.Assistant; +import com.openai.models.beta.assistants.AssistantUpdateParams; - - `RESPONSE_OUTPUT_ITEM_ADDED("response.output_item.added")` +public final class Main { + private Main() {} - - `Optional agent` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The agent that owns this multi-agent streaming event. + Assistant assistant = client.beta().assistants().update("assistant_id"); + } +} +``` - - `String agentName` +#### Response - The canonical name of the agent that produced this item. +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - - `class BetaResponseOutputItemDoneEvent:` +## Delete assistant - Emitted when an output item is marked done. +`AssistantDeleted beta().assistants().delete(AssistantDeleteParamsparams = AssistantDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `BetaResponseOutputItem item` +**delete** `/assistants/{assistant_id}` - The output item that was marked done. +Delete an assistant. - - `long outputIndex` +### Parameters - The index of the output item that was marked done. +- `AssistantDeleteParams params` - - `long sequenceNumber` + - `Optional assistantId` - The sequence number of this event. +### Returns - - `JsonValue; type "response.output_item.done"constant` +- `class AssistantDeleted:` - The type of the event. Always `response.output_item.done`. + - `String id` - - `RESPONSE_OUTPUT_ITEM_DONE("response.output_item.done")` + - `boolean deleted` - - `Optional agent` + - `JsonValue; object_ "assistant.deleted"constant` - The agent that owns this multi-agent streaming event. + - `ASSISTANT_DELETED("assistant.deleted")` - - `String agentName` +### Example - The canonical name of the agent that produced this item. +```java +package com.openai.example; - - `class BetaResponseReasoningSummaryPartAddedEvent:` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.assistants.AssistantDeleteParams; +import com.openai.models.beta.assistants.AssistantDeleted; - Emitted when a new reasoning summary part is added. +public final class Main { + private Main() {} - - `String itemId` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The ID of the item this summary part is associated with. + AssistantDeleted assistantDeleted = client.beta().assistants().delete("assistant_id"); + } +} +``` - - `long outputIndex` +#### Response - The index of the output item this summary part is associated with. +```json +{ + "id": "id", + "deleted": true, + "object": "assistant.deleted" +} +``` - - `Part part` +## Domain Types - The summary part that was added. +### Assistant - - `String text` +- `class Assistant:` - The text of the summary part. + Represents an `assistant` that can call the model and use tools. - - `JsonValue; type "summary_text"constant` + - `String id` - The type of the summary part. Always `summary_text`. + The identifier, which can be referenced in API endpoints. - - `SUMMARY_TEXT("summary_text")` + - `long createdAt` - - `long sequenceNumber` + The Unix timestamp (in seconds) for when the assistant was created. - The sequence number of this event. + - `Optional description` - - `long summaryIndex` + The description of the assistant. The maximum length is 512 characters. - The index of the summary part within the reasoning summary. + - `Optional instructions` - - `JsonValue; type "response.reasoning_summary_part.added"constant` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The type of the event. Always `response.reasoning_summary_part.added`. + - `Optional metadata` - - `RESPONSE_REASONING_SUMMARY_PART_ADDED("response.reasoning_summary_part.added")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Optional agent` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The agent that owns this multi-agent streaming event. + - `String model` - - `String agentName` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - The canonical name of the agent that produced this item. + - `Optional name` - - `class BetaResponseReasoningSummaryPartDoneEvent:` + The name of the assistant. The maximum length is 256 characters. - Emitted when a reasoning summary part is completed. + - `JsonValue; object_ "assistant"constant` - - `String itemId` + The object type, which is always `assistant`. - The ID of the item this summary part is associated with. + - `ASSISTANT("assistant")` - - `long outputIndex` + - `List tools` - The index of the output item this summary part is associated with. + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `Part part` + - `class CodeInterpreterTool:` - The completed summary part. + - `JsonValue; type "code_interpreter"constant` - - `String text` + The type of tool being defined: `code_interpreter` - The text of the summary part. + - `CODE_INTERPRETER("code_interpreter")` - - `JsonValue; type "summary_text"constant` + - `class FileSearchTool:` - The type of the summary part. Always `summary_text`. + - `JsonValue; type "file_search"constant` - - `SUMMARY_TEXT("summary_text")` + The type of tool being defined: `file_search` - - `long sequenceNumber` + - `FILE_SEARCH("file_search")` - The sequence number of this event. + - `Optional fileSearch` - - `long summaryIndex` + Overrides for the file search tool. - The index of the summary part within the reasoning summary. + - `Optional maxNumResults` - - `JsonValue; type "response.reasoning_summary_part.done"constant` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The type of the event. Always `response.reasoning_summary_part.done`. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `RESPONSE_REASONING_SUMMARY_PART_DONE("response.reasoning_summary_part.done")` + - `Optional rankingOptions` - - `Optional agent` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The agent that owns this multi-agent streaming event. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `String agentName` + - `double scoreThreshold` - The canonical name of the agent that produced this item. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `Optional status` + - `Optional ranker` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `INCOMPLETE("incomplete")` + - `AUTO("auto")` - - `class BetaResponseReasoningSummaryTextDeltaEvent:` + - `DEFAULT_2024_08_21("default_2024_08_21")` - Emitted when a delta is added to a reasoning summary text. + - `class FunctionTool:` - - `String delta` + - `FunctionDefinition function` - The text delta that was added to the summary. + - `String name` - - `String itemId` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The ID of the item this summary text delta is associated with. + - `Optional description` - - `long outputIndex` + A description of what the function does, used by the model to choose when and how to call the function. - The index of the output item this summary text delta is associated with. + - `Optional parameters` - - `long sequenceNumber` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The sequence number of this event. + Omitting `parameters` defines a function with an empty parameter list. - - `long summaryIndex` + - `Optional strict` - The index of the summary part within the reasoning summary. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `JsonValue; type "response.reasoning_summary_text.delta"constant` + - `JsonValue; type "function"constant` - The type of the event. Always `response.reasoning_summary_text.delta`. + The type of tool being defined: `function` - - `RESPONSE_REASONING_SUMMARY_TEXT_DELTA("response.reasoning_summary_text.delta")` + - `FUNCTION("function")` - - `Optional agent` + - `Optional responseFormat` - The agent that owns this multi-agent streaming event. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `String agentName` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The canonical name of the agent that produced this item. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `class BetaResponseReasoningSummaryTextDoneEvent:` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - Emitted when a reasoning summary text is completed. + - `JsonValue;` - - `String itemId` + - `AUTO("auto")` - The ID of the item this summary text is associated with. + - `class ResponseFormatText:` - - `long outputIndex` + Default response format. Used to generate text responses. - The index of the output item this summary text is associated with. + - `JsonValue; type "text"constant` - - `long sequenceNumber` + The type of response format being defined. Always `text`. - The sequence number of this event. + - `TEXT("text")` - - `long summaryIndex` + - `class ResponseFormatJsonObject:` - The index of the summary part within the reasoning summary. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `String text` + - `JsonValue; type "json_object"constant` - The full text of the completed reasoning summary. + The type of response format being defined. Always `json_object`. - - `JsonValue; type "response.reasoning_summary_text.done"constant` + - `JSON_OBJECT("json_object")` - The type of the event. Always `response.reasoning_summary_text.done`. + - `class ResponseFormatJsonSchema:` - - `RESPONSE_REASONING_SUMMARY_TEXT_DONE("response.reasoning_summary_text.done")` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional agent` + - `JsonSchema jsonSchema` - The agent that owns this multi-agent streaming event. + Structured Outputs configuration options, including a JSON Schema. - - `String agentName` + - `String name` - The canonical name of the agent that produced this item. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `class BetaResponseReasoningTextDeltaEvent:` + - `Optional description` - Emitted when a delta is added to a reasoning text. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `long contentIndex` + - `Optional schema` - The index of the reasoning content part this delta is associated with. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `String delta` + - `Optional strict` - The text delta that was added to the reasoning content. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `String itemId` + - `JsonValue; type "json_schema"constant` - The ID of the item this reasoning text delta is associated with. + The type of response format being defined. Always `json_schema`. - - `long outputIndex` + - `JSON_SCHEMA("json_schema")` - The index of the output item this reasoning text delta is associated with. + - `Optional temperature` - - `long sequenceNumber` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - The sequence number of this event. + - `Optional toolResources` - - `JsonValue; type "response.reasoning_text.delta"constant` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The type of the event. Always `response.reasoning_text.delta`. + - `Optional codeInterpreter` - - `RESPONSE_REASONING_TEXT_DELTA("response.reasoning_text.delta")` + - `Optional> fileIds` - - `Optional agent` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - The agent that owns this multi-agent streaming event. + - `Optional fileSearch` - - `String agentName` + - `Optional> vectorStoreIds` - The canonical name of the agent that produced this item. + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `class BetaResponseReasoningTextDoneEvent:` + - `Optional topP` - Emitted when a reasoning text is completed. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `long contentIndex` + We generally recommend altering this or temperature but not both. - The index of the reasoning content part. +### Assistant Deleted - - `String itemId` +- `class AssistantDeleted:` - The ID of the item this reasoning text is associated with. + - `String id` - - `long outputIndex` + - `boolean deleted` - The index of the output item this reasoning text is associated with. + - `JsonValue; object_ "assistant.deleted"constant` - - `long sequenceNumber` + - `ASSISTANT_DELETED("assistant.deleted")` - The sequence number of this event. +### Assistant Stream Event - - `String text` +- `class AssistantStreamEvent: A class that can be one of several variants.union` - The full text of the completed reasoning content. + Represents an event emitted when streaming a Run. - - `JsonValue; type "response.reasoning_text.done"constant` + Each event in a server-sent events stream has an `event` and `data` property: - The type of the event. Always `response.reasoning_text.done`. + ``` + event: thread.created + data: {"id": "thread_123", "object": "thread", ...} + ``` - - `RESPONSE_REASONING_TEXT_DONE("response.reasoning_text.done")` + We emit events whenever a new object is created, transitions to a new state, or is being + streamed in parts (deltas). For example, we emit `thread.run.created` when a new run + is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses + to create a message during a run, we emit a `thread.message.created event`, a + `thread.message.in_progress` event, many `thread.message.delta` events, and finally a + `thread.message.completed` event. - - `Optional agent` + We may add additional events over time, so we recommend handling unknown events gracefully + in your code. See the [Assistants API quickstart](https://platform.openai.com/docs/assistants/overview) to learn how to + integrate the Assistants API with streaming. - The agent that owns this multi-agent streaming event. + - `ThreadCreated` - - `String agentName` + - `Thread data` - The canonical name of the agent that produced this item. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `class BetaResponseRefusalDeltaEvent:` + - `String id` - Emitted when there is a partial refusal text. + The identifier, which can be referenced in API endpoints. - - `long contentIndex` + - `long createdAt` - The index of the content part that the refusal text is added to. + The Unix timestamp (in seconds) for when the thread was created. - - `String delta` + - `Optional metadata` - The refusal text that is added. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `String itemId` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The ID of the output item that the refusal text is added to. + - `JsonValue; object_ "thread"constant` - - `long outputIndex` + The object type, which is always `thread`. - The index of the output item that the refusal text is added to. + - `THREAD("thread")` - - `long sequenceNumber` + - `Optional toolResources` - The sequence number of this event. + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `JsonValue; type "response.refusal.delta"constant` + - `Optional codeInterpreter` - The type of the event. Always `response.refusal.delta`. + - `Optional> fileIds` - - `RESPONSE_REFUSAL_DELTA("response.refusal.delta")` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `Optional agent` + - `Optional fileSearch` - The agent that owns this multi-agent streaming event. + - `Optional> vectorStoreIds` - - `String agentName` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - The canonical name of the agent that produced this item. + - `JsonValue; event "thread.created"constant` - - `class BetaResponseRefusalDoneEvent:` + - `THREAD_CREATED("thread.created")` - Emitted when refusal text is finalized. + - `Optional enabled` - - `long contentIndex` + Whether to enable input audio transcription. - The index of the content part that the refusal text is finalized. + - `ThreadRunCreated` - - `String itemId` + - `Run data` - The ID of the output item that the refusal text is finalized. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `long outputIndex` + - `String id` - The index of the output item that the refusal text is finalized. + The identifier, which can be referenced in API endpoints. - - `String refusal` + - `String assistantId` - The refusal text that is finalized. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `long sequenceNumber` + - `Optional cancelledAt` - The sequence number of this event. + The Unix timestamp (in seconds) for when the run was cancelled. - - `JsonValue; type "response.refusal.done"constant` + - `Optional completedAt` - The type of the event. Always `response.refusal.done`. + The Unix timestamp (in seconds) for when the run was completed. - - `RESPONSE_REFUSAL_DONE("response.refusal.done")` + - `long createdAt` - - `Optional agent` + The Unix timestamp (in seconds) for when the run was created. - The agent that owns this multi-agent streaming event. + - `Optional expiresAt` - - `String agentName` + The Unix timestamp (in seconds) for when the run will expire. - The canonical name of the agent that produced this item. + - `Optional failedAt` - - `class BetaResponseTextDeltaEvent:` + The Unix timestamp (in seconds) for when the run failed. - Emitted when there is an additional text delta. + - `Optional incompleteDetails` - - `long contentIndex` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The index of the content part that the text delta was added to. + - `Optional reason` - - `String delta` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The text delta that was added. + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `String itemId` + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - The ID of the output item that the text delta was added to. + - `String instructions` - - `List logprobs` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The log probabilities of the tokens in the delta. + - `Optional lastError` - - `String token` + The last error associated with this run. Will be `null` if there are no errors. - A possible text token. + - `Code code` - - `double logprob` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The log probability of this token. + - `SERVER_ERROR("server_error")` - - `Optional> topLogprobs` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The log probabilities of up to 20 of the most likely tokens. + - `INVALID_PROMPT("invalid_prompt")` - - `Optional token` + - `String message` - A possible text token. + A human-readable description of the error. - - `Optional logprob` + - `Optional maxCompletionTokens` - The log probability of this token. + The maximum number of completion tokens specified to have been used over the course of the run. - - `long outputIndex` + - `Optional maxPromptTokens` - The index of the output item that the text delta was added to. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `long sequenceNumber` + - `Optional metadata` - The sequence number for this event. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `JsonValue; type "response.output_text.delta"constant` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the event. Always `response.output_text.delta`. + - `String model` - - `RESPONSE_OUTPUT_TEXT_DELTA("response.output_text.delta")` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `Optional agent` + - `JsonValue; object_ "thread.run"constant` - The agent that owns this multi-agent streaming event. + The object type, which is always `thread.run`. - - `String agentName` + - `THREAD_RUN("thread.run")` - The canonical name of the agent that produced this item. + - `boolean parallelToolCalls` - - `class BetaResponseTextDoneEvent:` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - Emitted when text content is finalized. + - `Optional requiredAction` - - `long contentIndex` + Details on the action required to continue the run. Will be `null` if no action is required. - The index of the content part that the text content is finalized. + - `SubmitToolOutputs submitToolOutputs` - - `String itemId` + Details on the tool outputs needed for this run to continue. - The ID of the output item that the text content is finalized. + - `List toolCalls` - - `List logprobs` + A list of the relevant tool calls. - The log probabilities of the tokens in the delta. + - `String id` - - `String token` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - A possible text token. + - `Function function` - - `double logprob` + The function definition. - The log probability of this token. + - `String arguments` - - `Optional> topLogprobs` + The arguments that the model expects you to pass to the function. - The log probabilities of up to 20 of the most likely tokens. + - `String name` - - `Optional token` + The name of the function. - A possible text token. + - `JsonValue; type "function"constant` - - `Optional logprob` + The type of tool call the output is required for. For now, this is always `function`. - The log probability of this token. + - `FUNCTION("function")` - - `long outputIndex` + - `JsonValue; type "submit_tool_outputs"constant` - The index of the output item that the text content is finalized. + For now, this is always `submit_tool_outputs`. - - `long sequenceNumber` + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - The sequence number for this event. + - `Optional responseFormat` - - `String text` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The text content that is finalized. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `JsonValue; type "response.output_text.done"constant` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The type of the event. Always `response.output_text.done`. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `RESPONSE_OUTPUT_TEXT_DONE("response.output_text.done")` + - `JsonValue;` - - `Optional agent` + - `AUTO("auto")` - The agent that owns this multi-agent streaming event. + - `class ResponseFormatText:` - - `String agentName` + Default response format. Used to generate text responses. - The canonical name of the agent that produced this item. + - `JsonValue; type "text"constant` - - `class BetaResponseWebSearchCallCompletedEvent:` + The type of response format being defined. Always `text`. - Emitted when a web search call is completed. + - `TEXT("text")` - - `String itemId` + - `class ResponseFormatJsonObject:` - Unique ID for the output item associated with the web search call. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `long outputIndex` + - `JsonValue; type "json_object"constant` - The index of the output item that the web search call is associated with. + The type of response format being defined. Always `json_object`. - - `long sequenceNumber` + - `JSON_OBJECT("json_object")` - The sequence number of the web search call being processed. + - `class ResponseFormatJsonSchema:` - - `JsonValue; type "response.web_search_call.completed"constant` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The type of the event. Always `response.web_search_call.completed`. + - `JsonSchema jsonSchema` - - `RESPONSE_WEB_SEARCH_CALL_COMPLETED("response.web_search_call.completed")` + Structured Outputs configuration options, including a JSON Schema. - - `Optional agent` + - `String name` - The agent that owns this multi-agent streaming event. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `String agentName` + - `Optional description` - The canonical name of the agent that produced this item. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `class BetaResponseWebSearchCallInProgressEvent:` + - `Optional schema` - Emitted when a web search call is initiated. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `String itemId` + - `Optional strict` - Unique ID for the output item associated with the web search call. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `long outputIndex` + - `JsonValue; type "json_schema"constant` - The index of the output item that the web search call is associated with. + The type of response format being defined. Always `json_schema`. - - `long sequenceNumber` + - `JSON_SCHEMA("json_schema")` - The sequence number of the web search call being processed. + - `Optional startedAt` - - `JsonValue; type "response.web_search_call.in_progress"constant` + The Unix timestamp (in seconds) for when the run was started. - The type of the event. Always `response.web_search_call.in_progress`. + - `RunStatus status` - - `RESPONSE_WEB_SEARCH_CALL_IN_PROGRESS("response.web_search_call.in_progress")` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `Optional agent` + - `QUEUED("queued")` - The agent that owns this multi-agent streaming event. + - `IN_PROGRESS("in_progress")` - - `String agentName` + - `REQUIRES_ACTION("requires_action")` - The canonical name of the agent that produced this item. + - `CANCELLING("cancelling")` - - `class BetaResponseWebSearchCallSearchingEvent:` + - `CANCELLED("cancelled")` - Emitted when a web search call is executing. + - `FAILED("failed")` - - `String itemId` + - `COMPLETED("completed")` - Unique ID for the output item associated with the web search call. + - `INCOMPLETE("incomplete")` - - `long outputIndex` + - `EXPIRED("expired")` - The index of the output item that the web search call is associated with. + - `String threadId` - - `long sequenceNumber` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The sequence number of the web search call being processed. + - `Optional toolChoice` - - `JsonValue; type "response.web_search_call.searching"constant` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of the event. Always `response.web_search_call.searching`. + - `Auto` - - `RESPONSE_WEB_SEARCH_CALL_SEARCHING("response.web_search_call.searching")` + - `NONE("none")` - - `Optional agent` + - `AUTO("auto")` - The agent that owns this multi-agent streaming event. + - `REQUIRED("required")` - - `String agentName` + - `class AssistantToolChoice:` - The canonical name of the agent that produced this item. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `class BetaResponseImageGenCallCompletedEvent:` + - `Type type` - Emitted when an image generation tool call has completed and the final image is available. + The type of the tool. If type is `function`, the function name must be set - - `String itemId` + - `FUNCTION("function")` - The unique identifier of the image generation item being processed. + - `CODE_INTERPRETER("code_interpreter")` - - `long outputIndex` + - `FILE_SEARCH("file_search")` - The index of the output item in the response's output array. + - `Optional function` - - `long sequenceNumber` + - `String name` - The sequence number of this event. + The name of the function to call. - - `JsonValue; type "response.image_generation_call.completed"constant` + - `List tools` - The type of the event. Always 'response.image_generation_call.completed'. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `RESPONSE_IMAGE_GENERATION_CALL_COMPLETED("response.image_generation_call.completed")` + - `class CodeInterpreterTool:` - - `Optional agent` + - `JsonValue; type "code_interpreter"constant` - The agent that owns this multi-agent streaming event. + The type of tool being defined: `code_interpreter` - - `String agentName` + - `CODE_INTERPRETER("code_interpreter")` - The canonical name of the agent that produced this item. + - `class FileSearchTool:` - - `class BetaResponseImageGenCallGeneratingEvent:` + - `JsonValue; type "file_search"constant` - Emitted when an image generation tool call is actively generating an image (intermediate state). + The type of tool being defined: `file_search` - - `String itemId` + - `FILE_SEARCH("file_search")` - The unique identifier of the image generation item being processed. + - `Optional fileSearch` - - `long outputIndex` + Overrides for the file search tool. - The index of the output item in the response's output array. + - `Optional maxNumResults` - - `long sequenceNumber` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The sequence number of the image generation item being processed. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `JsonValue; type "response.image_generation_call.generating"constant` + - `Optional rankingOptions` - The type of the event. Always 'response.image_generation_call.generating'. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `RESPONSE_IMAGE_GENERATION_CALL_GENERATING("response.image_generation_call.generating")` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Optional agent` + - `double scoreThreshold` - The agent that owns this multi-agent streaming event. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `String agentName` + - `Optional ranker` - The canonical name of the agent that produced this item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `class BetaResponseImageGenCallInProgressEvent:` + - `AUTO("auto")` - Emitted when an image generation tool call is in progress. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `String itemId` + - `class FunctionTool:` - The unique identifier of the image generation item being processed. + - `FunctionDefinition function` - - `long outputIndex` + - `String name` - The index of the output item in the response's output array. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `long sequenceNumber` + - `Optional description` - The sequence number of the image generation item being processed. + A description of what the function does, used by the model to choose when and how to call the function. - - `JsonValue; type "response.image_generation_call.in_progress"constant` + - `Optional parameters` - The type of the event. Always 'response.image_generation_call.in_progress'. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `RESPONSE_IMAGE_GENERATION_CALL_IN_PROGRESS("response.image_generation_call.in_progress")` + Omitting `parameters` defines a function with an empty parameter list. - - `Optional agent` + - `Optional strict` - The agent that owns this multi-agent streaming event. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `String agentName` + - `JsonValue; type "function"constant` - The canonical name of the agent that produced this item. + The type of tool being defined: `function` - - `class BetaResponseImageGenCallPartialImageEvent:` + - `FUNCTION("function")` - Emitted when a partial image is available during image generation streaming. + - `Optional truncationStrategy` - - `String itemId` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The unique identifier of the image generation item being processed. + - `Type type` - - `long outputIndex` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The index of the output item in the response's output array. + - `AUTO("auto")` - - `String partialImageB64` + - `LAST_MESSAGES("last_messages")` - Base64-encoded partial image data, suitable for rendering as an image. + - `Optional lastMessages` - - `long partialImageIndex` + The number of most recent messages from the thread when constructing the context for the run. - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `Optional usage` - - `long sequenceNumber` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The sequence number of the image generation item being processed. + - `long completionTokens` - - `JsonValue; type "response.image_generation_call.partial_image"constant` + Number of completion tokens used over the course of the run. - The type of the event. Always 'response.image_generation_call.partial_image'. + - `long promptTokens` - - `RESPONSE_IMAGE_GENERATION_CALL_PARTIAL_IMAGE("response.image_generation_call.partial_image")` + Number of prompt tokens used over the course of the run. - - `Optional agent` + - `long totalTokens` - The agent that owns this multi-agent streaming event. + Total number of tokens used (prompt + completion). - - `String agentName` + - `Optional temperature` - The canonical name of the agent that produced this item. + The sampling temperature used for this run. If not set, defaults to 1. - - `class BetaResponseMcpCallArgumentsDeltaEvent:` + - `Optional topP` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `String delta` + - `JsonValue; event "thread.run.created"constant` - A JSON string containing the partial update to the arguments for the MCP tool call. + - `THREAD_RUN_CREATED("thread.run.created")` - - `String itemId` + - `ThreadRunQueued` - The unique identifier of the MCP tool call item being processed. + - `Run data` - - `long outputIndex` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The index of the output item in the response's output array. + - `JsonValue; event "thread.run.queued"constant` - - `long sequenceNumber` + - `THREAD_RUN_QUEUED("thread.run.queued")` - The sequence number of this event. + - `ThreadRunInProgress` - - `JsonValue; type "response.mcp_call_arguments.delta"constant` + - `Run data` - The type of the event. Always 'response.mcp_call_arguments.delta'. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `RESPONSE_MCP_CALL_ARGUMENTS_DELTA("response.mcp_call_arguments.delta")` + - `JsonValue; event "thread.run.in_progress"constant` - - `Optional agent` + - `THREAD_RUN_IN_PROGRESS("thread.run.in_progress")` - The agent that owns this multi-agent streaming event. + - `ThreadRunRequiresAction` - - `String agentName` + - `Run data` - The canonical name of the agent that produced this item. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class BetaResponseMcpCallArgumentsDoneEvent:` + - `JsonValue; event "thread.run.requires_action"constant` - Emitted when the arguments for an MCP tool call are finalized. + - `THREAD_RUN_REQUIRES_ACTION("thread.run.requires_action")` - - `String arguments` + - `ThreadRunCompleted` - A JSON string containing the finalized arguments for the MCP tool call. + - `Run data` - - `String itemId` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The unique identifier of the MCP tool call item being processed. + - `JsonValue; event "thread.run.completed"constant` - - `long outputIndex` + - `THREAD_RUN_COMPLETED("thread.run.completed")` - The index of the output item in the response's output array. + - `ThreadRunIncomplete` - - `long sequenceNumber` + - `Run data` - The sequence number of this event. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `JsonValue; type "response.mcp_call_arguments.done"constant` + - `JsonValue; event "thread.run.incomplete"constant` - The type of the event. Always 'response.mcp_call_arguments.done'. + - `THREAD_RUN_INCOMPLETE("thread.run.incomplete")` - - `RESPONSE_MCP_CALL_ARGUMENTS_DONE("response.mcp_call_arguments.done")` + - `ThreadRunFailed` - - `Optional agent` + - `Run data` - The agent that owns this multi-agent streaming event. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `String agentName` + - `JsonValue; event "thread.run.failed"constant` - The canonical name of the agent that produced this item. + - `THREAD_RUN_FAILED("thread.run.failed")` - - `class BetaResponseMcpCallCompletedEvent:` + - `ThreadRunCancelling` - Emitted when an MCP tool call has completed successfully. + - `Run data` - - `String itemId` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The ID of the MCP tool call item that completed. + - `JsonValue; event "thread.run.cancelling"constant` - - `long outputIndex` + - `THREAD_RUN_CANCELLING("thread.run.cancelling")` - The index of the output item that completed. + - `ThreadRunCancelled` - - `long sequenceNumber` + - `Run data` - The sequence number of this event. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `JsonValue; type "response.mcp_call.completed"constant` + - `JsonValue; event "thread.run.cancelled"constant` - The type of the event. Always 'response.mcp_call.completed'. + - `THREAD_RUN_CANCELLED("thread.run.cancelled")` - - `RESPONSE_MCP_CALL_COMPLETED("response.mcp_call.completed")` + - `ThreadRunExpired` - - `Optional agent` + - `Run data` - The agent that owns this multi-agent streaming event. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `String agentName` + - `JsonValue; event "thread.run.expired"constant` - The canonical name of the agent that produced this item. + - `THREAD_RUN_EXPIRED("thread.run.expired")` - - `class BetaResponseMcpCallFailedEvent:` + - `ThreadRunStepCreated` - Emitted when an MCP tool call has failed. + - `RunStep data` - - `String itemId` + Represents a step in execution of a run. - The ID of the MCP tool call item that failed. + - `String id` - - `long outputIndex` + The identifier of the run step, which can be referenced in API endpoints. - The index of the output item that failed. + - `String assistantId` - - `long sequenceNumber` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The sequence number of this event. + - `Optional cancelledAt` - - `JsonValue; type "response.mcp_call.failed"constant` + The Unix timestamp (in seconds) for when the run step was cancelled. - The type of the event. Always 'response.mcp_call.failed'. + - `Optional completedAt` - - `RESPONSE_MCP_CALL_FAILED("response.mcp_call.failed")` + The Unix timestamp (in seconds) for when the run step completed. - - `Optional agent` + - `long createdAt` - The agent that owns this multi-agent streaming event. + The Unix timestamp (in seconds) for when the run step was created. - - `String agentName` + - `Optional expiredAt` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `class BetaResponseMcpCallInProgressEvent:` + - `Optional failedAt` - Emitted when an MCP tool call is in progress. + The Unix timestamp (in seconds) for when the run step failed. - - `String itemId` + - `Optional lastError` - The unique identifier of the MCP tool call item being processed. + The last error associated with this run step. Will be `null` if there are no errors. - - `long outputIndex` + - `Code code` - The index of the output item in the response's output array. + One of `server_error` or `rate_limit_exceeded`. - - `long sequenceNumber` + - `SERVER_ERROR("server_error")` - The sequence number of this event. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `JsonValue; type "response.mcp_call.in_progress"constant` + - `String message` - The type of the event. Always 'response.mcp_call.in_progress'. + A human-readable description of the error. - - `RESPONSE_MCP_CALL_IN_PROGRESS("response.mcp_call.in_progress")` + - `Optional metadata` - - `Optional agent` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The agent that owns this multi-agent streaming event. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `String agentName` + - `JsonValue; object_ "thread.run.step"constant` - The canonical name of the agent that produced this item. + The object type, which is always `thread.run.step`. - - `class BetaResponseMcpListToolsCompletedEvent:` + - `THREAD_RUN_STEP("thread.run.step")` - Emitted when the list of available MCP tools has been successfully retrieved. + - `String runId` - - `String itemId` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - The ID of the MCP tool call item that produced this output. + - `Status status` - - `long outputIndex` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The index of the output item that was processed. + - `IN_PROGRESS("in_progress")` - - `long sequenceNumber` + - `CANCELLED("cancelled")` - The sequence number of this event. + - `FAILED("failed")` - - `JsonValue; type "response.mcp_list_tools.completed"constant` + - `COMPLETED("completed")` - The type of the event. Always 'response.mcp_list_tools.completed'. + - `EXPIRED("expired")` - - `RESPONSE_MCP_LIST_TOOLS_COMPLETED("response.mcp_list_tools.completed")` + - `StepDetails stepDetails` - - `Optional agent` + The details of the run step. - The agent that owns this multi-agent streaming event. + - `class MessageCreationStepDetails:` - - `String agentName` + Details of the message creation by the run step. - The canonical name of the agent that produced this item. + - `MessageCreation messageCreation` - - `class BetaResponseMcpListToolsFailedEvent:` + - `String messageId` - Emitted when the attempt to list available MCP tools has failed. + The ID of the message that was created by this run step. - - `String itemId` + - `JsonValue; type "message_creation"constant` - The ID of the MCP tool call item that failed. + Always `message_creation`. - - `long outputIndex` + - `MESSAGE_CREATION("message_creation")` - The index of the output item that failed. + - `class ToolCallsStepDetails:` - - `long sequenceNumber` + Details of the tool call. - The sequence number of this event. + - `List toolCalls` - - `JsonValue; type "response.mcp_list_tools.failed"constant` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The type of the event. Always 'response.mcp_list_tools.failed'. + - `class CodeInterpreterToolCall:` - - `RESPONSE_MCP_LIST_TOOLS_FAILED("response.mcp_list_tools.failed")` + Details of the Code Interpreter tool call the run step was involved in. - - `Optional agent` + - `String id` - The agent that owns this multi-agent streaming event. + The ID of the tool call. - - `String agentName` + - `CodeInterpreter codeInterpreter` - The canonical name of the agent that produced this item. + The Code Interpreter tool call definition. - - `class BetaResponseMcpListToolsInProgressEvent:` + - `String input` - Emitted when the system is in the process of retrieving the list of available MCP tools. + The input to the Code Interpreter tool call. - - `String itemId` + - `List outputs` - The ID of the MCP tool call item that is being processed. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `long outputIndex` + - `class LogsOutput:` - The index of the output item that is being processed. + Text output from the Code Interpreter tool call as part of a run step. - - `long sequenceNumber` + - `String logs` - The sequence number of this event. + The text output from the Code Interpreter tool call. - - `JsonValue; type "response.mcp_list_tools.in_progress"constant` + - `JsonValue; type "logs"constant` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + Always `logs`. - - `RESPONSE_MCP_LIST_TOOLS_IN_PROGRESS("response.mcp_list_tools.in_progress")` + - `LOGS("logs")` - - `Optional agent` + - `class ImageOutput:` - The agent that owns this multi-agent streaming event. + - `Image image` - - `String agentName` + - `String fileId` - The canonical name of the agent that produced this item. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `class BetaResponseOutputTextAnnotationAddedEvent:` + - `JsonValue; type "image"constant` - Emitted when an annotation is added to output text content. + Always `image`. - - `JsonValue annotation` + - `IMAGE("image")` - The annotation object being added. (See annotation schema for details.) + - `JsonValue; type "code_interpreter"constant` - - `long annotationIndex` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The index of the annotation within the content part. + - `CODE_INTERPRETER("code_interpreter")` - - `long contentIndex` + - `class FileSearchToolCall:` - The index of the content part within the output item. + - `String id` - - `String itemId` + The ID of the tool call object. - The unique identifier of the item to which the annotation is being added. + - `FileSearch fileSearch` - - `long outputIndex` + For now, this is always going to be an empty object. - The index of the output item in the response's output array. + - `Optional rankingOptions` - - `long sequenceNumber` + The ranking options for the file search. - The sequence number of this event. + - `Ranker ranker` - - `JsonValue; type "response.output_text.annotation.added"constant` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The type of the event. Always 'response.output_text.annotation.added'. + - `AUTO("auto")` - - `RESPONSE_OUTPUT_TEXT_ANNOTATION_ADDED("response.output_text.annotation.added")` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `Optional agent` + - `double scoreThreshold` - The agent that owns this multi-agent streaming event. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `String agentName` + - `Optional> results` - The canonical name of the agent that produced this item. + The results of the file search. - - `class BetaResponseQueuedEvent:` + - `String fileId` - Emitted when a response is queued and waiting to be processed. + The ID of the file that result was found in. - - `BetaResponse response` + - `String fileName` - The full response object that is queued. + The name of the file that result was found in. - - `long sequenceNumber` + - `double score` - The sequence number for this event. + The score of the result. All values must be a floating point number between 0 and 1. - - `JsonValue; type "response.queued"constant` + - `Optional> content` - The type of the event. Always 'response.queued'. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `RESPONSE_QUEUED("response.queued")` + - `Optional text` - - `Optional agent` + The text content of the file. - The agent that owns this multi-agent streaming event. + - `Optional type` - - `String agentName` + The type of the content. - The canonical name of the agent that produced this item. + - `TEXT("text")` - - `class BetaResponseCustomToolCallInputDeltaEvent:` + - `JsonValue; type "file_search"constant` - Event representing a delta (partial update) to the input of a custom tool call. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `String delta` + - `FILE_SEARCH("file_search")` - The incremental input data (delta) for the custom tool call. + - `class FunctionToolCall:` - - `String itemId` + - `String id` - Unique identifier for the API item associated with this event. + The ID of the tool call object. - - `long outputIndex` + - `Function function` - The index of the output this delta applies to. + The definition of the function that was called. - - `long sequenceNumber` + - `String arguments` - The sequence number of this event. + The arguments passed to the function. - - `JsonValue; type "response.custom_tool_call_input.delta"constant` + - `String name` - The event type identifier. + The name of the function. - - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DELTA("response.custom_tool_call_input.delta")` + - `Optional output` - - `Optional agent` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The agent that owns this multi-agent streaming event. + - `JsonValue; type "function"constant` - - `String agentName` + The type of tool call. This is always going to be `function` for this type of tool call. - The canonical name of the agent that produced this item. + - `FUNCTION("function")` - - `class BetaResponseCustomToolCallInputDoneEvent:` + - `JsonValue; type "tool_calls"constant` - Event indicating that input for a custom tool call is complete. + Always `tool_calls`. - - `String input` + - `TOOL_CALLS("tool_calls")` - The complete input data for the custom tool call. + - `String threadId` - - `String itemId` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - Unique identifier for the API item associated with this event. + - `Type type` - - `long outputIndex` + The type of run step, which can be either `message_creation` or `tool_calls`. - The index of the output this event applies to. + - `MESSAGE_CREATION("message_creation")` - - `long sequenceNumber` + - `TOOL_CALLS("tool_calls")` - The sequence number of this event. + - `Optional usage` - - `JsonValue; type "response.custom_tool_call_input.done"constant` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The event type identifier. + - `long completionTokens` - - `RESPONSE_CUSTOM_TOOL_CALL_INPUT_DONE("response.custom_tool_call_input.done")` + Number of completion tokens used over the course of the run step. - - `Optional agent` + - `long promptTokens` - The agent that owns this multi-agent streaming event. + Number of prompt tokens used over the course of the run step. - - `String agentName` + - `long totalTokens` - The canonical name of the agent that produced this item. + Total number of tokens used (prompt + completion). - - `ResponseInjectCreated` + - `JsonValue; event "thread.run.step.created"constant` - - `String responseId` + - `THREAD_RUN_STEP_CREATED("thread.run.step.created")` - The ID of the response that accepted the input. + - `ThreadRunStepInProgress` - - `long sequenceNumber` + - `RunStep data` - The sequence number for this event. + Represents a step in execution of a run. - - `JsonValue; type "response.inject.created"constant` + - `JsonValue; event "thread.run.step.in_progress"constant` - The event discriminator. Always `response.inject.created`. + - `THREAD_RUN_STEP_IN_PROGRESS("thread.run.step.in_progress")` - - `RESPONSE_INJECT_CREATED("response.inject.created")` + - `ThreadRunStepDelta` - - `Optional streamId` + - `RunStepDeltaEvent data` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `ResponseInjectFailed` + - `String id` - - `Error error` + The identifier of the run step, which can be referenced in API endpoints. - Information about why the input was not committed. + - `RunStepDelta delta` - - `Code code` + The delta containing the fields that have changed on the run step. - A machine-readable error code. + - `Optional stepDetails` - - `RESPONSE_ALREADY_COMPLETED("response_already_completed")` + The details of the run step. - - `RESPONSE_NOT_FOUND("response_not_found")` + - `class RunStepDeltaMessageDelta:` - - `String message` + Details of the message creation by the run step. - A human-readable description of the error. + - `JsonValue; type "message_creation"constant` - - `List input` + Always `message_creation`. - The raw input items that were not committed. + - `MESSAGE_CREATION("message_creation")` - - `class BetaEasyInputMessage:` + - `Optional messageCreation` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `Optional messageId` - - `Message` + The ID of the message that was created by this run step. - - `class BetaResponseOutputMessage:` + - `class ToolCallDeltaObject:` - An output message from the model. + Details of the tool call. - - `class BetaResponseFileSearchToolCall:` + - `JsonValue; type "tool_calls"constant` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + Always `tool_calls`. - - `class BetaResponseComputerToolCall:` + - `TOOL_CALLS("tool_calls")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `Optional> toolCalls` - - `ComputerCallOutput` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `class BetaResponseFunctionWebSearch:` + - `class CodeInterpreterToolCallDelta:` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + Details of the Code Interpreter tool call the run step was involved in. - - `class BetaResponseFunctionToolCall:` + - `long index` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The index of the tool call in the tool calls array. - - `FunctionCallOutput` + - `JsonValue; type "code_interpreter"constant` - - `AgentMessage` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `MultiAgentCall` + - `CODE_INTERPRETER("code_interpreter")` - - `MultiAgentCallOutput` + - `Optional id` - - `ToolSearchCall` + The ID of the tool call. - - `class BetaResponseToolSearchOutputItemParam:` + - `Optional codeInterpreter` - - `AdditionalTools` + The Code Interpreter tool call definition. - - `class BetaResponseReasoningItem:` + - `Optional input` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The input to the Code Interpreter tool call. - - `class BetaResponseCompactionItemParam:` + - `Optional> outputs` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `ImageGenerationCall` + - `class CodeInterpreterLogs:` - - `class BetaResponseCodeInterpreterToolCall:` + Text output from the Code Interpreter tool call as part of a run step. - A tool call to run code. + - `long index` - - `LocalShellCall` + The index of the output in the outputs array. - - `LocalShellCallOutput` + - `JsonValue; type "logs"constant` - - `ShellCall` + Always `logs`. - - `ShellCallOutput` + - `LOGS("logs")` - - `ApplyPatchCall` + - `Optional logs` - - `ApplyPatchCallOutput` + The text output from the Code Interpreter tool call. - - `McpListTools` + - `class CodeInterpreterOutputImage:` - - `McpApprovalRequest` + - `long index` - - `McpApprovalResponse` + The index of the output in the outputs array. - - `McpCall` + - `JsonValue; type "image"constant` - - `class BetaResponseCustomToolCallOutput:` + Always `image`. - The output of a custom tool call from your code, being sent back to the model. + - `IMAGE("image")` - - `class BetaResponseCustomToolCall:` + - `Optional image` - A call to a custom tool created by the model. + - `Optional fileId` - - `CompactionTrigger` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `ItemReference` + - `class FileSearchToolCallDelta:` - - `Program` + - `JsonValue fileSearch` - - `ProgramOutput` + For now, this is always going to be an empty object. - - `String responseId` + - `long index` - The ID of the response that rejected the input. + The index of the tool call in the tool calls array. - - `long sequenceNumber` + - `JsonValue; type "file_search"constant` - The sequence number for this event. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `JsonValue; type "response.inject.failed"constant` + - `FILE_SEARCH("file_search")` - The event discriminator. Always `response.inject.failed`. + - `Optional id` - - `RESPONSE_INJECT_FAILED("response.inject.failed")` + The ID of the tool call object. - - `Optional streamId` + - `class FunctionToolCallDelta:` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `long index` -### Beta Skill Reference + The index of the tool call in the tool calls array. -- `class BetaSkillReference:` + - `JsonValue; type "function"constant` - - `String skillId` + The type of tool call. This is always going to be `function` for this type of tool call. - The ID of the referenced skill. + - `FUNCTION("function")` - - `JsonValue; type "skill_reference"constant` + - `Optional id` - References a skill created with the /v1/skills endpoint. + The ID of the tool call object. - - `SKILL_REFERENCE("skill_reference")` + - `Optional function` - - `Optional version` + The definition of the function that was called. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `Optional arguments` -### Beta Tool + The arguments passed to the function. -- `class BetaTool: A class that can be one of several variants.union` + - `Optional name` - A tool that can be used to generate a response. + The name of the function. - - `class BetaFunctionTool:` + - `Optional output` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `String name` + - `JsonValue; object_ "thread.run.step.delta"constant` - The name of the function to call. + The object type, which is always `thread.run.step.delta`. - - `Optional parameters` + - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` - A JSON schema object describing the parameters of the function. + - `JsonValue; event "thread.run.step.delta"constant` - - `Optional strict` + - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` - Whether strict parameter validation is enforced for this function tool. + - `ThreadRunStepCompleted` - - `JsonValue; type "function"constant` + - `RunStep data` - The type of the function tool. Always `function`. + Represents a step in execution of a run. - - `FUNCTION("function")` + - `JsonValue; event "thread.run.step.completed"constant` - - `Optional> allowedCallers` + - `THREAD_RUN_STEP_COMPLETED("thread.run.step.completed")` - The tool invocation context(s). + - `ThreadRunStepFailed` - - `DIRECT("direct")` + - `RunStep data` - - `PROGRAMMATIC("programmatic")` + Represents a step in execution of a run. - - `Optional deferLoading` + - `JsonValue; event "thread.run.step.failed"constant` - Whether this function is deferred and loaded via tool search. + - `THREAD_RUN_STEP_FAILED("thread.run.step.failed")` - - `Optional description` + - `ThreadRunStepCancelled` - A description of the function. Used by the model to determine whether or not to call the function. + - `RunStep data` - - `Optional outputSchema` + Represents a step in execution of a run. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `JsonValue; event "thread.run.step.cancelled"constant` - - `class BetaFileSearchTool:` + - `THREAD_RUN_STEP_CANCELLED("thread.run.step.cancelled")` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `ThreadRunStepExpired` - - `JsonValue; type "file_search"constant` + - `RunStep data` - The type of the file search tool. Always `file_search`. + Represents a step in execution of a run. - - `FILE_SEARCH("file_search")` + - `JsonValue; event "thread.run.step.expired"constant` - - `List vectorStoreIds` + - `THREAD_RUN_STEP_EXPIRED("thread.run.step.expired")` - The IDs of the vector stores to search. + - `ThreadMessageCreated` - - `Optional filters` + - `Message data` - A filter to apply. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class ComparisonFilter:` + - `String id` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The identifier, which can be referenced in API endpoints. - - `String key` + - `Optional assistantId` - The key to compare against the value. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `Type type` + - `Optional> attachments` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A list of files attached to the message, and the tools they were added to. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `Optional fileId` - - `EQ("eq")` + The ID of the file to attach to the message. - - `NE("ne")` + - `Optional> tools` - - `GT("gt")` + The tools to add this file to. - - `GTE("gte")` + - `class CodeInterpreterTool:` - - `LT("lt")` + - `JsonValue;` - - `LTE("lte")` + - `JsonValue; type "file_search"constant` - - `IN("in")` + The type of tool being defined: `file_search` - - `NIN("nin")` + - `FILE_SEARCH("file_search")` - - `Value value` + - `Optional completedAt` - The value to compare against the attribute key; supports string, number, or boolean types. + The Unix timestamp (in seconds) for when the message was completed. - - `String` + - `List content` - - `double` + The content of the message in array of text and/or images. - - `boolean` + - `class ImageFileContentBlock:` - - `List` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `class CompoundFilter:` + - `ImageFile imageFile` - Combine multiple filters using `and` or `or`. + - `String fileId` - - `List filters` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `Optional detail` - - `class ComparisonFilter:` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `AUTO("auto")` - - `String key` + - `LOW("low")` - The key to compare against the value. + - `HIGH("high")` - - `Type type` + - `JsonValue; type "image_file"constant` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Always `image_file`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `IMAGE_FILE("image_file")` - - `EQ("eq")` + - `class ImageUrlContentBlock:` - - `NE("ne")` + References an image URL in the content of a message. - - `GT("gt")` + - `ImageUrl imageUrl` - - `GTE("gte")` + - `String url` - - `LT("lt")` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `LTE("lte")` + - `Optional detail` - - `IN("in")` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `NIN("nin")` + - `AUTO("auto")` - - `Value value` + - `LOW("low")` - The value to compare against the attribute key; supports string, number, or boolean types. + - `HIGH("high")` - - `String` + - `JsonValue; type "image_url"constant` - - `double` + The type of the content part. - - `boolean` + - `IMAGE_URL("image_url")` - - `List` + - `class TextContentBlock:` - - `JsonValue` + The text content that is part of a message. - - `Type type` + - `Text text` - Type of operation: `and` or `or`. + - `List annotations` - - `AND("and")` + - `class FileCitationAnnotation:` - - `OR("or")` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `Optional maxNumResults` + - `long endIndex` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `FileCitation fileCitation` - - `Optional rankingOptions` + - `String fileId` - Ranking options for search. + The ID of the specific File the citation is from. - - `Optional hybridSearch` + - `long startIndex` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `String text` - - `double embeddingWeight` + The text in the message content that needs to be replaced. - The weight of the embedding in the reciprocal ranking fusion. + - `JsonValue; type "file_citation"constant` - - `double textWeight` + Always `file_citation`. - The weight of the text in the reciprocal ranking fusion. + - `FILE_CITATION("file_citation")` - - `Optional ranker` + - `class FilePathAnnotation:` - The ranker to use for the file search. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `AUTO("auto")` + - `long endIndex` - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `FilePath filePath` - - `Optional scoreThreshold` + - `String fileId` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The ID of the file that was generated. - - `class BetaComputerTool:` + - `long startIndex` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String text` - - `JsonValue; type "computer"constant` + The text in the message content that needs to be replaced. - The type of the computer tool. Always `computer`. + - `JsonValue; type "file_path"constant` - - `COMPUTER("computer")` + Always `file_path`. - - `class BetaComputerUsePreviewTool:` + - `FILE_PATH("file_path")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String value` - - `long displayHeight` + The data that makes up the text. - The height of the computer display. + - `JsonValue; type "text"constant` - - `long displayWidth` + Always `text`. - The width of the computer display. + - `TEXT("text")` - - `Environment environment` + - `class RefusalContentBlock:` - The type of computer environment to control. + The refusal content generated by the assistant. - - `WINDOWS("windows")` + - `String refusal` - - `MAC("mac")` + - `JsonValue; type "refusal"constant` - - `LINUX("linux")` + Always `refusal`. - - `UBUNTU("ubuntu")` + - `REFUSAL("refusal")` - - `BROWSER("browser")` + - `long createdAt` - - `JsonValue; type "computer_use_preview"constant` + The Unix timestamp (in seconds) for when the message was created. - The type of the computer use tool. Always `computer_use_preview`. + - `Optional incompleteAt` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `class BetaWebSearchTool:` + - `Optional incompleteDetails` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + On an incomplete message, details about why the message is incomplete. - - `Type type` + - `Reason reason` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The reason the message is incomplete. - - `WEB_SEARCH("web_search")` + - `CONTENT_FILTER("content_filter")` - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `MAX_TOKENS("max_tokens")` - - `Optional filters` + - `RUN_CANCELLED("run_cancelled")` - Filters for the search. + - `RUN_EXPIRED("run_expired")` - - `Optional> allowedDomains` + - `RUN_FAILED("run_failed")` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Optional metadata` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Optional searchContextSize` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `JsonValue; object_ "thread.message"constant` - - `LOW("low")` + The object type, which is always `thread.message`. - - `MEDIUM("medium")` + - `THREAD_MESSAGE("thread.message")` - - `HIGH("high")` + - `Role role` - - `Optional userLocation` + The entity that produced the message. One of `user` or `assistant`. - The approximate location of the user. + - `USER("user")` - - `Optional city` + - `ASSISTANT("assistant")` - Free text input for the city of the user, e.g. `San Francisco`. + - `Optional runId` - - `Optional country` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Status status` - - `Optional region` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - Free text input for the region of the user, e.g. `California`. + - `IN_PROGRESS("in_progress")` - - `Optional timezone` + - `INCOMPLETE("incomplete")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `COMPLETED("completed")` - - `Optional type` + - `String threadId` - The type of location approximation. Always `approximate`. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `APPROXIMATE("approximate")` + - `JsonValue; event "thread.message.created"constant` - - `Mcp` + - `THREAD_MESSAGE_CREATED("thread.message.created")` - - `String serverLabel` + - `ThreadMessageInProgress` - A label for this MCP server, used to identify it in tool calls. + - `Message data` - - `JsonValue; type "mcp"constant` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The type of the MCP tool. Always `mcp`. + - `JsonValue; event "thread.message.in_progress"constant` - - `MCP("mcp")` + - `THREAD_MESSAGE_IN_PROGRESS("thread.message.in_progress")` - - `Optional> allowedCallers` + - `ThreadMessageDelta` - The tool invocation context(s). + - `MessageDeltaEvent data` - - `DIRECT("direct")` + Represents a message delta i.e. any changed fields on a message during streaming. - - `PROGRAMMATIC("programmatic")` + - `String id` - - `Optional allowedTools` + The identifier of the message, which can be referenced in API endpoints. - List of allowed tool names or a filter object. + - `MessageDelta delta` - - `List` + The delta containing the fields that have changed on the Message. - - `class McpToolFilter:` + - `Optional> content` - A filter object to specify which tools are allowed. + The content of the message in array of text and/or images. - - `Optional readOnly` + - `class ImageFileDeltaBlock:` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `Optional> toolNames` + - `long index` - List of allowed tool names. + The index of the content part in the message. - - `Optional authorization` + - `JsonValue; type "image_file"constant` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + Always `image_file`. - - `Optional connectorId` + - `IMAGE_FILE("image_file")` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `Optional imageFile` - Currently supported `connector_id` values are: + - `Optional detail` - - 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` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `AUTO("auto")` - - `CONNECTOR_GMAIL("connector_gmail")` + - `LOW("low")` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `HIGH("high")` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `Optional fileId` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `class TextDeltaBlock:` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + The text content that is part of a message. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `long index` - - `Optional deferLoading` + The index of the content part in the message. - Whether this MCP tool is deferred and discovered via tool search. + - `JsonValue; type "text"constant` - - `Optional headers` + Always `text`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `TEXT("text")` - - `Optional requireApproval` + - `Optional text` - Specify which of the MCP server's tools require approval. + - `Optional> annotations` - - `class McpToolApprovalFilter:` + - `class FileCitationDeltaAnnotation:` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `Optional always` + - `long index` - A filter object to specify which tools are allowed. + The index of the annotation in the text content part. - - `Optional readOnly` + - `JsonValue; type "file_citation"constant` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Always `file_citation`. - - `Optional> toolNames` + - `FILE_CITATION("file_citation")` - List of allowed tool names. + - `Optional endIndex` - - `Optional never` + - `Optional fileCitation` - A filter object to specify which tools are allowed. + - `Optional fileId` - - `Optional readOnly` + The ID of the specific File the citation is from. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Optional quote` - - `Optional> toolNames` + The specific quote in the file. - List of allowed tool names. + - `Optional startIndex` - - `enum McpToolApprovalSetting:` + - `Optional text` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The text in the message content that needs to be replaced. - - `ALWAYS("always")` + - `class FilePathDeltaAnnotation:` - - `NEVER("never")` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `Optional serverDescription` + - `long index` - Optional description of the MCP server, used to provide more context. + The index of the annotation in the text content part. - - `Optional serverUrl` + - `JsonValue; type "file_path"constant` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Always `file_path`. - - `Optional tunnelId` + - `FILE_PATH("file_path")` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `Optional endIndex` - - `CodeInterpreter` + - `Optional filePath` - - `Container container` + - `Optional fileId` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The ID of the file that was generated. - - `String` + - `Optional startIndex` - - `class CodeInterpreterToolAuto:` + - `Optional text` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The text in the message content that needs to be replaced. - - `JsonValue; type "auto"constant` + - `Optional value` - Always `auto`. + The data that makes up the text. - - `AUTO("auto")` + - `class RefusalDeltaBlock:` - - `Optional> fileIds` + The refusal content that is part of a message. - An optional list of uploaded files to make available to your code. + - `long index` - - `Optional memoryLimit` + The index of the refusal part in the message. - The memory limit for the code interpreter container. + - `JsonValue; type "refusal"constant` - - `_1G("1g")` + Always `refusal`. - - `_4G("4g")` + - `REFUSAL("refusal")` - - `_16G("16g")` + - `Optional refusal` - - `_64G("64g")` + - `class ImageUrlDeltaBlock:` - - `Optional networkPolicy` + References an image URL in the content of a message. - Network access policy for the container. + - `long index` - - `class BetaContainerNetworkPolicyDisabled:` + The index of the content part in the message. - - `JsonValue; type "disabled"constant` + - `JsonValue; type "image_url"constant` - Disable outbound network access. Always `disabled`. + Always `image_url`. - - `DISABLED("disabled")` + - `IMAGE_URL("image_url")` - - `class BetaContainerNetworkPolicyAllowlist:` + - `Optional imageUrl` - - `List allowedDomains` + - `Optional detail` - A list of allowed domains when type is `allowlist`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `JsonValue; type "allowlist"constant` + - `AUTO("auto")` - Allow outbound network access only to specified domains. Always `allowlist`. + - `LOW("low")` - - `ALLOWLIST("allowlist")` + - `HIGH("high")` - - `Optional> domainSecrets` + - `Optional url` - Optional domain-scoped secrets for allowlisted domains. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `String domain` + - `Optional role` - The domain associated with the secret. + The entity that produced the message. One of `user` or `assistant`. - - `String name` + - `USER("user")` - The name of the secret to inject for the domain. + - `ASSISTANT("assistant")` - - `String value` + - `JsonValue; object_ "thread.message.delta"constant` - The secret value to inject for the domain. + The object type, which is always `thread.message.delta`. - - `JsonValue; type "code_interpreter"constant` + - `THREAD_MESSAGE_DELTA("thread.message.delta")` - The type of the code interpreter tool. Always `code_interpreter`. + - `JsonValue; event "thread.message.delta"constant` - - `CODE_INTERPRETER("code_interpreter")` + - `THREAD_MESSAGE_DELTA("thread.message.delta")` - - `Optional> allowedCallers` + - `ThreadMessageCompleted` - The tool invocation context(s). + - `Message data` - - `DIRECT("direct")` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `PROGRAMMATIC("programmatic")` + - `JsonValue; event "thread.message.completed"constant` - - `JsonValue;` + - `THREAD_MESSAGE_COMPLETED("thread.message.completed")` - - `JsonValue; type "programmatic_tool_calling"constant` + - `ThreadMessageIncomplete` - The type of the tool. Always `programmatic_tool_calling`. + - `Message data` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `ImageGeneration` + - `JsonValue; event "thread.message.incomplete"constant` - - `JsonValue; type "image_generation"constant` + - `THREAD_MESSAGE_INCOMPLETE("thread.message.incomplete")` - The type of the image generation tool. Always `image_generation`. + - `ErrorEvent` - - `IMAGE_GENERATION("image_generation")` + - `ErrorObject data` - - `Optional action` + - `Optional code` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `String message` - - `GENERATE("generate")` + - `Optional param` - - `EDIT("edit")` + - `String type` - - `AUTO("auto")` + - `JsonValue; event "error"constant` - - `Optional background` + - `ERROR("error")` - 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. +### Assistant Tool - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. +- `class AssistantTool: A class that can be one of several variants.union` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `class CodeInterpreterTool:` - - `TRANSPARENT("transparent")` + - `JsonValue; type "code_interpreter"constant` - - `OPAQUE("opaque")` + The type of tool being defined: `code_interpreter` - - `AUTO("auto")` + - `CODE_INTERPRETER("code_interpreter")` - - `Optional inputFidelity` + - `class FileSearchTool:` - 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`. + - `JsonValue; type "file_search"constant` - - `HIGH("high")` + The type of tool being defined: `file_search` - - `LOW("low")` + - `FILE_SEARCH("file_search")` - - `Optional inputImageMask` + - `Optional fileSearch` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Overrides for the file search tool. - - `Optional fileId` + - `Optional maxNumResults` - File ID for the mask image. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `Optional imageUrl` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Base64-encoded mask image. + - `Optional rankingOptions` - - `Optional model` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The image generation model to use. Default: `gpt-image-1`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `GPT_IMAGE_1("gpt-image-1")` + - `double scoreThreshold` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `GPT_IMAGE_2("gpt-image-2")` + - `Optional ranker` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `AUTO("auto")` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `Optional moderation` + - `class FunctionTool:` - Moderation level for the generated image. Default: `auto`. + - `FunctionDefinition function` - - `AUTO("auto")` + - `String name` - - `LOW("low")` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `Optional outputCompression` + - `Optional description` - Compression level for the output image. Default: 100. + A description of what the function does, used by the model to choose when and how to call the function. - - `Optional outputFormat` + - `Optional parameters` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `PNG("png")` + Omitting `parameters` defines a function with an empty parameter list. - - `WEBP("webp")` + - `Optional strict` - - `JPEG("jpeg")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `Optional partialImages` + - `JsonValue; type "function"constant` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The type of tool being defined: `function` - - `Optional quality` + - `FUNCTION("function")` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. +### Code Interpreter Tool - - `LOW("low")` +- `class CodeInterpreterTool:` - - `MEDIUM("medium")` + - `JsonValue; type "code_interpreter"constant` - - `HIGH("high")` + The type of tool being defined: `code_interpreter` - - `AUTO("auto")` + - `CODE_INTERPRETER("code_interpreter")` - - `Optional size` +### File Search Tool - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. +- `class FileSearchTool:` - - `_1024X1024("1024x1024")` + - `JsonValue; type "file_search"constant` - - `_1024X1536("1024x1536")` + The type of tool being defined: `file_search` - - `_1536X1024("1536x1024")` + - `FILE_SEARCH("file_search")` - - `AUTO("auto")` + - `Optional fileSearch` - - `JsonValue;` + Overrides for the file search tool. - - `JsonValue; type "local_shell"constant` + - `Optional maxNumResults` - The type of the local shell tool. Always `local_shell`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `LOCAL_SHELL("local_shell")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaFunctionShellTool:` + - `Optional rankingOptions` - A tool that allows the model to execute shell commands. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `JsonValue; type "shell"constant` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The type of the shell tool. Always `shell`. + - `double scoreThreshold` - - `SHELL("shell")` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `Optional> allowedCallers` + - `Optional ranker` - The tool invocation context(s). + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `DIRECT("direct")` + - `AUTO("auto")` - - `PROGRAMMATIC("programmatic")` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `Optional environment` +### Function Tool - - `class BetaContainerAuto:` +- `class FunctionTool:` - - `JsonValue; type "container_auto"constant` + - `FunctionDefinition function` - Automatically creates a container for this request + - `String name` - - `CONTAINER_AUTO("container_auto")` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `Optional> fileIds` + - `Optional description` - An optional list of uploaded files to make available to your code. + A description of what the function does, used by the model to choose when and how to call the function. - - `Optional memoryLimit` + - `Optional parameters` - The memory limit for the container. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `_1G("1g")` + Omitting `parameters` defines a function with an empty parameter list. - - `_4G("4g")` + - `Optional strict` - - `_16G("16g")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `_64G("64g")` + - `JsonValue; type "function"constant` - - `Optional networkPolicy` + The type of tool being defined: `function` - Network access policy for the container. + - `FUNCTION("function")` - - `class BetaContainerNetworkPolicyDisabled:` +### Message Stream Event - - `class BetaContainerNetworkPolicyAllowlist:` +- `class MessageStreamEvent: A class that can be one of several variants.union` - - `Optional> skills` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - An optional list of skills referenced by id or inline data. + - `ThreadMessageCreated` - - `class BetaSkillReference:` + - `Message data` - - `String skillId` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The ID of the referenced skill. + - `String id` - - `JsonValue; type "skill_reference"constant` + The identifier, which can be referenced in API endpoints. - References a skill created with the /v1/skills endpoint. + - `Optional assistantId` - - `SKILL_REFERENCE("skill_reference")` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `Optional version` + - `Optional> attachments` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + A list of files attached to the message, and the tools they were added to. - - `class BetaInlineSkill:` + - `Optional fileId` - - `String description` + The ID of the file to attach to the message. - The description of the skill. + - `Optional> tools` - - `String name` + The tools to add this file to. - The name of the skill. + - `class CodeInterpreterTool:` - - `BetaInlineSkillSource source` + - `JsonValue; type "code_interpreter"constant` - Inline skill payload + The type of tool being defined: `code_interpreter` - - `String data` + - `CODE_INTERPRETER("code_interpreter")` - Base64-encoded skill zip bundle. + - `JsonValue;` - - `JsonValue; mediaType "application/zip"constant` + - `JsonValue; type "file_search"constant` - The media type of the inline skill payload. Must be `application/zip`. + The type of tool being defined: `file_search` - - `APPLICATION_ZIP("application/zip")` + - `FILE_SEARCH("file_search")` - - `JsonValue; type "base64"constant` + - `Optional completedAt` - The type of the inline skill source. Must be `base64`. + The Unix timestamp (in seconds) for when the message was completed. - - `BASE64("base64")` + - `List content` - - `JsonValue; type "inline"constant` + The content of the message in array of text and/or images. - Defines an inline skill for this request. + - `class ImageFileContentBlock:` - - `INLINE("inline")` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `class BetaLocalEnvironment:` + - `ImageFile imageFile` - - `JsonValue; type "local"constant` + - `String fileId` - Use a local computer environment. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `LOCAL("local")` + - `Optional detail` - - `Optional> skills` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - An optional list of skills. + - `AUTO("auto")` - - `String description` + - `LOW("low")` - The description of the skill. + - `HIGH("high")` - - `String name` + - `JsonValue; type "image_file"constant` - The name of the skill. + Always `image_file`. - - `String path` + - `IMAGE_FILE("image_file")` - The path to the directory containing the skill. + - `class ImageUrlContentBlock:` - - `class BetaContainerReference:` + References an image URL in the content of a message. - - `String containerId` + - `ImageUrl imageUrl` - The ID of the referenced container. + - `String url` - - `JsonValue; type "container_reference"constant` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - References a container created with the /v1/containers endpoint + - `Optional detail` - - `CONTAINER_REFERENCE("container_reference")` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `class BetaCustomTool:` + - `AUTO("auto")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `LOW("low")` - - `String name` + - `HIGH("high")` - The name of the custom tool, used to identify it in tool calls. + - `JsonValue; type "image_url"constant` - - `JsonValue; type "custom"constant` + The type of the content part. - The type of the custom tool. Always `custom`. + - `IMAGE_URL("image_url")` - - `CUSTOM("custom")` + - `class TextContentBlock:` - - `Optional> allowedCallers` + The text content that is part of a message. - The tool invocation context(s). + - `Text text` - - `DIRECT("direct")` + - `List annotations` - - `PROGRAMMATIC("programmatic")` + - `class FileCitationAnnotation:` - - `Optional deferLoading` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Whether this tool should be deferred and discovered via tool search. + - `long endIndex` - - `Optional description` + - `FileCitation fileCitation` - Optional description of the custom tool, used to provide more context. + - `String fileId` - - `Optional format` + The ID of the specific File the citation is from. - The input format for the custom tool. Default is unconstrained text. + - `long startIndex` - - `JsonValue;` + - `String text` - - `JsonValue; type "text"constant` + The text in the message content that needs to be replaced. - Unconstrained text format. Always `text`. + - `JsonValue; type "file_citation"constant` - - `TEXT("text")` + Always `file_citation`. - - `class Grammar:` + - `FILE_CITATION("file_citation")` - A grammar defined by the user. + - `class FilePathAnnotation:` - - `String definition` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The grammar definition. + - `long endIndex` - - `Syntax syntax` + - `FilePath filePath` - The syntax of the grammar definition. One of `lark` or `regex`. + - `String fileId` - - `LARK("lark")` + The ID of the file that was generated. - - `REGEX("regex")` + - `long startIndex` - - `JsonValue; type "grammar"constant` + - `String text` - Grammar format. Always `grammar`. + The text in the message content that needs to be replaced. - - `GRAMMAR("grammar")` + - `JsonValue; type "file_path"constant` - - `class BetaNamespaceTool:` + Always `file_path`. - Groups function/custom tools under a shared namespace. + - `FILE_PATH("file_path")` - - `String description` + - `String value` - A description of the namespace shown to the model. + The data that makes up the text. - - `String name` + - `JsonValue; type "text"constant` - The namespace name used in tool calls (for example, `crm`). + Always `text`. - - `List tools` + - `TEXT("text")` - The function/custom tools available inside this namespace. + - `class RefusalContentBlock:` - - `class Function:` + The refusal content generated by the assistant. - - `String name` + - `String refusal` - - `JsonValue; type "function"constant` + - `JsonValue; type "refusal"constant` - - `FUNCTION("function")` + Always `refusal`. - - `Optional> allowedCallers` + - `REFUSAL("refusal")` - The tool invocation context(s). + - `long createdAt` - - `DIRECT("direct")` + The Unix timestamp (in seconds) for when the message was created. - - `PROGRAMMATIC("programmatic")` + - `Optional incompleteAt` - - `Optional deferLoading` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - Whether this function should be deferred and discovered via tool search. + - `Optional incompleteDetails` - - `Optional description` + On an incomplete message, details about why the message is incomplete. - - `Optional outputSchema` + - `Reason reason` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The reason the message is incomplete. - - `Optional parameters` + - `CONTENT_FILTER("content_filter")` - - `Optional strict` + - `MAX_TOKENS("max_tokens")` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `RUN_CANCELLED("run_cancelled")` - - `class BetaCustomTool:` + - `RUN_EXPIRED("run_expired")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `RUN_FAILED("run_failed")` - - `JsonValue; type "namespace"constant` + - `Optional metadata` - The type of the tool. Always `namespace`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `NAMESPACE("namespace")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class BetaToolSearchTool:` + - `JsonValue; object_ "thread.message"constant` - Hosted or BYOT tool search configuration for deferred tools. + The object type, which is always `thread.message`. - - `JsonValue; type "tool_search"constant` + - `THREAD_MESSAGE("thread.message")` - The type of the tool. Always `tool_search`. + - `Role role` - - `TOOL_SEARCH("tool_search")` + The entity that produced the message. One of `user` or `assistant`. - - `Optional description` + - `USER("user")` - Description shown to the model for a client-executed tool search tool. + - `ASSISTANT("assistant")` - - `Optional execution` + - `Optional runId` - Whether tool search is executed by the server or by the client. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `SERVER("server")` + - `Status status` - - `CLIENT("client")` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `Optional parameters` + - `IN_PROGRESS("in_progress")` - Parameter schema for a client-executed tool search tool. + - `INCOMPLETE("incomplete")` - - `class BetaWebSearchPreviewTool:` + - `COMPLETED("completed")` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String threadId` - - `Type type` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `JsonValue; event "thread.message.created"constant` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `THREAD_MESSAGE_CREATED("thread.message.created")` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `ThreadMessageInProgress` - - `Optional> searchContentTypes` + - `Message data` - - `TEXT("text")` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `IMAGE("image")` + - `JsonValue; event "thread.message.in_progress"constant` - - `Optional searchContextSize` + - `THREAD_MESSAGE_IN_PROGRESS("thread.message.in_progress")` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `ThreadMessageDelta` - - `LOW("low")` + - `MessageDeltaEvent data` - - `MEDIUM("medium")` + Represents a message delta i.e. any changed fields on a message during streaming. - - `HIGH("high")` + - `String id` - - `Optional userLocation` + The identifier of the message, which can be referenced in API endpoints. - The user's location. + - `MessageDelta delta` - - `JsonValue; type "approximate"constant` + The delta containing the fields that have changed on the Message. - The type of location approximation. Always `approximate`. + - `Optional> content` - - `APPROXIMATE("approximate")` + The content of the message in array of text and/or images. - - `Optional city` + - `class ImageFileDeltaBlock:` - Free text input for the city of the user, e.g. `San Francisco`. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `Optional country` + - `long index` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The index of the content part in the message. - - `Optional region` + - `JsonValue; type "image_file"constant` - Free text input for the region of the user, e.g. `California`. + Always `image_file`. - - `Optional timezone` + - `IMAGE_FILE("image_file")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `Optional imageFile` - - `class BetaApplyPatchTool:` + - `Optional detail` - Allows the assistant to create, delete, or update files using unified diffs. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `JsonValue; type "apply_patch"constant` + - `AUTO("auto")` - The type of the tool. Always `apply_patch`. + - `LOW("low")` - - `APPLY_PATCH("apply_patch")` + - `HIGH("high")` - - `Optional> allowedCallers` + - `Optional fileId` - The tool invocation context(s). + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `DIRECT("direct")` + - `class TextDeltaBlock:` - - `PROGRAMMATIC("programmatic")` + The text content that is part of a message. -### Beta Tool Choice Allowed + - `long index` -- `class BetaToolChoiceAllowed:` + The index of the content part in the message. - Constrains the tools available to the model to a pre-defined set. + - `JsonValue; type "text"constant` - - `Mode mode` + Always `text`. - Constrains the tools available to the model to a pre-defined set. + - `TEXT("text")` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `Optional text` - `required` requires the model to call one or more of the allowed tools. + - `Optional> annotations` - - `AUTO("auto")` + - `class FileCitationDeltaAnnotation:` - - `REQUIRED("required")` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `List tools` + - `long index` - A list of tool definitions that the model should be allowed to call. + The index of the annotation in the text content part. - For the Responses API, the list of tool definitions might look like: + - `JsonValue; type "file_citation"constant` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + Always `file_citation`. - - `JsonValue; type "allowed_tools"constant` + - `FILE_CITATION("file_citation")` - Allowed tool configuration type. Always `allowed_tools`. + - `Optional endIndex` - - `ALLOWED_TOOLS("allowed_tools")` + - `Optional fileCitation` -### Beta Tool Choice Apply Patch + - `Optional fileId` -- `class BetaToolChoiceApplyPatch:` + The ID of the specific File the citation is from. - Forces the model to call the apply_patch tool when executing a tool call. + - `Optional quote` - - `JsonValue; type "apply_patch"constant` + The specific quote in the file. - The tool to call. Always `apply_patch`. + - `Optional startIndex` - - `APPLY_PATCH("apply_patch")` + - `Optional text` -### Beta Tool Choice Custom + The text in the message content that needs to be replaced. -- `class BetaToolChoiceCustom:` + - `class FilePathDeltaAnnotation:` - Use this option to force the model to call a specific custom tool. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `String name` + - `long index` - The name of the custom tool to call. + The index of the annotation in the text content part. - - `JsonValue; type "custom"constant` + - `JsonValue; type "file_path"constant` - For custom tool calling, the type is always `custom`. + Always `file_path`. - - `CUSTOM("custom")` + - `FILE_PATH("file_path")` -### Beta Tool Choice Function + - `Optional endIndex` -- `class BetaToolChoiceFunction:` + - `Optional filePath` - Use this option to force the model to call a specific function. + - `Optional fileId` - - `String name` + The ID of the file that was generated. - The name of the function to call. + - `Optional startIndex` - - `JsonValue; type "function"constant` + - `Optional text` - For function calling, the type is always `function`. + The text in the message content that needs to be replaced. - - `FUNCTION("function")` + - `Optional value` -### Beta Tool Choice Mcp + The data that makes up the text. -- `class BetaToolChoiceMcp:` + - `class RefusalDeltaBlock:` - Use this option to force the model to call a specific tool on a remote MCP server. + The refusal content that is part of a message. - - `String serverLabel` + - `long index` - The label of the MCP server to use. + The index of the refusal part in the message. - - `JsonValue; type "mcp"constant` + - `JsonValue; type "refusal"constant` - For MCP tools, the type is always `mcp`. + Always `refusal`. - - `MCP("mcp")` + - `REFUSAL("refusal")` - - `Optional name` + - `Optional refusal` - The name of the tool to call on the server. + - `class ImageUrlDeltaBlock:` -### Beta Tool Choice Options + References an image URL in the content of a message. -- `enum BetaToolChoiceOptions:` + - `long index` - Controls which (if any) tool is called by the model. + The index of the content part in the message. - `none` means the model will not call any tool and instead generates a message. + - `JsonValue; type "image_url"constant` - `auto` means the model can pick between generating a message or calling one or - more tools. + Always `image_url`. - `required` means the model must call one or more tools. + - `IMAGE_URL("image_url")` - - `NONE("none")` + - `Optional imageUrl` - - `AUTO("auto")` + - `Optional detail` - - `REQUIRED("required")` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. -### Beta Tool Choice Shell + - `AUTO("auto")` -- `class BetaToolChoiceShell:` + - `LOW("low")` - Forces the model to call the shell tool when a tool call is required. + - `HIGH("high")` - - `JsonValue; type "shell"constant` + - `Optional url` - The tool to call. Always `shell`. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `SHELL("shell")` + - `Optional role` -### Beta Tool Choice Types + The entity that produced the message. One of `user` or `assistant`. -- `class BetaToolChoiceTypes:` + - `USER("user")` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `ASSISTANT("assistant")` - - `Type type` + - `JsonValue; object_ "thread.message.delta"constant` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + The object type, which is always `thread.message.delta`. - Allowed values are: + - `THREAD_MESSAGE_DELTA("thread.message.delta")` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `JsonValue; event "thread.message.delta"constant` - - `FILE_SEARCH("file_search")` + - `THREAD_MESSAGE_DELTA("thread.message.delta")` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `ThreadMessageCompleted` - - `COMPUTER("computer")` + - `Message data` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `COMPUTER_USE("computer_use")` + - `JsonValue; event "thread.message.completed"constant` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `THREAD_MESSAGE_COMPLETED("thread.message.completed")` - - `IMAGE_GENERATION("image_generation")` + - `ThreadMessageIncomplete` - - `CODE_INTERPRETER("code_interpreter")` + - `Message data` -### Beta Tool Search Tool + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). -- `class BetaToolSearchTool:` + - `JsonValue; event "thread.message.incomplete"constant` - Hosted or BYOT tool search configuration for deferred tools. + - `THREAD_MESSAGE_INCOMPLETE("thread.message.incomplete")` - - `JsonValue; type "tool_search"constant` +### Run Step Stream Event - The type of the tool. Always `tool_search`. +- `class RunStepStreamEvent: A class that can be one of several variants.union` - - `TOOL_SEARCH("tool_search")` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `Optional description` + - `ThreadRunStepCreated` - Description shown to the model for a client-executed tool search tool. + - `RunStep data` - - `Optional execution` + Represents a step in execution of a run. - Whether tool search is executed by the server or by the client. + - `String id` - - `SERVER("server")` + The identifier of the run step, which can be referenced in API endpoints. - - `CLIENT("client")` + - `String assistantId` - - `Optional parameters` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - Parameter schema for a client-executed tool search tool. + - `Optional cancelledAt` -### Beta Web Search Preview Tool + The Unix timestamp (in seconds) for when the run step was cancelled. -- `class BetaWebSearchPreviewTool:` + - `Optional completedAt` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The Unix timestamp (in seconds) for when the run step completed. - - `Type type` + - `long createdAt` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The Unix timestamp (in seconds) for when the run step was created. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `Optional expiredAt` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `Optional> searchContentTypes` + - `Optional failedAt` - - `TEXT("text")` + The Unix timestamp (in seconds) for when the run step failed. - - `IMAGE("image")` + - `Optional lastError` - - `Optional searchContextSize` + The last error associated with this run step. Will be `null` if there are no errors. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `Code code` - - `LOW("low")` + One of `server_error` or `rate_limit_exceeded`. - - `MEDIUM("medium")` + - `SERVER_ERROR("server_error")` - - `HIGH("high")` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `Optional userLocation` + - `String message` - The user's location. + A human-readable description of the error. - - `JsonValue; type "approximate"constant` + - `Optional metadata` - The type of location approximation. Always `approximate`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `APPROXIMATE("approximate")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Optional city` + - `JsonValue; object_ "thread.run.step"constant` - Free text input for the city of the user, e.g. `San Francisco`. + The object type, which is always `thread.run.step`. - - `Optional country` + - `THREAD_RUN_STEP("thread.run.step")` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `String runId` - - `Optional region` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - Free text input for the region of the user, e.g. `California`. + - `Status status` - - `Optional timezone` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `IN_PROGRESS("in_progress")` -### Beta Web Search Tool + - `CANCELLED("cancelled")` -- `class BetaWebSearchTool:` + - `FAILED("failed")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `COMPLETED("completed")` - - `Type type` + - `EXPIRED("expired")` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `StepDetails stepDetails` - - `WEB_SEARCH("web_search")` + The details of the run step. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `class MessageCreationStepDetails:` - - `Optional filters` + Details of the message creation by the run step. - Filters for the search. + - `MessageCreation messageCreation` - - `Optional> allowedDomains` + - `String messageId` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The ID of the message that was created by this run step. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `JsonValue; type "message_creation"constant` - - `Optional searchContextSize` + Always `message_creation`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `MESSAGE_CREATION("message_creation")` - - `LOW("low")` + - `class ToolCallsStepDetails:` - - `MEDIUM("medium")` + Details of the tool call. - - `HIGH("high")` + - `List toolCalls` - - `Optional userLocation` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The approximate location of the user. + - `class CodeInterpreterToolCall:` - - `Optional city` + Details of the Code Interpreter tool call the run step was involved in. - Free text input for the city of the user, e.g. `San Francisco`. + - `String id` - - `Optional country` + The ID of the tool call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `CodeInterpreter codeInterpreter` - - `Optional region` + The Code Interpreter tool call definition. - Free text input for the region of the user, e.g. `California`. + - `String input` - - `Optional timezone` + The input to the Code Interpreter tool call. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `List outputs` - - `Optional type` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The type of location approximation. Always `approximate`. + - `class LogsOutput:` - - `APPROXIMATE("approximate")` + Text output from the Code Interpreter tool call as part of a run step. -# Input Items + - `String logs` -## List input items + The text output from the Code Interpreter tool call. -`InputItemListPage beta().responses().inputItems().list(InputItemListParamsparams = InputItemListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + - `JsonValue; type "logs"constant` -**get** `/responses/{response_id}/input_items?beta=true` + Always `logs`. -List input items + - `LOGS("logs")` -### Parameters + - `class ImageOutput:` -- `InputItemListParams params` + - `Image image` - - `Optional responseId` + - `String fileId` - - `Optional after` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - An item ID to list items after, used in pagination. + - `JsonValue; type "image"constant` - - `Optional> include` + Always `image`. - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `IMAGE("image")` - - `FILE_SEARCH_CALL_RESULTS("file_search_call.results")` + - `JsonValue; type "code_interpreter"constant` - - `WEB_SEARCH_CALL_RESULTS("web_search_call.results")` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `WEB_SEARCH_CALL_ACTION_SOURCES("web_search_call.action.sources")` + - `CODE_INTERPRETER("code_interpreter")` - - `MESSAGE_INPUT_IMAGE_IMAGE_URL("message.input_image.image_url")` + - `class FileSearchToolCall:` - - `COMPUTER_CALL_OUTPUT_OUTPUT_IMAGE_URL("computer_call_output.output.image_url")` + - `String id` - - `CODE_INTERPRETER_CALL_OUTPUTS("code_interpreter_call.outputs")` + The ID of the tool call object. - - `REASONING_ENCRYPTED_CONTENT("reasoning.encrypted_content")` + - `FileSearch fileSearch` - - `MESSAGE_OUTPUT_TEXT_LOGPROBS("message.output_text.logprobs")` + For now, this is always going to be an empty object. - - `Optional limit` + - `Optional rankingOptions` - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. + The ranking options for the file search. - - `Optional order` + - `Ranker ranker` - The order to return the input items in. Default is `desc`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. + - `AUTO("auto")` - - `ASC("asc")` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `DESC("desc")` + - `double scoreThreshold` - - `Optional> betas` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + - `Optional> results` -### Returns + The results of the file search. -- `class BetaResponseItem: A class that can be one of several variants.union` + - `String fileId` - Content item used to generate a response. + The ID of the file that result was found in. - - `class BetaResponseInputMessageItem:` + - `String fileName` - - `String id` + The name of the file that result was found in. - The unique ID of the message input. + - `double score` - - `List content` + The score of the result. All values must be a floating point number between 0 and 1. - A list of one or many input items to the model, containing different content - types. + - `Optional> content` - - `class BetaResponseInputText:` + The content of the result that was found. The content is only included if requested via the include query parameter. - A text input to the model. + - `Optional text` - - `String text` + The text content of the file. - The text input to the model. + - `Optional type` - - `JsonValue; type "input_text"constant` + The type of the content. - The type of the input item. Always `input_text`. + - `TEXT("text")` - - `INPUT_TEXT("input_text")` + - `JsonValue; type "file_search"constant` - - `Optional promptCacheBreakpoint` + The type of tool call. This is always going to be `file_search` for this type of tool call. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `FILE_SEARCH("file_search")` - - `JsonValue; mode "explicit"constant` + - `class FunctionToolCall:` - The breakpoint mode. Always `explicit`. + - `String id` - - `EXPLICIT("explicit")` + The ID of the tool call object. - - `class BetaResponseInputImage:` + - `Function function` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The definition of the function that was called. - - `Detail detail` + - `String arguments` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The arguments passed to the function. - - `LOW("low")` + - `String name` - - `HIGH("high")` + The name of the function. - - `AUTO("auto")` + - `Optional output` - - `ORIGINAL("original")` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `JsonValue; type "input_image"constant` + - `JsonValue; type "function"constant` - The type of the input item. Always `input_image`. + The type of tool call. This is always going to be `function` for this type of tool call. - - `INPUT_IMAGE("input_image")` + - `FUNCTION("function")` - - `Optional fileId` + - `JsonValue; type "tool_calls"constant` - The ID of the file to be sent to the model. + Always `tool_calls`. - - `Optional imageUrl` + - `TOOL_CALLS("tool_calls")` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `String threadId` - - `Optional promptCacheBreakpoint` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Type type` - - `JsonValue; mode "explicit"constant` + The type of run step, which can be either `message_creation` or `tool_calls`. - The breakpoint mode. Always `explicit`. + - `MESSAGE_CREATION("message_creation")` - - `EXPLICIT("explicit")` + - `TOOL_CALLS("tool_calls")` - - `class BetaResponseInputFile:` + - `Optional usage` - A file input to the model. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `JsonValue; type "input_file"constant` + - `long completionTokens` - The type of the input item. Always `input_file`. + Number of completion tokens used over the course of the run step. - - `INPUT_FILE("input_file")` + - `long promptTokens` - - `Optional detail` + Number of prompt tokens used over the course of the run step. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `long totalTokens` - - `AUTO("auto")` + Total number of tokens used (prompt + completion). - - `LOW("low")` + - `JsonValue; event "thread.run.step.created"constant` - - `HIGH("high")` + - `THREAD_RUN_STEP_CREATED("thread.run.step.created")` - - `Optional fileData` + - `ThreadRunStepInProgress` - The content of the file to be sent to the model. + - `RunStep data` - - `Optional fileId` + Represents a step in execution of a run. - The ID of the file to be sent to the model. + - `JsonValue; event "thread.run.step.in_progress"constant` - - `Optional fileUrl` + - `THREAD_RUN_STEP_IN_PROGRESS("thread.run.step.in_progress")` - The URL of the file to be sent to the model. + - `ThreadRunStepDelta` - - `Optional filename` + - `RunStepDeltaEvent data` - The name of the file to be sent to the model. + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `Optional promptCacheBreakpoint` + - `String id` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The identifier of the run step, which can be referenced in API endpoints. - - `JsonValue; mode "explicit"constant` + - `RunStepDelta delta` - The breakpoint mode. Always `explicit`. + The delta containing the fields that have changed on the run step. - - `EXPLICIT("explicit")` + - `Optional stepDetails` - - `Role role` + The details of the run step. - The role of the message input. One of `user`, `system`, or `developer`. + - `class RunStepDeltaMessageDelta:` - - `USER("user")` + Details of the message creation by the run step. - - `SYSTEM("system")` + - `JsonValue; type "message_creation"constant` - - `DEVELOPER("developer")` + Always `message_creation`. - - `JsonValue; type "message"constant` + - `MESSAGE_CREATION("message_creation")` - The type of the message input. Always set to `message`. + - `Optional messageCreation` - - `MESSAGE("message")` + - `Optional messageId` - - `Optional agent` + The ID of the message that was created by this run step. - The agent that produced this item. + - `class ToolCallDeltaObject:` - - `String agentName` + Details of the tool call. - The canonical name of the agent that produced this item. + - `JsonValue; type "tool_calls"constant` - - `Optional status` + Always `tool_calls`. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `TOOL_CALLS("tool_calls")` - - `IN_PROGRESS("in_progress")` + - `Optional> toolCalls` - - `COMPLETED("completed")` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `INCOMPLETE("incomplete")` + - `class CodeInterpreterToolCallDelta:` - - `class BetaResponseOutputMessage:` + Details of the Code Interpreter tool call the run step was involved in. - An output message from the model. + - `long index` - - `String id` + The index of the tool call in the tool calls array. - The unique ID of the output message. + - `JsonValue; type "code_interpreter"constant` - - `List content` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The content of the output message. + - `CODE_INTERPRETER("code_interpreter")` - - `class BetaResponseOutputText:` + - `Optional id` - A text output from the model. + The ID of the tool call. - - `List annotations` + - `Optional codeInterpreter` - The annotations of the text output. + The Code Interpreter tool call definition. - - `class FileCitation:` + - `Optional input` - A citation to a file. + The input to the Code Interpreter tool call. - - `String fileId` + - `Optional> outputs` - The ID of the file. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `String filename` + - `class CodeInterpreterLogs:` - The filename of the file cited. + Text output from the Code Interpreter tool call as part of a run step. - `long index` - The index of the file in the list of files. + The index of the output in the outputs array. - - `JsonValue; type "file_citation"constant` + - `JsonValue; type "logs"constant` - The type of the file citation. Always `file_citation`. + Always `logs`. - - `FILE_CITATION("file_citation")` + - `LOGS("logs")` - - `class UrlCitation:` + - `Optional logs` - A citation for a web resource used to generate a model response. + The text output from the Code Interpreter tool call. - - `long endIndex` + - `class CodeInterpreterOutputImage:` - The index of the last character of the URL citation in the message. + - `long index` - - `long startIndex` + The index of the output in the outputs array. - The index of the first character of the URL citation in the message. + - `JsonValue; type "image"constant` - - `String title` + Always `image`. - The title of the web resource. + - `IMAGE("image")` - - `JsonValue; type "url_citation"constant` + - `Optional image` - The type of the URL citation. Always `url_citation`. + - `Optional fileId` - - `URL_CITATION("url_citation")` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `String url` + - `class FileSearchToolCallDelta:` - The URL of the web resource. + - `JsonValue fileSearch` - - `class ContainerFileCitation:` + For now, this is always going to be an empty object. - A citation for a container file used to generate a model response. + - `long index` - - `String containerId` + The index of the tool call in the tool calls array. - The ID of the container file. + - `JsonValue; type "file_search"constant` - - `long endIndex` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The index of the last character of the container file citation in the message. + - `FILE_SEARCH("file_search")` - - `String fileId` + - `Optional id` - The ID of the file. + The ID of the tool call object. - - `String filename` + - `class FunctionToolCallDelta:` - The filename of the container file cited. + - `long index` - - `long startIndex` + The index of the tool call in the tool calls array. - The index of the first character of the container file citation in the message. + - `JsonValue; type "function"constant` - - `JsonValue; type "container_file_citation"constant` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the container file citation. Always `container_file_citation`. + - `FUNCTION("function")` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `Optional id` - - `class FilePath:` + The ID of the tool call object. - A path to a file. + - `Optional function` - - `String fileId` + The definition of the function that was called. - The ID of the file. + - `Optional arguments` - - `long index` + The arguments passed to the function. - The index of the file in the list of files. + - `Optional name` - - `JsonValue; type "file_path"constant` + The name of the function. - The type of the file path. Always `file_path`. + - `Optional output` - - `FILE_PATH("file_path")` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `String text` + - `JsonValue; object_ "thread.run.step.delta"constant` - The text output from the model. + The object type, which is always `thread.run.step.delta`. - - `JsonValue; type "output_text"constant` + - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` - The type of the output text. Always `output_text`. + - `JsonValue; event "thread.run.step.delta"constant` - - `OUTPUT_TEXT("output_text")` + - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` - - `Optional> logprobs` + - `ThreadRunStepCompleted` - - `String token` + - `RunStep data` - - `List bytes` + Represents a step in execution of a run. - - `double logprob` + - `JsonValue; event "thread.run.step.completed"constant` - - `List topLogprobs` + - `THREAD_RUN_STEP_COMPLETED("thread.run.step.completed")` - - `String token` + - `ThreadRunStepFailed` - - `List bytes` + - `RunStep data` - - `double logprob` + Represents a step in execution of a run. - - `class BetaResponseOutputRefusal:` + - `JsonValue; event "thread.run.step.failed"constant` - A refusal from the model. + - `THREAD_RUN_STEP_FAILED("thread.run.step.failed")` - - `String refusal` + - `ThreadRunStepCancelled` - The refusal explanation from the model. + - `RunStep data` - - `JsonValue; type "refusal"constant` + Represents a step in execution of a run. - The type of the refusal. Always `refusal`. + - `JsonValue; event "thread.run.step.cancelled"constant` - - `REFUSAL("refusal")` + - `THREAD_RUN_STEP_CANCELLED("thread.run.step.cancelled")` - - `JsonValue; role "assistant"constant` + - `ThreadRunStepExpired` - The role of the output message. Always `assistant`. + - `RunStep data` - - `ASSISTANT("assistant")` + Represents a step in execution of a run. - - `Status status` + - `JsonValue; event "thread.run.step.expired"constant` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `THREAD_RUN_STEP_EXPIRED("thread.run.step.expired")` - - `IN_PROGRESS("in_progress")` +### Run Stream Event - - `COMPLETED("completed")` +- `class RunStreamEvent: A class that can be one of several variants.union` - - `INCOMPLETE("incomplete")` + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - `JsonValue; type "message"constant` + - `ThreadRunCreated` - The type of the output message. Always `message`. + - `Run data` - - `MESSAGE("message")` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `Optional agent` + - `String id` - The agent that produced this item. + The identifier, which can be referenced in API endpoints. - - `String agentName` + - `String assistantId` - The canonical name of the agent that produced this item. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `Optional phase` + - `Optional cancelledAt` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The Unix timestamp (in seconds) for when the run was cancelled. - - `COMMENTARY("commentary")` + - `Optional completedAt` - - `class BetaResponseFileSearchToolCall:` + The Unix timestamp (in seconds) for when the run was completed. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `long createdAt` - - `String id` + The Unix timestamp (in seconds) for when the run was created. - The unique ID of the file search tool call. + - `Optional expiresAt` - - `List queries` + The Unix timestamp (in seconds) for when the run will expire. - The queries used to search for files. + - `Optional failedAt` - - `Status status` + The Unix timestamp (in seconds) for when the run failed. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `Optional incompleteDetails` - - `IN_PROGRESS("in_progress")` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `SEARCHING("searching")` + - `Optional reason` - - `COMPLETED("completed")` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `INCOMPLETE("incomplete")` + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `FAILED("failed")` + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - - `JsonValue; type "file_search_call"constant` + - `String instructions` - The type of the file search tool call. Always `file_search_call`. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `FILE_SEARCH_CALL("file_search_call")` + - `Optional lastError` - - `Optional agent` + The last error associated with this run. Will be `null` if there are no errors. - The agent that produced this item. + - `Code code` - - `String agentName` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The canonical name of the agent that produced this item. + - `SERVER_ERROR("server_error")` - - `Optional> results` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The results of the file search tool call. + - `INVALID_PROMPT("invalid_prompt")` - - `Optional attributes` + - `String message` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + A human-readable description of the error. - - `String` + - `Optional maxCompletionTokens` - - `double` + The maximum number of completion tokens specified to have been used over the course of the run. - - `boolean` + - `Optional maxPromptTokens` - - `Optional fileId` + The maximum number of prompt tokens specified to have been used over the course of the run. - The unique ID of the file. + - `Optional metadata` - - `Optional filename` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The name of the file. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Optional score` + - `String model` - The relevance score of the file - a value between 0 and 1. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `Optional text` + - `JsonValue; object_ "thread.run"constant` - The text that was retrieved from the file. + The object type, which is always `thread.run`. - - `class BetaResponseComputerToolCall:` + - `THREAD_RUN("thread.run")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `boolean parallelToolCalls` - - `String id` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The unique ID of the computer call. + - `Optional requiredAction` - - `String callId` + Details on the action required to continue the run. Will be `null` if no action is required. - An identifier used when responding to the tool call with output. + - `SubmitToolOutputs submitToolOutputs` - - `List pendingSafetyChecks` + Details on the tool outputs needed for this run to continue. - The pending safety checks for the computer call. + - `List toolCalls` - - `String id` + A list of the relevant tool calls. - The ID of the pending safety check. + - `String id` - - `Optional code` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - The type of the pending safety check. + - `Function function` - - `Optional message` + The function definition. - Details about the pending safety check. + - `String arguments` - - `Status status` + The arguments that the model expects you to pass to the function. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `String name` - - `IN_PROGRESS("in_progress")` + The name of the function. - - `COMPLETED("completed")` + - `JsonValue; type "function"constant` - - `INCOMPLETE("incomplete")` + The type of tool call the output is required for. For now, this is always `function`. - - `Type type` + - `FUNCTION("function")` - The type of the computer call. Always `computer_call`. + - `JsonValue; type "submit_tool_outputs"constant` - - `COMPUTER_CALL("computer_call")` + For now, this is always `submit_tool_outputs`. - - `Optional action` + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - A click action. + - `Optional responseFormat` - - `Click` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `Button button` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `LEFT("left")` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `RIGHT("right")` + - `JsonValue;` - - `WHEEL("wheel")` + - `AUTO("auto")` - - `BACK("back")` + - `class ResponseFormatText:` - - `FORWARD("forward")` + Default response format. Used to generate text responses. - - `JsonValue; type "click"constant` + - `JsonValue; type "text"constant` - Specifies the event type. For a click action, this property is always `click`. + The type of response format being defined. Always `text`. - - `CLICK("click")` + - `TEXT("text")` - - `long x` + - `class ResponseFormatJsonObject:` - The x-coordinate where the click occurred. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `long y` + - `JsonValue; type "json_object"constant` - The y-coordinate where the click occurred. + The type of response format being defined. Always `json_object`. - - `Optional> keys` + - `JSON_OBJECT("json_object")` - The keys being held while clicking. + - `class ResponseFormatJsonSchema:` - - `DoubleClick` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional> keys` + - `JsonSchema jsonSchema` - The keys being held while double-clicking. + Structured Outputs configuration options, including a JSON Schema. - - `JsonValue; type "double_click"constant` + - `String name` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `DOUBLE_CLICK("double_click")` + - `Optional description` - - `long x` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The x-coordinate where the double click occurred. + - `Optional schema` - - `long y` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The y-coordinate where the double click occurred. + - `Optional strict` - - `Drag` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `List path` + - `JsonValue; type "json_schema"constant` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The type of response format being defined. Always `json_schema`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `JSON_SCHEMA("json_schema")` - - `long x` + - `Optional startedAt` - The x-coordinate. + The Unix timestamp (in seconds) for when the run was started. - - `long y` + - `RunStatus status` - The y-coordinate. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `JsonValue; type "drag"constant` + - `QUEUED("queued")` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `IN_PROGRESS("in_progress")` - - `DRAG("drag")` + - `REQUIRES_ACTION("requires_action")` - - `Optional> keys` + - `CANCELLING("cancelling")` - The keys being held while dragging the mouse. + - `CANCELLED("cancelled")` - - `Keypress` + - `FAILED("failed")` - - `List keys` + - `COMPLETED("completed")` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "keypress"constant` + - `EXPIRED("expired")` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `String threadId` - - `KEYPRESS("keypress")` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `Move` + - `Optional toolChoice` - - `JsonValue; type "move"constant` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - Specifies the event type. For a move action, this property is always set to `move`. + - `Auto` - - `MOVE("move")` + - `NONE("none")` - - `long x` + - `AUTO("auto")` - The x-coordinate to move to. + - `REQUIRED("required")` - - `long y` + - `class AssistantToolChoice:` - The y-coordinate to move to. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `Optional> keys` + - `Type type` - The keys being held while moving the mouse. + The type of the tool. If type is `function`, the function name must be set - - `JsonValue;` + - `FUNCTION("function")` - - `JsonValue; type "screenshot"constant` + - `CODE_INTERPRETER("code_interpreter")` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `FILE_SEARCH("file_search")` - - `SCREENSHOT("screenshot")` + - `Optional function` - - `Scroll` + - `String name` - - `long scrollX` + The name of the function to call. - The horizontal scroll distance. + - `List tools` - - `long scrollY` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The vertical scroll distance. + - `class CodeInterpreterTool:` - - `JsonValue; type "scroll"constant` + - `JsonValue; type "code_interpreter"constant` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The type of tool being defined: `code_interpreter` - - `SCROLL("scroll")` + - `CODE_INTERPRETER("code_interpreter")` - - `long x` + - `class FileSearchTool:` - The x-coordinate where the scroll occurred. + - `JsonValue; type "file_search"constant` - - `long y` + The type of tool being defined: `file_search` - The y-coordinate where the scroll occurred. + - `FILE_SEARCH("file_search")` - - `Optional> keys` + - `Optional fileSearch` - The keys being held while scrolling. + Overrides for the file search tool. - - `Type` + - `Optional maxNumResults` - - `String text` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The text to type. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `JsonValue; type "type"constant` + - `Optional rankingOptions` - Specifies the event type. For a type action, this property is always set to `type`. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `TYPE("type")` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `JsonValue;` + - `double scoreThreshold` - - `JsonValue; type "wait"constant` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `Optional ranker` - - `WAIT("wait")` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `Optional> actions` + - `AUTO("auto")` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `Click` + - `class FunctionTool:` - - `DoubleClick` + - `FunctionDefinition function` - - `Drag` + - `String name` - - `Keypress` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `Move` + - `Optional description` - - `JsonValue;` + A description of what the function does, used by the model to choose when and how to call the function. - - `Scroll` + - `Optional parameters` - - `Type` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `JsonValue;` + Omitting `parameters` defines a function with an empty parameter list. - - `Optional agent` + - `Optional strict` - The agent that produced this item. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `String agentName` + - `JsonValue; type "function"constant` - The canonical name of the agent that produced this item. + The type of tool being defined: `function` - - `class BetaResponseComputerToolCallOutputItem:` + - `FUNCTION("function")` - - `String id` + - `Optional truncationStrategy` - The unique ID of the computer call tool output. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `String callId` + - `Type type` - The ID of the computer tool call that produced the output. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `BetaResponseComputerToolCallOutputScreenshot output` + - `AUTO("auto")` - A computer screenshot image used with the computer use tool. + - `LAST_MESSAGES("last_messages")` - - `JsonValue; type "computer_screenshot"constant` + - `Optional lastMessages` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The number of most recent messages from the thread when constructing the context for the run. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `Optional usage` - - `Optional fileId` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The identifier of an uploaded file that contains the screenshot. + - `long completionTokens` - - `Optional imageUrl` + Number of completion tokens used over the course of the run. - The URL of the screenshot image. + - `long promptTokens` - - `Status status` + Number of prompt tokens used over the course of the run. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `long totalTokens` - - `COMPLETED("completed")` + Total number of tokens used (prompt + completion). - - `INCOMPLETE("incomplete")` + - `Optional temperature` - - `FAILED("failed")` + The sampling temperature used for this run. If not set, defaults to 1. - - `IN_PROGRESS("in_progress")` + - `Optional topP` - - `JsonValue; type "computer_call_output"constant` + The nucleus sampling value used for this run. If not set, defaults to 1. - The type of the computer tool call output. Always `computer_call_output`. + - `JsonValue; event "thread.run.created"constant` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `THREAD_RUN_CREATED("thread.run.created")` - - `Optional> acknowledgedSafetyChecks` + - `ThreadRunQueued` - The safety checks reported by the API that have been acknowledged by the - developer. + - `Run data` - - `String id` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The ID of the pending safety check. + - `JsonValue; event "thread.run.queued"constant` - - `Optional code` + - `THREAD_RUN_QUEUED("thread.run.queued")` - The type of the pending safety check. + - `ThreadRunInProgress` - - `Optional message` + - `Run data` - Details about the pending safety check. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `Optional agent` + - `JsonValue; event "thread.run.in_progress"constant` - The agent that produced this item. + - `THREAD_RUN_IN_PROGRESS("thread.run.in_progress")` - - `String agentName` + - `ThreadRunRequiresAction` - The canonical name of the agent that produced this item. + - `Run data` - - `Optional createdBy` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The identifier of the actor that created the item. + - `JsonValue; event "thread.run.requires_action"constant` - - `class BetaResponseFunctionWebSearch:` + - `THREAD_RUN_REQUIRES_ACTION("thread.run.requires_action")` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `ThreadRunCompleted` - - `String id` + - `Run data` - The unique ID of the web search tool call. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `Action action` + - `JsonValue; event "thread.run.completed"constant` - 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). + - `THREAD_RUN_COMPLETED("thread.run.completed")` - - `class Search:` + - `ThreadRunIncomplete` - Action type "search" - Performs a web search query. + - `Run data` - - `JsonValue; type "search"constant` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The action type. + - `JsonValue; event "thread.run.incomplete"constant` - - `SEARCH("search")` + - `THREAD_RUN_INCOMPLETE("thread.run.incomplete")` - - `Optional> queries` + - `ThreadRunFailed` - The search queries. + - `Run data` - - `Optional query` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The search query. + - `JsonValue; event "thread.run.failed"constant` - - `Optional> sources` + - `THREAD_RUN_FAILED("thread.run.failed")` - The sources used in the search. + - `ThreadRunCancelling` - - `JsonValue; type "url"constant` + - `Run data` - The type of source. Always `url`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `URL("url")` + - `JsonValue; event "thread.run.cancelling"constant` - - `String url` + - `THREAD_RUN_CANCELLING("thread.run.cancelling")` - The URL of the source. + - `ThreadRunCancelled` - - `class OpenPage:` + - `Run data` - Action type "open_page" - Opens a specific URL from search results. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `JsonValue; type "open_page"constant` + - `JsonValue; event "thread.run.cancelled"constant` - The action type. + - `THREAD_RUN_CANCELLED("thread.run.cancelled")` - - `OPEN_PAGE("open_page")` + - `ThreadRunExpired` - - `Optional url` + - `Run data` - The URL opened by the model. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class FindInPage:` + - `JsonValue; event "thread.run.expired"constant` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `THREAD_RUN_EXPIRED("thread.run.expired")` - - `String pattern` +### Thread Stream Event - The pattern or text to search for within the page. +- `class ThreadStreamEvent:` - - `JsonValue; type "find_in_page"constant` + Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - The action type. + - `Thread data` - - `FIND_IN_PAGE("find_in_page")` + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `String url` + - `String id` - The URL of the page searched for the pattern. + The identifier, which can be referenced in API endpoints. - - `Status status` + - `long createdAt` - The status of the web search tool call. + The Unix timestamp (in seconds) for when the thread was created. - - `IN_PROGRESS("in_progress")` + - `Optional metadata` - - `SEARCHING("searching")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `COMPLETED("completed")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `FAILED("failed")` + - `JsonValue; object_ "thread"constant` - - `JsonValue; type "web_search_call"constant` + The object type, which is always `thread`. - The type of the web search tool call. Always `web_search_call`. + - `THREAD("thread")` - - `WEB_SEARCH_CALL("web_search_call")` + - `Optional toolResources` - - `Optional agent` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The agent that produced this item. + - `Optional codeInterpreter` - - `String agentName` + - `Optional> fileIds` - The canonical name of the agent that produced this item. + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `class BetaResponseFunctionToolCallItem:` + - `Optional fileSearch` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `Optional> vectorStoreIds` - - `String id` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - The unique ID of the function tool call. + - `JsonValue; event "thread.created"constant` - - `Status status` + - `THREAD_CREATED("thread.created")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional enabled` - - `IN_PROGRESS("in_progress")` + Whether to enable input audio transcription. - - `COMPLETED("completed")` +# Threads - - `INCOMPLETE("incomplete")` +## Create thread - - `Optional createdBy` +`Thread beta().threads().create(ThreadCreateParamsparams = ThreadCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - The identifier of the actor that created the item. +**post** `/threads` - - `class BetaResponseFunctionToolCallOutputItem:` +Create a thread. - - `String id` +### Parameters - The unique ID of the function call tool output. +- `ThreadCreateParams params` - - `String callId` + - `Optional> messages` - The unique ID of the function tool call generated by the model. + A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. - - `Output output` + - `Content content` - The output from the function call generated by your code. - Can be a string or an list of output content. + The text contents of the message. - `String` - - `List` + - `List` - - `class BetaResponseInputText:` + - `class ImageFileContentBlock:` - A text input to the model. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `class BetaResponseInputImage:` + - `ImageFile imageFile` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `String fileId` - - `class BetaResponseInputFile:` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - A file input to the model. + - `Optional detail` - - `Status status` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `AUTO("auto")` - - `IN_PROGRESS("in_progress")` + - `LOW("low")` - - `COMPLETED("completed")` + - `HIGH("high")` - - `INCOMPLETE("incomplete")` + - `JsonValue; type "image_file"constant` - - `JsonValue; type "function_call_output"constant` + Always `image_file`. - The type of the function tool call output. Always `function_call_output`. + - `IMAGE_FILE("image_file")` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + - `class ImageUrlContentBlock:` - - `Optional agent` + References an image URL in the content of a message. - The agent that produced this item. + - `ImageUrl imageUrl` - - `String agentName` + - `String url` - The canonical name of the agent that produced this item. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `Optional caller` + - `Optional detail` - The execution context that produced this tool call. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `JsonValue;` + - `AUTO("auto")` - - `JsonValue; type "direct"constant` + - `LOW("low")` - The caller type. Always `direct`. + - `HIGH("high")` - - `DIRECT("direct")` + - `JsonValue; type "image_url"constant` - - `class Program:` + The type of the content part. - - `String callerId` + - `IMAGE_URL("image_url")` - The call ID of the program item that produced this tool call. + - `class TextContentBlockParam:` - - `JsonValue; type "program"constant` + The text content that is part of a message. - The caller type. Always `program`. + - `String text` - - `PROGRAM("program")` + Text content to be sent to the model - - `Optional createdBy` + - `JsonValue; type "text"constant` - The identifier of the actor that created the item. + Always `text`. - - `AgentMessage` + - `TEXT("text")` - - `String id` + - `Role role` - The unique ID of the agent message. + The role of the entity that is creating the message. Allowed values include: - - `String author` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - The sending agent identity. + - `USER("user")` - - `List content` + - `ASSISTANT("assistant")` - Encrypted content sent between agents. + - `Optional> attachments` - - `class BetaResponseInputText:` + A list of files attached to the message, and the tools they should be added to. - A text input to the model. + - `Optional fileId` - - `class BetaResponseOutputText:` + The ID of the file to attach to the message. - A text output from the model. + - `Optional> tools` - - `class Text:` + The tools to add this file to. - A text content. + - `class CodeInterpreterTool:` - - `String text` + - `JsonValue; type "code_interpreter"constant` - - `JsonValue; type "text"constant` + The type of tool being defined: `code_interpreter` - - `TEXT("text")` + - `CODE_INTERPRETER("code_interpreter")` - - `class SummaryText:` + - `JsonValue;` - A summary text from the model. + - `JsonValue; type "file_search"constant` - - `String text` + The type of tool being defined: `file_search` - A summary of the reasoning output from the model so far. + - `FILE_SEARCH("file_search")` - - `JsonValue; type "summary_text"constant` + - `Optional metadata` - The type of the object. Always `summary_text`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `SUMMARY_TEXT("summary_text")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class ReasoningText:` + - `Optional metadata` - Reasoning text from the model. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `String text` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The reasoning text from the model. + - `Optional toolResources` - - `JsonValue; type "reasoning_text"constant` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The type of the reasoning text. Always `reasoning_text`. + - `Optional codeInterpreter` - - `REASONING_TEXT("reasoning_text")` + - `Optional> fileIds` - - `class BetaResponseOutputRefusal:` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - A refusal from the model. + - `Optional fileSearch` - - `class BetaResponseInputImage:` + - `Optional> vectorStoreIds` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `class ComputerScreenshot:` + - `Optional> vectorStores` - A screenshot of a computer. + A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. - - `Detail detail` + - `Optional chunkingStrategy` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `LOW("low")` + - `JsonValue;` - - `HIGH("high")` + - `JsonValue; type "auto"constant` + + Always `auto`. - `AUTO("auto")` - - `ORIGINAL("original")` + - `class Static:` - - `Optional fileId` + - `InnerStatic static_` - The identifier of an uploaded file that contains the screenshot. + - `long chunkOverlapTokens` - - `Optional imageUrl` + The number of tokens that overlap between chunks. The default value is `400`. - The URL of the screenshot image. + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `JsonValue; type "computer_screenshot"constant` + - `long maxChunkSizeTokens` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `JsonValue; type "static"constant` - - `Optional promptCacheBreakpoint` + Always `static`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `STATIC("static")` - - `JsonValue; mode "explicit"constant` + - `Optional> fileIds` - The breakpoint mode. Always `explicit`. + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. - - `EXPLICIT("explicit")` + - `Optional metadata` - - `class BetaResponseInputFile:` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - A file input to the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class EncryptedContent:` +### Returns - Opaque encrypted content that Responses API decrypts inside trusted model execution. +- `class Thread:` - - `String encryptedContent` + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - Opaque encrypted content. + - `String id` - - `JsonValue; type "encrypted_content"constant` + The identifier, which can be referenced in API endpoints. - The type of the input item. Always `encrypted_content`. + - `long createdAt` - - `ENCRYPTED_CONTENT("encrypted_content")` + The Unix timestamp (in seconds) for when the thread was created. - - `String recipient` + - `Optional metadata` - The destination agent identity. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `JsonValue; type "agent_message"constant` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the item. Always `agent_message`. + - `JsonValue; object_ "thread"constant` - - `AGENT_MESSAGE("agent_message")` + The object type, which is always `thread`. - - `Optional agent` + - `THREAD("thread")` - The agent that produced this item. + - `Optional toolResources` - - `String agentName` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The canonical name of the agent that produced this item. + - `Optional codeInterpreter` - - `MultiAgentCall` + - `Optional> fileIds` - - `String id` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - The unique ID of the multi-agent call item. + - `Optional fileSearch` - - `Action action` + - `Optional> vectorStoreIds` - The multi-agent action to execute. + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `SPAWN_AGENT("spawn_agent")` +### Example - - `INTERRUPT_AGENT("interrupt_agent")` +```java +package com.openai.example; - - `LIST_AGENTS("list_agents")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.Thread; +import com.openai.models.beta.threads.ThreadCreateParams; - - `SEND_MESSAGE("send_message")` +public final class Main { + private Main() {} - - `FOLLOWUP_TASK("followup_task")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `WAIT_AGENT("wait_agent")` + Thread thread = client.beta().threads().create(); + } +} +``` - - `String arguments` +#### Response - The JSON string of arguments generated for the action. +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - - `String callId` +## Create thread and run - The unique ID linking this call to its output. +`Run beta().threads().createAndRun(ThreadCreateAndRunParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `JsonValue; type "multi_agent_call"constant` +**post** `/threads/runs` - The type of the multi-agent call. Always `multi_agent_call`. +Create a thread and run it in one request. - - `MULTI_AGENT_CALL("multi_agent_call")` +### Parameters - - `Optional agent` +- `ThreadCreateAndRunParams params` - The agent that produced this item. + - `String assistantId` - - `String agentName` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - The canonical name of the agent that produced this item. + - `Optional instructions` - - `MultiAgentCallOutput` + Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. - - `String id` + - `Optional maxCompletionTokens` - The unique ID of the multi-agent call output item. + The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `Action action` + - `Optional maxPromptTokens` - The multi-agent action that produced this result. + The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `SPAWN_AGENT("spawn_agent")` + - `Optional metadata` - - `INTERRUPT_AGENT("interrupt_agent")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `LIST_AGENTS("list_agents")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `SEND_MESSAGE("send_message")` + - `Optional model` - - `FOLLOWUP_TASK("followup_task")` + The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - - `WAIT_AGENT("wait_agent")` + - `Optional parallelToolCalls` - - `String callId` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The unique ID of the multi-agent call. + - `Optional responseFormat` - - `List output` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - Text output returned by the multi-agent action. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `List annotations` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The annotations of the text output. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `String text` + - `Optional temperature` - The text output from the model. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `JsonValue; type "output_text"constant` + - `Optional thread` - The type of the output text. Always `output_text`. + Options to create a new thread. If no thread is provided when running a + request, an empty thread will be created. - - `Optional> logprobs` + - `Optional> messages` - - `JsonValue; type "multi_agent_call_output"constant` + A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `Content content` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + The text contents of the message. - - `Optional agent` + - `String` - The agent that produced this item. + - `List` - - `String agentName` + - `class ImageFileContentBlock:` - The canonical name of the agent that produced this item. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `class BetaResponseToolSearchCall:` + - `ImageFile imageFile` - - `String id` + - `String fileId` - The unique ID of the tool search call item. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `JsonValue arguments` + - `Optional detail` - Arguments used for the tool search call. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `Optional callId` + - `AUTO("auto")` - The unique ID of the tool search call generated by the model. + - `LOW("low")` - - `Execution execution` + - `HIGH("high")` - Whether tool search was executed by the server or by the client. + - `JsonValue; type "image_file"constant` - - `SERVER("server")` + Always `image_file`. - - `CLIENT("client")` + - `IMAGE_FILE("image_file")` - - `Status status` + - `class ImageUrlContentBlock:` - The status of the tool search call item that was recorded. + References an image URL in the content of a message. - - `IN_PROGRESS("in_progress")` + - `ImageUrl imageUrl` - - `COMPLETED("completed")` + - `String url` - - `INCOMPLETE("incomplete")` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `JsonValue; type "tool_search_call"constant` + - `Optional detail` - The type of the item. Always `tool_search_call`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `AUTO("auto")` - - `Optional agent` + - `LOW("low")` - The agent that produced this item. + - `HIGH("high")` - - `String agentName` + - `JsonValue; type "image_url"constant` - The canonical name of the agent that produced this item. + The type of the content part. - - `Optional createdBy` + - `IMAGE_URL("image_url")` - The identifier of the actor that created the item. + - `class TextContentBlockParam:` - - `class BetaResponseToolSearchOutputItem:` + The text content that is part of a message. - - `String id` + - `String text` - The unique ID of the tool search output item. + Text content to be sent to the model - - `Optional callId` + - `JsonValue; type "text"constant` - The unique ID of the tool search call generated by the model. + Always `text`. - - `Execution execution` + - `TEXT("text")` - Whether tool search was executed by the server or by the client. + - `Role role` - - `SERVER("server")` + The role of the entity that is creating the message. Allowed values include: - - `CLIENT("client")` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - - `Status status` + - `USER("user")` - The status of the tool search output item that was recorded. + - `ASSISTANT("assistant")` - - `IN_PROGRESS("in_progress")` + - `Optional> attachments` - - `COMPLETED("completed")` + A list of files attached to the message, and the tools they should be added to. - - `INCOMPLETE("incomplete")` + - `Optional fileId` - - `List tools` + The ID of the file to attach to the message. - The loaded tool definitions returned by tool search. + - `Optional> tools` - - `class BetaFunctionTool:` + The tools to add this file to. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `class CodeInterpreterTool:` - - `String name` + - `JsonValue; type "code_interpreter"constant` - The name of the function to call. + The type of tool being defined: `code_interpreter` - - `Optional parameters` + - `CODE_INTERPRETER("code_interpreter")` - A JSON schema object describing the parameters of the function. + - `JsonValue;` - - `Optional strict` + - `JsonValue; type "file_search"constant` - Whether strict parameter validation is enforced for this function tool. + The type of tool being defined: `file_search` - - `JsonValue; type "function"constant` + - `FILE_SEARCH("file_search")` - The type of the function tool. Always `function`. + - `Optional metadata` - - `FUNCTION("function")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Optional> allowedCallers` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The tool invocation context(s). + - `Optional metadata` - - `DIRECT("direct")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `PROGRAMMATIC("programmatic")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Optional deferLoading` + - `Optional toolResources` - Whether this function is deferred and loaded via tool search. + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `Optional description` + - `Optional codeInterpreter` - A description of the function. Used by the model to determine whether or not to call the function. + - `Optional> fileIds` - - `Optional outputSchema` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `Optional fileSearch` - - `class BetaFileSearchTool:` + - `Optional> vectorStoreIds` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `JsonValue; type "file_search"constant` + - `Optional> vectorStores` - The type of the file search tool. Always `file_search`. + A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread. - - `FILE_SEARCH("file_search")` + - `Optional chunkingStrategy` - - `List vectorStoreIds` + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - The IDs of the vector stores to search. + - `JsonValue;` - - `Optional filters` + - `JsonValue; type "auto"constant` - A filter to apply. + Always `auto`. - - `class ComparisonFilter:` + - `AUTO("auto")` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `class Static:` - - `String key` + - `InnerStatic static_` - The key to compare against the value. + - `long chunkOverlapTokens` - - `Type type` + The number of tokens that overlap between chunks. The default value is `400`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `long maxChunkSizeTokens` - - `EQ("eq")` + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `NE("ne")` + - `JsonValue; type "static"constant` - - `GT("gt")` + Always `static`. - - `GTE("gte")` + - `STATIC("static")` - - `LT("lt")` + - `Optional> fileIds` - - `LTE("lte")` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. - - `IN("in")` + - `Optional metadata` - - `NIN("nin")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Value value` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The value to compare against the attribute key; supports string, number, or boolean types. + - `Optional toolChoice` - - `String` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `double` + - `Optional toolResources` - - `boolean` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `List` + - `Optional codeInterpreter` - - `class CompoundFilter:` + - `Optional> fileIds` - Combine multiple filters using `and` or `or`. + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `List filters` + - `Optional fileSearch` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `Optional> vectorStoreIds` - - `class ComparisonFilter:` + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `Optional> tools` - - `String key` + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - The key to compare against the value. + - `class CodeInterpreterTool:` - - `Type type` + - `class FileSearchTool:` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `JsonValue; type "file_search"constant` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The type of tool being defined: `file_search` - - `EQ("eq")` + - `FILE_SEARCH("file_search")` - - `NE("ne")` + - `Optional fileSearch` - - `GT("gt")` + Overrides for the file search tool. - - `GTE("gte")` + - `Optional maxNumResults` - - `LT("lt")` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `LTE("lte")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `IN("in")` + - `Optional rankingOptions` - - `NIN("nin")` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `Value value` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The value to compare against the attribute key; supports string, number, or boolean types. + - `double scoreThreshold` - - `String` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `double` + - `Optional ranker` - - `boolean` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `List` + - `AUTO("auto")` - - `JsonValue` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `Type type` + - `class FunctionTool:` - Type of operation: `and` or `or`. + - `FunctionDefinition function` - - `AND("and")` + - `String name` - - `OR("or")` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `Optional maxNumResults` + - `Optional description` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A description of what the function does, used by the model to choose when and how to call the function. - - `Optional rankingOptions` + - `Optional parameters` - Ranking options for search. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `Optional hybridSearch` + Omitting `parameters` defines a function with an empty parameter list. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `Optional strict` - - `double embeddingWeight` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The weight of the embedding in the reciprocal ranking fusion. + - `JsonValue; type "function"constant` - - `double textWeight` + The type of tool being defined: `function` - The weight of the text in the reciprocal ranking fusion. + - `FUNCTION("function")` - - `Optional ranker` + - `Optional topP` - The ranker to use for the file search. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `AUTO("auto")` + We generally recommend altering this or temperature but not both. - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `Optional truncationStrategy` - - `Optional scoreThreshold` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `Type type` - - `class BetaComputerTool:` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `AUTO("auto")` - - `JsonValue; type "computer"constant` + - `LAST_MESSAGES("last_messages")` - The type of the computer tool. Always `computer`. + - `Optional lastMessages` - - `COMPUTER("computer")` + The number of most recent messages from the thread when constructing the context for the run. - - `class BetaComputerUsePreviewTool:` +### Returns - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `class Run:` - - `long displayHeight` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The height of the computer display. + - `String id` - - `long displayWidth` + The identifier, which can be referenced in API endpoints. - The width of the computer display. + - `String assistantId` - - `Environment environment` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The type of computer environment to control. + - `Optional cancelledAt` - - `WINDOWS("windows")` + The Unix timestamp (in seconds) for when the run was cancelled. - - `MAC("mac")` + - `Optional completedAt` - - `LINUX("linux")` + The Unix timestamp (in seconds) for when the run was completed. - - `UBUNTU("ubuntu")` + - `long createdAt` - - `BROWSER("browser")` + The Unix timestamp (in seconds) for when the run was created. - - `JsonValue; type "computer_use_preview"constant` + - `Optional expiresAt` - The type of the computer use tool. Always `computer_use_preview`. + The Unix timestamp (in seconds) for when the run will expire. - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `Optional failedAt` - - `class BetaWebSearchTool:` + The Unix timestamp (in seconds) for when the run failed. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional incompleteDetails` - - `Type type` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `Optional reason` - - `WEB_SEARCH("web_search")` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `Optional filters` + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - Filters for the search. + - `String instructions` - - `Optional> allowedDomains` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Optional lastError` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The last error associated with this run. Will be `null` if there are no errors. - - `Optional searchContextSize` + - `Code code` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `LOW("low")` + - `SERVER_ERROR("server_error")` - - `MEDIUM("medium")` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `HIGH("high")` + - `INVALID_PROMPT("invalid_prompt")` - - `Optional userLocation` + - `String message` - The approximate location of the user. + A human-readable description of the error. - - `Optional city` + - `Optional maxCompletionTokens` - Free text input for the city of the user, e.g. `San Francisco`. + The maximum number of completion tokens specified to have been used over the course of the run. - - `Optional country` + - `Optional maxPromptTokens` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `Optional region` + - `Optional metadata` - Free text input for the region of the user, e.g. `California`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Optional timezone` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `String model` - - `Optional type` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of location approximation. Always `approximate`. + - `JsonValue; object_ "thread.run"constant` - - `APPROXIMATE("approximate")` + The object type, which is always `thread.run`. - - `Mcp` + - `THREAD_RUN("thread.run")` - - `String serverLabel` + - `boolean parallelToolCalls` - A label for this MCP server, used to identify it in tool calls. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `JsonValue; type "mcp"constant` + - `Optional requiredAction` - The type of the MCP tool. Always `mcp`. + Details on the action required to continue the run. Will be `null` if no action is required. - - `MCP("mcp")` + - `SubmitToolOutputs submitToolOutputs` - - `Optional> allowedCallers` + Details on the tool outputs needed for this run to continue. - The tool invocation context(s). + - `List toolCalls` - - `DIRECT("direct")` + A list of the relevant tool calls. - - `PROGRAMMATIC("programmatic")` + - `String id` - - `Optional allowedTools` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - List of allowed tool names or a filter object. + - `Function function` - - `List` + The function definition. - - `class McpToolFilter:` + - `String arguments` - A filter object to specify which tools are allowed. + The arguments that the model expects you to pass to the function. - - `Optional readOnly` + - `String name` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The name of the function. - - `Optional> toolNames` + - `JsonValue; type "function"constant` - List of allowed tool names. + The type of tool call the output is required for. For now, this is always `function`. - - `Optional authorization` + - `FUNCTION("function")` - 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. + - `JsonValue; type "submit_tool_outputs"constant` - - `Optional connectorId` + For now, this is always `submit_tool_outputs`. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - Currently supported `connector_id` values are: + - `Optional responseFormat` - - 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` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `CONNECTOR_DROPBOX("connector_dropbox")` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `CONNECTOR_GMAIL("connector_gmail")` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `JsonValue;` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + - `AUTO("auto")` - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `class ResponseFormatText:` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + Default response format. Used to generate text responses. - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + - `JsonValue; type "text"constant` - - `Optional deferLoading` + The type of response format being defined. Always `text`. - Whether this MCP tool is deferred and discovered via tool search. + - `TEXT("text")` - - `Optional headers` + - `class ResponseFormatJsonObject:` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `Optional requireApproval` + - `JsonValue; type "json_object"constant` - Specify which of the MCP server's tools require approval. + The type of response format being defined. Always `json_object`. - - `class McpToolApprovalFilter:` + - `JSON_OBJECT("json_object")` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `class ResponseFormatJsonSchema:` - - `Optional always` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - A filter object to specify which tools are allowed. + - `JsonSchema jsonSchema` - - `Optional readOnly` + Structured Outputs configuration options, including a JSON Schema. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `String name` - - `Optional> toolNames` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - List of allowed tool names. + - `Optional description` - - `Optional never` + A description of what the response format is for, used by the model to + determine how to respond in the format. - A filter object to specify which tools are allowed. + - `Optional schema` - - `Optional readOnly` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Optional strict` - - `Optional> toolNames` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - List of allowed tool names. + - `JsonValue; type "json_schema"constant` - - `enum McpToolApprovalSetting:` + The type of response format being defined. Always `json_schema`. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `JSON_SCHEMA("json_schema")` - - `ALWAYS("always")` + - `Optional startedAt` - - `NEVER("never")` + The Unix timestamp (in seconds) for when the run was started. - - `Optional serverDescription` + - `RunStatus status` - Optional description of the MCP server, used to provide more context. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `Optional serverUrl` + - `QUEUED("queued")` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `IN_PROGRESS("in_progress")` - - `Optional tunnelId` + - `REQUIRES_ACTION("requires_action")` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `CANCELLING("cancelling")` - - `CodeInterpreter` + - `CANCELLED("cancelled")` - - `Container container` + - `FAILED("failed")` - 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. + - `COMPLETED("completed")` - - `String` + - `INCOMPLETE("incomplete")` - - `class CodeInterpreterToolAuto:` + - `EXPIRED("expired")` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `String threadId` - - `JsonValue; type "auto"constant` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - Always `auto`. + - `Optional toolChoice` - - `AUTO("auto")` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `Optional> fileIds` + - `Auto` - An optional list of uploaded files to make available to your code. + - `NONE("none")` - - `Optional memoryLimit` + - `AUTO("auto")` - The memory limit for the code interpreter container. + - `REQUIRED("required")` - - `_1G("1g")` + - `class AssistantToolChoice:` - - `_4G("4g")` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `_16G("16g")` + - `Type type` - - `_64G("64g")` + The type of the tool. If type is `function`, the function name must be set - - `Optional networkPolicy` + - `FUNCTION("function")` - Network access policy for the container. + - `CODE_INTERPRETER("code_interpreter")` - - `class BetaContainerNetworkPolicyDisabled:` + - `FILE_SEARCH("file_search")` - - `JsonValue; type "disabled"constant` + - `Optional function` - Disable outbound network access. Always `disabled`. + - `String name` - - `DISABLED("disabled")` + The name of the function to call. - - `class BetaContainerNetworkPolicyAllowlist:` + - `List tools` - - `List allowedDomains` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - A list of allowed domains when type is `allowlist`. + - `class CodeInterpreterTool:` - - `JsonValue; type "allowlist"constant` + - `JsonValue; type "code_interpreter"constant` + + The type of tool being defined: `code_interpreter` + + - `CODE_INTERPRETER("code_interpreter")` - Allow outbound network access only to specified domains. Always `allowlist`. + - `class FileSearchTool:` - - `ALLOWLIST("allowlist")` + - `JsonValue; type "file_search"constant` - - `Optional> domainSecrets` + The type of tool being defined: `file_search` - Optional domain-scoped secrets for allowlisted domains. + - `FILE_SEARCH("file_search")` - - `String domain` + - `Optional fileSearch` - The domain associated with the secret. + Overrides for the file search tool. - - `String name` + - `Optional maxNumResults` - The name of the secret to inject for the domain. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `String value` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The secret value to inject for the domain. + - `Optional rankingOptions` - - `JsonValue; type "code_interpreter"constant` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The type of the code interpreter tool. Always `code_interpreter`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `CODE_INTERPRETER("code_interpreter")` + - `double scoreThreshold` - - `Optional> allowedCallers` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The tool invocation context(s). + - `Optional ranker` - - `DIRECT("direct")` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `PROGRAMMATIC("programmatic")` + - `AUTO("auto")` - - `JsonValue;` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `JsonValue; type "programmatic_tool_calling"constant` + - `class FunctionTool:` - The type of the tool. Always `programmatic_tool_calling`. + - `FunctionDefinition function` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `String name` - - `ImageGeneration` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `JsonValue; type "image_generation"constant` + - `Optional description` - The type of the image generation tool. Always `image_generation`. + A description of what the function does, used by the model to choose when and how to call the function. - - `IMAGE_GENERATION("image_generation")` + - `Optional parameters` - - `Optional action` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - Whether to generate a new image or edit an existing image. Default: `auto`. + Omitting `parameters` defines a function with an empty parameter list. - - `GENERATE("generate")` + - `Optional strict` - - `EDIT("edit")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `AUTO("auto")` + - `JsonValue; type "function"constant` - - `Optional background` + The type of tool being defined: `function` - 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. + - `FUNCTION("function")` - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `Optional truncationStrategy` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `TRANSPARENT("transparent")` + - `Type type` - - `OPAQUE("opaque")` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - `AUTO("auto")` - - `Optional inputFidelity` + - `LAST_MESSAGES("last_messages")` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `Optional lastMessages` - - `HIGH("high")` + The number of most recent messages from the thread when constructing the context for the run. - - `LOW("low")` + - `Optional usage` - - `Optional inputImageMask` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `long completionTokens` - - `Optional fileId` + Number of completion tokens used over the course of the run. - File ID for the mask image. + - `long promptTokens` - - `Optional imageUrl` + Number of prompt tokens used over the course of the run. - Base64-encoded mask image. + - `long totalTokens` - - `Optional model` + Total number of tokens used (prompt + completion). - The image generation model to use. Default: `gpt-image-1`. + - `Optional temperature` - - `GPT_IMAGE_1("gpt-image-1")` + The sampling temperature used for this run. If not set, defaults to 1. - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `Optional topP` - - `GPT_IMAGE_2("gpt-image-2")` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` +### Example - - `GPT_IMAGE_1_5("gpt-image-1.5")` +```java +package com.openai.example; - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.ThreadCreateAndRunParams; +import com.openai.models.beta.threads.runs.Run; - - `Optional moderation` +public final class Main { + private Main() {} - Moderation level for the generated image. Default: `auto`. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `AUTO("auto")` + ThreadCreateAndRunParams params = ThreadCreateAndRunParams.builder() + .assistantId("assistant_id") + .build(); + Run run = client.beta().threads().createAndRun(params); + } +} +``` - - `LOW("low")` +#### Response - - `Optional outputCompression` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - Compression level for the output image. Default: 100. +## Retrieve thread - - `Optional outputFormat` +`Thread beta().threads().retrieve(ThreadRetrieveParamsparams = ThreadRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. +**get** `/threads/{thread_id}` - - `PNG("png")` +Retrieves a thread. - - `WEBP("webp")` +### Parameters - - `JPEG("jpeg")` +- `ThreadRetrieveParams params` - - `Optional partialImages` + - `Optional threadId` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. +### Returns - - `Optional quality` +- `class Thread:` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `LOW("low")` + - `String id` - - `MEDIUM("medium")` + The identifier, which can be referenced in API endpoints. - - `HIGH("high")` + - `long createdAt` - - `AUTO("auto")` + The Unix timestamp (in seconds) for when the thread was created. - - `Optional size` + - `Optional metadata` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `_1024X1024("1024x1024")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `_1024X1536("1024x1536")` + - `JsonValue; object_ "thread"constant` - - `_1536X1024("1536x1024")` + The object type, which is always `thread`. - - `AUTO("auto")` + - `THREAD("thread")` - - `JsonValue;` + - `Optional toolResources` - - `JsonValue; type "local_shell"constant` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The type of the local shell tool. Always `local_shell`. + - `Optional codeInterpreter` - - `LOCAL_SHELL("local_shell")` + - `Optional> fileIds` - - `class BetaFunctionShellTool:` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - A tool that allows the model to execute shell commands. + - `Optional fileSearch` - - `JsonValue; type "shell"constant` + - `Optional> vectorStoreIds` - The type of the shell tool. Always `shell`. + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `SHELL("shell")` +### Example - - `Optional> allowedCallers` +```java +package com.openai.example; - The tool invocation context(s). +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.Thread; +import com.openai.models.beta.threads.ThreadRetrieveParams; - - `DIRECT("direct")` +public final class Main { + private Main() {} - - `PROGRAMMATIC("programmatic")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `Optional environment` + Thread thread = client.beta().threads().retrieve("thread_id"); + } +} +``` - - `class BetaContainerAuto:` +#### Response - - `JsonValue; type "container_auto"constant` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - Automatically creates a container for this request +## Modify thread - - `CONTAINER_AUTO("container_auto")` +`Thread beta().threads().update(ThreadUpdateParamsparams = ThreadUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `Optional> fileIds` +**post** `/threads/{thread_id}` - An optional list of uploaded files to make available to your code. +Modifies a thread. - - `Optional memoryLimit` +### Parameters - The memory limit for the container. +- `ThreadUpdateParams params` - - `_1G("1g")` + - `Optional threadId` - - `_4G("4g")` + - `Optional metadata` - - `_16G("16g")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `_64G("64g")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Optional networkPolicy` + - `Optional toolResources` - Network access policy for the container. + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `class BetaContainerNetworkPolicyDisabled:` + - `Optional codeInterpreter` - - `class BetaContainerNetworkPolicyAllowlist:` + - `Optional> fileIds` - - `Optional> skills` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - An optional list of skills referenced by id or inline data. + - `Optional fileSearch` - - `class BetaSkillReference:` + - `Optional> vectorStoreIds` - - `String skillId` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - The ID of the referenced skill. +### Returns - - `JsonValue; type "skill_reference"constant` +- `class Thread:` - References a skill created with the /v1/skills endpoint. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `SKILL_REFERENCE("skill_reference")` + - `String id` - - `Optional version` + The identifier, which can be referenced in API endpoints. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `long createdAt` - - `class BetaInlineSkill:` + The Unix timestamp (in seconds) for when the thread was created. - - `String description` + - `Optional metadata` - The description of the skill. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `String name` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The name of the skill. + - `JsonValue; object_ "thread"constant` - - `BetaInlineSkillSource source` + The object type, which is always `thread`. - Inline skill payload + - `THREAD("thread")` - - `String data` + - `Optional toolResources` - Base64-encoded skill zip bundle. + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `JsonValue; mediaType "application/zip"constant` + - `Optional codeInterpreter` - The media type of the inline skill payload. Must be `application/zip`. + - `Optional> fileIds` - - `APPLICATION_ZIP("application/zip")` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `JsonValue; type "base64"constant` + - `Optional fileSearch` - The type of the inline skill source. Must be `base64`. + - `Optional> vectorStoreIds` - - `BASE64("base64")` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `JsonValue; type "inline"constant` +### Example - Defines an inline skill for this request. +```java +package com.openai.example; - - `INLINE("inline")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.Thread; +import com.openai.models.beta.threads.ThreadUpdateParams; - - `class BetaLocalEnvironment:` +public final class Main { + private Main() {} - - `JsonValue; type "local"constant` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - Use a local computer environment. + Thread thread = client.beta().threads().update("thread_id"); + } +} +``` - - `LOCAL("local")` +#### Response - - `Optional> skills` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - An optional list of skills. +## Delete thread - - `String description` +`ThreadDeleted beta().threads().delete(ThreadDeleteParamsparams = ThreadDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - The description of the skill. +**delete** `/threads/{thread_id}` - - `String name` +Delete a thread. - The name of the skill. +### Parameters - - `String path` +- `ThreadDeleteParams params` - The path to the directory containing the skill. + - `Optional threadId` - - `class BetaContainerReference:` +### Returns - - `String containerId` +- `class ThreadDeleted:` - The ID of the referenced container. + - `String id` - - `JsonValue; type "container_reference"constant` + - `boolean deleted` - References a container created with the /v1/containers endpoint + - `JsonValue; object_ "thread.deleted"constant` - - `CONTAINER_REFERENCE("container_reference")` + - `THREAD_DELETED("thread.deleted")` - - `class BetaCustomTool:` +### Example - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +```java +package com.openai.example; - - `String name` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.ThreadDeleteParams; +import com.openai.models.beta.threads.ThreadDeleted; - The name of the custom tool, used to identify it in tool calls. +public final class Main { + private Main() {} - - `JsonValue; type "custom"constant` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The type of the custom tool. Always `custom`. + ThreadDeleted threadDeleted = client.beta().threads().delete("thread_id"); + } +} +``` - - `CUSTOM("custom")` +#### Response - - `Optional> allowedCallers` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.deleted" +} +``` - The tool invocation context(s). +## Domain Types - - `DIRECT("direct")` +### Assistant Response Format Option - - `PROGRAMMATIC("programmatic")` +- `class AssistantResponseFormatOption: A class that can be one of several variants.union` - - `Optional deferLoading` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - Whether this tool should be deferred and discovered via tool search. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional description` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Optional description of the custom tool, used to provide more context. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `Optional format` + - `JsonValue;` - The input format for the custom tool. Default is unconstrained text. + - `AUTO("auto")` - - `JsonValue;` + - `class ResponseFormatText:` + + Default response format. Used to generate text responses. - `JsonValue; type "text"constant` - Unconstrained text format. Always `text`. + The type of response format being defined. Always `text`. - `TEXT("text")` - - `class Grammar:` + - `class ResponseFormatJsonObject:` - A grammar defined by the user. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `String definition` + - `JsonValue; type "json_object"constant` - The grammar definition. + The type of response format being defined. Always `json_object`. - - `Syntax syntax` + - `JSON_OBJECT("json_object")` - The syntax of the grammar definition. One of `lark` or `regex`. + - `class ResponseFormatJsonSchema:` - - `LARK("lark")` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `REGEX("regex")` + - `JsonSchema jsonSchema` - - `JsonValue; type "grammar"constant` + Structured Outputs configuration options, including a JSON Schema. - Grammar format. Always `grammar`. + - `String name` - - `GRAMMAR("grammar")` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `class BetaNamespaceTool:` + - `Optional description` - Groups function/custom tools under a shared namespace. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `String description` + - `Optional schema` - A description of the namespace shown to the model. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `String name` + - `Optional strict` - The namespace name used in tool calls (for example, `crm`). + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `List tools` + - `JsonValue; type "json_schema"constant` - The function/custom tools available inside this namespace. + The type of response format being defined. Always `json_schema`. - - `class Function:` + - `JSON_SCHEMA("json_schema")` - - `String name` +### Assistant Tool Choice - - `JsonValue; type "function"constant` +- `class AssistantToolChoice:` - - `FUNCTION("function")` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `Optional> allowedCallers` + - `Type type` - The tool invocation context(s). + The type of the tool. If type is `function`, the function name must be set - - `DIRECT("direct")` + - `FUNCTION("function")` - - `PROGRAMMATIC("programmatic")` + - `CODE_INTERPRETER("code_interpreter")` - - `Optional deferLoading` + - `FILE_SEARCH("file_search")` - Whether this function should be deferred and discovered via tool search. + - `Optional function` - - `Optional description` + - `String name` - - `Optional outputSchema` + The name of the function to call. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +### Assistant Tool Choice Function - - `Optional parameters` +- `class AssistantToolChoiceFunction:` - - `Optional strict` + - `String name` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The name of the function to call. - - `class BetaCustomTool:` +### Assistant Tool Choice Option - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +- `class AssistantToolChoiceOption: A class that can be one of several variants.union` - - `JsonValue; type "namespace"constant` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of the tool. Always `namespace`. + - `Auto` - - `NAMESPACE("namespace")` + - `NONE("none")` - - `class BetaToolSearchTool:` + - `AUTO("auto")` - Hosted or BYOT tool search configuration for deferred tools. + - `REQUIRED("required")` - - `JsonValue; type "tool_search"constant` + - `class AssistantToolChoice:` - The type of the tool. Always `tool_search`. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `TOOL_SEARCH("tool_search")` + - `Type type` - - `Optional description` + The type of the tool. If type is `function`, the function name must be set - Description shown to the model for a client-executed tool search tool. + - `FUNCTION("function")` - - `Optional execution` + - `CODE_INTERPRETER("code_interpreter")` - Whether tool search is executed by the server or by the client. + - `FILE_SEARCH("file_search")` - - `SERVER("server")` + - `Optional function` - - `CLIENT("client")` + - `String name` - - `Optional parameters` + The name of the function to call. - Parameter schema for a client-executed tool search tool. +### Thread - - `class BetaWebSearchPreviewTool:` +- `class Thread:` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `Type type` + - `String id` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The identifier, which can be referenced in API endpoints. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `long createdAt` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The Unix timestamp (in seconds) for when the thread was created. - - `Optional> searchContentTypes` + - `Optional metadata` - - `TEXT("text")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `IMAGE("image")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Optional searchContextSize` + - `JsonValue; object_ "thread"constant` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The object type, which is always `thread`. - - `LOW("low")` + - `THREAD("thread")` - - `MEDIUM("medium")` + - `Optional toolResources` - - `HIGH("high")` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `Optional userLocation` + - `Optional codeInterpreter` - The user's location. + - `Optional> fileIds` - - `JsonValue; type "approximate"constant` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - The type of location approximation. Always `approximate`. + - `Optional fileSearch` - - `APPROXIMATE("approximate")` + - `Optional> vectorStoreIds` - - `Optional city` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - Free text input for the city of the user, e.g. `San Francisco`. +### Thread Deleted - - `Optional country` +- `class ThreadDeleted:` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `String id` - - `Optional region` + - `boolean deleted` - Free text input for the region of the user, e.g. `California`. + - `JsonValue; object_ "thread.deleted"constant` - - `Optional timezone` + - `THREAD_DELETED("thread.deleted")` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +# Runs - - `class BetaApplyPatchTool:` +## List runs - Allows the assistant to create, delete, or update files using unified diffs. +`RunListPage beta().threads().runs().list(RunListParamsparams = RunListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `JsonValue; type "apply_patch"constant` +**get** `/threads/{thread_id}/runs` - The type of the tool. Always `apply_patch`. +Returns a list of runs belonging to a thread. - - `APPLY_PATCH("apply_patch")` +### Parameters - - `Optional> allowedCallers` +- `RunListParams params` - The tool invocation context(s). + - `Optional threadId` - - `DIRECT("direct")` + - `Optional after` - - `PROGRAMMATIC("programmatic")` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `JsonValue; type "tool_search_output"constant` + - `Optional before` - The type of the item. Always `tool_search_output`. + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + - `Optional limit` - - `Optional agent` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The agent that produced this item. + - `Optional order` - - `String agentName` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - The canonical name of the agent that produced this item. + - `ASC("asc")` - - `Optional createdBy` + - `DESC("desc")` - The identifier of the actor that created the item. +### Returns - - `AdditionalTools` +- `class Run:` + + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - `String id` - The unique ID of the additional tools item. + The identifier, which can be referenced in API endpoints. - - `Role role` + - `String assistantId` - The role that provided the additional tools. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `UNKNOWN("unknown")` + - `Optional cancelledAt` - - `USER("user")` + The Unix timestamp (in seconds) for when the run was cancelled. - - `ASSISTANT("assistant")` + - `Optional completedAt` - - `SYSTEM("system")` + The Unix timestamp (in seconds) for when the run was completed. - - `CRITIC("critic")` + - `long createdAt` - - `DISCRIMINATOR("discriminator")` + The Unix timestamp (in seconds) for when the run was created. - - `DEVELOPER("developer")` + - `Optional expiresAt` - - `TOOL("tool")` + The Unix timestamp (in seconds) for when the run will expire. - - `List tools` + - `Optional failedAt` - The additional tool definitions made available at this item. + The Unix timestamp (in seconds) for when the run failed. - - `class BetaFunctionTool:` + - `Optional incompleteDetails` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `class BetaFileSearchTool:` + - `Optional reason` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `class BetaComputerTool:` + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - - `class BetaComputerUsePreviewTool:` + - `String instructions` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `class BetaWebSearchTool:` + - `Optional lastError` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The last error associated with this run. Will be `null` if there are no errors. - - `Mcp` + - `Code code` - - `CodeInterpreter` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `JsonValue;` + - `SERVER_ERROR("server_error")` - - `ImageGeneration` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `JsonValue;` + - `INVALID_PROMPT("invalid_prompt")` - - `class BetaFunctionShellTool:` + - `String message` - A tool that allows the model to execute shell commands. + A human-readable description of the error. - - `class BetaCustomTool:` + - `Optional maxCompletionTokens` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The maximum number of completion tokens specified to have been used over the course of the run. - - `class BetaNamespaceTool:` + - `Optional maxPromptTokens` - Groups function/custom tools under a shared namespace. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `class BetaToolSearchTool:` + - `Optional metadata` - Hosted or BYOT tool search configuration for deferred tools. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `class BetaWebSearchPreviewTool:` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String model` - - `class BetaApplyPatchTool:` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Allows the assistant to create, delete, or update files using unified diffs. + - `JsonValue; object_ "thread.run"constant` - - `JsonValue; type "additional_tools"constant` + The object type, which is always `thread.run`. - The type of the item. Always `additional_tools`. + - `THREAD_RUN("thread.run")` - - `ADDITIONAL_TOOLS("additional_tools")` + - `boolean parallelToolCalls` - - `Optional agent` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The agent that produced this item. + - `Optional requiredAction` - - `String agentName` + Details on the action required to continue the run. Will be `null` if no action is required. - The canonical name of the agent that produced this item. + - `SubmitToolOutputs submitToolOutputs` - - `class BetaResponseReasoningItem:` + Details on the tool outputs needed for this run to continue. - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `List toolCalls` + + A list of the relevant tool calls. - `String id` - The unique identifier of the reasoning content. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `List summary` + - `Function function` - Reasoning summary content. + The function definition. - - `String text` + - `String arguments` - A summary of the reasoning output from the model so far. + The arguments that the model expects you to pass to the function. - - `JsonValue; type "summary_text"constant` + - `String name` - The type of the object. Always `summary_text`. + The name of the function. - - `SUMMARY_TEXT("summary_text")` + - `JsonValue; type "function"constant` - - `JsonValue; type "reasoning"constant` + The type of tool call the output is required for. For now, this is always `function`. - The type of the object. Always `reasoning`. + - `FUNCTION("function")` - - `REASONING("reasoning")` + - `JsonValue; type "submit_tool_outputs"constant` - - `Optional agent` + For now, this is always `submit_tool_outputs`. - The agent that produced this item. + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - - `String agentName` + - `Optional responseFormat` - The canonical name of the agent that produced this item. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `Optional> content` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - Reasoning text content. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `String text` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The reasoning text from the model. + - `JsonValue;` - - `JsonValue; type "reasoning_text"constant` + - `AUTO("auto")` - The type of the reasoning text. Always `reasoning_text`. + - `class ResponseFormatText:` - - `REASONING_TEXT("reasoning_text")` + Default response format. Used to generate text responses. - - `Optional encryptedContent` + - `JsonValue; type "text"constant` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The type of response format being defined. Always `text`. - - `Optional status` + - `TEXT("text")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class ResponseFormatJsonObject:` - - `IN_PROGRESS("in_progress")` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `COMPLETED("completed")` + - `JsonValue; type "json_object"constant` - - `INCOMPLETE("incomplete")` + The type of response format being defined. Always `json_object`. - - `Program` + - `JSON_OBJECT("json_object")` - - `String id` + - `class ResponseFormatJsonSchema:` - The unique ID of the program item. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `String callId` + - `JsonSchema jsonSchema` - The stable call ID of the program item. + Structured Outputs configuration options, including a JSON Schema. - - `String code` + - `String name` - The JavaScript source executed by programmatic tool calling. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `String fingerprint` + - `Optional description` - Opaque program replay fingerprint that must be round-tripped. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `JsonValue; type "program"constant` + - `Optional schema` - The type of the item. Always `program`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `PROGRAM("program")` + - `Optional strict` - - `Optional agent` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The agent that produced this item. + - `JsonValue; type "json_schema"constant` - - `String agentName` + The type of response format being defined. Always `json_schema`. - The canonical name of the agent that produced this item. + - `JSON_SCHEMA("json_schema")` - - `ProgramOutput` + - `Optional startedAt` - - `String id` + The Unix timestamp (in seconds) for when the run was started. - The unique ID of the program output item. + - `RunStatus status` - - `String callId` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The call ID of the program item. + - `QUEUED("queued")` - - `String result` + - `IN_PROGRESS("in_progress")` - The result produced by the program item. + - `REQUIRES_ACTION("requires_action")` - - `Status status` + - `CANCELLING("cancelling")` - The terminal status of the program output item. + - `CANCELLED("cancelled")` + + - `FAILED("failed")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - - `JsonValue; type "program_output"constant` - - The type of the item. Always `program_output`. - - - `PROGRAM_OUTPUT("program_output")` - - - `Optional agent` + - `EXPIRED("expired")` - The agent that produced this item. + - `String threadId` - - `String agentName` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The canonical name of the agent that produced this item. + - `Optional toolChoice` - - `class BetaResponseCompactionItem:` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `Auto` - - `String id` + - `NONE("none")` - The unique ID of the compaction item. + - `AUTO("auto")` - - `String encryptedContent` + - `REQUIRED("required")` - The encrypted content that was produced by compaction. + - `class AssistantToolChoice:` - - `JsonValue; type "compaction"constant` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The type of the item. Always `compaction`. + - `Type type` - - `COMPACTION("compaction")` + The type of the tool. If type is `function`, the function name must be set - - `Optional agent` + - `FUNCTION("function")` - The agent that produced this item. + - `CODE_INTERPRETER("code_interpreter")` - - `String agentName` + - `FILE_SEARCH("file_search")` - The canonical name of the agent that produced this item. + - `Optional function` - - `Optional createdBy` + - `String name` - The identifier of the actor that created the item. + The name of the function to call. - - `ImageGenerationCall` + - `List tools` - - `String id` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The unique ID of the image generation call. + - `class CodeInterpreterTool:` - - `Optional result` + - `JsonValue; type "code_interpreter"constant` - The generated image encoded in base64. + The type of tool being defined: `code_interpreter` - - `Status status` + - `CODE_INTERPRETER("code_interpreter")` - The status of the image generation call. + - `class FileSearchTool:` - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "file_search"constant` - - `COMPLETED("completed")` + The type of tool being defined: `file_search` - - `GENERATING("generating")` + - `FILE_SEARCH("file_search")` - - `FAILED("failed")` + - `Optional fileSearch` - - `JsonValue; type "image_generation_call"constant` + Overrides for the file search tool. - The type of the image generation call. Always `image_generation_call`. + - `Optional maxNumResults` - - `IMAGE_GENERATION_CALL("image_generation_call")` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `Optional agent` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The agent that produced this item. + - `Optional rankingOptions` - - `String agentName` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The canonical name of the agent that produced this item. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaResponseCodeInterpreterToolCall:` + - `double scoreThreshold` - A tool call to run code. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `String id` + - `Optional ranker` - The unique ID of the code interpreter tool call. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `Optional code` + - `AUTO("auto")` - The code to run, or null if not available. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `String containerId` + - `class FunctionTool:` - The ID of the container used to run the code. + - `FunctionDefinition function` - - `Optional> outputs` + - `String name` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `class Logs:` + - `Optional description` - The logs output from the code interpreter. + A description of what the function does, used by the model to choose when and how to call the function. - - `String logs` + - `Optional parameters` - The logs output from the code interpreter. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `JsonValue; type "logs"constant` + Omitting `parameters` defines a function with an empty parameter list. - The type of the output. Always `logs`. + - `Optional strict` - - `LOGS("logs")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `class Image:` + - `JsonValue; type "function"constant` - The image output from the code interpreter. + The type of tool being defined: `function` - - `JsonValue; type "image"constant` + - `FUNCTION("function")` - The type of the output. Always `image`. + - `Optional truncationStrategy` - - `IMAGE("image")` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `String url` + - `Type type` - The URL of the image output from the code interpreter. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `Status status` + - `AUTO("auto")` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `LAST_MESSAGES("last_messages")` - - `IN_PROGRESS("in_progress")` + - `Optional lastMessages` - - `COMPLETED("completed")` + The number of most recent messages from the thread when constructing the context for the run. - - `INCOMPLETE("incomplete")` + - `Optional usage` - - `INTERPRETING("interpreting")` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `FAILED("failed")` + - `long completionTokens` - - `JsonValue; type "code_interpreter_call"constant` + Number of completion tokens used over the course of the run. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `long promptTokens` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + Number of prompt tokens used over the course of the run. - - `Optional agent` + - `long totalTokens` - The agent that produced this item. + Total number of tokens used (prompt + completion). - - `String agentName` + - `Optional temperature` - The canonical name of the agent that produced this item. + The sampling temperature used for this run. If not set, defaults to 1. - - `LocalShellCall` + - `Optional topP` - - `String id` + The nucleus sampling value used for this run. If not set, defaults to 1. - The unique ID of the local shell call. +### Example - - `Action action` +```java +package com.openai.example; - Execute a shell command on the server. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.runs.RunListPage; +import com.openai.models.beta.threads.runs.RunListParams; - - `List command` +public final class Main { + private Main() {} - The command to run. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `Env env` + RunListPage page = client.beta().threads().runs().list("thread_id"); + } +} +``` - Environment variables to set for the command. +#### Response - - `JsonValue; type "exec"constant` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 + } + ], + "first_id": "run_abc123", + "has_more": false, + "last_id": "run_abc456", + "object": "list" +} +``` - The type of the local shell action. Always `exec`. +## Create run - - `EXEC("exec")` +`Run beta().threads().runs().create(RunCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `Optional timeoutMs` +**post** `/threads/{thread_id}/runs` - Optional timeout in milliseconds for the command. +Create a run. - - `Optional user` +### Parameters - Optional user to run the command as. +- `RunCreateParams params` - - `Optional workingDirectory` + - `Optional threadId` - Optional working directory to run the command in. + - `Optional> include` - - `String callId` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - The unique ID of the local shell tool call generated by the model. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Status status` + - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` - The status of the local shell call. + - `String assistantId` - - `IN_PROGRESS("in_progress")` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - - `COMPLETED("completed")` + - `Optional additionalInstructions` - - `INCOMPLETE("incomplete")` + Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. - - `JsonValue; type "local_shell_call"constant` + - `Optional> additionalMessages` - The type of the local shell call. Always `local_shell_call`. + Adds additional messages to the thread before creating the run. - - `LOCAL_SHELL_CALL("local_shell_call")` + - `Content content` - - `Optional agent` + The text contents of the message. - The agent that produced this item. + - `String` - - `String agentName` + - `List` - The canonical name of the agent that produced this item. + - `class ImageFileContentBlock:` - - `LocalShellCallOutput` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `String id` + - `ImageFile imageFile` - The unique ID of the local shell tool call generated by the model. + - `String fileId` - - `String output` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - A JSON string of the output of the local shell tool call. + - `Optional detail` - - `JsonValue; type "local_shell_call_output"constant` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `AUTO("auto")` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `LOW("low")` - - `Optional agent` + - `HIGH("high")` - The agent that produced this item. + - `JsonValue; type "image_file"constant` - - `String agentName` + Always `image_file`. - The canonical name of the agent that produced this item. + - `IMAGE_FILE("image_file")` - - `Optional status` + - `class ImageUrlContentBlock:` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + References an image URL in the content of a message. - - `IN_PROGRESS("in_progress")` + - `ImageUrl imageUrl` - - `COMPLETED("completed")` + - `String url` - - `INCOMPLETE("incomplete")` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `class BetaResponseFunctionShellToolCall:` + - `Optional detail` - A tool call that executes one or more shell commands in a managed environment. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `String id` + - `AUTO("auto")` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `LOW("low")` - - `Action action` + - `HIGH("high")` - The shell commands and limits that describe how to run the tool call. + - `JsonValue; type "image_url"constant` - - `List commands` + The type of the content part. - - `Optional maxOutputLength` + - `IMAGE_URL("image_url")` - Optional maximum number of characters to return from each command. + - `class TextContentBlockParam:` - - `Optional timeoutMs` + The text content that is part of a message. - Optional timeout in milliseconds for the commands. + - `String text` - - `String callId` + Text content to be sent to the model - The unique ID of the shell tool call generated by the model. + - `JsonValue; type "text"constant` - - `Optional environment` + Always `text`. - Represents the use of a local environment to perform shell actions. + - `TEXT("text")` - - `class BetaResponseLocalEnvironment:` + - `Role role` - Represents the use of a local environment to perform shell actions. + The role of the entity that is creating the message. Allowed values include: - - `JsonValue; type "local"constant` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - The environment type. Always `local`. + - `USER("user")` - - `LOCAL("local")` + - `ASSISTANT("assistant")` - - `class BetaResponseContainerReference:` + - `Optional> attachments` - Represents a container created with /v1/containers. + A list of files attached to the message, and the tools they should be added to. - - `String containerId` + - `Optional fileId` - - `JsonValue; type "container_reference"constant` + The ID of the file to attach to the message. - The environment type. Always `container_reference`. + - `Optional> tools` - - `CONTAINER_REFERENCE("container_reference")` + The tools to add this file to. - - `Status status` + - `class CodeInterpreterTool:` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `JsonValue; type "code_interpreter"constant` - - `IN_PROGRESS("in_progress")` + The type of tool being defined: `code_interpreter` - - `COMPLETED("completed")` + - `CODE_INTERPRETER("code_interpreter")` - - `INCOMPLETE("incomplete")` + - `JsonValue;` - - `JsonValue; type "shell_call"constant` + - `JsonValue; type "file_search"constant` - The type of the item. Always `shell_call`. + The type of tool being defined: `file_search` - - `SHELL_CALL("shell_call")` + - `FILE_SEARCH("file_search")` - - `Optional agent` + - `Optional metadata` - The agent that produced this item. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `String agentName` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The canonical name of the agent that produced this item. + - `Optional instructions` - - `Optional caller` + Overrides the [instructions](https://platform.openai.com/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. - The execution context that produced this tool call. + - `Optional maxCompletionTokens` - - `JsonValue;` + The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `JsonValue; type "direct"constant` + - `Optional maxPromptTokens` - - `DIRECT("direct")` + The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `class Program:` + - `Optional metadata` - - `String callerId` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The call ID of the program item that produced this tool call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `JsonValue; type "program"constant` + - `Optional model` - - `PROGRAM("program")` + The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - - `Optional createdBy` + - `Optional parallelToolCalls` - The ID of the entity that created this tool call. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `class BetaResponseFunctionShellToolCallOutput:` + - `Optional reasoningEffort` - The output of a shell tool call that was emitted. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `String id` + - `Optional responseFormat` - The unique ID of the shell call output. Populated when this item is returned via API. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `String callId` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The unique ID of the shell tool call generated by the model. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `Optional maxOutputLength` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `Optional temperature` - - `List output` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - An array of shell call output contents + - `Optional toolChoice` - - `Outcome outcome` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `Optional> tools` - - `JsonValue;` + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - - `JsonValue; type "timeout"constant` + - `class CodeInterpreterTool:` - The outcome type. Always `timeout`. + - `class FileSearchTool:` - - `TIMEOUT("timeout")` + - `JsonValue; type "file_search"constant` - - `class Exit:` + The type of tool being defined: `file_search` - Indicates that the shell commands finished and returned an exit code. + - `FILE_SEARCH("file_search")` - - `long exitCode` + - `Optional fileSearch` - Exit code from the shell process. + Overrides for the file search tool. - - `JsonValue; type "exit"constant` + - `Optional maxNumResults` - The outcome type. Always `exit`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `EXIT("exit")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `String stderr` + - `Optional rankingOptions` - The standard error output that was captured. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `String stdout` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The standard output that was captured. + - `double scoreThreshold` - - `Optional createdBy` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The identifier of the actor that created the item. + - `Optional ranker` - - `Status status` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `AUTO("auto")` - - `IN_PROGRESS("in_progress")` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `COMPLETED("completed")` + - `class FunctionTool:` - - `INCOMPLETE("incomplete")` + - `FunctionDefinition function` - - `JsonValue; type "shell_call_output"constant` + - `String name` - The type of the shell call output. Always `shell_call_output`. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `Optional description` - - `Optional agent` + A description of what the function does, used by the model to choose when and how to call the function. - The agent that produced this item. + - `Optional parameters` - - `String agentName` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The canonical name of the agent that produced this item. + Omitting `parameters` defines a function with an empty parameter list. - - `Optional caller` + - `Optional strict` - The execution context that produced this tool call. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `JsonValue;` + - `JsonValue; type "function"constant` - - `JsonValue; type "direct"constant` + The type of tool being defined: `function` - - `DIRECT("direct")` + - `FUNCTION("function")` - - `class Program:` + - `Optional topP` - - `String callerId` + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - The call ID of the program item that produced this tool call. + We generally recommend altering this or temperature but not both. - - `JsonValue; type "program"constant` + - `Optional truncationStrategy` - - `PROGRAM("program")` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `Optional createdBy` + - `Type type` - The identifier of the actor that created the item. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `class BetaResponseApplyPatchToolCall:` + - `AUTO("auto")` - A tool call that applies file diffs by creating, deleting, or updating files. + - `LAST_MESSAGES("last_messages")` - - `String id` + - `Optional lastMessages` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The number of most recent messages from the thread when constructing the context for the run. - - `String callId` +### Returns - The unique ID of the apply patch tool call generated by the model. +- `class Run:` - - `Operation operation` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `String id` - - `class CreateFile:` + The identifier, which can be referenced in API endpoints. - Instruction describing how to create a file via the apply_patch tool. + - `String assistantId` - - `String diff` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - Diff to apply. + - `Optional cancelledAt` - - `String path` + The Unix timestamp (in seconds) for when the run was cancelled. - Path of the file to create. + - `Optional completedAt` - - `JsonValue; type "create_file"constant` + The Unix timestamp (in seconds) for when the run was completed. - Create a new file with the provided diff. + - `long createdAt` - - `CREATE_FILE("create_file")` + The Unix timestamp (in seconds) for when the run was created. - - `class DeleteFile:` + - `Optional expiresAt` - Instruction describing how to delete a file via the apply_patch tool. + The Unix timestamp (in seconds) for when the run will expire. - - `String path` + - `Optional failedAt` - Path of the file to delete. + The Unix timestamp (in seconds) for when the run failed. - - `JsonValue; type "delete_file"constant` + - `Optional incompleteDetails` - Delete the specified file. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `DELETE_FILE("delete_file")` + - `Optional reason` - - `class UpdateFile:` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - Instruction describing how to update a file via the apply_patch tool. + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `String diff` + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - Diff to apply. + - `String instructions` - - `String path` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Path of the file to update. + - `Optional lastError` - - `JsonValue; type "update_file"constant` + The last error associated with this run. Will be `null` if there are no errors. - Update an existing file with the provided diff. + - `Code code` - - `UPDATE_FILE("update_file")` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `Status status` + - `SERVER_ERROR("server_error")` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `IN_PROGRESS("in_progress")` + - `INVALID_PROMPT("invalid_prompt")` - - `COMPLETED("completed")` + - `String message` - - `JsonValue; type "apply_patch_call"constant` + A human-readable description of the error. - The type of the item. Always `apply_patch_call`. + - `Optional maxCompletionTokens` - - `APPLY_PATCH_CALL("apply_patch_call")` + The maximum number of completion tokens specified to have been used over the course of the run. - - `Optional agent` + - `Optional maxPromptTokens` - The agent that produced this item. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `String agentName` + - `Optional metadata` - The canonical name of the agent that produced this item. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Optional caller` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The execution context that produced this tool call. + - `String model` - - `JsonValue;` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `JsonValue; type "direct"constant` + - `JsonValue; object_ "thread.run"constant` - - `DIRECT("direct")` + The object type, which is always `thread.run`. - - `class Program:` + - `THREAD_RUN("thread.run")` - - `String callerId` + - `boolean parallelToolCalls` - The call ID of the program item that produced this tool call. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `JsonValue; type "program"constant` + - `Optional requiredAction` - - `PROGRAM("program")` + Details on the action required to continue the run. Will be `null` if no action is required. - - `Optional createdBy` + - `SubmitToolOutputs submitToolOutputs` - The ID of the entity that created this tool call. + Details on the tool outputs needed for this run to continue. - - `class BetaResponseApplyPatchToolCallOutput:` + - `List toolCalls` - The output emitted by an apply patch tool call. + A list of the relevant tool calls. - `String id` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `String callId` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - The unique ID of the apply patch tool call generated by the model. + - `Function function` - - `Status status` + The function definition. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `String arguments` - - `COMPLETED("completed")` + The arguments that the model expects you to pass to the function. - - `FAILED("failed")` + - `String name` - - `JsonValue; type "apply_patch_call_output"constant` + The name of the function. - The type of the item. Always `apply_patch_call_output`. + - `JsonValue; type "function"constant` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The type of tool call the output is required for. For now, this is always `function`. - - `Optional agent` + - `FUNCTION("function")` - The agent that produced this item. + - `JsonValue; type "submit_tool_outputs"constant` - - `String agentName` + For now, this is always `submit_tool_outputs`. - The canonical name of the agent that produced this item. + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - - `Optional caller` + - `Optional responseFormat` - The execution context that produced this tool call. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `JsonValue;` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `JsonValue; type "direct"constant` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `DIRECT("direct")` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `class Program:` + - `JsonValue;` - - `String callerId` + - `AUTO("auto")` - The call ID of the program item that produced this tool call. + - `class ResponseFormatText:` - - `JsonValue; type "program"constant` + Default response format. Used to generate text responses. - - `PROGRAM("program")` + - `JsonValue; type "text"constant` - - `Optional createdBy` + The type of response format being defined. Always `text`. - The ID of the entity that created this tool call output. + - `TEXT("text")` - - `Optional output` + - `class ResponseFormatJsonObject:` - Optional textual output returned by the apply patch tool. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `McpListTools` + - `JsonValue; type "json_object"constant` - - `String id` + The type of response format being defined. Always `json_object`. - The unique ID of the list. + - `JSON_OBJECT("json_object")` - - `String serverLabel` + - `class ResponseFormatJsonSchema:` - The label of the MCP server. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `List tools` + - `JsonSchema jsonSchema` - The tools available on the server. + Structured Outputs configuration options, including a JSON Schema. - - `JsonValue inputSchema` + - `String name` - The JSON schema describing the tool's input. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `String name` + - `Optional description` - The name of the tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `Optional annotations` + - `Optional schema` - Additional annotations about the tool. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `Optional description` + - `Optional strict` - The description of the tool. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `JsonValue; type "mcp_list_tools"constant` + - `JsonValue; type "json_schema"constant` - The type of the item. Always `mcp_list_tools`. + The type of response format being defined. Always `json_schema`. - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `JSON_SCHEMA("json_schema")` - - `Optional agent` + - `Optional startedAt` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run was started. - - `String agentName` + - `RunStatus status` - The canonical name of the agent that produced this item. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `Optional error` + - `QUEUED("queued")` - Error message if the server could not list tools. + - `IN_PROGRESS("in_progress")` - - `McpApprovalRequest` + - `REQUIRES_ACTION("requires_action")` - - `String id` + - `CANCELLING("cancelling")` - The unique ID of the approval request. + - `CANCELLED("cancelled")` - - `String arguments` + - `FAILED("failed")` - A JSON string of arguments for the tool. + - `COMPLETED("completed")` - - `String name` + - `INCOMPLETE("incomplete")` - The name of the tool to run. + - `EXPIRED("expired")` - - `String serverLabel` + - `String threadId` - The label of the MCP server making the request. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `JsonValue; type "mcp_approval_request"constant` + - `Optional toolChoice` - The type of the item. Always `mcp_approval_request`. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `Auto` - - `Optional agent` + - `NONE("none")` - The agent that produced this item. + - `AUTO("auto")` - - `String agentName` + - `REQUIRED("required")` - The canonical name of the agent that produced this item. + - `class AssistantToolChoice:` - - `McpApprovalResponse` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `String id` + - `Type type` - The unique ID of the approval response + The type of the tool. If type is `function`, the function name must be set - - `String approvalRequestId` + - `FUNCTION("function")` - The ID of the approval request being answered. + - `CODE_INTERPRETER("code_interpreter")` - - `boolean approve` + - `FILE_SEARCH("file_search")` - Whether the request was approved. + - `Optional function` - - `JsonValue; type "mcp_approval_response"constant` + - `String name` - The type of the item. Always `mcp_approval_response`. + The name of the function to call. - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + - `List tools` - - `Optional agent` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The agent that produced this item. + - `class CodeInterpreterTool:` - - `String agentName` + - `JsonValue; type "code_interpreter"constant` - The canonical name of the agent that produced this item. + The type of tool being defined: `code_interpreter` - - `Optional reason` + - `CODE_INTERPRETER("code_interpreter")` - Optional reason for the decision. + - `class FileSearchTool:` - - `McpCall` + - `JsonValue; type "file_search"constant` - - `String id` + The type of tool being defined: `file_search` - The unique ID of the tool call. + - `FILE_SEARCH("file_search")` - - `String arguments` + - `Optional fileSearch` - A JSON string of the arguments passed to the tool. + Overrides for the file search tool. - - `String name` + - `Optional maxNumResults` - The name of the tool that was run. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `String serverLabel` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The label of the MCP server running the tool. + - `Optional rankingOptions` - - `JsonValue; type "mcp_call"constant` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The type of the item. Always `mcp_call`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `MCP_CALL("mcp_call")` + - `double scoreThreshold` - - `Optional agent` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The agent that produced this item. + - `Optional ranker` - - `String agentName` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The canonical name of the agent that produced this item. + - `AUTO("auto")` - - `Optional approvalRequestId` + - `DEFAULT_2024_08_21("default_2024_08_21")` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `class FunctionTool:` - - `Optional error` + - `FunctionDefinition function` - The error from the tool call, if any. + - `String name` - - `Optional output` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The output from the tool call. + - `Optional description` - - `Optional status` + A description of what the function does, used by the model to choose when and how to call the function. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `Optional parameters` - - `IN_PROGRESS("in_progress")` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `COMPLETED("completed")` + Omitting `parameters` defines a function with an empty parameter list. - - `INCOMPLETE("incomplete")` + - `Optional strict` - - `CALLING("calling")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `FAILED("failed")` + - `JsonValue; type "function"constant` - - `class BetaResponseCustomToolCallItem:` + The type of tool being defined: `function` - A call to a custom tool created by the model. + - `FUNCTION("function")` - - `String id` + - `Optional truncationStrategy` - The unique ID of the custom tool call item. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `Status status` + - `Type type` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `IN_PROGRESS("in_progress")` + - `AUTO("auto")` - - `COMPLETED("completed")` + - `LAST_MESSAGES("last_messages")` - - `INCOMPLETE("incomplete")` + - `Optional lastMessages` - - `Optional createdBy` + The number of most recent messages from the thread when constructing the context for the run. - The identifier of the actor that created the item. + - `Optional usage` - - `class BetaResponseCustomToolCallOutputItem:` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The output of a custom tool call from your code, being sent back to the model. + - `long completionTokens` - - `String id` + Number of completion tokens used over the course of the run. - The unique ID of the custom tool call output item. + - `long promptTokens` - - `Status status` + Number of prompt tokens used over the course of the run. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `long totalTokens` - - `IN_PROGRESS("in_progress")` + Total number of tokens used (prompt + completion). - - `COMPLETED("completed")` + - `Optional temperature` - - `INCOMPLETE("incomplete")` + The sampling temperature used for this run. If not set, defaults to 1. - - `Optional createdBy` + - `Optional topP` - The identifier of the actor that created the item. + The nucleus sampling value used for this run. If not set, defaults to 1. ### Example @@ -144882,8 +157966,8 @@ package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.responses.inputitems.InputItemListPage; -import com.openai.models.beta.responses.inputitems.InputItemListParams; +import com.openai.models.beta.threads.runs.Run; +import com.openai.models.beta.threads.runs.RunCreateParams; public final class Main { private Main() {} @@ -144891,7 +157975,11 @@ public final class Main { public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - InputItemListPage page = client.beta().responses().inputItems().list("response_id"); + RunCreateParams params = RunCreateParams.builder() + .threadId("thread_id") + .assistantId("assistant_id") + .build(); + Run run = client.beta().threads().runs().create(params); } } ``` @@ -144900,7726 +157988,8172 @@ public final class Main { ```json { - "data": [ - { "id": "id", - "content": [ + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ { - "text": "text", - "type": "input_text", - "prompt_cache_breakpoint": { - "mode": "explicit" - } + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" } - ], - "role": "user", - "type": "message", - "agent": { - "agent_name": "agent_name" + ] }, - "status": "in_progress" + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" } ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 } ``` -## Domain Types - -### Beta Response Item List - -- `class BetaResponseItemList:` - - A list of Response items. - - - `List data` - - A list of items used to generate this response. - - - `class BetaResponseInputMessageItem:` - - - `String id` - - The unique ID of the message input. - - - `List content` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText:` - - 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")` - - - `Optional promptCacheBreakpoint` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `JsonValue; mode "explicit"constant` - - The breakpoint mode. Always `explicit`. - - - `EXPLICIT("explicit")` - - - `class BetaResponseInputImage:` +## Retrieve run - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). +`Run beta().threads().runs().retrieve(RunRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `Detail detail` +**get** `/threads/{thread_id}/runs/{run_id}` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +Retrieves a run. - - `LOW("low")` +### Parameters - - `HIGH("high")` +- `RunRetrieveParams params` - - `AUTO("auto")` + - `String threadId` - - `ORIGINAL("original")` + - `Optional runId` - - `JsonValue; type "input_image"constant` +### Returns - The type of the input item. Always `input_image`. +- `class Run:` - - `INPUT_IMAGE("input_image")` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `Optional fileId` + - `String id` - The ID of the file to be sent to the model. + The identifier, which can be referenced in API endpoints. - - `Optional imageUrl` + - `String assistantId` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `Optional promptCacheBreakpoint` + - `Optional cancelledAt` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The Unix timestamp (in seconds) for when the run was cancelled. - - `JsonValue; mode "explicit"constant` + - `Optional completedAt` - The breakpoint mode. Always `explicit`. + The Unix timestamp (in seconds) for when the run was completed. - - `EXPLICIT("explicit")` + - `long createdAt` - - `class BetaResponseInputFile:` + The Unix timestamp (in seconds) for when the run was created. - A file input to the model. + - `Optional expiresAt` - - `JsonValue; type "input_file"constant` + The Unix timestamp (in seconds) for when the run will expire. - The type of the input item. Always `input_file`. + - `Optional failedAt` - - `INPUT_FILE("input_file")` + The Unix timestamp (in seconds) for when the run failed. - - `Optional detail` + - `Optional incompleteDetails` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `AUTO("auto")` + - `Optional reason` - - `LOW("low")` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `HIGH("high")` + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `Optional fileData` + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - The content of the file to be sent to the model. + - `String instructions` - - `Optional fileId` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The ID of the file to be sent to the model. + - `Optional lastError` - - `Optional fileUrl` + The last error associated with this run. Will be `null` if there are no errors. - The URL of the file to be sent to the model. + - `Code code` - - `Optional filename` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The name of the file to be sent to the model. + - `SERVER_ERROR("server_error")` - - `Optional promptCacheBreakpoint` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `INVALID_PROMPT("invalid_prompt")` - - `JsonValue; mode "explicit"constant` + - `String message` - The breakpoint mode. Always `explicit`. + A human-readable description of the error. - - `EXPLICIT("explicit")` + - `Optional maxCompletionTokens` - - `Role role` + The maximum number of completion tokens specified to have been used over the course of the run. - The role of the message input. One of `user`, `system`, or `developer`. + - `Optional maxPromptTokens` - - `USER("user")` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `SYSTEM("system")` + - `Optional metadata` - - `DEVELOPER("developer")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `JsonValue; type "message"constant` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the message input. Always set to `message`. + - `String model` - - `MESSAGE("message")` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `Optional agent` + - `JsonValue; object_ "thread.run"constant` - The agent that produced this item. + The object type, which is always `thread.run`. - - `String agentName` + - `THREAD_RUN("thread.run")` - The canonical name of the agent that produced this item. + - `boolean parallelToolCalls` - - `Optional status` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Optional requiredAction` - - `IN_PROGRESS("in_progress")` + Details on the action required to continue the run. Will be `null` if no action is required. - - `COMPLETED("completed")` + - `SubmitToolOutputs submitToolOutputs` - - `INCOMPLETE("incomplete")` + Details on the tool outputs needed for this run to continue. - - `class BetaResponseOutputMessage:` + - `List toolCalls` - An output message from the model. + A list of the relevant tool calls. - `String id` - The unique ID of the output message. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `List content` + - `Function function` - The content of the output message. + The function definition. - - `class BetaResponseOutputText:` + - `String arguments` - A text output from the model. + The arguments that the model expects you to pass to the function. - - `List annotations` + - `String name` - The annotations of the text output. + The name of the function. - - `class FileCitation:` + - `JsonValue; type "function"constant` - A citation to a file. + The type of tool call the output is required for. For now, this is always `function`. - - `String fileId` + - `FUNCTION("function")` - The ID of the file. + - `JsonValue; type "submit_tool_outputs"constant` - - `String filename` + For now, this is always `submit_tool_outputs`. - The filename of the file cited. + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - - `long index` + - `Optional responseFormat` - The index of the file in the list of files. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `JsonValue; type "file_citation"constant` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The type of the file citation. Always `file_citation`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `FILE_CITATION("file_citation")` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `class UrlCitation:` + - `JsonValue;` - A citation for a web resource used to generate a model response. + - `AUTO("auto")` - - `long endIndex` + - `class ResponseFormatText:` - The index of the last character of the URL citation in the message. + Default response format. Used to generate text responses. - - `long startIndex` + - `JsonValue; type "text"constant` - The index of the first character of the URL citation in the message. + The type of response format being defined. Always `text`. - - `String title` + - `TEXT("text")` - The title of the web resource. + - `class ResponseFormatJsonObject:` - - `JsonValue; type "url_citation"constant` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The type of the URL citation. Always `url_citation`. + - `JsonValue; type "json_object"constant` - - `URL_CITATION("url_citation")` + The type of response format being defined. Always `json_object`. - - `String url` + - `JSON_OBJECT("json_object")` - The URL of the web resource. + - `class ResponseFormatJsonSchema:` - - `class ContainerFileCitation:` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - A citation for a container file used to generate a model response. + - `JsonSchema jsonSchema` - - `String containerId` + Structured Outputs configuration options, including a JSON Schema. - The ID of the container file. + - `String name` - - `long endIndex` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The index of the last character of the container file citation in the message. + - `Optional description` - - `String fileId` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The ID of the file. + - `Optional schema` - - `String filename` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The filename of the container file cited. + - `Optional strict` - - `long startIndex` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The index of the first character of the container file citation in the message. + - `JsonValue; type "json_schema"constant` - - `JsonValue; type "container_file_citation"constant` + The type of response format being defined. Always `json_schema`. - The type of the container file citation. Always `container_file_citation`. + - `JSON_SCHEMA("json_schema")` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `Optional startedAt` - - `class FilePath:` + The Unix timestamp (in seconds) for when the run was started. - A path to a file. + - `RunStatus status` - - `String fileId` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The ID of the file. + - `QUEUED("queued")` - - `long index` + - `IN_PROGRESS("in_progress")` - The index of the file in the list of files. + - `REQUIRES_ACTION("requires_action")` - - `JsonValue; type "file_path"constant` + - `CANCELLING("cancelling")` - The type of the file path. Always `file_path`. + - `CANCELLED("cancelled")` - - `FILE_PATH("file_path")` + - `FAILED("failed")` - - `String text` + - `COMPLETED("completed")` - The text output from the model. + - `INCOMPLETE("incomplete")` - - `JsonValue; type "output_text"constant` + - `EXPIRED("expired")` - The type of the output text. Always `output_text`. + - `String threadId` - - `OUTPUT_TEXT("output_text")` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `Optional> logprobs` + - `Optional toolChoice` - - `String token` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `List bytes` + - `Auto` - - `double logprob` + - `NONE("none")` - - `List topLogprobs` + - `AUTO("auto")` - - `String token` + - `REQUIRED("required")` - - `List bytes` + - `class AssistantToolChoice:` - - `double logprob` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `class BetaResponseOutputRefusal:` + - `Type type` - A refusal from the model. + The type of the tool. If type is `function`, the function name must be set - - `String refusal` + - `FUNCTION("function")` - The refusal explanation from the model. + - `CODE_INTERPRETER("code_interpreter")` - - `JsonValue; type "refusal"constant` + - `FILE_SEARCH("file_search")` - The type of the refusal. Always `refusal`. + - `Optional function` - - `REFUSAL("refusal")` + - `String name` - - `JsonValue; role "assistant"constant` + The name of the function to call. - The role of the output message. Always `assistant`. + - `List tools` - - `ASSISTANT("assistant")` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `Status status` + - `class CodeInterpreterTool:` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `JsonValue; type "code_interpreter"constant` - - `IN_PROGRESS("in_progress")` + The type of tool being defined: `code_interpreter` - - `COMPLETED("completed")` + - `CODE_INTERPRETER("code_interpreter")` - - `INCOMPLETE("incomplete")` + - `class FileSearchTool:` - - `JsonValue; type "message"constant` + - `JsonValue; type "file_search"constant` - The type of the output message. Always `message`. + The type of tool being defined: `file_search` - - `MESSAGE("message")` + - `FILE_SEARCH("file_search")` - - `Optional agent` + - `Optional fileSearch` - The agent that produced this item. + Overrides for the file search tool. - - `String agentName` + - `Optional maxNumResults` - The canonical name of the agent that produced this item. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `Optional phase` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - 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. + - `Optional rankingOptions` - - `COMMENTARY("commentary")` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `class BetaResponseFileSearchToolCall:` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `double scoreThreshold` - - `String id` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The unique ID of the file search tool call. + - `Optional ranker` - - `List queries` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The queries used to search for files. + - `AUTO("auto")` - - `Status status` + - `DEFAULT_2024_08_21("default_2024_08_21")` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `class FunctionTool:` - - `IN_PROGRESS("in_progress")` + - `FunctionDefinition function` - - `SEARCHING("searching")` + - `String name` - - `COMPLETED("completed")` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `INCOMPLETE("incomplete")` + - `Optional description` - - `FAILED("failed")` + A description of what the function does, used by the model to choose when and how to call the function. - - `JsonValue; type "file_search_call"constant` + - `Optional parameters` - The type of the file search tool call. Always `file_search_call`. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `FILE_SEARCH_CALL("file_search_call")` + Omitting `parameters` defines a function with an empty parameter list. - - `Optional agent` + - `Optional strict` - The agent that produced this item. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `String agentName` + - `JsonValue; type "function"constant` - The canonical name of the agent that produced this item. + The type of tool being defined: `function` - - `Optional> results` + - `FUNCTION("function")` - The results of the file search tool call. + - `Optional truncationStrategy` - - `Optional attributes` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `Type type` - - `String` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `double` + - `AUTO("auto")` - - `boolean` + - `LAST_MESSAGES("last_messages")` - - `Optional fileId` + - `Optional lastMessages` - The unique ID of the file. + The number of most recent messages from the thread when constructing the context for the run. - - `Optional filename` + - `Optional usage` - The name of the file. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `Optional score` + - `long completionTokens` - The relevance score of the file - a value between 0 and 1. + Number of completion tokens used over the course of the run. - - `Optional text` + - `long promptTokens` - The text that was retrieved from the file. + Number of prompt tokens used over the course of the run. - - `class BetaResponseComputerToolCall:` + - `long totalTokens` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + Total number of tokens used (prompt + completion). - - `String id` + - `Optional temperature` - The unique ID of the computer call. + The sampling temperature used for this run. If not set, defaults to 1. - - `String callId` + - `Optional topP` - An identifier used when responding to the tool call with output. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `List pendingSafetyChecks` +### Example - The pending safety checks for the computer call. +```java +package com.openai.example; - - `String id` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.runs.Run; +import com.openai.models.beta.threads.runs.RunRetrieveParams; - The ID of the pending safety check. +public final class Main { + private Main() {} - - `Optional code` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The type of the pending safety check. + RunRetrieveParams params = RunRetrieveParams.builder() + .threadId("thread_id") + .runId("run_id") + .build(); + Run run = client.beta().threads().runs().retrieve(params); + } +} +``` - - `Optional message` +#### Response - Details about the pending safety check. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `Status status` +## Modify run - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +`Run beta().threads().runs().update(RunUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `IN_PROGRESS("in_progress")` +**post** `/threads/{thread_id}/runs/{run_id}` - - `COMPLETED("completed")` +Modifies a run. - - `INCOMPLETE("incomplete")` +### Parameters - - `Type type` +- `RunUpdateParams params` - The type of the computer call. Always `computer_call`. + - `String threadId` - - `COMPUTER_CALL("computer_call")` + - `Optional runId` - - `Optional action` + - `Optional metadata` - A click action. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Click` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Button button` +### Returns - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. +- `class Run:` - - `LEFT("left")` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `RIGHT("right")` + - `String id` - - `WHEEL("wheel")` + The identifier, which can be referenced in API endpoints. - - `BACK("back")` + - `String assistantId` - - `FORWARD("forward")` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `JsonValue; type "click"constant` + - `Optional cancelledAt` - Specifies the event type. For a click action, this property is always `click`. + The Unix timestamp (in seconds) for when the run was cancelled. - - `CLICK("click")` + - `Optional completedAt` - - `long x` + The Unix timestamp (in seconds) for when the run was completed. - The x-coordinate where the click occurred. + - `long createdAt` - - `long y` + The Unix timestamp (in seconds) for when the run was created. - The y-coordinate where the click occurred. + - `Optional expiresAt` - - `Optional> keys` + The Unix timestamp (in seconds) for when the run will expire. - The keys being held while clicking. + - `Optional failedAt` - - `DoubleClick` + The Unix timestamp (in seconds) for when the run failed. - - `Optional> keys` + - `Optional incompleteDetails` - The keys being held while double-clicking. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `JsonValue; type "double_click"constant` + - `Optional reason` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `DOUBLE_CLICK("double_click")` + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `long x` + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - The x-coordinate where the double click occurred. + - `String instructions` - - `long y` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The y-coordinate where the double click occurred. + - `Optional lastError` - - `Drag` + The last error associated with this run. Will be `null` if there are no errors. - - `List path` + - `Code code` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `SERVER_ERROR("server_error")` - - `long x` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The x-coordinate. + - `INVALID_PROMPT("invalid_prompt")` - - `long y` + - `String message` - The y-coordinate. + A human-readable description of the error. - - `JsonValue; type "drag"constant` + - `Optional maxCompletionTokens` - Specifies the event type. For a drag action, this property is always set to `drag`. + The maximum number of completion tokens specified to have been used over the course of the run. - - `DRAG("drag")` + - `Optional maxPromptTokens` - - `Optional> keys` + The maximum number of prompt tokens specified to have been used over the course of the run. - The keys being held while dragging the mouse. + - `Optional metadata` - - `Keypress` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `List keys` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `String model` - - `JsonValue; type "keypress"constant` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `JsonValue; object_ "thread.run"constant` - - `KEYPRESS("keypress")` + The object type, which is always `thread.run`. - - `Move` + - `THREAD_RUN("thread.run")` - - `JsonValue; type "move"constant` + - `boolean parallelToolCalls` - Specifies the event type. For a move action, this property is always set to `move`. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `MOVE("move")` + - `Optional requiredAction` - - `long x` + Details on the action required to continue the run. Will be `null` if no action is required. - The x-coordinate to move to. + - `SubmitToolOutputs submitToolOutputs` - - `long y` + Details on the tool outputs needed for this run to continue. - The y-coordinate to move to. + - `List toolCalls` - - `Optional> keys` + A list of the relevant tool calls. - The keys being held while moving the mouse. + - `String id` - - `JsonValue;` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `JsonValue; type "screenshot"constant` + - `Function function` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The function definition. - - `SCREENSHOT("screenshot")` + - `String arguments` - - `Scroll` + The arguments that the model expects you to pass to the function. - - `long scrollX` + - `String name` - The horizontal scroll distance. + The name of the function. - - `long scrollY` + - `JsonValue; type "function"constant` - The vertical scroll distance. + The type of tool call the output is required for. For now, this is always `function`. - - `JsonValue; type "scroll"constant` + - `FUNCTION("function")` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `JsonValue; type "submit_tool_outputs"constant` - - `SCROLL("scroll")` + For now, this is always `submit_tool_outputs`. - - `long x` + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - The x-coordinate where the scroll occurred. + - `Optional responseFormat` - - `long y` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The y-coordinate where the scroll occurred. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional> keys` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The keys being held while scrolling. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `Type` + - `JsonValue;` - - `String text` + - `AUTO("auto")` - The text to type. + - `class ResponseFormatText:` - - `JsonValue; type "type"constant` + Default response format. Used to generate text responses. - Specifies the event type. For a type action, this property is always set to `type`. + - `JsonValue; type "text"constant` - - `TYPE("type")` + The type of response format being defined. Always `text`. - - `JsonValue;` + - `TEXT("text")` - - `JsonValue; type "wait"constant` + - `class ResponseFormatJsonObject:` - Specifies the event type. For a wait action, this property is always set to `wait`. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `WAIT("wait")` + - `JsonValue; type "json_object"constant` - - `Optional> actions` + The type of response format being defined. Always `json_object`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `JSON_OBJECT("json_object")` - - `Click` + - `class ResponseFormatJsonSchema:` - - `DoubleClick` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `Drag` + - `JsonSchema jsonSchema` - - `Keypress` + Structured Outputs configuration options, including a JSON Schema. - - `Move` + - `String name` - - `JsonValue;` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `Scroll` + - `Optional description` - - `Type` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `JsonValue;` + - `Optional schema` - - `Optional agent` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The agent that produced this item. + - `Optional strict` - - `String agentName` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The canonical name of the agent that produced this item. + - `JsonValue; type "json_schema"constant` - - `class BetaResponseComputerToolCallOutputItem:` + The type of response format being defined. Always `json_schema`. - - `String id` + - `JSON_SCHEMA("json_schema")` - The unique ID of the computer call tool output. + - `Optional startedAt` - - `String callId` + The Unix timestamp (in seconds) for when the run was started. - The ID of the computer tool call that produced the output. + - `RunStatus status` - - `BetaResponseComputerToolCallOutputScreenshot output` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - A computer screenshot image used with the computer use tool. + - `QUEUED("queued")` - - `JsonValue; type "computer_screenshot"constant` + - `IN_PROGRESS("in_progress")` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `REQUIRES_ACTION("requires_action")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `CANCELLING("cancelling")` - - `Optional fileId` + - `CANCELLED("cancelled")` - The identifier of an uploaded file that contains the screenshot. + - `FAILED("failed")` - - `Optional imageUrl` + - `COMPLETED("completed")` - The URL of the screenshot image. + - `INCOMPLETE("incomplete")` - - `Status status` + - `EXPIRED("expired")` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `String threadId` - - `COMPLETED("completed")` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `INCOMPLETE("incomplete")` + - `Optional toolChoice` - - `FAILED("failed")` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `IN_PROGRESS("in_progress")` + - `Auto` - - `JsonValue; type "computer_call_output"constant` + - `NONE("none")` - The type of the computer tool call output. Always `computer_call_output`. + - `AUTO("auto")` - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `REQUIRED("required")` - - `Optional> acknowledgedSafetyChecks` + - `class AssistantToolChoice:` - The safety checks reported by the API that have been acknowledged by the - developer. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `String id` + - `Type type` - The ID of the pending safety check. + The type of the tool. If type is `function`, the function name must be set - - `Optional code` + - `FUNCTION("function")` - The type of the pending safety check. + - `CODE_INTERPRETER("code_interpreter")` - - `Optional message` + - `FILE_SEARCH("file_search")` - Details about the pending safety check. + - `Optional function` - - `Optional agent` + - `String name` - The agent that produced this item. + The name of the function to call. - - `String agentName` + - `List tools` - The canonical name of the agent that produced this item. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `Optional createdBy` + - `class CodeInterpreterTool:` - The identifier of the actor that created the item. + - `JsonValue; type "code_interpreter"constant` - - `class BetaResponseFunctionWebSearch:` + The type of tool being defined: `code_interpreter` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + - `CODE_INTERPRETER("code_interpreter")` - - `String id` + - `class FileSearchTool:` - The unique ID of the web search tool call. + - `JsonValue; type "file_search"constant` - - `Action action` + The type of tool being defined: `file_search` - 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). + - `FILE_SEARCH("file_search")` - - `class Search:` + - `Optional fileSearch` - Action type "search" - Performs a web search query. + Overrides for the file search tool. - - `JsonValue; type "search"constant` + - `Optional maxNumResults` - The action type. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `SEARCH("search")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Optional> queries` + - `Optional rankingOptions` - The search queries. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `Optional query` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The search query. + - `double scoreThreshold` - - `Optional> sources` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The sources used in the search. + - `Optional ranker` - - `JsonValue; type "url"constant` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The type of source. Always `url`. + - `AUTO("auto")` - - `URL("url")` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `String url` + - `class FunctionTool:` - The URL of the source. + - `FunctionDefinition function` - - `class OpenPage:` + - `String name` - Action type "open_page" - Opens a specific URL from search results. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `JsonValue; type "open_page"constant` + - `Optional description` - The action type. + A description of what the function does, used by the model to choose when and how to call the function. - - `OPEN_PAGE("open_page")` + - `Optional parameters` - - `Optional url` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The URL opened by the model. + Omitting `parameters` defines a function with an empty parameter list. - - `class FindInPage:` + - `Optional strict` - Action type "find_in_page": Searches for a pattern within a loaded page. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `String pattern` + - `JsonValue; type "function"constant` - The pattern or text to search for within the page. + The type of tool being defined: `function` - - `JsonValue; type "find_in_page"constant` + - `FUNCTION("function")` - The action type. + - `Optional truncationStrategy` - - `FIND_IN_PAGE("find_in_page")` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `String url` + - `Type type` - The URL of the page searched for the pattern. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `Status status` + - `AUTO("auto")` - The status of the web search tool call. + - `LAST_MESSAGES("last_messages")` - - `IN_PROGRESS("in_progress")` + - `Optional lastMessages` - - `SEARCHING("searching")` + The number of most recent messages from the thread when constructing the context for the run. - - `COMPLETED("completed")` + - `Optional usage` - - `FAILED("failed")` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `JsonValue; type "web_search_call"constant` + - `long completionTokens` - The type of the web search tool call. Always `web_search_call`. + Number of completion tokens used over the course of the run. - - `WEB_SEARCH_CALL("web_search_call")` + - `long promptTokens` - - `Optional agent` + Number of prompt tokens used over the course of the run. - The agent that produced this item. + - `long totalTokens` - - `String agentName` + Total number of tokens used (prompt + completion). - The canonical name of the agent that produced this item. + - `Optional temperature` - - `class BetaResponseFunctionToolCallItem:` + The sampling temperature used for this run. If not set, defaults to 1. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `Optional topP` - - `String id` + The nucleus sampling value used for this run. If not set, defaults to 1. - The unique ID of the function tool call. +### Example - - `Status status` +```java +package com.openai.example; - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.runs.Run; +import com.openai.models.beta.threads.runs.RunUpdateParams; - - `IN_PROGRESS("in_progress")` +public final class Main { + private Main() {} - - `COMPLETED("completed")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `INCOMPLETE("incomplete")` + RunUpdateParams params = RunUpdateParams.builder() + .threadId("thread_id") + .runId("run_id") + .build(); + Run run = client.beta().threads().runs().update(params); + } +} +``` - - `Optional createdBy` +#### Response - The identifier of the actor that created the item. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `class BetaResponseFunctionToolCallOutputItem:` +## Submit tool outputs to run - - `String id` +`Run beta().threads().runs().submitToolOutputs(RunSubmitToolOutputsParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - The unique ID of the function call tool output. +**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` - - `String callId` +When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. - The unique ID of the function tool call generated by the model. +### Parameters - - `Output output` +- `RunSubmitToolOutputsParams params` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `String threadId` - - `String` + - `Optional runId` - - `List` + - `List toolOutputs` - - `class BetaResponseInputText:` + A list of tools for which the outputs are being submitted. - A text input to the model. + - `Optional output` - - `class BetaResponseInputImage:` + The output of the tool call to be submitted to continue the run. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `Optional toolCallId` - - `class BetaResponseInputFile:` + The ID of the tool call in the `required_action` object within the run object the output is being submitted for. - A file input to the model. +### Returns - - `Status status` +- `class Run:` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The identifier, which can be referenced in API endpoints. - - `INCOMPLETE("incomplete")` + - `String assistantId` - - `JsonValue; type "function_call_output"constant` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The type of the function tool call output. Always `function_call_output`. + - `Optional cancelledAt` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + The Unix timestamp (in seconds) for when the run was cancelled. - - `Optional agent` + - `Optional completedAt` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run was completed. - - `String agentName` + - `long createdAt` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run was created. - - `Optional caller` + - `Optional expiresAt` - The execution context that produced this tool call. + The Unix timestamp (in seconds) for when the run will expire. - - `JsonValue;` + - `Optional failedAt` - - `JsonValue; type "direct"constant` + The Unix timestamp (in seconds) for when the run failed. - The caller type. Always `direct`. + - `Optional incompleteDetails` - - `DIRECT("direct")` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `class Program:` + - `Optional reason` - - `String callerId` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The call ID of the program item that produced this tool call. + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `JsonValue; type "program"constant` + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - The caller type. Always `program`. + - `String instructions` - - `PROGRAM("program")` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `Optional createdBy` + - `Optional lastError` - The identifier of the actor that created the item. + The last error associated with this run. Will be `null` if there are no errors. - - `AgentMessage` + - `Code code` - - `String id` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The unique ID of the agent message. + - `SERVER_ERROR("server_error")` - - `String author` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The sending agent identity. + - `INVALID_PROMPT("invalid_prompt")` - - `List content` + - `String message` - Encrypted content sent between agents. + A human-readable description of the error. - - `class BetaResponseInputText:` + - `Optional maxCompletionTokens` - A text input to the model. + The maximum number of completion tokens specified to have been used over the course of the run. - - `class BetaResponseOutputText:` + - `Optional maxPromptTokens` - A text output from the model. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `class Text:` + - `Optional metadata` - A text content. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `String text` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `JsonValue; type "text"constant` + - `String model` - - `TEXT("text")` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `class SummaryText:` + - `JsonValue; object_ "thread.run"constant` - A summary text from the model. + The object type, which is always `thread.run`. - - `String text` + - `THREAD_RUN("thread.run")` - A summary of the reasoning output from the model so far. + - `boolean parallelToolCalls` - - `JsonValue; type "summary_text"constant` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The type of the object. Always `summary_text`. + - `Optional requiredAction` - - `SUMMARY_TEXT("summary_text")` + Details on the action required to continue the run. Will be `null` if no action is required. - - `class ReasoningText:` + - `SubmitToolOutputs submitToolOutputs` - Reasoning text from the model. + Details on the tool outputs needed for this run to continue. - - `String text` + - `List toolCalls` - The reasoning text from the model. + A list of the relevant tool calls. - - `JsonValue; type "reasoning_text"constant` + - `String id` - The type of the reasoning text. Always `reasoning_text`. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `REASONING_TEXT("reasoning_text")` + - `Function function` - - `class BetaResponseOutputRefusal:` + The function definition. - A refusal from the model. + - `String arguments` - - `class BetaResponseInputImage:` + The arguments that the model expects you to pass to the function. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `String name` - - `class ComputerScreenshot:` + The name of the function. - A screenshot of a computer. + - `JsonValue; type "function"constant` - - `Detail detail` + The type of tool call the output is required for. For now, this is always `function`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `FUNCTION("function")` - - `LOW("low")` + - `JsonValue; type "submit_tool_outputs"constant` - - `HIGH("high")` + For now, this is always `submit_tool_outputs`. - - `AUTO("auto")` + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - - `ORIGINAL("original")` + - `Optional responseFormat` - - `Optional fileId` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The identifier of an uploaded file that contains the screenshot. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional imageUrl` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The URL of the screenshot image. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `JsonValue; type "computer_screenshot"constant` + - `JsonValue;` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `AUTO("auto")` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + - `class ResponseFormatText:` - - `Optional promptCacheBreakpoint` + Default response format. Used to generate text responses. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `JsonValue; type "text"constant` - - `JsonValue; mode "explicit"constant` + The type of response format being defined. Always `text`. - The breakpoint mode. Always `explicit`. + - `TEXT("text")` - - `EXPLICIT("explicit")` + - `class ResponseFormatJsonObject:` - - `class BetaResponseInputFile:` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - A file input to the model. + - `JsonValue; type "json_object"constant` - - `class EncryptedContent:` + The type of response format being defined. Always `json_object`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `JSON_OBJECT("json_object")` - - `String encryptedContent` + - `class ResponseFormatJsonSchema:` - Opaque encrypted content. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `JsonValue; type "encrypted_content"constant` + - `JsonSchema jsonSchema` - The type of the input item. Always `encrypted_content`. + Structured Outputs configuration options, including a JSON Schema. - - `ENCRYPTED_CONTENT("encrypted_content")` + - `String name` - - `String recipient` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The destination agent identity. + - `Optional description` - - `JsonValue; type "agent_message"constant` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The type of the item. Always `agent_message`. + - `Optional schema` - - `AGENT_MESSAGE("agent_message")` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `Optional agent` + - `Optional strict` - The agent that produced this item. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `String agentName` + - `JsonValue; type "json_schema"constant` - The canonical name of the agent that produced this item. + The type of response format being defined. Always `json_schema`. - - `MultiAgentCall` + - `JSON_SCHEMA("json_schema")` - - `String id` + - `Optional startedAt` - The unique ID of the multi-agent call item. + The Unix timestamp (in seconds) for when the run was started. - - `Action action` + - `RunStatus status` - The multi-agent action to execute. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `SPAWN_AGENT("spawn_agent")` + - `QUEUED("queued")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `IN_PROGRESS("in_progress")` - - `LIST_AGENTS("list_agents")` + - `REQUIRES_ACTION("requires_action")` - - `SEND_MESSAGE("send_message")` + - `CANCELLING("cancelling")` - - `FOLLOWUP_TASK("followup_task")` + - `CANCELLED("cancelled")` - - `WAIT_AGENT("wait_agent")` + - `FAILED("failed")` - - `String arguments` + - `COMPLETED("completed")` - The JSON string of arguments generated for the action. + - `INCOMPLETE("incomplete")` - - `String callId` + - `EXPIRED("expired")` - The unique ID linking this call to its output. + - `String threadId` - - `JsonValue; type "multi_agent_call"constant` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The type of the multi-agent call. Always `multi_agent_call`. + - `Optional toolChoice` - - `MULTI_AGENT_CALL("multi_agent_call")` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `Optional agent` + - `Auto` - The agent that produced this item. + - `NONE("none")` - - `String agentName` + - `AUTO("auto")` - The canonical name of the agent that produced this item. + - `REQUIRED("required")` - - `MultiAgentCallOutput` + - `class AssistantToolChoice:` - - `String id` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The unique ID of the multi-agent call output item. + - `Type type` - - `Action action` + The type of the tool. If type is `function`, the function name must be set - The multi-agent action that produced this result. + - `FUNCTION("function")` - - `SPAWN_AGENT("spawn_agent")` + - `CODE_INTERPRETER("code_interpreter")` - - `INTERRUPT_AGENT("interrupt_agent")` + - `FILE_SEARCH("file_search")` - - `LIST_AGENTS("list_agents")` + - `Optional function` - - `SEND_MESSAGE("send_message")` + - `String name` - - `FOLLOWUP_TASK("followup_task")` + The name of the function to call. - - `WAIT_AGENT("wait_agent")` + - `List tools` - - `String callId` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The unique ID of the multi-agent call. + - `class CodeInterpreterTool:` - - `List output` + - `JsonValue; type "code_interpreter"constant` - Text output returned by the multi-agent action. + The type of tool being defined: `code_interpreter` - - `List annotations` + - `CODE_INTERPRETER("code_interpreter")` - The annotations of the text output. + - `class FileSearchTool:` - - `String text` + - `JsonValue; type "file_search"constant` - The text output from the model. + The type of tool being defined: `file_search` - - `JsonValue; type "output_text"constant` + - `FILE_SEARCH("file_search")` - The type of the output text. Always `output_text`. + - `Optional fileSearch` - - `Optional> logprobs` + Overrides for the file search tool. - - `JsonValue; type "multi_agent_call_output"constant` + - `Optional maxNumResults` - The type of the multi-agent result. Always `multi_agent_call_output`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Optional agent` + - `Optional rankingOptions` - The agent that produced this item. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `String agentName` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The canonical name of the agent that produced this item. + - `double scoreThreshold` - - `class BetaResponseToolSearchCall:` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `String id` + - `Optional ranker` - The unique ID of the tool search call item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `JsonValue arguments` + - `AUTO("auto")` - Arguments used for the tool search call. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `Optional callId` + - `class FunctionTool:` - The unique ID of the tool search call generated by the model. + - `FunctionDefinition function` - - `Execution execution` + - `String name` - Whether tool search was executed by the server or by the client. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `SERVER("server")` + - `Optional description` - - `CLIENT("client")` + A description of what the function does, used by the model to choose when and how to call the function. - - `Status status` + - `Optional parameters` - The status of the tool search call item that was recorded. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `IN_PROGRESS("in_progress")` + Omitting `parameters` defines a function with an empty parameter list. - - `COMPLETED("completed")` + - `Optional strict` - - `INCOMPLETE("incomplete")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `JsonValue; type "tool_search_call"constant` + - `JsonValue; type "function"constant` - The type of the item. Always `tool_search_call`. + The type of tool being defined: `function` - - `TOOL_SEARCH_CALL("tool_search_call")` + - `FUNCTION("function")` - - `Optional agent` + - `Optional truncationStrategy` - The agent that produced this item. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `String agentName` + - `Type type` - The canonical name of the agent that produced this item. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `Optional createdBy` + - `AUTO("auto")` - The identifier of the actor that created the item. + - `LAST_MESSAGES("last_messages")` - - `class BetaResponseToolSearchOutputItem:` + - `Optional lastMessages` - - `String id` + The number of most recent messages from the thread when constructing the context for the run. - The unique ID of the tool search output item. + - `Optional usage` - - `Optional callId` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The unique ID of the tool search call generated by the model. + - `long completionTokens` - - `Execution execution` + Number of completion tokens used over the course of the run. - Whether tool search was executed by the server or by the client. + - `long promptTokens` - - `SERVER("server")` + Number of prompt tokens used over the course of the run. - - `CLIENT("client")` + - `long totalTokens` - - `Status status` + Total number of tokens used (prompt + completion). - The status of the tool search output item that was recorded. + - `Optional temperature` - - `IN_PROGRESS("in_progress")` + The sampling temperature used for this run. If not set, defaults to 1. - - `COMPLETED("completed")` + - `Optional topP` - - `INCOMPLETE("incomplete")` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `List tools` +### Example - The loaded tool definitions returned by tool search. +```java +package com.openai.example; - - `class BetaFunctionTool:` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.runs.Run; +import com.openai.models.beta.threads.runs.RunSubmitToolOutputsParams; - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). +public final class Main { + private Main() {} - - `String name` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The name of the function to call. + RunSubmitToolOutputsParams params = RunSubmitToolOutputsParams.builder() + .threadId("thread_id") + .runId("run_id") + .addToolOutput(RunSubmitToolOutputsParams.ToolOutput.builder().build()) + .build(); + Run run = client.beta().threads().runs().submitToolOutputs(params); + } +} +``` - - `Optional parameters` +#### Response - A JSON schema object describing the parameters of the function. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `Optional strict` +## Cancel a run - Whether strict parameter validation is enforced for this function tool. +`Run beta().threads().runs().cancel(RunCancelParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `JsonValue; type "function"constant` +**post** `/threads/{thread_id}/runs/{run_id}/cancel` - The type of the function tool. Always `function`. +Cancels a run that is `in_progress`. - - `FUNCTION("function")` +### Parameters - - `Optional> allowedCallers` +- `RunCancelParams params` - The tool invocation context(s). + - `String threadId` - - `DIRECT("direct")` + - `Optional runId` - - `PROGRAMMATIC("programmatic")` +### Returns - - `Optional deferLoading` +- `class Run:` - Whether this function is deferred and loaded via tool search. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `Optional description` + - `String id` - A description of the function. Used by the model to determine whether or not to call the function. + The identifier, which can be referenced in API endpoints. - - `Optional outputSchema` + - `String assistantId` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `class BetaFileSearchTool:` + - `Optional cancelledAt` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + The Unix timestamp (in seconds) for when the run was cancelled. - - `JsonValue; type "file_search"constant` + - `Optional completedAt` - The type of the file search tool. Always `file_search`. + The Unix timestamp (in seconds) for when the run was completed. - - `FILE_SEARCH("file_search")` + - `long createdAt` - - `List vectorStoreIds` + The Unix timestamp (in seconds) for when the run was created. - The IDs of the vector stores to search. + - `Optional expiresAt` - - `Optional filters` + The Unix timestamp (in seconds) for when the run will expire. - A filter to apply. + - `Optional failedAt` - - `class ComparisonFilter:` + The Unix timestamp (in seconds) for when the run failed. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `Optional incompleteDetails` - - `String key` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The key to compare against the value. + - `Optional reason` - - `Type type` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - - `EQ("eq")` + - `String instructions` - - `NE("ne")` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `GT("gt")` + - `Optional lastError` - - `GTE("gte")` + The last error associated with this run. Will be `null` if there are no errors. - - `LT("lt")` + - `Code code` - - `LTE("lte")` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `IN("in")` + - `SERVER_ERROR("server_error")` - - `NIN("nin")` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `Value value` + - `INVALID_PROMPT("invalid_prompt")` - The value to compare against the attribute key; supports string, number, or boolean types. + - `String message` - - `String` + A human-readable description of the error. - - `double` + - `Optional maxCompletionTokens` - - `boolean` + The maximum number of completion tokens specified to have been used over the course of the run. - - `List` + - `Optional maxPromptTokens` - - `class CompoundFilter:` + The maximum number of prompt tokens specified to have been used over the course of the run. - Combine multiple filters using `and` or `or`. + - `Optional metadata` - - `List filters` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class ComparisonFilter:` + - `String model` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `String key` + - `JsonValue; object_ "thread.run"constant` - The key to compare against the value. + The object type, which is always `thread.run`. - - `Type type` + - `THREAD_RUN("thread.run")` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `boolean parallelToolCalls` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `EQ("eq")` + - `Optional requiredAction` - - `NE("ne")` + Details on the action required to continue the run. Will be `null` if no action is required. - - `GT("gt")` + - `SubmitToolOutputs submitToolOutputs` - - `GTE("gte")` + Details on the tool outputs needed for this run to continue. - - `LT("lt")` + - `List toolCalls` - - `LTE("lte")` + A list of the relevant tool calls. - - `IN("in")` + - `String id` - - `NIN("nin")` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `Value value` + - `Function function` - The value to compare against the attribute key; supports string, number, or boolean types. + The function definition. - - `String` + - `String arguments` - - `double` + The arguments that the model expects you to pass to the function. - - `boolean` + - `String name` - - `List` + The name of the function. - - `JsonValue` + - `JsonValue; type "function"constant` - - `Type type` + The type of tool call the output is required for. For now, this is always `function`. - Type of operation: `and` or `or`. + - `FUNCTION("function")` - - `AND("and")` + - `JsonValue; type "submit_tool_outputs"constant` - - `OR("or")` + For now, this is always `submit_tool_outputs`. - - `Optional maxNumResults` + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `Optional responseFormat` - - `Optional rankingOptions` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - Ranking options for search. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `Optional hybridSearch` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `double embeddingWeight` + - `JsonValue;` - The weight of the embedding in the reciprocal ranking fusion. + - `AUTO("auto")` - - `double textWeight` + - `class ResponseFormatText:` - The weight of the text in the reciprocal ranking fusion. + Default response format. Used to generate text responses. - - `Optional ranker` + - `JsonValue; type "text"constant` - The ranker to use for the file search. + The type of response format being defined. Always `text`. - - `AUTO("auto")` + - `TEXT("text")` - - `DEFAULT_2024_11_15("default-2024-11-15")` + - `class ResponseFormatJsonObject:` - - `Optional scoreThreshold` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The 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. + - `JsonValue; type "json_object"constant` - - `class BetaComputerTool:` + The type of response format being defined. Always `json_object`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `JSON_OBJECT("json_object")` - - `JsonValue; type "computer"constant` + - `class ResponseFormatJsonSchema:` - The type of the computer tool. Always `computer`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `COMPUTER("computer")` + - `JsonSchema jsonSchema` - - `class BetaComputerUsePreviewTool:` + Structured Outputs configuration options, including a JSON Schema. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String name` - - `long displayHeight` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The height of the computer display. + - `Optional description` - - `long displayWidth` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The width of the computer display. + - `Optional schema` - - `Environment environment` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The type of computer environment to control. + - `Optional strict` - - `WINDOWS("windows")` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `MAC("mac")` + - `JsonValue; type "json_schema"constant` - - `LINUX("linux")` + The type of response format being defined. Always `json_schema`. - - `UBUNTU("ubuntu")` + - `JSON_SCHEMA("json_schema")` - - `BROWSER("browser")` + - `Optional startedAt` - - `JsonValue; type "computer_use_preview"constant` + The Unix timestamp (in seconds) for when the run was started. - The type of the computer use tool. Always `computer_use_preview`. + - `RunStatus status` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `class BetaWebSearchTool:` + - `QUEUED("queued")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `IN_PROGRESS("in_progress")` - - `Type type` + - `REQUIRES_ACTION("requires_action")` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `CANCELLING("cancelling")` - - `WEB_SEARCH("web_search")` + - `CANCELLED("cancelled")` - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` + - `FAILED("failed")` - - `Optional filters` + - `COMPLETED("completed")` - Filters for the search. + - `INCOMPLETE("incomplete")` - - `Optional> allowedDomains` + - `EXPIRED("expired")` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `String threadId` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `Optional searchContextSize` + - `Optional toolChoice` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `LOW("low")` + - `Auto` - - `MEDIUM("medium")` + - `NONE("none")` - - `HIGH("high")` + - `AUTO("auto")` - - `Optional userLocation` + - `REQUIRED("required")` - The approximate location of the user. + - `class AssistantToolChoice:` - - `Optional city` + Specifies a tool the model should use. Use to force the model to call a specific tool. - Free text input for the city of the user, e.g. `San Francisco`. + - `Type type` - - `Optional country` + The type of the tool. If type is `function`, the function name must be set - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `FUNCTION("function")` - - `Optional region` + - `CODE_INTERPRETER("code_interpreter")` - Free text input for the region of the user, e.g. `California`. + - `FILE_SEARCH("file_search")` - - `Optional timezone` + - `Optional function` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `String name` - - `Optional type` + The name of the function to call. - The type of location approximation. Always `approximate`. + - `List tools` - - `APPROXIMATE("approximate")` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `Mcp` + - `class CodeInterpreterTool:` - - `String serverLabel` + - `JsonValue; type "code_interpreter"constant` - A label for this MCP server, used to identify it in tool calls. + The type of tool being defined: `code_interpreter` - - `JsonValue; type "mcp"constant` + - `CODE_INTERPRETER("code_interpreter")` - The type of the MCP tool. Always `mcp`. + - `class FileSearchTool:` - - `MCP("mcp")` + - `JsonValue; type "file_search"constant` - - `Optional> allowedCallers` + The type of tool being defined: `file_search` - The tool invocation context(s). + - `FILE_SEARCH("file_search")` - - `DIRECT("direct")` + - `Optional fileSearch` - - `PROGRAMMATIC("programmatic")` + Overrides for the file search tool. - - `Optional allowedTools` + - `Optional maxNumResults` - List of allowed tool names or a filter object. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `List` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class McpToolFilter:` + - `Optional rankingOptions` - A filter object to specify which tools are allowed. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `Optional readOnly` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `double scoreThreshold` - - `Optional> toolNames` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - List of allowed tool names. + - `Optional ranker` - - `Optional authorization` + The ranker to use for the file search. If not specified will use the `auto` ranker. - 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. + - `AUTO("auto")` - - `Optional connectorId` + - `DEFAULT_2024_08_21("default_2024_08_21")` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `class FunctionTool:` - Currently supported `connector_id` values are: + - `FunctionDefinition function` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `String name` - - `CONNECTOR_DROPBOX("connector_dropbox")` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `CONNECTOR_GMAIL("connector_gmail")` + - `Optional description` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + A description of what the function does, used by the model to choose when and how to call the function. - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `Optional parameters` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + Omitting `parameters` defines a function with an empty parameter list. - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `Optional strict` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `Optional deferLoading` + - `JsonValue; type "function"constant` - Whether this MCP tool is deferred and discovered via tool search. + The type of tool being defined: `function` - - `Optional headers` + - `FUNCTION("function")` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `Optional truncationStrategy` - - `Optional requireApproval` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - Specify which of the MCP server's tools require approval. + - `Type type` - - `class McpToolApprovalFilter:` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `AUTO("auto")` - - `Optional always` + - `LAST_MESSAGES("last_messages")` - A filter object to specify which tools are allowed. + - `Optional lastMessages` - - `Optional readOnly` + The number of most recent messages from the thread when constructing the context for the run. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `Optional usage` - - `Optional> toolNames` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - List of allowed tool names. + - `long completionTokens` - - `Optional never` + Number of completion tokens used over the course of the run. - A filter object to specify which tools are allowed. + - `long promptTokens` - - `Optional readOnly` + Number of prompt tokens used over the course of the run. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `long totalTokens` - - `Optional> toolNames` + Total number of tokens used (prompt + completion). - List of allowed tool names. + - `Optional temperature` - - `enum McpToolApprovalSetting:` + The sampling temperature used for this run. If not set, defaults to 1. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `Optional topP` - - `ALWAYS("always")` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `NEVER("never")` +### Example - - `Optional serverDescription` +```java +package com.openai.example; - Optional description of the MCP server, used to provide more context. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.runs.Run; +import com.openai.models.beta.threads.runs.RunCancelParams; - - `Optional serverUrl` +public final class Main { + private Main() {} - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `Optional tunnelId` + RunCancelParams params = RunCancelParams.builder() + .threadId("thread_id") + .runId("run_id") + .build(); + Run run = client.beta().threads().runs().cancel(params); + } +} +``` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. +#### Response - - `CodeInterpreter` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `Container container` +## Domain Types - 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. +### Required Action Function Tool Call - - `String` +- `class RequiredActionFunctionToolCall:` - - `class CodeInterpreterToolAuto:` + Tool call objects - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `String id` - - `JsonValue; type "auto"constant` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - Always `auto`. + - `Function function` - - `AUTO("auto")` + The function definition. - - `Optional> fileIds` + - `String arguments` - An optional list of uploaded files to make available to your code. + The arguments that the model expects you to pass to the function. - - `Optional memoryLimit` + - `String name` - The memory limit for the code interpreter container. + The name of the function. - - `_1G("1g")` + - `JsonValue; type "function"constant` - - `_4G("4g")` + The type of tool call the output is required for. For now, this is always `function`. - - `_16G("16g")` + - `FUNCTION("function")` - - `_64G("64g")` +### Run - - `Optional networkPolicy` +- `class Run:` - Network access policy for the container. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `class BetaContainerNetworkPolicyDisabled:` + - `String id` - - `JsonValue; type "disabled"constant` + The identifier, which can be referenced in API endpoints. - Disable outbound network access. Always `disabled`. + - `String assistantId` - - `DISABLED("disabled")` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `class BetaContainerNetworkPolicyAllowlist:` + - `Optional cancelledAt` - - `List allowedDomains` + The Unix timestamp (in seconds) for when the run was cancelled. - A list of allowed domains when type is `allowlist`. + - `Optional completedAt` - - `JsonValue; type "allowlist"constant` + The Unix timestamp (in seconds) for when the run was completed. - Allow outbound network access only to specified domains. Always `allowlist`. + - `long createdAt` - - `ALLOWLIST("allowlist")` + The Unix timestamp (in seconds) for when the run was created. - - `Optional> domainSecrets` + - `Optional expiresAt` - Optional domain-scoped secrets for allowlisted domains. + The Unix timestamp (in seconds) for when the run will expire. - - `String domain` + - `Optional failedAt` - The domain associated with the secret. + The Unix timestamp (in seconds) for when the run failed. - - `String name` + - `Optional incompleteDetails` - The name of the secret to inject for the domain. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `String value` + - `Optional reason` - The secret value to inject for the domain. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `JsonValue; type "code_interpreter"constant` + - `MAX_COMPLETION_TOKENS("max_completion_tokens")` - The type of the code interpreter tool. Always `code_interpreter`. + - `MAX_PROMPT_TOKENS("max_prompt_tokens")` - - `CODE_INTERPRETER("code_interpreter")` + - `String instructions` - - `Optional> allowedCallers` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The tool invocation context(s). + - `Optional lastError` - - `DIRECT("direct")` + The last error associated with this run. Will be `null` if there are no errors. - - `PROGRAMMATIC("programmatic")` + - `Code code` - - `JsonValue;` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `JsonValue; type "programmatic_tool_calling"constant` + - `SERVER_ERROR("server_error")` - The type of the tool. Always `programmatic_tool_calling`. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `INVALID_PROMPT("invalid_prompt")` - - `ImageGeneration` + - `String message` - - `JsonValue; type "image_generation"constant` + A human-readable description of the error. - The type of the image generation tool. Always `image_generation`. + - `Optional maxCompletionTokens` - - `IMAGE_GENERATION("image_generation")` + The maximum number of completion tokens specified to have been used over the course of the run. - - `Optional action` + - `Optional maxPromptTokens` - Whether to generate a new image or edit an existing image. Default: `auto`. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `GENERATE("generate")` + - `Optional metadata` - - `EDIT("edit")` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `AUTO("auto")` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Optional background` + - `String model` - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. + - `JsonValue; object_ "thread.run"constant` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The object type, which is always `thread.run`. - - `TRANSPARENT("transparent")` + - `THREAD_RUN("thread.run")` - - `OPAQUE("opaque")` + - `boolean parallelToolCalls` - - `AUTO("auto")` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `Optional inputFidelity` + - `Optional requiredAction` - 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`. + Details on the action required to continue the run. Will be `null` if no action is required. - - `HIGH("high")` + - `SubmitToolOutputs submitToolOutputs` - - `LOW("low")` + Details on the tool outputs needed for this run to continue. - - `Optional inputImageMask` + - `List toolCalls` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A list of the relevant tool calls. - - `Optional fileId` + - `String id` - File ID for the mask image. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `Optional imageUrl` + - `Function function` - Base64-encoded mask image. + The function definition. - - `Optional model` + - `String arguments` - The image generation model to use. Default: `gpt-image-1`. + The arguments that the model expects you to pass to the function. - - `GPT_IMAGE_1("gpt-image-1")` + - `String name` - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + The name of the function. - - `GPT_IMAGE_2("gpt-image-2")` + - `JsonValue; type "function"constant` - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + The type of tool call the output is required for. For now, this is always `function`. - - `GPT_IMAGE_1_5("gpt-image-1.5")` + - `FUNCTION("function")` - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `JsonValue; type "submit_tool_outputs"constant` - - `Optional moderation` + For now, this is always `submit_tool_outputs`. - Moderation level for the generated image. Default: `auto`. + - `SUBMIT_TOOL_OUTPUTS("submit_tool_outputs")` - - `AUTO("auto")` + - `Optional responseFormat` - - `LOW("low")` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `Optional outputCompression` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - Compression level for the output image. Default: 100. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `Optional outputFormat` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `JsonValue;` - - `PNG("png")` + - `AUTO("auto")` - - `WEBP("webp")` + - `class ResponseFormatText:` - - `JPEG("jpeg")` + Default response format. Used to generate text responses. - - `Optional partialImages` + - `JsonValue; type "text"constant` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The type of response format being defined. Always `text`. - - `Optional quality` + - `TEXT("text")` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `class ResponseFormatJsonObject:` - - `LOW("low")` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `MEDIUM("medium")` + - `JsonValue; type "json_object"constant` - - `HIGH("high")` + The type of response format being defined. Always `json_object`. - - `AUTO("auto")` + - `JSON_OBJECT("json_object")` - - `Optional size` + - `class ResponseFormatJsonSchema:` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `_1024X1024("1024x1024")` + - `JsonSchema jsonSchema` - - `_1024X1536("1024x1536")` + Structured Outputs configuration options, including a JSON Schema. - - `_1536X1024("1536x1024")` + - `String name` - - `AUTO("auto")` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `JsonValue;` + - `Optional description` - - `JsonValue; type "local_shell"constant` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The type of the local shell tool. Always `local_shell`. + - `Optional schema` - - `LOCAL_SHELL("local_shell")` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `class BetaFunctionShellTool:` + - `Optional strict` - A tool that allows the model to execute shell commands. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `JsonValue; type "shell"constant` + - `JsonValue; type "json_schema"constant` - The type of the shell tool. Always `shell`. + The type of response format being defined. Always `json_schema`. - - `SHELL("shell")` + - `JSON_SCHEMA("json_schema")` - - `Optional> allowedCallers` + - `Optional startedAt` - The tool invocation context(s). + The Unix timestamp (in seconds) for when the run was started. - - `DIRECT("direct")` + - `RunStatus status` - - `PROGRAMMATIC("programmatic")` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `Optional environment` + - `QUEUED("queued")` - - `class BetaContainerAuto:` + - `IN_PROGRESS("in_progress")` - - `JsonValue; type "container_auto"constant` + - `REQUIRES_ACTION("requires_action")` - Automatically creates a container for this request + - `CANCELLING("cancelling")` - - `CONTAINER_AUTO("container_auto")` + - `CANCELLED("cancelled")` - - `Optional> fileIds` + - `FAILED("failed")` - An optional list of uploaded files to make available to your code. + - `COMPLETED("completed")` - - `Optional memoryLimit` + - `INCOMPLETE("incomplete")` - The memory limit for the container. + - `EXPIRED("expired")` - - `_1G("1g")` + - `String threadId` - - `_4G("4g")` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `_16G("16g")` + - `Optional toolChoice` - - `_64G("64g")` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `Optional networkPolicy` + - `Auto` - Network access policy for the container. + - `NONE("none")` - - `class BetaContainerNetworkPolicyDisabled:` + - `AUTO("auto")` - - `class BetaContainerNetworkPolicyAllowlist:` + - `REQUIRED("required")` - - `Optional> skills` + - `class AssistantToolChoice:` - An optional list of skills referenced by id or inline data. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `class BetaSkillReference:` + - `Type type` - - `String skillId` + The type of the tool. If type is `function`, the function name must be set - The ID of the referenced skill. + - `FUNCTION("function")` - - `JsonValue; type "skill_reference"constant` + - `CODE_INTERPRETER("code_interpreter")` - References a skill created with the /v1/skills endpoint. + - `FILE_SEARCH("file_search")` - - `SKILL_REFERENCE("skill_reference")` + - `Optional function` - - `Optional version` + - `String name` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The name of the function to call. - - `class BetaInlineSkill:` + - `List tools` - - `String description` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The description of the skill. + - `class CodeInterpreterTool:` - - `String name` + - `JsonValue; type "code_interpreter"constant` - The name of the skill. + The type of tool being defined: `code_interpreter` - - `BetaInlineSkillSource source` + - `CODE_INTERPRETER("code_interpreter")` - Inline skill payload + - `class FileSearchTool:` - - `String data` + - `JsonValue; type "file_search"constant` - Base64-encoded skill zip bundle. + The type of tool being defined: `file_search` - - `JsonValue; mediaType "application/zip"constant` + - `FILE_SEARCH("file_search")` - The media type of the inline skill payload. Must be `application/zip`. + - `Optional fileSearch` - - `APPLICATION_ZIP("application/zip")` + Overrides for the file search tool. - - `JsonValue; type "base64"constant` + - `Optional maxNumResults` - The type of the inline skill source. Must be `base64`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `BASE64("base64")` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `JsonValue; type "inline"constant` + - `Optional rankingOptions` - Defines an inline skill for this request. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `INLINE("inline")` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `class BetaLocalEnvironment:` + - `double scoreThreshold` - - `JsonValue; type "local"constant` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Use a local computer environment. + - `Optional ranker` - - `LOCAL("local")` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `Optional> skills` + - `AUTO("auto")` - An optional list of skills. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `String description` + - `class FunctionTool:` - The description of the skill. + - `FunctionDefinition function` - `String name` - The name of the skill. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `String path` + - `Optional description` - The path to the directory containing the skill. + A description of what the function does, used by the model to choose when and how to call the function. - - `class BetaContainerReference:` + - `Optional parameters` - - `String containerId` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The ID of the referenced container. + Omitting `parameters` defines a function with an empty parameter list. - - `JsonValue; type "container_reference"constant` + - `Optional strict` - References a container created with the /v1/containers endpoint + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `CONTAINER_REFERENCE("container_reference")` + - `JsonValue; type "function"constant` - - `class BetaCustomTool:` + The type of tool being defined: `function` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `FUNCTION("function")` - - `String name` + - `Optional truncationStrategy` - The name of the custom tool, used to identify it in tool calls. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `JsonValue; type "custom"constant` + - `Type type` - The type of the custom tool. Always `custom`. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `CUSTOM("custom")` + - `AUTO("auto")` - - `Optional> allowedCallers` + - `LAST_MESSAGES("last_messages")` - The tool invocation context(s). + - `Optional lastMessages` - - `DIRECT("direct")` + The number of most recent messages from the thread when constructing the context for the run. - - `PROGRAMMATIC("programmatic")` + - `Optional usage` - - `Optional deferLoading` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - Whether this tool should be deferred and discovered via tool search. + - `long completionTokens` - - `Optional description` + Number of completion tokens used over the course of the run. - Optional description of the custom tool, used to provide more context. + - `long promptTokens` - - `Optional format` + Number of prompt tokens used over the course of the run. - The input format for the custom tool. Default is unconstrained text. + - `long totalTokens` - - `JsonValue;` + Total number of tokens used (prompt + completion). - - `JsonValue; type "text"constant` + - `Optional temperature` - Unconstrained text format. Always `text`. + The sampling temperature used for this run. If not set, defaults to 1. - - `TEXT("text")` + - `Optional topP` - - `class Grammar:` + The nucleus sampling value used for this run. If not set, defaults to 1. - A grammar defined by the user. +### Run Status - - `String definition` +- `enum RunStatus:` - The grammar definition. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `Syntax syntax` + - `QUEUED("queued")` - The syntax of the grammar definition. One of `lark` or `regex`. + - `IN_PROGRESS("in_progress")` - - `LARK("lark")` + - `REQUIRES_ACTION("requires_action")` - - `REGEX("regex")` + - `CANCELLING("cancelling")` - - `JsonValue; type "grammar"constant` + - `CANCELLED("cancelled")` - Grammar format. Always `grammar`. + - `FAILED("failed")` - - `GRAMMAR("grammar")` + - `COMPLETED("completed")` - - `class BetaNamespaceTool:` + - `INCOMPLETE("incomplete")` - Groups function/custom tools under a shared namespace. + - `EXPIRED("expired")` - - `String description` +# Steps - A description of the namespace shown to the model. +## List run steps - - `String name` +`StepListPage beta().threads().runs().steps().list(StepListParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - The namespace name used in tool calls (for example, `crm`). +**get** `/threads/{thread_id}/runs/{run_id}/steps` - - `List tools` +Returns a list of run steps belonging to a run. - The function/custom tools available inside this namespace. +### Parameters - - `class Function:` +- `StepListParams params` - - `String name` + - `String threadId` - - `JsonValue; type "function"constant` + - `Optional runId` - - `FUNCTION("function")` + - `Optional after` - - `Optional> allowedCallers` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - The tool invocation context(s). + - `Optional before` - - `DIRECT("direct")` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - - `PROGRAMMATIC("programmatic")` + - `Optional> include` - - `Optional deferLoading` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - Whether this function should be deferred and discovered via tool search. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `Optional description` + - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` - - `Optional outputSchema` + - `Optional limit` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `Optional parameters` + - `Optional order` - - `Optional strict` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `ASC("asc")` - - `class BetaCustomTool:` + - `DESC("desc")` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) +### Returns - - `JsonValue; type "namespace"constant` +- `class RunStep:` - The type of the tool. Always `namespace`. + Represents a step in execution of a run. - - `NAMESPACE("namespace")` + - `String id` - - `class BetaToolSearchTool:` + The identifier of the run step, which can be referenced in API endpoints. - Hosted or BYOT tool search configuration for deferred tools. + - `String assistantId` - - `JsonValue; type "tool_search"constant` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The type of the tool. Always `tool_search`. + - `Optional cancelledAt` - - `TOOL_SEARCH("tool_search")` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `Optional description` + - `Optional completedAt` - Description shown to the model for a client-executed tool search tool. + The Unix timestamp (in seconds) for when the run step completed. - - `Optional execution` + - `long createdAt` - Whether tool search is executed by the server or by the client. + The Unix timestamp (in seconds) for when the run step was created. - - `SERVER("server")` + - `Optional expiredAt` - - `CLIENT("client")` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `Optional parameters` + - `Optional failedAt` - Parameter schema for a client-executed tool search tool. + The Unix timestamp (in seconds) for when the run step failed. - - `class BetaWebSearchPreviewTool:` + - `Optional lastError` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The last error associated with this run step. Will be `null` if there are no errors. - - `Type type` + - `Code code` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + One of `server_error` or `rate_limit_exceeded`. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `SERVER_ERROR("server_error")` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `Optional> searchContentTypes` + - `String message` - - `TEXT("text")` + A human-readable description of the error. - - `IMAGE("image")` + - `Optional metadata` - - `Optional searchContextSize` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `LOW("low")` + - `JsonValue; object_ "thread.run.step"constant` - - `MEDIUM("medium")` + The object type, which is always `thread.run.step`. - - `HIGH("high")` + - `THREAD_RUN_STEP("thread.run.step")` - - `Optional userLocation` + - `String runId` - The user's location. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `JsonValue; type "approximate"constant` + - `Status status` - The type of location approximation. Always `approximate`. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `APPROXIMATE("approximate")` + - `IN_PROGRESS("in_progress")` - - `Optional city` + - `CANCELLED("cancelled")` - Free text input for the city of the user, e.g. `San Francisco`. + - `FAILED("failed")` - - `Optional country` + - `COMPLETED("completed")` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `EXPIRED("expired")` - - `Optional region` + - `StepDetails stepDetails` - Free text input for the region of the user, e.g. `California`. + The details of the run step. - - `Optional timezone` + - `class MessageCreationStepDetails:` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Details of the message creation by the run step. - - `class BetaApplyPatchTool:` + - `MessageCreation messageCreation` - Allows the assistant to create, delete, or update files using unified diffs. + - `String messageId` - - `JsonValue; type "apply_patch"constant` + The ID of the message that was created by this run step. - The type of the tool. Always `apply_patch`. + - `JsonValue; type "message_creation"constant` - - `APPLY_PATCH("apply_patch")` + Always `message_creation`. - - `Optional> allowedCallers` + - `MESSAGE_CREATION("message_creation")` - The tool invocation context(s). + - `class ToolCallsStepDetails:` - - `DIRECT("direct")` + Details of the tool call. - - `PROGRAMMATIC("programmatic")` + - `List toolCalls` - - `JsonValue; type "tool_search_output"constant` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The type of the item. Always `tool_search_output`. + - `class CodeInterpreterToolCall:` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + Details of the Code Interpreter tool call the run step was involved in. - - `Optional agent` + - `String id` - The agent that produced this item. + The ID of the tool call. - - `String agentName` + - `CodeInterpreter codeInterpreter` - The canonical name of the agent that produced this item. + The Code Interpreter tool call definition. - - `Optional createdBy` + - `String input` - The identifier of the actor that created the item. + The input to the Code Interpreter tool call. - - `AdditionalTools` + - `List outputs` - - `String id` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The unique ID of the additional tools item. + - `class LogsOutput:` - - `Role role` + Text output from the Code Interpreter tool call as part of a run step. - The role that provided the additional tools. + - `String logs` - - `UNKNOWN("unknown")` + The text output from the Code Interpreter tool call. - - `USER("user")` + - `JsonValue; type "logs"constant` - - `ASSISTANT("assistant")` + Always `logs`. - - `SYSTEM("system")` + - `LOGS("logs")` - - `CRITIC("critic")` + - `class ImageOutput:` - - `DISCRIMINATOR("discriminator")` + - `Image image` - - `DEVELOPER("developer")` + - `String fileId` - - `TOOL("tool")` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `List tools` + - `JsonValue; type "image"constant` - The additional tool definitions made available at this item. + Always `image`. - - `class BetaFunctionTool:` + - `IMAGE("image")` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `JsonValue; type "code_interpreter"constant` - - `class BetaFileSearchTool:` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `CODE_INTERPRETER("code_interpreter")` - - `class BetaComputerTool:` + - `class FileSearchToolCall:` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `String id` - - `class BetaComputerUsePreviewTool:` + The ID of the tool call object. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `FileSearch fileSearch` - - `class BetaWebSearchTool:` + For now, this is always going to be an empty object. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional rankingOptions` - - `Mcp` + The ranking options for the file search. - - `CodeInterpreter` + - `Ranker ranker` - - `JsonValue;` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `ImageGeneration` + - `AUTO("auto")` - - `JsonValue;` + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `class BetaFunctionShellTool:` + - `double scoreThreshold` - A tool that allows the model to execute shell commands. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `class BetaCustomTool:` + - `Optional> results` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The results of the file search. - - `class BetaNamespaceTool:` + - `String fileId` - Groups function/custom tools under a shared namespace. + The ID of the file that result was found in. - - `class BetaToolSearchTool:` + - `String fileName` - Hosted or BYOT tool search configuration for deferred tools. + The name of the file that result was found in. - - `class BetaWebSearchPreviewTool:` + - `double score` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The score of the result. All values must be a floating point number between 0 and 1. - - `class BetaApplyPatchTool:` + - `Optional> content` - Allows the assistant to create, delete, or update files using unified diffs. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `JsonValue; type "additional_tools"constant` + - `Optional text` - The type of the item. Always `additional_tools`. + The text content of the file. - - `ADDITIONAL_TOOLS("additional_tools")` + - `Optional type` - - `Optional agent` + The type of the content. - The agent that produced this item. + - `TEXT("text")` - - `String agentName` + - `JsonValue; type "file_search"constant` - The canonical name of the agent that produced this item. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `class BetaResponseReasoningItem:` + - `FILE_SEARCH("file_search")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class FunctionToolCall:` - `String id` - The unique identifier of the reasoning content. + The ID of the tool call object. - - `List summary` + - `Function function` - Reasoning summary content. + The definition of the function that was called. - - `String text` + - `String arguments` - A summary of the reasoning output from the model so far. + The arguments passed to the function. - - `JsonValue; type "summary_text"constant` + - `String name` - The type of the object. Always `summary_text`. + The name of the function. - - `SUMMARY_TEXT("summary_text")` + - `Optional output` - - `JsonValue; type "reasoning"constant` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The type of the object. Always `reasoning`. + - `JsonValue; type "function"constant` - - `REASONING("reasoning")` + The type of tool call. This is always going to be `function` for this type of tool call. - - `Optional agent` + - `FUNCTION("function")` - The agent that produced this item. + - `JsonValue; type "tool_calls"constant` - - `String agentName` + Always `tool_calls`. - The canonical name of the agent that produced this item. + - `TOOL_CALLS("tool_calls")` - - `Optional> content` + - `String threadId` - Reasoning text content. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `String text` + - `Type type` - The reasoning text from the model. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `JsonValue; type "reasoning_text"constant` + - `MESSAGE_CREATION("message_creation")` - The type of the reasoning text. Always `reasoning_text`. + - `TOOL_CALLS("tool_calls")` - - `REASONING_TEXT("reasoning_text")` + - `Optional usage` - - `Optional encryptedContent` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `long completionTokens` - - `Optional status` + Number of completion tokens used over the course of the run step. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `long promptTokens` - - `IN_PROGRESS("in_progress")` + Number of prompt tokens used over the course of the run step. - - `COMPLETED("completed")` + - `long totalTokens` - - `INCOMPLETE("incomplete")` + Total number of tokens used (prompt + completion). - - `Program` +### Example - - `String id` +```java +package com.openai.example; - The unique ID of the program item. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.runs.steps.StepListPage; +import com.openai.models.beta.threads.runs.steps.StepListParams; - - `String callId` +public final class Main { + private Main() {} - The stable call ID of the program item. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `String code` + StepListParams params = StepListParams.builder() + .threadId("thread_id") + .runId("run_id") + .build(); + StepListPage page = client.beta().threads().runs().steps().list(params); + } +} +``` - The JavaScript source executed by programmatic tool calling. +#### Response - - `String fingerprint` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } + } + ], + "first_id": "step_abc123", + "has_more": false, + "last_id": "step_abc456", + "object": "list" +} +``` - Opaque program replay fingerprint that must be round-tripped. +## Retrieve run step - - `JsonValue; type "program"constant` +`RunStep beta().threads().runs().steps().retrieve(StepRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - The type of the item. Always `program`. +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` - - `PROGRAM("program")` +Retrieves a run step. - - `Optional agent` +### Parameters - The agent that produced this item. +- `StepRetrieveParams params` - - `String agentName` + - `String threadId` - The canonical name of the agent that produced this item. + - `String runId` - - `ProgramOutput` + - `Optional stepId` - - `String id` + - `Optional> include` - The unique ID of the program output item. + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - - `String callId` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The call ID of the program item. + - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` - - `String result` +### Returns - The result produced by the program item. +- `class RunStep:` - - `Status status` + Represents a step in execution of a run. - The terminal status of the program output item. + - `String id` - - `COMPLETED("completed")` + The identifier of the run step, which can be referenced in API endpoints. - - `INCOMPLETE("incomplete")` + - `String assistantId` - - `JsonValue; type "program_output"constant` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The type of the item. Always `program_output`. + - `Optional cancelledAt` - - `PROGRAM_OUTPUT("program_output")` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `Optional agent` + - `Optional completedAt` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run step completed. - - `String agentName` + - `long createdAt` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run step was created. - - `class BetaResponseCompactionItem:` + - `Optional expiredAt` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `String id` + - `Optional failedAt` - The unique ID of the compaction item. + The Unix timestamp (in seconds) for when the run step failed. - - `String encryptedContent` + - `Optional lastError` - The encrypted content that was produced by compaction. + The last error associated with this run step. Will be `null` if there are no errors. - - `JsonValue; type "compaction"constant` + - `Code code` - The type of the item. Always `compaction`. + One of `server_error` or `rate_limit_exceeded`. - - `COMPACTION("compaction")` + - `SERVER_ERROR("server_error")` - - `Optional agent` + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - The agent that produced this item. + - `String message` - - `String agentName` + A human-readable description of the error. - The canonical name of the agent that produced this item. + - `Optional metadata` - - `Optional createdBy` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The identifier of the actor that created the item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `ImageGenerationCall` + - `JsonValue; object_ "thread.run.step"constant` - - `String id` + The object type, which is always `thread.run.step`. - The unique ID of the image generation call. + - `THREAD_RUN_STEP("thread.run.step")` - - `Optional result` + - `String runId` - The generated image encoded in base64. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - `Status status` - The status of the image generation call. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - `IN_PROGRESS("in_progress")` - - `COMPLETED("completed")` - - - `GENERATING("generating")` + - `CANCELLED("cancelled")` - `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")` - - - `Optional agent` - - The agent that produced this item. - - - `String agentName` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCodeInterpreterToolCall:` - - A tool call to run code. - - - `String id` - - The unique ID of the code interpreter tool call. - - - `Optional code` - - The code to run, or null if not available. - - - `String containerId` - - The ID of the container used to run the code. - - - `Optional> 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` + - `COMPLETED("completed")` - The type of the output. Always `logs`. + - `EXPIRED("expired")` - - `LOGS("logs")` + - `StepDetails stepDetails` - - `class Image:` + The details of the run step. - The image output from the code interpreter. + - `class MessageCreationStepDetails:` - - `JsonValue; type "image"constant` + Details of the message creation by the run step. - The type of the output. Always `image`. + - `MessageCreation messageCreation` - - `IMAGE("image")` + - `String messageId` - - `String url` + The ID of the message that was created by this run step. - The URL of the image output from the code interpreter. + - `JsonValue; type "message_creation"constant` - - `Status status` + Always `message_creation`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `MESSAGE_CREATION("message_creation")` - - `IN_PROGRESS("in_progress")` + - `class ToolCallsStepDetails:` - - `COMPLETED("completed")` + Details of the tool call. - - `INCOMPLETE("incomplete")` + - `List toolCalls` - - `INTERPRETING("interpreting")` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `FAILED("failed")` + - `class CodeInterpreterToolCall:` - - `JsonValue; type "code_interpreter_call"constant` + Details of the Code Interpreter tool call the run step was involved in. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `String id` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + The ID of the tool call. - - `Optional agent` + - `CodeInterpreter codeInterpreter` - The agent that produced this item. + The Code Interpreter tool call definition. - - `String agentName` + - `String input` - The canonical name of the agent that produced this item. + The input to the Code Interpreter tool call. - - `LocalShellCall` + - `List outputs` - - `String id` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The unique ID of the local shell call. + - `class LogsOutput:` - - `Action action` + Text output from the Code Interpreter tool call as part of a run step. - Execute a shell command on the server. + - `String logs` - - `List command` + The text output from the Code Interpreter tool call. - The command to run. + - `JsonValue; type "logs"constant` - - `Env env` + Always `logs`. - Environment variables to set for the command. + - `LOGS("logs")` - - `JsonValue; type "exec"constant` + - `class ImageOutput:` - The type of the local shell action. Always `exec`. + - `Image image` - - `EXEC("exec")` + - `String fileId` - - `Optional timeoutMs` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Optional timeout in milliseconds for the command. + - `JsonValue; type "image"constant` - - `Optional user` + Always `image`. - Optional user to run the command as. + - `IMAGE("image")` - - `Optional workingDirectory` + - `JsonValue; type "code_interpreter"constant` - Optional working directory to run the command in. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `String callId` + - `CODE_INTERPRETER("code_interpreter")` - The unique ID of the local shell tool call generated by the model. + - `class FileSearchToolCall:` - - `Status status` + - `String id` - The status of the local shell call. + The ID of the tool call object. - - `IN_PROGRESS("in_progress")` + - `FileSearch fileSearch` - - `COMPLETED("completed")` + For now, this is always going to be an empty object. - - `INCOMPLETE("incomplete")` + - `Optional rankingOptions` - - `JsonValue; type "local_shell_call"constant` + The ranking options for the file search. - The type of the local shell call. Always `local_shell_call`. + - `Ranker ranker` - - `LOCAL_SHELL_CALL("local_shell_call")` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `Optional agent` + - `AUTO("auto")` - The agent that produced this item. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `String agentName` + - `double scoreThreshold` - The canonical name of the agent that produced this item. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `LocalShellCallOutput` + - `Optional> results` - - `String id` + The results of the file search. - The unique ID of the local shell tool call generated by the model. + - `String fileId` - - `String output` + The ID of the file that result was found in. - A JSON string of the output of the local shell tool call. + - `String fileName` - - `JsonValue; type "local_shell_call_output"constant` + The name of the file that result was found in. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `double score` - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + The score of the result. All values must be a floating point number between 0 and 1. - - `Optional agent` + - `Optional> content` - The agent that produced this item. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `String agentName` + - `Optional text` - The canonical name of the agent that produced this item. + The text content of the file. - - `Optional status` + - `Optional type` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The type of the content. - - `IN_PROGRESS("in_progress")` + - `TEXT("text")` - - `COMPLETED("completed")` + - `JsonValue; type "file_search"constant` - - `INCOMPLETE("incomplete")` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `class BetaResponseFunctionShellToolCall:` + - `FILE_SEARCH("file_search")` - A tool call that executes one or more shell commands in a managed environment. + - `class FunctionToolCall:` - `String id` - The unique ID of the shell tool call. Populated when this item is returned via API. + The ID of the tool call object. - - `Action action` + - `Function function` - The shell commands and limits that describe how to run the tool call. + The definition of the function that was called. - - `List commands` + - `String arguments` - - `Optional maxOutputLength` + The arguments passed to the function. - Optional maximum number of characters to return from each command. + - `String name` - - `Optional timeoutMs` + The name of the function. - Optional timeout in milliseconds for the commands. + - `Optional output` - - `String callId` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The unique ID of the shell tool call generated by the model. + - `JsonValue; type "function"constant` - - `Optional environment` + The type of tool call. This is always going to be `function` for this type of tool call. - Represents the use of a local environment to perform shell actions. + - `FUNCTION("function")` - - `class BetaResponseLocalEnvironment:` + - `JsonValue; type "tool_calls"constant` - Represents the use of a local environment to perform shell actions. + Always `tool_calls`. - - `JsonValue; type "local"constant` + - `TOOL_CALLS("tool_calls")` - The environment type. Always `local`. + - `String threadId` - - `LOCAL("local")` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `class BetaResponseContainerReference:` + - `Type type` - Represents a container created with /v1/containers. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `String containerId` + - `MESSAGE_CREATION("message_creation")` - - `JsonValue; type "container_reference"constant` + - `TOOL_CALLS("tool_calls")` - The environment type. Always `container_reference`. + - `Optional usage` - - `CONTAINER_REFERENCE("container_reference")` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `Status status` + - `long completionTokens` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Number of completion tokens used over the course of the run step. - - `IN_PROGRESS("in_progress")` + - `long promptTokens` - - `COMPLETED("completed")` + Number of prompt tokens used over the course of the run step. - - `INCOMPLETE("incomplete")` + - `long totalTokens` - - `JsonValue; type "shell_call"constant` + Total number of tokens used (prompt + completion). - The type of the item. Always `shell_call`. +### Example - - `SHELL_CALL("shell_call")` +```java +package com.openai.example; - - `Optional agent` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.runs.steps.RunStep; +import com.openai.models.beta.threads.runs.steps.StepRetrieveParams; - The agent that produced this item. +public final class Main { + private Main() {} - - `String agentName` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - The canonical name of the agent that produced this item. + StepRetrieveParams params = StepRetrieveParams.builder() + .threadId("thread_id") + .runId("run_id") + .stepId("step_id") + .build(); + RunStep runStep = client.beta().threads().runs().steps().retrieve(params); + } +} +``` - - `Optional caller` +#### Response - The execution context that produced this tool call. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` - - `JsonValue;` +## Domain Types - - `JsonValue; type "direct"constant` +### Code Interpreter Logs - - `DIRECT("direct")` +- `class CodeInterpreterLogs:` - - `class Program:` + Text output from the Code Interpreter tool call as part of a run step. - - `String callerId` + - `long index` - The call ID of the program item that produced this tool call. + The index of the output in the outputs array. - - `JsonValue; type "program"constant` + - `JsonValue; type "logs"constant` - - `PROGRAM("program")` + Always `logs`. - - `Optional createdBy` + - `LOGS("logs")` - The ID of the entity that created this tool call. + - `Optional logs` - - `class BetaResponseFunctionShellToolCallOutput:` + The text output from the Code Interpreter tool call. - The output of a shell tool call that was emitted. +### Code Interpreter Output Image - - `String id` +- `class CodeInterpreterOutputImage:` - The unique ID of the shell call output. Populated when this item is returned via API. + - `long index` - - `String callId` + The index of the output in the outputs array. - The unique ID of the shell tool call generated by the model. + - `JsonValue; type "image"constant` - - `Optional maxOutputLength` + Always `image`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `IMAGE("image")` - - `List output` + - `Optional image` - An array of shell call output contents + - `Optional fileId` - - `Outcome outcome` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. +### Code Interpreter Tool Call - - `JsonValue;` +- `class CodeInterpreterToolCall:` - - `JsonValue; type "timeout"constant` + Details of the Code Interpreter tool call the run step was involved in. - The outcome type. Always `timeout`. + - `String id` - - `TIMEOUT("timeout")` + The ID of the tool call. - - `class Exit:` + - `CodeInterpreter codeInterpreter` - Indicates that the shell commands finished and returned an exit code. + The Code Interpreter tool call definition. - - `long exitCode` + - `String input` - Exit code from the shell process. + The input to the Code Interpreter tool call. - - `JsonValue; type "exit"constant` + - `List outputs` - The outcome type. Always `exit`. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `EXIT("exit")` + - `class LogsOutput:` - - `String stderr` + Text output from the Code Interpreter tool call as part of a run step. - The standard error output that was captured. + - `String logs` - - `String stdout` + The text output from the Code Interpreter tool call. - The standard output that was captured. + - `JsonValue; type "logs"constant` - - `Optional createdBy` + Always `logs`. - The identifier of the actor that created the item. + - `LOGS("logs")` - - `Status status` + - `class ImageOutput:` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `Image image` - - `IN_PROGRESS("in_progress")` + - `String fileId` - - `COMPLETED("completed")` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `INCOMPLETE("incomplete")` + - `JsonValue; type "image"constant` - - `JsonValue; type "shell_call_output"constant` + Always `image`. - The type of the shell call output. Always `shell_call_output`. + - `IMAGE("image")` - - `SHELL_CALL_OUTPUT("shell_call_output")` + - `JsonValue; type "code_interpreter"constant` - - `Optional agent` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The agent that produced this item. + - `CODE_INTERPRETER("code_interpreter")` - - `String agentName` +### Code Interpreter Tool Call Delta - The canonical name of the agent that produced this item. +- `class CodeInterpreterToolCallDelta:` - - `Optional caller` + Details of the Code Interpreter tool call the run step was involved in. - The execution context that produced this tool call. + - `long index` - - `JsonValue;` + The index of the tool call in the tool calls array. - - `JsonValue; type "direct"constant` + - `JsonValue; type "code_interpreter"constant` - - `DIRECT("direct")` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class Program:` + - `CODE_INTERPRETER("code_interpreter")` - - `String callerId` + - `Optional id` - The call ID of the program item that produced this tool call. + The ID of the tool call. - - `JsonValue; type "program"constant` + - `Optional codeInterpreter` - - `PROGRAM("program")` + The Code Interpreter tool call definition. - - `Optional createdBy` + - `Optional input` - The identifier of the actor that created the item. + The input to the Code Interpreter tool call. - - `class BetaResponseApplyPatchToolCall:` + - `Optional> outputs` - A tool call that applies file diffs by creating, deleting, or updating files. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `String id` + - `class CodeInterpreterLogs:` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Text output from the Code Interpreter tool call as part of a run step. - - `String callId` + - `long index` - The unique ID of the apply patch tool call generated by the model. + The index of the output in the outputs array. - - `Operation operation` + - `JsonValue; type "logs"constant` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Always `logs`. - - `class CreateFile:` + - `LOGS("logs")` - Instruction describing how to create a file via the apply_patch tool. + - `Optional logs` - - `String diff` + The text output from the Code Interpreter tool call. - Diff to apply. + - `class CodeInterpreterOutputImage:` - - `String path` + - `long index` - Path of the file to create. + The index of the output in the outputs array. - - `JsonValue; type "create_file"constant` + - `JsonValue; type "image"constant` - Create a new file with the provided diff. + Always `image`. - - `CREATE_FILE("create_file")` + - `IMAGE("image")` - - `class DeleteFile:` + - `Optional image` - Instruction describing how to delete a file via the apply_patch tool. + - `Optional fileId` - - `String path` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Path of the file to delete. +### File Search Tool Call - - `JsonValue; type "delete_file"constant` +- `class FileSearchToolCall:` - Delete the specified file. + - `String id` - - `DELETE_FILE("delete_file")` + The ID of the tool call object. - - `class UpdateFile:` + - `FileSearch fileSearch` - Instruction describing how to update a file via the apply_patch tool. + For now, this is always going to be an empty object. - - `String diff` + - `Optional rankingOptions` - Diff to apply. + The ranking options for the file search. - - `String path` + - `Ranker ranker` - Path of the file to update. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `JsonValue; type "update_file"constant` + - `AUTO("auto")` - Update an existing file with the provided diff. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `UPDATE_FILE("update_file")` + - `double scoreThreshold` - - `Status status` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `Optional> results` - - `IN_PROGRESS("in_progress")` + The results of the file search. - - `COMPLETED("completed")` + - `String fileId` - - `JsonValue; type "apply_patch_call"constant` + The ID of the file that result was found in. - The type of the item. Always `apply_patch_call`. + - `String fileName` - - `APPLY_PATCH_CALL("apply_patch_call")` + The name of the file that result was found in. - - `Optional agent` + - `double score` - The agent that produced this item. + The score of the result. All values must be a floating point number between 0 and 1. - - `String agentName` + - `Optional> content` - The canonical name of the agent that produced this item. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `Optional caller` + - `Optional text` - The execution context that produced this tool call. + The text content of the file. - - `JsonValue;` + - `Optional type` - - `JsonValue; type "direct"constant` + The type of the content. - - `DIRECT("direct")` + - `TEXT("text")` - - `class Program:` + - `JsonValue; type "file_search"constant` - - `String callerId` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The call ID of the program item that produced this tool call. + - `FILE_SEARCH("file_search")` - - `JsonValue; type "program"constant` +### File Search Tool Call Delta - - `PROGRAM("program")` +- `class FileSearchToolCallDelta:` - - `Optional createdBy` + - `JsonValue fileSearch` - The ID of the entity that created this tool call. + For now, this is always going to be an empty object. - - `class BetaResponseApplyPatchToolCallOutput:` + - `long index` - The output emitted by an apply patch tool call. + The index of the tool call in the tool calls array. - - `String id` + - `JsonValue; type "file_search"constant` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `String callId` + - `FILE_SEARCH("file_search")` - The unique ID of the apply patch tool call generated by the model. + - `Optional id` - - `Status status` + The ID of the tool call object. - The status of the apply patch tool call output. One of `completed` or `failed`. +### Function Tool Call - - `COMPLETED("completed")` +- `class FunctionToolCall:` - - `FAILED("failed")` + - `String id` - - `JsonValue; type "apply_patch_call_output"constant` + The ID of the tool call object. - The type of the item. Always `apply_patch_call_output`. + - `Function function` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + The definition of the function that was called. - - `Optional agent` + - `String arguments` - The agent that produced this item. + The arguments passed to the function. - - `String agentName` + - `String name` - The canonical name of the agent that produced this item. + The name of the function. - - `Optional caller` + - `Optional output` - The execution context that produced this tool call. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `JsonValue;` + - `JsonValue; type "function"constant` - - `JsonValue; type "direct"constant` + The type of tool call. This is always going to be `function` for this type of tool call. - - `DIRECT("direct")` + - `FUNCTION("function")` - - `class Program:` +### Function Tool Call Delta - - `String callerId` +- `class FunctionToolCallDelta:` - The call ID of the program item that produced this tool call. + - `long index` - - `JsonValue; type "program"constant` + The index of the tool call in the tool calls array. - - `PROGRAM("program")` + - `JsonValue; type "function"constant` - - `Optional createdBy` + The type of tool call. This is always going to be `function` for this type of tool call. - The ID of the entity that created this tool call output. + - `FUNCTION("function")` - - `Optional output` + - `Optional id` - Optional textual output returned by the apply patch tool. + The ID of the tool call object. - - `McpListTools` + - `Optional function` - - `String id` + The definition of the function that was called. - The unique ID of the list. + - `Optional arguments` - - `String serverLabel` + The arguments passed to the function. - The label of the MCP server. + - `Optional name` - - `List tools` + The name of the function. - The tools available on the server. + - `Optional output` - - `JsonValue inputSchema` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The JSON schema describing the tool's input. +### Message Creation Step Details - - `String name` +- `class MessageCreationStepDetails:` - The name of the tool. + Details of the message creation by the run step. - - `Optional annotations` + - `MessageCreation messageCreation` - Additional annotations about the tool. + - `String messageId` - - `Optional description` + The ID of the message that was created by this run step. - The description of the tool. + - `JsonValue; type "message_creation"constant` - - `JsonValue; type "mcp_list_tools"constant` + Always `message_creation`. - The type of the item. Always `mcp_list_tools`. + - `MESSAGE_CREATION("message_creation")` - - `MCP_LIST_TOOLS("mcp_list_tools")` +### Run Step - - `Optional agent` +- `class RunStep:` - The agent that produced this item. + Represents a step in execution of a run. - - `String agentName` + - `String id` - The canonical name of the agent that produced this item. + The identifier of the run step, which can be referenced in API endpoints. - - `Optional error` + - `String assistantId` - Error message if the server could not list tools. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `McpApprovalRequest` + - `Optional cancelledAt` - - `String id` + The Unix timestamp (in seconds) for when the run step was cancelled. - The unique ID of the approval request. + - `Optional completedAt` - - `String arguments` + The Unix timestamp (in seconds) for when the run step completed. - A JSON string of arguments for the tool. + - `long createdAt` - - `String name` + The Unix timestamp (in seconds) for when the run step was created. - The name of the tool to run. + - `Optional expiredAt` - - `String serverLabel` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The label of the MCP server making the request. + - `Optional failedAt` - - `JsonValue; type "mcp_approval_request"constant` + The Unix timestamp (in seconds) for when the run step failed. - The type of the item. Always `mcp_approval_request`. + - `Optional lastError` - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + The last error associated with this run step. Will be `null` if there are no errors. - - `Optional agent` + - `Code code` - The agent that produced this item. + One of `server_error` or `rate_limit_exceeded`. - - `String agentName` + - `SERVER_ERROR("server_error")` - The canonical name of the agent that produced this item. + - `RATE_LIMIT_EXCEEDED("rate_limit_exceeded")` - - `McpApprovalResponse` + - `String message` - - `String id` + A human-readable description of the error. - The unique ID of the approval response + - `Optional metadata` - - `String approvalRequestId` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The ID of the approval request being answered. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `boolean approve` + - `JsonValue; object_ "thread.run.step"constant` - Whether the request was approved. + The object type, which is always `thread.run.step`. - - `JsonValue; type "mcp_approval_response"constant` + - `THREAD_RUN_STEP("thread.run.step")` - The type of the item. Always `mcp_approval_response`. + - `String runId` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `Optional agent` + - `Status status` - The agent that produced this item. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `String agentName` + - `IN_PROGRESS("in_progress")` - The canonical name of the agent that produced this item. + - `CANCELLED("cancelled")` - - `Optional reason` + - `FAILED("failed")` - Optional reason for the decision. + - `COMPLETED("completed")` - - `McpCall` + - `EXPIRED("expired")` - - `String id` + - `StepDetails stepDetails` - The unique ID of the tool call. + The details of the run step. - - `String arguments` + - `class MessageCreationStepDetails:` - A JSON string of the arguments passed to the tool. + Details of the message creation by the run step. - - `String name` + - `MessageCreation messageCreation` - The name of the tool that was run. + - `String messageId` - - `String serverLabel` + The ID of the message that was created by this run step. - The label of the MCP server running the tool. + - `JsonValue; type "message_creation"constant` - - `JsonValue; type "mcp_call"constant` + Always `message_creation`. - The type of the item. Always `mcp_call`. + - `MESSAGE_CREATION("message_creation")` - - `MCP_CALL("mcp_call")` + - `class ToolCallsStepDetails:` - - `Optional agent` + Details of the tool call. - The agent that produced this item. + - `List toolCalls` - - `String agentName` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The canonical name of the agent that produced this item. + - `class CodeInterpreterToolCall:` - - `Optional approvalRequestId` + Details of the Code Interpreter tool call the run step was involved in. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `String id` - - `Optional error` + The ID of the tool call. - The error from the tool call, if any. + - `CodeInterpreter codeInterpreter` - - `Optional output` + The Code Interpreter tool call definition. - The output from the tool call. + - `String input` - - `Optional status` + The input to the Code Interpreter tool call. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `List outputs` - - `IN_PROGRESS("in_progress")` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `COMPLETED("completed")` + - `class LogsOutput:` - - `INCOMPLETE("incomplete")` + Text output from the Code Interpreter tool call as part of a run step. - - `CALLING("calling")` + - `String logs` - - `FAILED("failed")` + The text output from the Code Interpreter tool call. - - `class BetaResponseCustomToolCallItem:` + - `JsonValue; type "logs"constant` - A call to a custom tool created by the model. + Always `logs`. - - `String id` + - `LOGS("logs")` - The unique ID of the custom tool call item. + - `class ImageOutput:` - - `Status status` + - `Image image` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `String fileId` - - `IN_PROGRESS("in_progress")` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `COMPLETED("completed")` + - `JsonValue; type "image"constant` - - `INCOMPLETE("incomplete")` + Always `image`. - - `Optional createdBy` + - `IMAGE("image")` - The identifier of the actor that created the item. + - `JsonValue; type "code_interpreter"constant` - - `class BetaResponseCustomToolCallOutputItem:` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The output of a custom tool call from your code, being sent back to the model. + - `CODE_INTERPRETER("code_interpreter")` - - `String id` + - `class FileSearchToolCall:` - The unique ID of the custom tool call output item. + - `String id` - - `Status status` + The ID of the tool call object. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `FileSearch fileSearch` - - `IN_PROGRESS("in_progress")` + For now, this is always going to be an empty object. - - `COMPLETED("completed")` + - `Optional rankingOptions` - - `INCOMPLETE("incomplete")` + The ranking options for the file search. - - `Optional createdBy` + - `Ranker ranker` - The identifier of the actor that created the item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `String firstId` + - `AUTO("auto")` - The ID of the first item in the list. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `boolean hasMore` + - `double scoreThreshold` - Whether there are more items available. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `String lastId` + - `Optional> results` - The ID of the last item in the list. + The results of the file search. - - `JsonValue; object_ "list"constant` + - `String fileId` - The type of object returned, must be `list`. + The ID of the file that result was found in. - - `LIST("list")` + - `String fileName` -# Input Tokens + The name of the file that result was found in. -## Get input token counts + - `double score` -`InputTokenCountResponse beta().responses().inputTokens().count(InputTokenCountParamsparams = InputTokenCountParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` + The score of the result. All values must be a floating point number between 0 and 1. -**post** `/responses/input_tokens?beta=true` + - `Optional> content` -Get input token counts + The content of the result that was found. The content is only included if requested via the include query parameter. -### Parameters + - `Optional text` -- `InputTokenCountParams params` + The text content of the file. - - `Optional> betas` + - `Optional type` - - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` + The type of the content. - - `Optional conversation` + - `TEXT("text")` - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + - `JsonValue; type "file_search"constant` - - `String` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `class BetaResponseConversationParam:` + - `FILE_SEARCH("file_search")` - The conversation that this response belongs to. + - `class FunctionToolCall:` - `String id` - The unique ID of the conversation. + The ID of the tool call object. - - `Optional input` + - `Function function` - Text, image, or file inputs to the model, used to generate a response + The definition of the function that was called. - - `String` + - `String arguments` - - `List` + The arguments passed to the function. - - `class BetaEasyInputMessage:` + - `String name` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + The name of the function. - - `Content content` + - `Optional output` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `String` + - `JsonValue; type "function"constant` - - `List` + The type of tool call. This is always going to be `function` for this type of tool call. - - `class BetaResponseInputText:` + - `FUNCTION("function")` - A text input to the model. + - `JsonValue; type "tool_calls"constant` - - `String text` + Always `tool_calls`. - The text input to the model. + - `TOOL_CALLS("tool_calls")` - - `JsonValue; type "input_text"constant` + - `String threadId` - The type of the input item. Always `input_text`. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `INPUT_TEXT("input_text")` + - `Type type` - - `Optional promptCacheBreakpoint` + The type of run step, which can be either `message_creation` or `tool_calls`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `MESSAGE_CREATION("message_creation")` - - `JsonValue; mode "explicit"constant` + - `TOOL_CALLS("tool_calls")` - The breakpoint mode. Always `explicit`. + - `Optional usage` - - `EXPLICIT("explicit")` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `class BetaResponseInputImage:` + - `long completionTokens` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Number of completion tokens used over the course of the run step. - - `Detail detail` + - `long promptTokens` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Number of prompt tokens used over the course of the run step. - - `LOW("low")` + - `long totalTokens` - - `HIGH("high")` + Total number of tokens used (prompt + completion). - - `AUTO("auto")` +### Run Step Delta - - `ORIGINAL("original")` +- `class RunStepDelta:` - - `JsonValue; type "input_image"constant` + The delta containing the fields that have changed on the run step. - The type of the input item. Always `input_image`. + - `Optional stepDetails` - - `INPUT_IMAGE("input_image")` + The details of the run step. - - `Optional fileId` + - `class RunStepDeltaMessageDelta:` - The ID of the file to be sent to the model. + Details of the message creation by the run step. - - `Optional imageUrl` + - `JsonValue; type "message_creation"constant` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Always `message_creation`. - - `Optional promptCacheBreakpoint` + - `MESSAGE_CREATION("message_creation")` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional messageCreation` - - `JsonValue; mode "explicit"constant` + - `Optional messageId` - The breakpoint mode. Always `explicit`. + The ID of the message that was created by this run step. - - `EXPLICIT("explicit")` + - `class ToolCallDeltaObject:` - - `class BetaResponseInputFile:` + Details of the tool call. - A file input to the model. + - `JsonValue; type "tool_calls"constant` - - `JsonValue; type "input_file"constant` + Always `tool_calls`. - The type of the input item. Always `input_file`. + - `TOOL_CALLS("tool_calls")` - - `INPUT_FILE("input_file")` + - `Optional> toolCalls` - - `Optional detail` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `class CodeInterpreterToolCallDelta:` - - `AUTO("auto")` + Details of the Code Interpreter tool call the run step was involved in. - - `LOW("low")` + - `long index` - - `HIGH("high")` + The index of the tool call in the tool calls array. - - `Optional fileData` + - `JsonValue; type "code_interpreter"constant` - The content of the file to be sent to the model. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `Optional fileId` + - `CODE_INTERPRETER("code_interpreter")` - The ID of the file to be sent to the model. + - `Optional id` - - `Optional fileUrl` + The ID of the tool call. - The URL of the file to be sent to the model. + - `Optional codeInterpreter` - - `Optional filename` + The Code Interpreter tool call definition. - The name of the file to be sent to the model. + - `Optional input` - - `Optional promptCacheBreakpoint` + The input to the Code Interpreter tool call. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `Optional> outputs` - - `JsonValue; mode "explicit"constant` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The breakpoint mode. Always `explicit`. + - `class CodeInterpreterLogs:` - - `EXPLICIT("explicit")` + Text output from the Code Interpreter tool call as part of a run step. - - `Role role` + - `long index` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The index of the output in the outputs array. - - `USER("user")` + - `JsonValue; type "logs"constant` - - `ASSISTANT("assistant")` + Always `logs`. - - `SYSTEM("system")` + - `LOGS("logs")` - - `DEVELOPER("developer")` + - `Optional logs` - - `Optional phase` + The text output from the Code Interpreter tool call. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `class CodeInterpreterOutputImage:` - - `COMMENTARY("commentary")` + - `long index` - - `Optional type` + The index of the output in the outputs array. - The type of the message input. Always `message`. + - `JsonValue; type "image"constant` - - `MESSAGE("message")` + Always `image`. - - `Message` + - `IMAGE("image")` - - `List content` + - `Optional image` - A list of one or many input items to the model, containing different content - types. + - `Optional fileId` - - `class BetaResponseInputText:` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - A text input to the model. + - `class FileSearchToolCallDelta:` - - `class BetaResponseInputImage:` + - `JsonValue fileSearch` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + For now, this is always going to be an empty object. - - `class BetaResponseInputFile:` + - `long index` - A file input to the model. + The index of the tool call in the tool calls array. - - `Role role` + - `JsonValue; type "file_search"constant` - The role of the message input. One of `user`, `system`, or `developer`. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `USER("user")` + - `FILE_SEARCH("file_search")` - - `SYSTEM("system")` + - `Optional id` - - `DEVELOPER("developer")` + The ID of the tool call object. - - `Optional agent` + - `class FunctionToolCallDelta:` - The agent that produced this item. + - `long index` - - `String agentName` + The index of the tool call in the tool calls array. - The canonical name of the agent that produced this item. + - `JsonValue; type "function"constant` - - `Optional status` + The type of tool call. This is always going to be `function` for this type of tool call. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `FUNCTION("function")` - - `IN_PROGRESS("in_progress")` + - `Optional id` - - `COMPLETED("completed")` + The ID of the tool call object. - - `INCOMPLETE("incomplete")` + - `Optional function` - - `Optional type` + The definition of the function that was called. - The type of the message input. Always set to `message`. + - `Optional arguments` - - `MESSAGE("message")` + The arguments passed to the function. - - `class BetaResponseOutputMessage:` + - `Optional name` - An output message from the model. + The name of the function. - - `String id` + - `Optional output` - The unique ID of the output message. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `List content` +### Run Step Delta Event - The content of the output message. +- `class RunStepDeltaEvent:` - - `class BetaResponseOutputText:` + Represents a run step delta i.e. any changed fields on a run step during streaming. - A text output from the model. + - `String id` - - `List annotations` + The identifier of the run step, which can be referenced in API endpoints. - The annotations of the text output. + - `RunStepDelta delta` - - `class FileCitation:` + The delta containing the fields that have changed on the run step. - A citation to a file. + - `Optional stepDetails` - - `String fileId` + The details of the run step. - The ID of the file. + - `class RunStepDeltaMessageDelta:` - - `String filename` + Details of the message creation by the run step. - The filename of the file cited. + - `JsonValue; type "message_creation"constant` - - `long index` + Always `message_creation`. - The index of the file in the list of files. + - `MESSAGE_CREATION("message_creation")` - - `JsonValue; type "file_citation"constant` + - `Optional messageCreation` - The type of the file citation. Always `file_citation`. + - `Optional messageId` - - `FILE_CITATION("file_citation")` + The ID of the message that was created by this run step. - - `class UrlCitation:` + - `class ToolCallDeltaObject:` - A citation for a web resource used to generate a model response. + Details of the tool call. - - `long endIndex` + - `JsonValue; type "tool_calls"constant` - The index of the last character of the URL citation in the message. + Always `tool_calls`. - - `long startIndex` + - `TOOL_CALLS("tool_calls")` - The index of the first character of the URL citation in the message. + - `Optional> toolCalls` - - `String title` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The title of the web resource. + - `class CodeInterpreterToolCallDelta:` - - `JsonValue; type "url_citation"constant` + Details of the Code Interpreter tool call the run step was involved in. - The type of the URL citation. Always `url_citation`. + - `long index` - - `URL_CITATION("url_citation")` + The index of the tool call in the tool calls array. - - `String url` + - `JsonValue; type "code_interpreter"constant` - The URL of the web resource. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class ContainerFileCitation:` + - `CODE_INTERPRETER("code_interpreter")` - A citation for a container file used to generate a model response. + - `Optional id` - - `String containerId` + The ID of the tool call. - The ID of the container file. + - `Optional codeInterpreter` - - `long endIndex` + The Code Interpreter tool call definition. - The index of the last character of the container file citation in the message. + - `Optional input` - - `String fileId` + The input to the Code Interpreter tool call. - The ID of the file. + - `Optional> outputs` - - `String filename` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The filename of the container file cited. + - `class CodeInterpreterLogs:` - - `long startIndex` + Text output from the Code Interpreter tool call as part of a run step. - The index of the first character of the container file citation in the message. + - `long index` - - `JsonValue; type "container_file_citation"constant` + The index of the output in the outputs array. - The type of the container file citation. Always `container_file_citation`. + - `JsonValue; type "logs"constant` - - `CONTAINER_FILE_CITATION("container_file_citation")` + Always `logs`. - - `class FilePath:` + - `LOGS("logs")` - A path to a file. + - `Optional logs` - - `String fileId` + The text output from the Code Interpreter tool call. - The ID of the file. + - `class CodeInterpreterOutputImage:` - `long index` - The index of the file in the list of files. + The index of the output in the outputs array. - - `JsonValue; type "file_path"constant` + - `JsonValue; type "image"constant` - The type of the file path. Always `file_path`. + Always `image`. - - `FILE_PATH("file_path")` + - `IMAGE("image")` - - `String text` + - `Optional image` - The text output from the model. + - `Optional fileId` - - `JsonValue; type "output_text"constant` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The type of the output text. Always `output_text`. + - `class FileSearchToolCallDelta:` - - `OUTPUT_TEXT("output_text")` + - `JsonValue fileSearch` - - `Optional> logprobs` + For now, this is always going to be an empty object. - - `String token` + - `long index` - - `List bytes` + The index of the tool call in the tool calls array. - - `double logprob` + - `JsonValue; type "file_search"constant` - - `List topLogprobs` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `String token` + - `FILE_SEARCH("file_search")` - - `List bytes` + - `Optional id` - - `double logprob` + The ID of the tool call object. - - `class BetaResponseOutputRefusal:` + - `class FunctionToolCallDelta:` - A refusal from the model. + - `long index` - - `String refusal` + The index of the tool call in the tool calls array. - The refusal explanation from the model. + - `JsonValue; type "function"constant` - - `JsonValue; type "refusal"constant` + The type of tool call. This is always going to be `function` for this type of tool call. - The type of the refusal. Always `refusal`. + - `FUNCTION("function")` - - `REFUSAL("refusal")` + - `Optional id` - - `JsonValue; role "assistant"constant` + The ID of the tool call object. - The role of the output message. Always `assistant`. + - `Optional function` - - `ASSISTANT("assistant")` + The definition of the function that was called. - - `Status status` + - `Optional arguments` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The arguments passed to the function. - - `IN_PROGRESS("in_progress")` + - `Optional name` - - `COMPLETED("completed")` + The name of the function. - - `INCOMPLETE("incomplete")` + - `Optional output` - - `JsonValue; type "message"constant` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The type of the output message. Always `message`. + - `JsonValue; object_ "thread.run.step.delta"constant` - - `MESSAGE("message")` + The object type, which is always `thread.run.step.delta`. - - `Optional agent` + - `THREAD_RUN_STEP_DELTA("thread.run.step.delta")` - The agent that produced this item. +### Run Step Delta Message Delta - - `String agentName` +- `class RunStepDeltaMessageDelta:` - The canonical name of the agent that produced this item. + Details of the message creation by the run step. - - `Optional phase` + - `JsonValue; type "message_creation"constant` - 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. + Always `message_creation`. - - `COMMENTARY("commentary")` + - `MESSAGE_CREATION("message_creation")` - - `class BetaResponseFileSearchToolCall:` + - `Optional messageCreation` - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + - `Optional messageId` - - `String id` + The ID of the message that was created by this run step. - The unique ID of the file search tool call. +### Run Step Include - - `List queries` +- `enum RunStepInclude:` - The queries used to search for files. + - `STEP_DETAILS_TOOL_CALLS_FILE_SEARCH_RESULTS_CONTENT("step_details.tool_calls[*].file_search.results[*].content")` - - `Status status` +### Tool Call - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, +- `class ToolCall: A class that can be one of several variants.union` - - `IN_PROGRESS("in_progress")` + Details of the Code Interpreter tool call the run step was involved in. - - `SEARCHING("searching")` + - `class CodeInterpreterToolCall:` - - `COMPLETED("completed")` + Details of the Code Interpreter tool call the run step was involved in. - - `INCOMPLETE("incomplete")` + - `String id` - - `FAILED("failed")` + The ID of the tool call. - - `JsonValue; type "file_search_call"constant` + - `CodeInterpreter codeInterpreter` - The type of the file search tool call. Always `file_search_call`. + The Code Interpreter tool call definition. - - `FILE_SEARCH_CALL("file_search_call")` + - `String input` - - `Optional agent` + The input to the Code Interpreter tool call. - The agent that produced this item. + - `List outputs` - - `String agentName` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The canonical name of the agent that produced this item. + - `class LogsOutput:` - - `Optional> results` + Text output from the Code Interpreter tool call as part of a run step. - The results of the file search tool call. + - `String logs` - - `Optional attributes` + The text output from the Code Interpreter tool call. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `JsonValue; type "logs"constant` - - `String` + Always `logs`. - - `double` + - `LOGS("logs")` - - `boolean` + - `class ImageOutput:` - - `Optional fileId` + - `Image image` - The unique ID of the file. + - `String fileId` - - `Optional filename` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The name of the file. + - `JsonValue; type "image"constant` - - `Optional score` + Always `image`. - The relevance score of the file - a value between 0 and 1. + - `IMAGE("image")` - - `Optional text` + - `JsonValue; type "code_interpreter"constant` - The text that was retrieved from the file. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `class BetaResponseComputerToolCall:` + - `CODE_INTERPRETER("code_interpreter")` - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `class FileSearchToolCall:` - `String id` - The unique ID of the computer call. + The ID of the tool call object. - - `String callId` + - `FileSearch fileSearch` - An identifier used when responding to the tool call with output. + For now, this is always going to be an empty object. - - `List pendingSafetyChecks` + - `Optional rankingOptions` - The pending safety checks for the computer call. + The ranking options for the file search. - - `String id` + - `Ranker ranker` - The ID of the pending safety check. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `Optional code` + - `AUTO("auto")` - The type of the pending safety check. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `Optional message` + - `double scoreThreshold` - Details about the pending safety check. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `Status status` + - `Optional> results` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The results of the file search. - - `IN_PROGRESS("in_progress")` + - `String fileId` - - `COMPLETED("completed")` + The ID of the file that result was found in. - - `INCOMPLETE("incomplete")` + - `String fileName` - - `Type type` + The name of the file that result was found in. - The type of the computer call. Always `computer_call`. + - `double score` - - `COMPUTER_CALL("computer_call")` + The score of the result. All values must be a floating point number between 0 and 1. - - `Optional action` + - `Optional> content` - A click action. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `Click` + - `Optional text` - - `Button button` + The text content of the file. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `Optional type` - - `LEFT("left")` + The type of the content. - - `RIGHT("right")` + - `TEXT("text")` - - `WHEEL("wheel")` + - `JsonValue; type "file_search"constant` - - `BACK("back")` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `FORWARD("forward")` + - `FILE_SEARCH("file_search")` - - `JsonValue; type "click"constant` + - `class FunctionToolCall:` - Specifies the event type. For a click action, this property is always `click`. + - `String id` - - `CLICK("click")` + The ID of the tool call object. - - `long x` + - `Function function` - The x-coordinate where the click occurred. + The definition of the function that was called. - - `long y` + - `String arguments` - The y-coordinate where the click occurred. + The arguments passed to the function. - - `Optional> keys` + - `String name` - The keys being held while clicking. + The name of the function. - - `DoubleClick` + - `Optional output` - - `Optional> keys` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The keys being held while double-clicking. + - `JsonValue; type "function"constant` - - `JsonValue; type "double_click"constant` + The type of tool call. This is always going to be `function` for this type of tool call. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `FUNCTION("function")` - - `DOUBLE_CLICK("double_click")` +### Tool Call Delta - - `long x` +- `class ToolCallDelta: A class that can be one of several variants.union` - The x-coordinate where the double click occurred. + Details of the Code Interpreter tool call the run step was involved in. - - `long y` + - `class CodeInterpreterToolCallDelta:` - The y-coordinate where the double click occurred. + Details of the Code Interpreter tool call the run step was involved in. - - `Drag` + - `long index` - - `List path` + The index of the tool call in the tool calls array. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `JsonValue; type "code_interpreter"constant` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `long x` + - `CODE_INTERPRETER("code_interpreter")` - The x-coordinate. + - `Optional id` - - `long y` + The ID of the tool call. - The y-coordinate. + - `Optional codeInterpreter` - - `JsonValue; type "drag"constant` + The Code Interpreter tool call definition. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `Optional input` - - `DRAG("drag")` + The input to the Code Interpreter tool call. - - `Optional> keys` + - `Optional> outputs` - The keys being held while dragging the mouse. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `Keypress` + - `class CodeInterpreterLogs:` - - `List keys` + Text output from the Code Interpreter tool call as part of a run step. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `long index` - - `JsonValue; type "keypress"constant` + The index of the output in the outputs array. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `JsonValue; type "logs"constant` - - `KEYPRESS("keypress")` + Always `logs`. - - `Move` + - `LOGS("logs")` - - `JsonValue; type "move"constant` + - `Optional logs` - Specifies the event type. For a move action, this property is always set to `move`. + The text output from the Code Interpreter tool call. - - `MOVE("move")` + - `class CodeInterpreterOutputImage:` - - `long x` + - `long index` - The x-coordinate to move to. + The index of the output in the outputs array. - - `long y` + - `JsonValue; type "image"constant` - The y-coordinate to move to. + Always `image`. - - `Optional> keys` + - `IMAGE("image")` - The keys being held while moving the mouse. + - `Optional image` - - `JsonValue;` + - `Optional fileId` - - `JsonValue; type "screenshot"constant` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `class FileSearchToolCallDelta:` - - `SCREENSHOT("screenshot")` + - `JsonValue fileSearch` - - `Scroll` + For now, this is always going to be an empty object. - - `long scrollX` + - `long index` - The horizontal scroll distance. + The index of the tool call in the tool calls array. - - `long scrollY` + - `JsonValue; type "file_search"constant` - The vertical scroll distance. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `JsonValue; type "scroll"constant` + - `FILE_SEARCH("file_search")` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `Optional id` - - `SCROLL("scroll")` + The ID of the tool call object. - - `long x` + - `class FunctionToolCallDelta:` - The x-coordinate where the scroll occurred. + - `long index` - - `long y` + The index of the tool call in the tool calls array. - The y-coordinate where the scroll occurred. + - `JsonValue; type "function"constant` - - `Optional> keys` + The type of tool call. This is always going to be `function` for this type of tool call. - The keys being held while scrolling. + - `FUNCTION("function")` - - `Type` + - `Optional id` - - `String text` + The ID of the tool call object. - The text to type. + - `Optional function` - - `JsonValue; type "type"constant` + The definition of the function that was called. - Specifies the event type. For a type action, this property is always set to `type`. + - `Optional arguments` - - `TYPE("type")` + The arguments passed to the function. - - `JsonValue;` + - `Optional name` - - `JsonValue; type "wait"constant` + The name of the function. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `Optional output` - - `WAIT("wait")` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `Optional> actions` +### Tool Call Delta Object - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. +- `class ToolCallDeltaObject:` - - `Click` + Details of the tool call. - - `DoubleClick` + - `JsonValue; type "tool_calls"constant` - - `Drag` + Always `tool_calls`. - - `Keypress` + - `TOOL_CALLS("tool_calls")` - - `Move` + - `Optional> toolCalls` - - `JsonValue;` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `Scroll` + - `class CodeInterpreterToolCallDelta:` - - `Type` + Details of the Code Interpreter tool call the run step was involved in. - - `JsonValue;` + - `long index` - - `Optional agent` + The index of the tool call in the tool calls array. - The agent that produced this item. + - `JsonValue; type "code_interpreter"constant` - - `String agentName` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The canonical name of the agent that produced this item. + - `CODE_INTERPRETER("code_interpreter")` - - `ComputerCallOutput` + - `Optional id` - - `String callId` + The ID of the tool call. - The ID of the computer tool call that produced the output. + - `Optional codeInterpreter` - - `BetaResponseComputerToolCallOutputScreenshot output` + The Code Interpreter tool call definition. - A computer screenshot image used with the computer use tool. + - `Optional input` - - `JsonValue; type "computer_screenshot"constant` + The input to the Code Interpreter tool call. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `Optional> outputs` - - `COMPUTER_SCREENSHOT("computer_screenshot")` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `Optional fileId` + - `class CodeInterpreterLogs:` - The identifier of an uploaded file that contains the screenshot. + Text output from the Code Interpreter tool call as part of a run step. - - `Optional imageUrl` + - `long index` - The URL of the screenshot image. + The index of the output in the outputs array. - - `JsonValue; type "computer_call_output"constant` + - `JsonValue; type "logs"constant` - The type of the computer tool call output. Always `computer_call_output`. + Always `logs`. - - `COMPUTER_CALL_OUTPUT("computer_call_output")` + - `LOGS("logs")` - - `Optional id` + - `Optional logs` - The ID of the computer tool call output. + The text output from the Code Interpreter tool call. - - `Optional> acknowledgedSafetyChecks` + - `class CodeInterpreterOutputImage:` - The safety checks reported by the API that have been acknowledged by the developer. + - `long index` - - `String id` + The index of the output in the outputs array. - The ID of the pending safety check. + - `JsonValue; type "image"constant` - - `Optional code` + Always `image`. - The type of the pending safety check. + - `IMAGE("image")` - - `Optional message` + - `Optional image` - Details about the pending safety check. + - `Optional fileId` - - `Optional agent` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The agent that produced this item. + - `class FileSearchToolCallDelta:` - - `String agentName` + - `JsonValue fileSearch` - The canonical name of the agent that produced this item. + For now, this is always going to be an empty object. - - `Optional status` + - `long index` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The index of the tool call in the tool calls array. - - `IN_PROGRESS("in_progress")` + - `JsonValue; type "file_search"constant` - - `COMPLETED("completed")` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `INCOMPLETE("incomplete")` + - `FILE_SEARCH("file_search")` - - `class BetaResponseFunctionWebSearch:` + - `Optional id` - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + The ID of the tool call object. - - `String id` + - `class FunctionToolCallDelta:` - The unique ID of the web search tool call. + - `long index` - - `Action action` + The index of the tool call in the tool calls array. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `JsonValue; type "function"constant` - - `class Search:` + The type of tool call. This is always going to be `function` for this type of tool call. - Action type "search" - Performs a web search query. + - `FUNCTION("function")` - - `JsonValue; type "search"constant` + - `Optional id` - The action type. + The ID of the tool call object. - - `SEARCH("search")` + - `Optional function` - - `Optional> queries` + The definition of the function that was called. - The search queries. + - `Optional arguments` - - `Optional query` + The arguments passed to the function. - The search query. + - `Optional name` - - `Optional> sources` + The name of the function. - The sources used in the search. + - `Optional output` - - `JsonValue; type "url"constant` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The type of source. Always `url`. +### Tool Calls Step Details - - `URL("url")` +- `class ToolCallsStepDetails:` - - `String url` + Details of the tool call. - The URL of the source. + - `List toolCalls` - - `class OpenPage:` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - Action type "open_page" - Opens a specific URL from search results. + - `class CodeInterpreterToolCall:` - - `JsonValue; type "open_page"constant` + Details of the Code Interpreter tool call the run step was involved in. - The action type. + - `String id` - - `OPEN_PAGE("open_page")` + The ID of the tool call. - - `Optional url` + - `CodeInterpreter codeInterpreter` - The URL opened by the model. + The Code Interpreter tool call definition. - - `class FindInPage:` + - `String input` - Action type "find_in_page": Searches for a pattern within a loaded page. + The input to the Code Interpreter tool call. - - `String pattern` + - `List outputs` - The pattern or text to search for within the page. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `JsonValue; type "find_in_page"constant` + - `class LogsOutput:` - The action type. + Text output from the Code Interpreter tool call as part of a run step. - - `FIND_IN_PAGE("find_in_page")` + - `String logs` - - `String url` + The text output from the Code Interpreter tool call. - The URL of the page searched for the pattern. + - `JsonValue; type "logs"constant` - - `Status status` + Always `logs`. - The status of the web search tool call. + - `LOGS("logs")` - - `IN_PROGRESS("in_progress")` + - `class ImageOutput:` - - `SEARCHING("searching")` + - `Image image` - - `COMPLETED("completed")` + - `String fileId` - - `FAILED("failed")` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `JsonValue; type "web_search_call"constant` + - `JsonValue; type "image"constant` - The type of the web search tool call. Always `web_search_call`. + Always `image`. - - `WEB_SEARCH_CALL("web_search_call")` + - `IMAGE("image")` - - `Optional agent` + - `JsonValue; type "code_interpreter"constant` - The agent that produced this item. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `String agentName` + - `CODE_INTERPRETER("code_interpreter")` - The canonical name of the agent that produced this item. + - `class FileSearchToolCall:` - - `class BetaResponseFunctionToolCall:` + - `String id` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The ID of the tool call object. - - `String arguments` + - `FileSearch fileSearch` - A JSON string of the arguments to pass to the function. + For now, this is always going to be an empty object. - - `String callId` + - `Optional rankingOptions` - The unique ID of the function tool call generated by the model. + The ranking options for the file search. - - `String name` + - `Ranker ranker` - The name of the function to run. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `JsonValue; type "function_call"constant` + - `AUTO("auto")` - The type of the function tool call. Always `function_call`. + - `DEFAULT_2024_08_21("default_2024_08_21")` - - `FUNCTION_CALL("function_call")` + - `double scoreThreshold` - - `Optional id` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The unique ID of the function tool call. + - `Optional> results` - - `Optional agent` + The results of the file search. - The agent that produced this item. + - `String fileId` - - `String agentName` + The ID of the file that result was found in. - The canonical name of the agent that produced this item. + - `String fileName` - - `Optional caller` + The name of the file that result was found in. - The execution context that produced this tool call. + - `double score` - - `JsonValue;` + The score of the result. All values must be a floating point number between 0 and 1. - - `JsonValue; type "direct"constant` + - `Optional> content` - - `DIRECT("direct")` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `class Program:` + - `Optional text` - - `String callerId` + The text content of the file. - The call ID of the program item that produced this tool call. + - `Optional type` - - `JsonValue; type "program"constant` + The type of the content. - - `PROGRAM("program")` + - `TEXT("text")` - - `Optional namespace` + - `JsonValue; type "file_search"constant` - The namespace of the function to run. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `Optional status` + - `FILE_SEARCH("file_search")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `class FunctionToolCall:` - - `IN_PROGRESS("in_progress")` + - `String id` - - `COMPLETED("completed")` + The ID of the tool call object. - - `INCOMPLETE("incomplete")` + - `Function function` - - `FunctionCallOutput` + The definition of the function that was called. - - `String callId` + - `String arguments` - The unique ID of the function tool call generated by the model. + The arguments passed to the function. - - `Output output` + - `String name` - Text, image, or file output of the function tool call. + The name of the function. - - `String` + - `Optional output` - - `List` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `class BetaResponseInputTextContent:` + - `JsonValue; type "function"constant` - A text input to the model. + The type of tool call. This is always going to be `function` for this type of tool call. - - `String text` + - `FUNCTION("function")` - The text input to the model. + - `JsonValue; type "tool_calls"constant` - - `JsonValue; type "input_text"constant` + Always `tool_calls`. - The type of the input item. Always `input_text`. + - `TOOL_CALLS("tool_calls")` - - `INPUT_TEXT("input_text")` +# Messages - - `Optional promptCacheBreakpoint` +## List messages - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. +`MessageListPage beta().threads().messages().list(MessageListParamsparams = MessageListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` - - `JsonValue; mode "explicit"constant` +**get** `/threads/{thread_id}/messages` - The breakpoint mode. Always `explicit`. +Returns a list of messages for a given thread. - - `EXPLICIT("explicit")` +### Parameters - - `class BetaResponseInputImageContent:` +- `MessageListParams params` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `Optional threadId` - - `JsonValue; type "input_image"constant` + - `Optional after` - The type of the input item. Always `input_image`. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `INPUT_IMAGE("input_image")` + - `Optional before` - - `Optional detail` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Optional limit` - - `LOW("low")` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `HIGH("high")` + - `Optional order` - - `AUTO("auto")` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `ORIGINAL("original")` + - `ASC("asc")` - - `Optional fileId` + - `DESC("desc")` - The ID of the file to be sent to the model. + - `Optional runId` - - `Optional imageUrl` + Filter messages by the run ID that generated them. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. +### Returns - - `Optional promptCacheBreakpoint` +- `class Message:` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `JsonValue; mode "explicit"constant` + - `String id` - The breakpoint mode. Always `explicit`. + The identifier, which can be referenced in API endpoints. - - `EXPLICIT("explicit")` + - `Optional assistantId` - - `class BetaResponseInputFileContent:` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - A file input to the model. + - `Optional> attachments` - - `JsonValue; type "input_file"constant` + A list of files attached to the message, and the tools they were added to. - The type of the input item. Always `input_file`. + - `Optional fileId` - - `INPUT_FILE("input_file")` + The ID of the file to attach to the message. - - `Optional detail` + - `Optional> tools` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The tools to add this file to. - - `AUTO("auto")` + - `class CodeInterpreterTool:` - - `LOW("low")` + - `JsonValue; type "code_interpreter"constant` - - `HIGH("high")` + The type of tool being defined: `code_interpreter` - - `Optional fileData` + - `CODE_INTERPRETER("code_interpreter")` - The base64-encoded data of the file to be sent to the model. + - `JsonValue;` - - `Optional fileId` + - `JsonValue; type "file_search"constant` - The ID of the file to be sent to the model. + The type of tool being defined: `file_search` - - `Optional fileUrl` + - `FILE_SEARCH("file_search")` - The URL of the file to be sent to the model. + - `Optional completedAt` - - `Optional filename` + The Unix timestamp (in seconds) for when the message was completed. - The name of the file to be sent to the model. + - `List content` - - `Optional promptCacheBreakpoint` + The content of the message in array of text and/or images. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `class ImageFileContentBlock:` - - `JsonValue; mode "explicit"constant` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The breakpoint mode. Always `explicit`. + - `ImageFile imageFile` - - `EXPLICIT("explicit")` + - `String fileId` - - `JsonValue; type "function_call_output"constant` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The type of the function tool call output. Always `function_call_output`. + - `Optional detail` - - `FUNCTION_CALL_OUTPUT("function_call_output")` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `Optional id` + - `AUTO("auto")` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `LOW("low")` - - `Optional agent` + - `HIGH("high")` - The agent that produced this item. + - `JsonValue; type "image_file"constant` - - `String agentName` + Always `image_file`. - The canonical name of the agent that produced this item. + - `IMAGE_FILE("image_file")` - - `Optional caller` + - `class ImageUrlContentBlock:` - The execution context that produced this tool call. + References an image URL in the content of a message. - - `JsonValue;` + - `ImageUrl imageUrl` - - `JsonValue; type "direct"constant` + - `String url` - The caller type. Always `direct`. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `DIRECT("direct")` + - `Optional detail` - - `class Program:` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `String callerId` + - `AUTO("auto")` - The call ID of the program item that produced this tool call. + - `LOW("low")` - - `JsonValue; type "program"constant` + - `HIGH("high")` - The caller type. Always `program`. + - `JsonValue; type "image_url"constant` - - `PROGRAM("program")` + The type of the content part. - - `Optional status` + - `IMAGE_URL("image_url")` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `class TextContentBlock:` - - `IN_PROGRESS("in_progress")` + The text content that is part of a message. - - `COMPLETED("completed")` + - `Text text` - - `INCOMPLETE("incomplete")` + - `List annotations` - - `AgentMessage` + - `class FileCitationAnnotation:` - - `String author` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The sending agent identity. + - `long endIndex` - - `List content` + - `FileCitation fileCitation` - Plaintext, image, or encrypted content sent between agents. + - `String fileId` - - `class BetaResponseInputTextContent:` + The ID of the specific File the citation is from. - A text input to the model. + - `long startIndex` - - `class BetaResponseInputImageContent:` + - `String text` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The text in the message content that needs to be replaced. - - `class EncryptedContent:` + - `JsonValue; type "file_citation"constant` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Always `file_citation`. - - `String encryptedContent` + - `FILE_CITATION("file_citation")` - Opaque encrypted content. + - `class FilePathAnnotation:` - - `JsonValue; type "encrypted_content"constant` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The type of the input item. Always `encrypted_content`. + - `long endIndex` - - `ENCRYPTED_CONTENT("encrypted_content")` + - `FilePath filePath` - - `String recipient` + - `String fileId` - The destination agent identity. + The ID of the file that was generated. - - `JsonValue; type "agent_message"constant` + - `long startIndex` - The item type. Always `agent_message`. + - `String text` - - `AGENT_MESSAGE("agent_message")` + The text in the message content that needs to be replaced. - - `Optional id` + - `JsonValue; type "file_path"constant` - The unique ID of this agent message item. + Always `file_path`. - - `Optional agent` + - `FILE_PATH("file_path")` - The agent that produced this item. + - `String value` - - `String agentName` + The data that makes up the text. - The canonical name of the agent that produced this item. + - `JsonValue; type "text"constant` - - `MultiAgentCall` + Always `text`. - - `Action action` + - `TEXT("text")` - The multi-agent action that was executed. + - `class RefusalContentBlock:` - - `SPAWN_AGENT("spawn_agent")` + The refusal content generated by the assistant. - - `INTERRUPT_AGENT("interrupt_agent")` + - `String refusal` - - `LIST_AGENTS("list_agents")` + - `JsonValue; type "refusal"constant` - - `SEND_MESSAGE("send_message")` + Always `refusal`. - - `FOLLOWUP_TASK("followup_task")` + - `REFUSAL("refusal")` - - `WAIT_AGENT("wait_agent")` + - `long createdAt` - - `String arguments` + The Unix timestamp (in seconds) for when the message was created. - The action arguments as a JSON string. + - `Optional incompleteAt` - - `String callId` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - The unique ID linking this call to its output. + - `Optional incompleteDetails` - - `JsonValue; type "multi_agent_call"constant` + On an incomplete message, details about why the message is incomplete. - The item type. Always `multi_agent_call`. + - `Reason reason` - - `MULTI_AGENT_CALL("multi_agent_call")` + The reason the message is incomplete. - - `Optional id` + - `CONTENT_FILTER("content_filter")` - The unique ID of this multi-agent call. + - `MAX_TOKENS("max_tokens")` - - `Optional agent` + - `RUN_CANCELLED("run_cancelled")` - The agent that produced this item. + - `RUN_EXPIRED("run_expired")` - - `String agentName` + - `RUN_FAILED("run_failed")` - The canonical name of the agent that produced this item. + - `Optional metadata` - - `MultiAgentCallOutput` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `Action action` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The multi-agent action that produced this result. + - `JsonValue; object_ "thread.message"constant` - - `SPAWN_AGENT("spawn_agent")` + The object type, which is always `thread.message`. - - `INTERRUPT_AGENT("interrupt_agent")` + - `THREAD_MESSAGE("thread.message")` - - `LIST_AGENTS("list_agents")` + - `Role role` - - `SEND_MESSAGE("send_message")` + The entity that produced the message. One of `user` or `assistant`. - - `FOLLOWUP_TASK("followup_task")` + - `USER("user")` - - `WAIT_AGENT("wait_agent")` + - `ASSISTANT("assistant")` - - `String callId` + - `Optional runId` - The unique ID of the multi-agent call. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + + - `Status status` + + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `List output` + - `IN_PROGRESS("in_progress")` - Text output returned by the multi-agent action. + - `INCOMPLETE("incomplete")` - - `String text` + - `COMPLETED("completed")` - The text content. + - `String threadId` - - `JsonValue; type "output_text"constant` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The content type. Always `output_text`. +### Example - - `OUTPUT_TEXT("output_text")` +```java +package com.openai.example; - - `Optional annotations` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.messages.MessageListPage; +import com.openai.models.beta.threads.messages.MessageListParams; - Citations associated with the text content. +public final class Main { + private Main() {} - - `List` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `String fileId` + MessageListPage page = client.beta().threads().messages().list("thread_id"); + } +} +``` - The ID of the file. +#### Response - - `String filename` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" + } + ], + "first_id": "msg_abc123", + "has_more": false, + "last_id": "msg_abc123", + "object": "list" +} +``` - The filename of the file cited. +## Create message - - `long index` +`Message beta().threads().messages().create(MessageCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - The index of the file in the list of files. +**post** `/threads/{thread_id}/messages` - - `JsonValue; type "file_citation"constant` +Create a message. - The citation type. Always `file_citation`. +### Parameters - - `FILE_CITATION("file_citation")` +- `MessageCreateParams params` - - `List` + - `Optional threadId` - - `long endIndex` + - `Content content` - The index of the last character of the citation in the message. + The text contents of the message. - - `long startIndex` + - `String` - The index of the first character of the citation in the message. + - `List` - - `String title` + - `class ImageFileContentBlock:` - The title of the cited resource. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `JsonValue; type "url_citation"constant` + - `ImageFile imageFile` - The citation type. Always `url_citation`. + - `String fileId` - - `URL_CITATION("url_citation")` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `String url` + - `Optional detail` - The URL of the cited resource. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `List` + - `AUTO("auto")` - - `String containerId` + - `LOW("low")` - The ID of the container. + - `HIGH("high")` - - `long endIndex` + - `JsonValue; type "image_file"constant` - The index of the last character of the citation in the message. + Always `image_file`. - - `String fileId` + - `IMAGE_FILE("image_file")` - The ID of the container file. + - `class ImageUrlContentBlock:` - - `String filename` + References an image URL in the content of a message. - The filename of the container file cited. + - `ImageUrl imageUrl` - - `long startIndex` + - `String url` - The index of the first character of the citation in the message. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `JsonValue; type "container_file_citation"constant` + - `Optional detail` - The citation type. Always `container_file_citation`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `CONTAINER_FILE_CITATION("container_file_citation")` + - `AUTO("auto")` - - `JsonValue; type "multi_agent_call_output"constant` + - `LOW("low")` - The item type. Always `multi_agent_call_output`. + - `HIGH("high")` - - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` + - `JsonValue; type "image_url"constant` - - `Optional id` + The type of the content part. - The unique ID of this multi-agent call output. + - `IMAGE_URL("image_url")` - - `Optional agent` + - `class TextContentBlockParam:` - The agent that produced this item. + The text content that is part of a message. - - `String agentName` + - `String text` - The canonical name of the agent that produced this item. + Text content to be sent to the model - - `ToolSearchCall` + - `JsonValue; type "text"constant` - - `JsonValue arguments` + Always `text`. - The arguments supplied to the tool search call. + - `TEXT("text")` - - `JsonValue; type "tool_search_call"constant` + - `Role role` - The item type. Always `tool_search_call`. + The role of the entity that is creating the message. Allowed values include: - - `TOOL_SEARCH_CALL("tool_search_call")` + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - - `Optional id` + - `USER("user")` - The unique ID of this tool search call. + - `ASSISTANT("assistant")` - - `Optional agent` + - `Optional> attachments` - The agent that produced this item. + A list of files attached to the message, and the tools they should be added to. - - `String agentName` + - `Optional fileId` - The canonical name of the agent that produced this item. + The ID of the file to attach to the message. - - `Optional callId` + - `Optional> tools` - The unique ID of the tool search call generated by the model. + The tools to add this file to. - - `Optional execution` + - `class CodeInterpreterTool:` - Whether tool search was executed by the server or by the client. + - `JsonValue; type "code_interpreter"constant` - - `SERVER("server")` + The type of tool being defined: `code_interpreter` - - `CLIENT("client")` + - `CODE_INTERPRETER("code_interpreter")` - - `Optional status` + - `JsonValue;` - The status of the tool search call. + - `JsonValue; type "file_search"constant` - - `IN_PROGRESS("in_progress")` + The type of tool being defined: `file_search` - - `COMPLETED("completed")` + - `FILE_SEARCH("file_search")` - - `INCOMPLETE("incomplete")` + - `Optional metadata` - - `class BetaResponseToolSearchOutputItemParam:` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `List tools` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The loaded tool definitions returned by the tool search output. +### Returns - - `class BetaFunctionTool:` +- `class Message:` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `String name` + - `String id` - The name of the function to call. + The identifier, which can be referenced in API endpoints. - - `Optional parameters` + - `Optional assistantId` - A JSON schema object describing the parameters of the function. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `Optional strict` + - `Optional> attachments` - Whether strict parameter validation is enforced for this function tool. + A list of files attached to the message, and the tools they were added to. - - `JsonValue; type "function"constant` + - `Optional fileId` - The type of the function tool. Always `function`. + The ID of the file to attach to the message. - - `FUNCTION("function")` + - `Optional> tools` - - `Optional> allowedCallers` + The tools to add this file to. - The tool invocation context(s). + - `class CodeInterpreterTool:` - - `DIRECT("direct")` + - `JsonValue; type "code_interpreter"constant` - - `PROGRAMMATIC("programmatic")` + The type of tool being defined: `code_interpreter` - - `Optional deferLoading` + - `CODE_INTERPRETER("code_interpreter")` - Whether this function is deferred and loaded via tool search. + - `JsonValue;` - - `Optional description` + - `JsonValue; type "file_search"constant` - A description of the function. Used by the model to determine whether or not to call the function. + The type of tool being defined: `file_search` - - `Optional outputSchema` + - `FILE_SEARCH("file_search")` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `Optional completedAt` - - `class BetaFileSearchTool:` + The Unix timestamp (in seconds) for when the message was completed. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `List content` - - `JsonValue; type "file_search"constant` + The content of the message in array of text and/or images. - The type of the file search tool. Always `file_search`. + - `class ImageFileContentBlock:` - - `FILE_SEARCH("file_search")` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `List vectorStoreIds` + - `ImageFile imageFile` - The IDs of the vector stores to search. + - `String fileId` - - `Optional filters` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - A filter to apply. + - `Optional detail` - - `class ComparisonFilter:` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `AUTO("auto")` - - `String key` + - `LOW("low")` - The key to compare against the value. + - `HIGH("high")` - - `Type type` + - `JsonValue; type "image_file"constant` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Always `image_file`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `IMAGE_FILE("image_file")` - - `EQ("eq")` + - `class ImageUrlContentBlock:` - - `NE("ne")` + References an image URL in the content of a message. - - `GT("gt")` + - `ImageUrl imageUrl` - - `GTE("gte")` + - `String url` - - `LT("lt")` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `LTE("lte")` + - `Optional detail` - - `IN("in")` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `NIN("nin")` + - `AUTO("auto")` - - `Value value` + - `LOW("low")` - The value to compare against the attribute key; supports string, number, or boolean types. + - `HIGH("high")` - - `String` + - `JsonValue; type "image_url"constant` - - `double` + The type of the content part. - - `boolean` + - `IMAGE_URL("image_url")` - - `List` + - `class TextContentBlock:` - - `class CompoundFilter:` + The text content that is part of a message. - Combine multiple filters using `and` or `or`. + - `Text text` - - `List filters` + - `List annotations` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `class FileCitationAnnotation:` - - `class ComparisonFilter:` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `long endIndex` - - `String key` + - `FileCitation fileCitation` - The key to compare against the value. + - `String fileId` - - `Type type` + The ID of the specific File the citation is from. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `long startIndex` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `String text` - - `EQ("eq")` + The text in the message content that needs to be replaced. - - `NE("ne")` + - `JsonValue; type "file_citation"constant` - - `GT("gt")` + Always `file_citation`. - - `GTE("gte")` + - `FILE_CITATION("file_citation")` - - `LT("lt")` + - `class FilePathAnnotation:` - - `LTE("lte")` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `IN("in")` + - `long endIndex` - - `NIN("nin")` + - `FilePath filePath` - - `Value value` + - `String fileId` - The value to compare against the attribute key; supports string, number, or boolean types. + The ID of the file that was generated. - - `String` + - `long startIndex` - - `double` + - `String text` - - `boolean` + The text in the message content that needs to be replaced. - - `List` + - `JsonValue; type "file_path"constant` - - `JsonValue` + Always `file_path`. - - `Type type` + - `FILE_PATH("file_path")` - Type of operation: `and` or `or`. + - `String value` - - `AND("and")` + The data that makes up the text. - - `OR("or")` + - `JsonValue; type "text"constant` - - `Optional maxNumResults` + Always `text`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `TEXT("text")` - - `Optional rankingOptions` + - `class RefusalContentBlock:` - Ranking options for search. + The refusal content generated by the assistant. - - `Optional hybridSearch` + - `String refusal` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `JsonValue; type "refusal"constant` - - `double embeddingWeight` + Always `refusal`. - The weight of the embedding in the reciprocal ranking fusion. + - `REFUSAL("refusal")` - - `double textWeight` + - `long createdAt` - The weight of the text in the reciprocal ranking fusion. + The Unix timestamp (in seconds) for when the message was created. - - `Optional ranker` + - `Optional incompleteAt` - The ranker to use for the file search. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `AUTO("auto")` + - `Optional incompleteDetails` - - `DEFAULT_2024_11_15("default-2024-11-15")` + On an incomplete message, details about why the message is incomplete. - - `Optional scoreThreshold` + - `Reason reason` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The reason the message is incomplete. - - `class BetaComputerTool:` + - `CONTENT_FILTER("content_filter")` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `MAX_TOKENS("max_tokens")` - - `JsonValue; type "computer"constant` + - `RUN_CANCELLED("run_cancelled")` - The type of the computer tool. Always `computer`. + - `RUN_EXPIRED("run_expired")` - - `COMPUTER("computer")` + - `RUN_FAILED("run_failed")` - - `class BetaComputerUsePreviewTool:` + - `Optional metadata` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `long displayHeight` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The height of the computer display. + - `JsonValue; object_ "thread.message"constant` - - `long displayWidth` + The object type, which is always `thread.message`. - The width of the computer display. + - `THREAD_MESSAGE("thread.message")` - - `Environment environment` + - `Role role` - The type of computer environment to control. + The entity that produced the message. One of `user` or `assistant`. - - `WINDOWS("windows")` + - `USER("user")` - - `MAC("mac")` + - `ASSISTANT("assistant")` - - `LINUX("linux")` + - `Optional runId` - - `UBUNTU("ubuntu")` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `BROWSER("browser")` + - `Status status` - - `JsonValue; type "computer_use_preview"constant` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The type of the computer use tool. Always `computer_use_preview`. + - `IN_PROGRESS("in_progress")` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `INCOMPLETE("incomplete")` - - `class BetaWebSearchTool:` + - `COMPLETED("completed")` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `String threadId` - - `Type type` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. +### Example - - `WEB_SEARCH("web_search")` +```java +package com.openai.example; - - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.messages.Message; +import com.openai.models.beta.threads.messages.MessageCreateParams; - - `Optional filters` +public final class Main { + private Main() {} - Filters for the search. + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `Optional> allowedDomains` + MessageCreateParams params = MessageCreateParams.builder() + .threadId("thread_id") + .content("string") + .role(MessageCreateParams.Role.USER) + .build(); + Message message = client.beta().threads().messages().create(params); + } +} +``` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. +#### Response - Example: `["pubmed.ncbi.nlm.nih.gov"]` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `Optional searchContextSize` +## Modify message - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. +`Message beta().threads().messages().update(MessageUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `LOW("low")` +**post** `/threads/{thread_id}/messages/{message_id}` - - `MEDIUM("medium")` +Modifies a message. - - `HIGH("high")` +### Parameters - - `Optional userLocation` +- `MessageUpdateParams params` - The approximate location of the user. + - `String threadId` - - `Optional city` + - `Optional messageId` - Free text input for the city of the user, e.g. `San Francisco`. + - `Optional metadata` - - `Optional country` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Optional region` +### Returns - Free text input for the region of the user, e.g. `California`. +- `class Message:` - - `Optional timezone` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `String id` - - `Optional type` + The identifier, which can be referenced in API endpoints. - The type of location approximation. Always `approximate`. + - `Optional assistantId` - - `APPROXIMATE("approximate")` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `Mcp` + - `Optional> attachments` - - `String serverLabel` + A list of files attached to the message, and the tools they were added to. - A label for this MCP server, used to identify it in tool calls. + - `Optional fileId` - - `JsonValue; type "mcp"constant` + The ID of the file to attach to the message. - The type of the MCP tool. Always `mcp`. + - `Optional> tools` - - `MCP("mcp")` + The tools to add this file to. - - `Optional> allowedCallers` + - `class CodeInterpreterTool:` - The tool invocation context(s). + - `JsonValue; type "code_interpreter"constant` - - `DIRECT("direct")` + The type of tool being defined: `code_interpreter` - - `PROGRAMMATIC("programmatic")` + - `CODE_INTERPRETER("code_interpreter")` - - `Optional allowedTools` + - `JsonValue;` - List of allowed tool names or a filter object. + - `JsonValue; type "file_search"constant` - - `List` + The type of tool being defined: `file_search` - - `class McpToolFilter:` + - `FILE_SEARCH("file_search")` - A filter object to specify which tools are allowed. + - `Optional completedAt` - - `Optional readOnly` + The Unix timestamp (in seconds) for when the message was completed. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `List content` - - `Optional> toolNames` + The content of the message in array of text and/or images. - List of allowed tool names. + - `class ImageFileContentBlock:` - - `Optional authorization` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `ImageFile imageFile` - - `Optional connectorId` + - `String fileId` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Currently supported `connector_id` values are: + - `Optional detail` - - 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` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `CONNECTOR_DROPBOX("connector_dropbox")` + - `AUTO("auto")` - - `CONNECTOR_GMAIL("connector_gmail")` + - `LOW("low")` - - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` + - `HIGH("high")` - - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` + - `JsonValue; type "image_file"constant` - - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` + Always `image_file`. - - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` + - `IMAGE_FILE("image_file")` - - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` + - `class ImageUrlContentBlock:` - - `CONNECTOR_SHAREPOINT("connector_sharepoint")` + References an image URL in the content of a message. - - `Optional deferLoading` + - `ImageUrl imageUrl` - Whether this MCP tool is deferred and discovered via tool search. + - `String url` - - `Optional headers` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `Optional detail` - - `Optional requireApproval` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - Specify which of the MCP server's tools require approval. + - `AUTO("auto")` - - `class McpToolApprovalFilter:` + - `LOW("low")` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `HIGH("high")` - - `Optional always` + - `JsonValue; type "image_url"constant` - A filter object to specify which tools are allowed. + The type of the content part. - - `Optional readOnly` + - `IMAGE_URL("image_url")` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `class TextContentBlock:` - - `Optional> toolNames` + The text content that is part of a message. - List of allowed tool names. + - `Text text` - - `Optional never` + - `List annotations` - A filter object to specify which tools are allowed. + - `class FileCitationAnnotation:` - - `Optional readOnly` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `long endIndex` - - `Optional> toolNames` + - `FileCitation fileCitation` - List of allowed tool names. + - `String fileId` - - `enum McpToolApprovalSetting:` + The ID of the specific File the citation is from. - 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. + - `long startIndex` - - `ALWAYS("always")` + - `String text` - - `NEVER("never")` + The text in the message content that needs to be replaced. - - `Optional serverDescription` + - `JsonValue; type "file_citation"constant` - Optional description of the MCP server, used to provide more context. + Always `file_citation`. - - `Optional serverUrl` + - `FILE_CITATION("file_citation")` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `class FilePathAnnotation:` - - `Optional tunnelId` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `long endIndex` - - `CodeInterpreter` + - `FilePath filePath` - - `Container container` + - `String fileId` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The ID of the file that was generated. - - `String` + - `long startIndex` - - `class CodeInterpreterToolAuto:` + - `String text` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The text in the message content that needs to be replaced. - - `JsonValue; type "auto"constant` + - `JsonValue; type "file_path"constant` - Always `auto`. + Always `file_path`. - - `AUTO("auto")` + - `FILE_PATH("file_path")` - - `Optional> fileIds` + - `String value` - An optional list of uploaded files to make available to your code. + The data that makes up the text. - - `Optional memoryLimit` + - `JsonValue; type "text"constant` - The memory limit for the code interpreter container. + Always `text`. - - `_1G("1g")` + - `TEXT("text")` - - `_4G("4g")` + - `class RefusalContentBlock:` - - `_16G("16g")` + The refusal content generated by the assistant. - - `_64G("64g")` + - `String refusal` - - `Optional networkPolicy` + - `JsonValue; type "refusal"constant` - Network access policy for the container. + Always `refusal`. - - `class BetaContainerNetworkPolicyDisabled:` + - `REFUSAL("refusal")` - - `JsonValue; type "disabled"constant` + - `long createdAt` - Disable outbound network access. Always `disabled`. + The Unix timestamp (in seconds) for when the message was created. - - `DISABLED("disabled")` + - `Optional incompleteAt` - - `class BetaContainerNetworkPolicyAllowlist:` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `List allowedDomains` + - `Optional incompleteDetails` - A list of allowed domains when type is `allowlist`. + On an incomplete message, details about why the message is incomplete. - - `JsonValue; type "allowlist"constant` + - `Reason reason` - Allow outbound network access only to specified domains. Always `allowlist`. + The reason the message is incomplete. - - `ALLOWLIST("allowlist")` + - `CONTENT_FILTER("content_filter")` - - `Optional> domainSecrets` + - `MAX_TOKENS("max_tokens")` - Optional domain-scoped secrets for allowlisted domains. + - `RUN_CANCELLED("run_cancelled")` - - `String domain` + - `RUN_EXPIRED("run_expired")` - The domain associated with the secret. + - `RUN_FAILED("run_failed")` - - `String name` + - `Optional metadata` - The name of the secret to inject for the domain. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `String value` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The secret value to inject for the domain. + - `JsonValue; object_ "thread.message"constant` - - `JsonValue; type "code_interpreter"constant` + The object type, which is always `thread.message`. - The type of the code interpreter tool. Always `code_interpreter`. + - `THREAD_MESSAGE("thread.message")` - - `CODE_INTERPRETER("code_interpreter")` + - `Role role` - - `Optional> allowedCallers` + The entity that produced the message. One of `user` or `assistant`. - The tool invocation context(s). + - `USER("user")` - - `DIRECT("direct")` + - `ASSISTANT("assistant")` - - `PROGRAMMATIC("programmatic")` + - `Optional runId` - - `JsonValue;` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `JsonValue; type "programmatic_tool_calling"constant` + - `Status status` - The type of the tool. Always `programmatic_tool_calling`. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `IN_PROGRESS("in_progress")` - - `ImageGeneration` + - `INCOMPLETE("incomplete")` - - `JsonValue; type "image_generation"constant` + - `COMPLETED("completed")` - The type of the image generation tool. Always `image_generation`. + - `String threadId` - - `IMAGE_GENERATION("image_generation")` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `Optional action` +### Example - Whether to generate a new image or edit an existing image. Default: `auto`. +```java +package com.openai.example; - - `GENERATE("generate")` +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.messages.Message; +import com.openai.models.beta.threads.messages.MessageUpdateParams; - - `EDIT("edit")` +public final class Main { + private Main() {} - - `AUTO("auto")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `Optional background` + MessageUpdateParams params = MessageUpdateParams.builder() + .threadId("thread_id") + .messageId("message_id") + .build(); + Message message = client.beta().threads().messages().update(params); + } +} +``` - 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. +#### Response - `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. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. +## Retrieve message - - `TRANSPARENT("transparent")` +`Message beta().threads().messages().retrieve(MessageRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - - `OPAQUE("opaque")` +**get** `/threads/{thread_id}/messages/{message_id}` - - `AUTO("auto")` +Retrieve a message. - - `Optional inputFidelity` +### Parameters - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. +- `MessageRetrieveParams params` - - `HIGH("high")` + - `String threadId` - - `LOW("low")` + - `Optional messageId` - - `Optional inputImageMask` +### Returns - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). +- `class Message:` - - `Optional fileId` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - File ID for the mask image. + - `String id` - - `Optional imageUrl` + The identifier, which can be referenced in API endpoints. - Base64-encoded mask image. + - `Optional assistantId` - - `Optional model` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - The image generation model to use. Default: `gpt-image-1`. + - `Optional> attachments` - - `GPT_IMAGE_1("gpt-image-1")` + A list of files attached to the message, and the tools they were added to. - - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` + - `Optional fileId` - - `GPT_IMAGE_2("gpt-image-2")` + The ID of the file to attach to the message. - - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` + - `Optional> tools` - - `GPT_IMAGE_1_5("gpt-image-1.5")` + The tools to add this file to. - - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` + - `class CodeInterpreterTool:` - - `Optional moderation` + - `JsonValue; type "code_interpreter"constant` - Moderation level for the generated image. Default: `auto`. + The type of tool being defined: `code_interpreter` - - `AUTO("auto")` + - `CODE_INTERPRETER("code_interpreter")` - - `LOW("low")` + - `JsonValue;` - - `Optional outputCompression` + - `JsonValue; type "file_search"constant` - Compression level for the output image. Default: 100. + The type of tool being defined: `file_search` - - `Optional outputFormat` + - `FILE_SEARCH("file_search")` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `Optional completedAt` - - `PNG("png")` + The Unix timestamp (in seconds) for when the message was completed. - - `WEBP("webp")` + - `List content` - - `JPEG("jpeg")` + The content of the message in array of text and/or images. - - `Optional partialImages` + - `class ImageFileContentBlock:` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `Optional quality` + - `ImageFile imageFile` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `String fileId` - - `LOW("low")` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `MEDIUM("medium")` + - `Optional detail` - - `HIGH("high")` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - `AUTO("auto")` - - `Optional size` + - `LOW("low")` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `HIGH("high")` - - `_1024X1024("1024x1024")` + - `JsonValue; type "image_file"constant` - - `_1024X1536("1024x1536")` + Always `image_file`. - - `_1536X1024("1536x1024")` + - `IMAGE_FILE("image_file")` - - `AUTO("auto")` + - `class ImageUrlContentBlock:` - - `JsonValue;` + References an image URL in the content of a message. - - `JsonValue; type "local_shell"constant` + - `ImageUrl imageUrl` - The type of the local shell tool. Always `local_shell`. + - `String url` - - `LOCAL_SHELL("local_shell")` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `class BetaFunctionShellTool:` + - `Optional detail` - A tool that allows the model to execute shell commands. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `JsonValue; type "shell"constant` + - `AUTO("auto")` - The type of the shell tool. Always `shell`. + - `LOW("low")` - - `SHELL("shell")` + - `HIGH("high")` - - `Optional> allowedCallers` + - `JsonValue; type "image_url"constant` - The tool invocation context(s). + The type of the content part. - - `DIRECT("direct")` + - `IMAGE_URL("image_url")` - - `PROGRAMMATIC("programmatic")` + - `class TextContentBlock:` - - `Optional environment` + The text content that is part of a message. - - `class BetaContainerAuto:` + - `Text text` - - `JsonValue; type "container_auto"constant` + - `List annotations` + + - `class FileCitationAnnotation:` - Automatically creates a container for this request + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `CONTAINER_AUTO("container_auto")` + - `long endIndex` - - `Optional> fileIds` + - `FileCitation fileCitation` - An optional list of uploaded files to make available to your code. + - `String fileId` - - `Optional memoryLimit` + The ID of the specific File the citation is from. - The memory limit for the container. + - `long startIndex` - - `_1G("1g")` + - `String text` - - `_4G("4g")` + The text in the message content that needs to be replaced. - - `_16G("16g")` + - `JsonValue; type "file_citation"constant` - - `_64G("64g")` + Always `file_citation`. - - `Optional networkPolicy` + - `FILE_CITATION("file_citation")` - Network access policy for the container. + - `class FilePathAnnotation:` - - `class BetaContainerNetworkPolicyDisabled:` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `class BetaContainerNetworkPolicyAllowlist:` + - `long endIndex` - - `Optional> skills` + - `FilePath filePath` - An optional list of skills referenced by id or inline data. + - `String fileId` - - `class BetaSkillReference:` + The ID of the file that was generated. - - `String skillId` + - `long startIndex` - The ID of the referenced skill. + - `String text` - - `JsonValue; type "skill_reference"constant` + The text in the message content that needs to be replaced. - References a skill created with the /v1/skills endpoint. + - `JsonValue; type "file_path"constant` - - `SKILL_REFERENCE("skill_reference")` + Always `file_path`. - - `Optional version` + - `FILE_PATH("file_path")` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `String value` - - `class BetaInlineSkill:` + The data that makes up the text. - - `String description` + - `JsonValue; type "text"constant` - The description of the skill. + Always `text`. - - `String name` + - `TEXT("text")` - The name of the skill. + - `class RefusalContentBlock:` - - `BetaInlineSkillSource source` + The refusal content generated by the assistant. - Inline skill payload + - `String refusal` - - `String data` + - `JsonValue; type "refusal"constant` - Base64-encoded skill zip bundle. + Always `refusal`. - - `JsonValue; mediaType "application/zip"constant` + - `REFUSAL("refusal")` - The media type of the inline skill payload. Must be `application/zip`. + - `long createdAt` - - `APPLICATION_ZIP("application/zip")` + The Unix timestamp (in seconds) for when the message was created. - - `JsonValue; type "base64"constant` + - `Optional incompleteAt` - The type of the inline skill source. Must be `base64`. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `BASE64("base64")` + - `Optional incompleteDetails` - - `JsonValue; type "inline"constant` + On an incomplete message, details about why the message is incomplete. - Defines an inline skill for this request. + - `Reason reason` - - `INLINE("inline")` + The reason the message is incomplete. - - `class BetaLocalEnvironment:` + - `CONTENT_FILTER("content_filter")` - - `JsonValue; type "local"constant` + - `MAX_TOKENS("max_tokens")` - Use a local computer environment. + - `RUN_CANCELLED("run_cancelled")` - - `LOCAL("local")` + - `RUN_EXPIRED("run_expired")` - - `Optional> skills` + - `RUN_FAILED("run_failed")` - An optional list of skills. + - `Optional metadata` - - `String description` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The description of the skill. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `String name` + - `JsonValue; object_ "thread.message"constant` - The name of the skill. + The object type, which is always `thread.message`. - - `String path` + - `THREAD_MESSAGE("thread.message")` - The path to the directory containing the skill. + - `Role role` - - `class BetaContainerReference:` + The entity that produced the message. One of `user` or `assistant`. - - `String containerId` + - `USER("user")` - The ID of the referenced container. + - `ASSISTANT("assistant")` - - `JsonValue; type "container_reference"constant` + - `Optional runId` - References a container created with the /v1/containers endpoint + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `CONTAINER_REFERENCE("container_reference")` + - `Status status` - - `class BetaCustomTool:` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `IN_PROGRESS("in_progress")` - - `String name` + - `INCOMPLETE("incomplete")` - The name of the custom tool, used to identify it in tool calls. + - `COMPLETED("completed")` - - `JsonValue; type "custom"constant` + - `String threadId` - The type of the custom tool. Always `custom`. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `CUSTOM("custom")` +### Example - - `Optional> allowedCallers` +```java +package com.openai.example; - The tool invocation context(s). +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.messages.Message; +import com.openai.models.beta.threads.messages.MessageRetrieveParams; - - `DIRECT("direct")` +public final class Main { + private Main() {} - - `PROGRAMMATIC("programmatic")` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - `Optional deferLoading` + MessageRetrieveParams params = MessageRetrieveParams.builder() + .threadId("thread_id") + .messageId("message_id") + .build(); + Message message = client.beta().threads().messages().retrieve(params); + } +} +``` - Whether this tool should be deferred and discovered via tool search. +#### Response - - `Optional description` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - Optional description of the custom tool, used to provide more context. +## Delete message - - `Optional format` +`MessageDeleted beta().threads().messages().delete(MessageDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` - The input format for the custom tool. Default is unconstrained text. +**delete** `/threads/{thread_id}/messages/{message_id}` - - `JsonValue;` +Deletes a message. - - `JsonValue; type "text"constant` +### Parameters - Unconstrained text format. Always `text`. +- `MessageDeleteParams params` - - `TEXT("text")` + - `String threadId` - - `class Grammar:` + - `Optional messageId` - A grammar defined by the user. +### Returns - - `String definition` +- `class MessageDeleted:` - The grammar definition. + - `String id` - - `Syntax syntax` + - `boolean deleted` - The syntax of the grammar definition. One of `lark` or `regex`. + - `JsonValue; object_ "thread.message.deleted"constant` - - `LARK("lark")` + - `THREAD_MESSAGE_DELETED("thread.message.deleted")` - - `REGEX("regex")` +### Example - - `JsonValue; type "grammar"constant` +```java +package com.openai.example; - Grammar format. Always `grammar`. +import com.openai.client.OpenAIClient; +import com.openai.client.okhttp.OpenAIOkHttpClient; +import com.openai.models.beta.threads.messages.MessageDeleteParams; +import com.openai.models.beta.threads.messages.MessageDeleted; - - `GRAMMAR("grammar")` +public final class Main { + private Main() {} - - `class BetaNamespaceTool:` + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - Groups function/custom tools under a shared namespace. + MessageDeleteParams params = MessageDeleteParams.builder() + .threadId("thread_id") + .messageId("message_id") + .build(); + MessageDeleted messageDeleted = client.beta().threads().messages().delete(params); + } +} +``` - - `String description` +#### Response - A description of the namespace shown to the model. +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` - - `String name` +## Domain Types - The namespace name used in tool calls (for example, `crm`). +### Annotation - - `List tools` +- `class Annotation: A class that can be one of several variants.union` - The function/custom tools available inside this namespace. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `class Function:` + - `class FileCitationAnnotation:` - - `String name` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `JsonValue; type "function"constant` + - `long endIndex` - - `FUNCTION("function")` + - `FileCitation fileCitation` - - `Optional> allowedCallers` + - `String fileId` - The tool invocation context(s). + The ID of the specific File the citation is from. - - `DIRECT("direct")` + - `long startIndex` - - `PROGRAMMATIC("programmatic")` + - `String text` - - `Optional deferLoading` + The text in the message content that needs to be replaced. - Whether this function should be deferred and discovered via tool search. + - `JsonValue; type "file_citation"constant` - - `Optional description` + Always `file_citation`. - - `Optional outputSchema` + - `FILE_CITATION("file_citation")` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `class FilePathAnnotation:` - - `Optional parameters` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `Optional strict` + - `long endIndex` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `FilePath filePath` - - `class BetaCustomTool:` + - `String fileId` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The ID of the file that was generated. - - `JsonValue; type "namespace"constant` + - `long startIndex` - The type of the tool. Always `namespace`. + - `String text` - - `NAMESPACE("namespace")` + The text in the message content that needs to be replaced. - - `class BetaToolSearchTool:` + - `JsonValue; type "file_path"constant` - Hosted or BYOT tool search configuration for deferred tools. + Always `file_path`. - - `JsonValue; type "tool_search"constant` + - `FILE_PATH("file_path")` - The type of the tool. Always `tool_search`. +### Annotation Delta - - `TOOL_SEARCH("tool_search")` +- `class AnnotationDelta: A class that can be one of several variants.union` - - `Optional description` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Description shown to the model for a client-executed tool search tool. + - `class FileCitationDeltaAnnotation:` - - `Optional execution` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Whether tool search is executed by the server or by the client. + - `long index` - - `SERVER("server")` + The index of the annotation in the text content part. - - `CLIENT("client")` + - `JsonValue; type "file_citation"constant` - - `Optional parameters` + Always `file_citation`. - Parameter schema for a client-executed tool search tool. + - `FILE_CITATION("file_citation")` - - `class BetaWebSearchPreviewTool:` + - `Optional endIndex` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional fileCitation` - - `Type type` + - `Optional fileId` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The ID of the specific File the citation is from. - - `WEB_SEARCH_PREVIEW("web_search_preview")` + - `Optional quote` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The specific quote in the file. - - `Optional> searchContentTypes` + - `Optional startIndex` - - `TEXT("text")` + - `Optional text` - - `IMAGE("image")` + The text in the message content that needs to be replaced. - - `Optional searchContextSize` + - `class FilePathDeltaAnnotation:` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `LOW("low")` + - `long index` - - `MEDIUM("medium")` + The index of the annotation in the text content part. - - `HIGH("high")` + - `JsonValue; type "file_path"constant` - - `Optional userLocation` + Always `file_path`. - The user's location. + - `FILE_PATH("file_path")` - - `JsonValue; type "approximate"constant` + - `Optional endIndex` - The type of location approximation. Always `approximate`. + - `Optional filePath` - - `APPROXIMATE("approximate")` + - `Optional fileId` - - `Optional city` + The ID of the file that was generated. - Free text input for the city of the user, e.g. `San Francisco`. + - `Optional startIndex` - - `Optional country` + - `Optional text` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The text in the message content that needs to be replaced. - - `Optional region` +### File Citation Annotation - Free text input for the region of the user, e.g. `California`. +- `class FileCitationAnnotation:` - - `Optional timezone` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `long endIndex` - - `class BetaApplyPatchTool:` + - `FileCitation fileCitation` - Allows the assistant to create, delete, or update files using unified diffs. + - `String fileId` - - `JsonValue; type "apply_patch"constant` + The ID of the specific File the citation is from. - The type of the tool. Always `apply_patch`. + - `long startIndex` - - `APPLY_PATCH("apply_patch")` + - `String text` - - `Optional> allowedCallers` + The text in the message content that needs to be replaced. - The tool invocation context(s). + - `JsonValue; type "file_citation"constant` - - `DIRECT("direct")` + Always `file_citation`. - - `PROGRAMMATIC("programmatic")` + - `FILE_CITATION("file_citation")` - - `JsonValue; type "tool_search_output"constant` +### File Citation Delta Annotation - The item type. Always `tool_search_output`. +- `class FileCitationDeltaAnnotation:` - - `TOOL_SEARCH_OUTPUT("tool_search_output")` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `Optional id` + - `long index` - The unique ID of this tool search output. + The index of the annotation in the text content part. - - `Optional agent` + - `JsonValue; type "file_citation"constant` - The agent that produced this item. + Always `file_citation`. - - `String agentName` + - `FILE_CITATION("file_citation")` - The canonical name of the agent that produced this item. + - `Optional endIndex` - - `Optional callId` + - `Optional fileCitation` - The unique ID of the tool search call generated by the model. + - `Optional fileId` - - `Optional execution` + The ID of the specific File the citation is from. - Whether tool search was executed by the server or by the client. + - `Optional quote` - - `SERVER("server")` + The specific quote in the file. - - `CLIENT("client")` + - `Optional startIndex` - - `Optional status` + - `Optional text` - The status of the tool search output. + The text in the message content that needs to be replaced. - - `IN_PROGRESS("in_progress")` +### File Path Annotation - - `COMPLETED("completed")` +- `class FilePathAnnotation:` - - `INCOMPLETE("incomplete")` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `AdditionalTools` + - `long endIndex` - - `JsonValue; role "developer"constant` + - `FilePath filePath` - The role that provided the additional tools. Only `developer` is supported. + - `String fileId` - - `DEVELOPER("developer")` + The ID of the file that was generated. - - `List tools` + - `long startIndex` - A list of additional tools made available at this item. + - `String text` - - `class BetaFunctionTool:` + The text in the message content that needs to be replaced. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `JsonValue; type "file_path"constant` - - `class BetaFileSearchTool:` + Always `file_path`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `FILE_PATH("file_path")` - - `class BetaComputerTool:` +### File Path Delta Annotation - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `class FilePathDeltaAnnotation:` - - `class BetaComputerUsePreviewTool:` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `long index` - - `class BetaWebSearchTool:` + The index of the annotation in the text content part. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `JsonValue; type "file_path"constant` - - `Mcp` + Always `file_path`. - - `CodeInterpreter` + - `FILE_PATH("file_path")` - - `JsonValue;` + - `Optional endIndex` - - `ImageGeneration` + - `Optional filePath` - - `JsonValue;` + - `Optional fileId` - - `class BetaFunctionShellTool:` + The ID of the file that was generated. - A tool that allows the model to execute shell commands. + - `Optional startIndex` - - `class BetaCustomTool:` + - `Optional text` - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + The text in the message content that needs to be replaced. - - `class BetaNamespaceTool:` +### Image File - Groups function/custom tools under a shared namespace. +- `class ImageFile:` - - `class BetaToolSearchTool:` + - `String fileId` - Hosted or BYOT tool search configuration for deferred tools. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `class BetaWebSearchPreviewTool:` + - `Optional detail` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `class BetaApplyPatchTool:` + - `AUTO("auto")` - Allows the assistant to create, delete, or update files using unified diffs. + - `LOW("low")` - - `JsonValue; type "additional_tools"constant` + - `HIGH("high")` - The item type. Always `additional_tools`. +### Image File Content Block - - `ADDITIONAL_TOOLS("additional_tools")` +- `class ImageFileContentBlock:` - - `Optional id` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The unique ID of this additional tools item. + - `ImageFile imageFile` - - `Optional agent` + - `String fileId` - The agent that produced this item. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `String agentName` + - `Optional detail` - The canonical name of the agent that produced this item. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `class BetaResponseReasoningItem:` + - `AUTO("auto")` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `LOW("low")` - - `String id` + - `HIGH("high")` - The unique identifier of the reasoning content. + - `JsonValue; type "image_file"constant` - - `List summary` + Always `image_file`. - Reasoning summary content. + - `IMAGE_FILE("image_file")` - - `String text` +### Image File Delta - A summary of the reasoning output from the model so far. +- `class ImageFileDelta:` - - `JsonValue; type "summary_text"constant` + - `Optional detail` - The type of the object. Always `summary_text`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `SUMMARY_TEXT("summary_text")` + - `AUTO("auto")` - - `JsonValue; type "reasoning"constant` + - `LOW("low")` - The type of the object. Always `reasoning`. + - `HIGH("high")` - - `REASONING("reasoning")` + - `Optional fileId` - - `Optional agent` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The agent that produced this item. +### Image File Delta Block - - `String agentName` +- `class ImageFileDeltaBlock:` - The canonical name of the agent that produced this item. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `Optional> content` + - `long index` - Reasoning text content. + The index of the content part in the message. - - `String text` + - `JsonValue; type "image_file"constant` - The reasoning text from the model. + Always `image_file`. - - `JsonValue; type "reasoning_text"constant` + - `IMAGE_FILE("image_file")` - The type of the reasoning text. Always `reasoning_text`. + - `Optional imageFile` - - `REASONING_TEXT("reasoning_text")` + - `Optional detail` - - `Optional encryptedContent` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `AUTO("auto")` - - `Optional status` + - `LOW("low")` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `HIGH("high")` - - `IN_PROGRESS("in_progress")` + - `Optional fileId` - - `COMPLETED("completed")` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `INCOMPLETE("incomplete")` +### Image URL - - `class BetaResponseCompactionItemParam:` +- `class ImageUrl:` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `String url` - - `String encryptedContent` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The encrypted content of the compaction summary. + - `Optional detail` - - `JsonValue; type "compaction"constant` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The type of the item. Always `compaction`. + - `AUTO("auto")` - - `COMPACTION("compaction")` + - `LOW("low")` - - `Optional id` + - `HIGH("high")` - The ID of the compaction item. +### Image URL Content Block - - `Optional agent` +- `class ImageUrlContentBlock:` - The agent that produced this item. + References an image URL in the content of a message. - - `String agentName` + - `ImageUrl imageUrl` - The canonical name of the agent that produced this item. + - `String url` - - `ImageGenerationCall` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `String id` + - `Optional detail` - The unique ID of the image generation call. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `Optional result` + - `AUTO("auto")` - The generated image encoded in base64. + - `LOW("low")` - - `Status status` + - `HIGH("high")` - The status of the image generation call. + - `JsonValue; type "image_url"constant` - - `IN_PROGRESS("in_progress")` + The type of the content part. - - `COMPLETED("completed")` + - `IMAGE_URL("image_url")` - - `GENERATING("generating")` +### Image URL Delta - - `FAILED("failed")` +- `class ImageUrlDelta:` - - `JsonValue; type "image_generation_call"constant` + - `Optional detail` - The type of the image generation call. Always `image_generation_call`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `IMAGE_GENERATION_CALL("image_generation_call")` + - `AUTO("auto")` - - `Optional agent` + - `LOW("low")` - The agent that produced this item. + - `HIGH("high")` - - `String agentName` + - `Optional url` - The canonical name of the agent that produced this item. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `class BetaResponseCodeInterpreterToolCall:` +### Image URL Delta Block - A tool call to run code. +- `class ImageUrlDeltaBlock:` - - `String id` + References an image URL in the content of a message. - The unique ID of the code interpreter tool call. + - `long index` - - `Optional code` + The index of the content part in the message. - The code to run, or null if not available. + - `JsonValue; type "image_url"constant` - - `String containerId` + Always `image_url`. - The ID of the container used to run the code. + - `IMAGE_URL("image_url")` - - `Optional> outputs` + - `Optional imageUrl` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `Optional detail` - - `class Logs:` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The logs output from the code interpreter. + - `AUTO("auto")` - - `String logs` + - `LOW("low")` - The logs output from the code interpreter. + - `HIGH("high")` - - `JsonValue; type "logs"constant` + - `Optional url` - The type of the output. Always `logs`. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `LOGS("logs")` +### Message - - `class Image:` +- `class Message:` - The image output from the code interpreter. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `JsonValue; type "image"constant` + - `String id` - The type of the output. Always `image`. + The identifier, which can be referenced in API endpoints. - - `IMAGE("image")` + - `Optional assistantId` - - `String url` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - The URL of the image output from the code interpreter. + - `Optional> attachments` - - `Status status` + A list of files attached to the message, and the tools they were added to. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `Optional fileId` - - `IN_PROGRESS("in_progress")` + The ID of the file to attach to the message. - - `COMPLETED("completed")` + - `Optional> tools` - - `INCOMPLETE("incomplete")` + The tools to add this file to. - - `INTERPRETING("interpreting")` + - `class CodeInterpreterTool:` - - `FAILED("failed")` + - `JsonValue; type "code_interpreter"constant` - - `JsonValue; type "code_interpreter_call"constant` + The type of tool being defined: `code_interpreter` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `CODE_INTERPRETER("code_interpreter")` - - `CODE_INTERPRETER_CALL("code_interpreter_call")` + - `JsonValue;` - - `Optional agent` + - `JsonValue; type "file_search"constant` - The agent that produced this item. + The type of tool being defined: `file_search` - - `String agentName` + - `FILE_SEARCH("file_search")` - The canonical name of the agent that produced this item. + - `Optional completedAt` - - `LocalShellCall` + The Unix timestamp (in seconds) for when the message was completed. - - `String id` + - `List content` - The unique ID of the local shell call. + The content of the message in array of text and/or images. - - `Action action` + - `class ImageFileContentBlock:` - Execute a shell command on the server. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `List command` + - `ImageFile imageFile` - The command to run. + - `String fileId` - - `Env env` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Environment variables to set for the command. + - `Optional detail` - - `JsonValue; type "exec"constant` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The type of the local shell action. Always `exec`. + - `AUTO("auto")` - - `EXEC("exec")` + - `LOW("low")` - - `Optional timeoutMs` + - `HIGH("high")` - Optional timeout in milliseconds for the command. + - `JsonValue; type "image_file"constant` - - `Optional user` + Always `image_file`. - Optional user to run the command as. + - `IMAGE_FILE("image_file")` - - `Optional workingDirectory` + - `class ImageUrlContentBlock:` - Optional working directory to run the command in. + References an image URL in the content of a message. - - `String callId` + - `ImageUrl imageUrl` - The unique ID of the local shell tool call generated by the model. + - `String url` - - `Status status` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The status of the local shell call. + - `Optional detail` - - `IN_PROGRESS("in_progress")` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `COMPLETED("completed")` + - `AUTO("auto")` - - `INCOMPLETE("incomplete")` + - `LOW("low")` - - `JsonValue; type "local_shell_call"constant` + - `HIGH("high")` - The type of the local shell call. Always `local_shell_call`. + - `JsonValue; type "image_url"constant` - - `LOCAL_SHELL_CALL("local_shell_call")` + The type of the content part. - - `Optional agent` + - `IMAGE_URL("image_url")` - The agent that produced this item. + - `class TextContentBlock:` - - `String agentName` + The text content that is part of a message. - The canonical name of the agent that produced this item. + - `Text text` - - `LocalShellCallOutput` + - `List annotations` - - `String id` + - `class FileCitationAnnotation:` - The unique ID of the local shell tool call generated by the model. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `String output` + - `long endIndex` - A JSON string of the output of the local shell tool call. + - `FileCitation fileCitation` - - `JsonValue; type "local_shell_call_output"constant` + - `String fileId` - The type of the local shell tool call output. Always `local_shell_call_output`. + The ID of the specific File the citation is from. - - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` + - `long startIndex` - - `Optional agent` + - `String text` - The agent that produced this item. + The text in the message content that needs to be replaced. - - `String agentName` + - `JsonValue; type "file_citation"constant` - The canonical name of the agent that produced this item. + Always `file_citation`. - - `Optional status` + - `FILE_CITATION("file_citation")` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `class FilePathAnnotation:` - - `IN_PROGRESS("in_progress")` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `COMPLETED("completed")` + - `long endIndex` - - `INCOMPLETE("incomplete")` + - `FilePath filePath` - - `ShellCall` + - `String fileId` - - `Action action` + The ID of the file that was generated. - The shell commands and limits that describe how to run the tool call. + - `long startIndex` - - `List commands` + - `String text` - Ordered shell commands for the execution environment to run. + The text in the message content that needs to be replaced. - - `Optional maxOutputLength` + - `JsonValue; type "file_path"constant` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Always `file_path`. - - `Optional timeoutMs` + - `FILE_PATH("file_path")` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `String value` - - `String callId` + The data that makes up the text. - The unique ID of the shell tool call generated by the model. + - `JsonValue; type "text"constant` - - `JsonValue; type "shell_call"constant` + Always `text`. - The type of the item. Always `shell_call`. + - `TEXT("text")` - - `SHELL_CALL("shell_call")` + - `class RefusalContentBlock:` - - `Optional id` + The refusal content generated by the assistant. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `String refusal` - - `Optional agent` + - `JsonValue; type "refusal"constant` - The agent that produced this item. + Always `refusal`. - - `String agentName` + - `REFUSAL("refusal")` - The canonical name of the agent that produced this item. + - `long createdAt` - - `Optional caller` + The Unix timestamp (in seconds) for when the message was created. - The execution context that produced this tool call. + - `Optional incompleteAt` - - `JsonValue;` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `JsonValue; type "direct"constant` + - `Optional incompleteDetails` - The caller type. Always `direct`. + On an incomplete message, details about why the message is incomplete. - - `DIRECT("direct")` + - `Reason reason` - - `class Program:` + The reason the message is incomplete. - - `String callerId` + - `CONTENT_FILTER("content_filter")` - The call ID of the program item that produced this tool call. + - `MAX_TOKENS("max_tokens")` - - `JsonValue; type "program"constant` + - `RUN_CANCELLED("run_cancelled")` - The caller type. Always `program`. + - `RUN_EXPIRED("run_expired")` - - `PROGRAM("program")` + - `RUN_FAILED("run_failed")` - - `Optional environment` + - `Optional metadata` - The environment to execute the shell commands in. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `class BetaLocalEnvironment:` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `class BetaContainerReference:` + - `JsonValue; object_ "thread.message"constant` - - `Optional status` + The object type, which is always `thread.message`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `THREAD_MESSAGE("thread.message")` - - `IN_PROGRESS("in_progress")` + - `Role role` - - `COMPLETED("completed")` + The entity that produced the message. One of `user` or `assistant`. - - `INCOMPLETE("incomplete")` + - `USER("user")` - - `ShellCallOutput` + - `ASSISTANT("assistant")` - - `String callId` + - `Optional runId` - The unique ID of the shell tool call generated by the model. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `List output` + - `Status status` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `Outcome outcome` + - `IN_PROGRESS("in_progress")` - The exit or timeout outcome associated with this shell call. + - `INCOMPLETE("incomplete")` - - `JsonValue;` + - `COMPLETED("completed")` - - `JsonValue; type "timeout"constant` + - `String threadId` - The outcome type. Always `timeout`. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `TIMEOUT("timeout")` +### Message Content - - `class Exit:` +- `class MessageContent: A class that can be one of several variants.union` - Indicates that the shell commands finished and returned an exit code. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `long exitCode` + - `class ImageFileContentBlock:` - The exit code returned by the shell process. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `JsonValue; type "exit"constant` + - `ImageFile imageFile` - The outcome type. Always `exit`. + - `String fileId` - - `EXIT("exit")` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `String stderr` + - `Optional detail` - Captured stderr output for the shell call. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `String stdout` + - `AUTO("auto")` - Captured stdout output for the shell call. + - `LOW("low")` - - `JsonValue; type "shell_call_output"constant` + - `HIGH("high")` - The type of the item. Always `shell_call_output`. + - `JsonValue; type "image_file"constant` - - `SHELL_CALL_OUTPUT("shell_call_output")` + Always `image_file`. - - `Optional id` + - `IMAGE_FILE("image_file")` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `class ImageUrlContentBlock:` - - `Optional agent` + References an image URL in the content of a message. - The agent that produced this item. + - `ImageUrl imageUrl` - - `String agentName` + - `String url` - The canonical name of the agent that produced this item. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `Optional caller` + - `Optional detail` - The execution context that produced this tool call. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `JsonValue;` + - `AUTO("auto")` - - `JsonValue; type "direct"constant` + - `LOW("low")` - The caller type. Always `direct`. + - `HIGH("high")` - - `DIRECT("direct")` + - `JsonValue; type "image_url"constant` - - `class Program:` + The type of the content part. - - `String callerId` + - `IMAGE_URL("image_url")` - The call ID of the program item that produced this tool call. + - `class TextContentBlock:` - - `JsonValue; type "program"constant` + The text content that is part of a message. - The caller type. Always `program`. + - `Text text` - - `PROGRAM("program")` + - `List annotations` - - `Optional maxOutputLength` + - `class FileCitationAnnotation:` - The maximum number of UTF-8 characters captured for this shell call's combined output. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `Optional status` + - `long endIndex` - The status of the shell call output. + - `FileCitation fileCitation` - - `IN_PROGRESS("in_progress")` + - `String fileId` - - `COMPLETED("completed")` + The ID of the specific File the citation is from. - - `INCOMPLETE("incomplete")` + - `long startIndex` - - `ApplyPatchCall` + - `String text` - - `String callId` + The text in the message content that needs to be replaced. - The unique ID of the apply patch tool call generated by the model. + - `JsonValue; type "file_citation"constant` - - `Operation operation` + Always `file_citation`. - The specific create, delete, or update instruction for the apply_patch tool call. + - `FILE_CITATION("file_citation")` - - `class CreateFile:` + - `class FilePathAnnotation:` - Instruction for creating a new file via the apply_patch tool. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `String diff` + - `long endIndex` - Unified diff content to apply when creating the file. + - `FilePath filePath` - - `String path` + - `String fileId` - Path of the file to create relative to the workspace root. + The ID of the file that was generated. - - `JsonValue; type "create_file"constant` + - `long startIndex` - The operation type. Always `create_file`. + - `String text` - - `CREATE_FILE("create_file")` + The text in the message content that needs to be replaced. - - `class DeleteFile:` + - `JsonValue; type "file_path"constant` - Instruction for deleting an existing file via the apply_patch tool. + Always `file_path`. - - `String path` + - `FILE_PATH("file_path")` - Path of the file to delete relative to the workspace root. + - `String value` - - `JsonValue; type "delete_file"constant` + The data that makes up the text. - The operation type. Always `delete_file`. + - `JsonValue; type "text"constant` - - `DELETE_FILE("delete_file")` + Always `text`. - - `class UpdateFile:` + - `TEXT("text")` - Instruction for updating an existing file via the apply_patch tool. + - `class RefusalContentBlock:` - - `String diff` + The refusal content generated by the assistant. - Unified diff content to apply to the existing file. + - `String refusal` - - `String path` + - `JsonValue; type "refusal"constant` - Path of the file to update relative to the workspace root. + Always `refusal`. - - `JsonValue; type "update_file"constant` + - `REFUSAL("refusal")` - The operation type. Always `update_file`. +### Message Content Delta - - `UPDATE_FILE("update_file")` +- `class MessageContentDelta: A class that can be one of several variants.union` - - `Status status` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `class ImageFileDeltaBlock:` - - `IN_PROGRESS("in_progress")` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `COMPLETED("completed")` + - `long index` - - `JsonValue; type "apply_patch_call"constant` + The index of the content part in the message. - The type of the item. Always `apply_patch_call`. + - `JsonValue; type "image_file"constant` - - `APPLY_PATCH_CALL("apply_patch_call")` + Always `image_file`. - - `Optional id` + - `IMAGE_FILE("image_file")` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `Optional imageFile` - - `Optional agent` + - `Optional detail` - The agent that produced this item. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `String agentName` + - `AUTO("auto")` - The canonical name of the agent that produced this item. + - `LOW("low")` - - `Optional caller` + - `HIGH("high")` - The execution context that produced this tool call. + - `Optional fileId` - - `JsonValue;` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `JsonValue; type "direct"constant` + - `class TextDeltaBlock:` - The caller type. Always `direct`. + The text content that is part of a message. - - `DIRECT("direct")` + - `long index` - - `class Program:` + The index of the content part in the message. - - `String callerId` + - `JsonValue; type "text"constant` - The call ID of the program item that produced this tool call. + Always `text`. - - `JsonValue; type "program"constant` + - `TEXT("text")` - The caller type. Always `program`. + - `Optional text` - - `PROGRAM("program")` + - `Optional> annotations` - - `ApplyPatchCallOutput` + - `class FileCitationDeltaAnnotation:` - - `String callId` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The unique ID of the apply patch tool call generated by the model. + - `long index` - - `Status status` + The index of the annotation in the text content part. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `JsonValue; type "file_citation"constant` - - `COMPLETED("completed")` + Always `file_citation`. - - `FAILED("failed")` + - `FILE_CITATION("file_citation")` - - `JsonValue; type "apply_patch_call_output"constant` + - `Optional endIndex` - The type of the item. Always `apply_patch_call_output`. + - `Optional fileCitation` - - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` + - `Optional fileId` - - `Optional id` + The ID of the specific File the citation is from. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `Optional quote` - - `Optional agent` + The specific quote in the file. - The agent that produced this item. + - `Optional startIndex` - - `String agentName` + - `Optional text` - The canonical name of the agent that produced this item. + The text in the message content that needs to be replaced. - - `Optional caller` + - `class FilePathDeltaAnnotation:` - The execution context that produced this tool call. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `JsonValue;` + - `long index` - - `JsonValue; type "direct"constant` + The index of the annotation in the text content part. - The caller type. Always `direct`. + - `JsonValue; type "file_path"constant` - - `DIRECT("direct")` + Always `file_path`. - - `class Program:` + - `FILE_PATH("file_path")` - - `String callerId` + - `Optional endIndex` - The call ID of the program item that produced this tool call. + - `Optional filePath` - - `JsonValue; type "program"constant` + - `Optional fileId` - The caller type. Always `program`. + The ID of the file that was generated. - - `PROGRAM("program")` + - `Optional startIndex` - - `Optional output` + - `Optional text` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The text in the message content that needs to be replaced. - - `McpListTools` + - `Optional value` - - `String id` + The data that makes up the text. - The unique ID of the list. + - `class RefusalDeltaBlock:` - - `String serverLabel` + The refusal content that is part of a message. - The label of the MCP server. + - `long index` - - `List tools` + The index of the refusal part in the message. - The tools available on the server. + - `JsonValue; type "refusal"constant` - - `JsonValue inputSchema` + Always `refusal`. - The JSON schema describing the tool's input. + - `REFUSAL("refusal")` - - `String name` + - `Optional refusal` - The name of the tool. + - `class ImageUrlDeltaBlock:` - - `Optional annotations` + References an image URL in the content of a message. - Additional annotations about the tool. + - `long index` - - `Optional description` + The index of the content part in the message. - The description of the tool. + - `JsonValue; type "image_url"constant` - - `JsonValue; type "mcp_list_tools"constant` + Always `image_url`. - The type of the item. Always `mcp_list_tools`. + - `IMAGE_URL("image_url")` - - `MCP_LIST_TOOLS("mcp_list_tools")` + - `Optional imageUrl` - - `Optional agent` + - `Optional detail` - The agent that produced this item. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `String agentName` + - `AUTO("auto")` - The canonical name of the agent that produced this item. + - `LOW("low")` - - `Optional error` + - `HIGH("high")` - Error message if the server could not list tools. + - `Optional url` - - `McpApprovalRequest` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `String id` +### Message Content Part Param - The unique ID of the approval request. +- `class MessageContentPartParam: A class that can be one of several variants.union` - - `String arguments` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - A JSON string of arguments for the tool. + - `class ImageFileContentBlock:` - - `String name` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The name of the tool to run. + - `ImageFile imageFile` - - `String serverLabel` + - `String fileId` - The label of the MCP server making the request. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `JsonValue; type "mcp_approval_request"constant` + - `Optional detail` - The type of the item. Always `mcp_approval_request`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `MCP_APPROVAL_REQUEST("mcp_approval_request")` + - `AUTO("auto")` - - `Optional agent` + - `LOW("low")` - The agent that produced this item. + - `HIGH("high")` - - `String agentName` + - `JsonValue; type "image_file"constant` - The canonical name of the agent that produced this item. + Always `image_file`. - - `McpApprovalResponse` + - `IMAGE_FILE("image_file")` - - `String approvalRequestId` + - `class ImageUrlContentBlock:` - The ID of the approval request being answered. + References an image URL in the content of a message. - - `boolean approve` + - `ImageUrl imageUrl` - Whether the request was approved. + - `String url` - - `JsonValue; type "mcp_approval_response"constant` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the item. Always `mcp_approval_response`. + - `Optional detail` - - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `Optional id` + - `AUTO("auto")` - The unique ID of the approval response + - `LOW("low")` - - `Optional agent` + - `HIGH("high")` - The agent that produced this item. + - `JsonValue; type "image_url"constant` - - `String agentName` + The type of the content part. - The canonical name of the agent that produced this item. + - `IMAGE_URL("image_url")` - - `Optional reason` + - `class TextContentBlockParam:` - Optional reason for the decision. + The text content that is part of a message. - - `McpCall` + - `String text` - - `String id` + Text content to be sent to the model - The unique ID of the tool call. + - `JsonValue; type "text"constant` - - `String arguments` + Always `text`. - A JSON string of the arguments passed to the tool. + - `TEXT("text")` - - `String name` +### Message Deleted - The name of the tool that was run. +- `class MessageDeleted:` - - `String serverLabel` + - `String id` - The label of the MCP server running the tool. + - `boolean deleted` - - `JsonValue; type "mcp_call"constant` + - `JsonValue; object_ "thread.message.deleted"constant` - The type of the item. Always `mcp_call`. + - `THREAD_MESSAGE_DELETED("thread.message.deleted")` - - `MCP_CALL("mcp_call")` +### Message Delta - - `Optional agent` +- `class MessageDelta:` - The agent that produced this item. + The delta containing the fields that have changed on the Message. - - `String agentName` + - `Optional> content` - The canonical name of the agent that produced this item. + The content of the message in array of text and/or images. - - `Optional approvalRequestId` + - `class ImageFileDeltaBlock:` - 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. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `Optional error` + - `long index` - The error from the tool call, if any. + The index of the content part in the message. - - `Optional output` + - `JsonValue; type "image_file"constant` - The output from the tool call. + Always `image_file`. - - `Optional status` + - `IMAGE_FILE("image_file")` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `Optional imageFile` - - `IN_PROGRESS("in_progress")` + - `Optional detail` - - `COMPLETED("completed")` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `INCOMPLETE("incomplete")` + - `AUTO("auto")` - - `CALLING("calling")` + - `LOW("low")` - - `FAILED("failed")` + - `HIGH("high")` - - `class BetaResponseCustomToolCallOutput:` + - `Optional fileId` - The output of a custom tool call from your code, being sent back to the model. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `String callId` + - `class TextDeltaBlock:` - The call ID, used to map this custom tool call output to a custom tool call. + The text content that is part of a message. - - `Output output` + - `long index` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The index of the content part in the message. - - `String` + - `JsonValue; type "text"constant` - - `List` + Always `text`. - - `class BetaResponseInputText:` + - `TEXT("text")` - A text input to the model. + - `Optional text` - - `class BetaResponseInputImage:` + - `Optional> annotations` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `class FileCitationDeltaAnnotation:` - - `class BetaResponseInputFile:` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - A file input to the model. + - `long index` - - `JsonValue; type "custom_tool_call_output"constant` + The index of the annotation in the text content part. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `JsonValue; type "file_citation"constant` - - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` + Always `file_citation`. - - `Optional id` + - `FILE_CITATION("file_citation")` - The unique ID of the custom tool call output in the OpenAI platform. + - `Optional endIndex` - - `Optional agent` + - `Optional fileCitation` - The agent that produced this item. + - `Optional fileId` - - `String agentName` + The ID of the specific File the citation is from. - The canonical name of the agent that produced this item. + - `Optional quote` - - `Optional caller` + The specific quote in the file. - The execution context that produced this tool call. + - `Optional startIndex` - - `JsonValue;` + - `Optional text` - - `JsonValue; type "direct"constant` + The text in the message content that needs to be replaced. - The caller type. Always `direct`. + - `class FilePathDeltaAnnotation:` - - `DIRECT("direct")` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `class Program:` + - `long index` - - `String callerId` + The index of the annotation in the text content part. - The call ID of the program item that produced this tool call. + - `JsonValue; type "file_path"constant` - - `JsonValue; type "program"constant` + Always `file_path`. - The caller type. Always `program`. + - `FILE_PATH("file_path")` - - `PROGRAM("program")` + - `Optional endIndex` - - `class BetaResponseCustomToolCall:` + - `Optional filePath` - A call to a custom tool created by the model. + - `Optional fileId` - - `String callId` + The ID of the file that was generated. - An identifier used to map this custom tool call to a tool call output. + - `Optional startIndex` - - `String input` + - `Optional text` - The input for the custom tool call generated by the model. + The text in the message content that needs to be replaced. - - `String name` + - `Optional value` - The name of the custom tool being called. + The data that makes up the text. - - `JsonValue; type "custom_tool_call"constant` + - `class RefusalDeltaBlock:` - The type of the custom tool call. Always `custom_tool_call`. + The refusal content that is part of a message. - - `CUSTOM_TOOL_CALL("custom_tool_call")` + - `long index` - - `Optional id` + The index of the refusal part in the message. - The unique ID of the custom tool call in the OpenAI platform. + - `JsonValue; type "refusal"constant` - - `Optional agent` + Always `refusal`. - The agent that produced this item. + - `REFUSAL("refusal")` - - `String agentName` + - `Optional refusal` - The canonical name of the agent that produced this item. + - `class ImageUrlDeltaBlock:` - - `Optional caller` + References an image URL in the content of a message. - The execution context that produced this tool call. + - `long index` - - `JsonValue;` + The index of the content part in the message. - - `JsonValue; type "direct"constant` + - `JsonValue; type "image_url"constant` - - `DIRECT("direct")` + Always `image_url`. - - `class Program:` + - `IMAGE_URL("image_url")` - - `String callerId` + - `Optional imageUrl` - The call ID of the program item that produced this tool call. + - `Optional detail` - - `JsonValue; type "program"constant` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `PROGRAM("program")` + - `AUTO("auto")` - - `Optional namespace` + - `LOW("low")` - The namespace of the custom tool being called. + - `HIGH("high")` - - `CompactionTrigger` + - `Optional url` - - `JsonValue; type "compaction_trigger"constant` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the item. Always `compaction_trigger`. + - `Optional role` - - `COMPACTION_TRIGGER("compaction_trigger")` + The entity that produced the message. One of `user` or `assistant`. - - `Optional agent` + - `USER("user")` - The agent that produced this item. + - `ASSISTANT("assistant")` - - `String agentName` +### Message Delta Event - The canonical name of the agent that produced this item. +- `class MessageDeltaEvent:` - - `ItemReference` + Represents a message delta i.e. any changed fields on a message during streaming. - `String id` - The ID of the item to reference. + The identifier of the message, which can be referenced in API endpoints. - - `Optional agent` + - `MessageDelta delta` - The agent that produced this item. + The delta containing the fields that have changed on the Message. - - `String agentName` + - `Optional> content` - The canonical name of the agent that produced this item. + The content of the message in array of text and/or images. - - `Optional type` + - `class ImageFileDeltaBlock:` - The type of item to reference. Always `item_reference`. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `ITEM_REFERENCE("item_reference")` + - `long index` - - `Program` + The index of the content part in the message. - - `String id` + - `JsonValue; type "image_file"constant` - The unique ID of this program item. + Always `image_file`. - - `String callId` + - `IMAGE_FILE("image_file")` - The stable call ID of the program item. + - `Optional imageFile` - - `String code` + - `Optional detail` - The JavaScript source executed by programmatic tool calling. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `String fingerprint` + - `AUTO("auto")` - Opaque program replay fingerprint that must be round-tripped. + - `LOW("low")` - - `JsonValue; type "program"constant` + - `HIGH("high")` - The item type. Always `program`. + - `Optional fileId` - - `PROGRAM("program")` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `Optional agent` + - `class TextDeltaBlock:` - The agent that produced this item. + The text content that is part of a message. - - `String agentName` + - `long index` - The canonical name of the agent that produced this item. + The index of the content part in the message. - - `ProgramOutput` + - `JsonValue; type "text"constant` - - `String id` + Always `text`. - The unique ID of this program output item. + - `TEXT("text")` - - `String callId` + - `Optional text` - The call ID of the program item. + - `Optional> annotations` - - `String result` + - `class FileCitationDeltaAnnotation:` - The result produced by the program item. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `Status status` + - `long index` - The terminal status of the program output. + The index of the annotation in the text content part. - - `COMPLETED("completed")` + - `JsonValue; type "file_citation"constant` - - `INCOMPLETE("incomplete")` + Always `file_citation`. - - `JsonValue; type "program_output"constant` + - `FILE_CITATION("file_citation")` - The item type. Always `program_output`. + - `Optional endIndex` - - `PROGRAM_OUTPUT("program_output")` + - `Optional fileCitation` - - `Optional agent` + - `Optional fileId` - The agent that produced this item. + The ID of the specific File the citation is from. - - `String agentName` + - `Optional quote` - The canonical name of the agent that produced this item. + The specific quote in the file. - - `Optional instructions` + - `Optional startIndex` - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - `Optional text` - - `Optional model` + The text in the message content that needs to be replaced. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. + - `class FilePathDeltaAnnotation:` - - `Optional parallelToolCalls` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Whether to allow the model to run tool calls in parallel. + - `long index` - - `Optional personality` + The index of the annotation in the text content part. - A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + - `JsonValue; type "file_path"constant` - - `FRIENDLY("friendly")` + Always `file_path`. - - `PRAGMATIC("pragmatic")` + - `FILE_PATH("file_path")` - - `Optional previousResponseId` + - `Optional endIndex` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `Optional filePath` - - `Optional reasoning` + - `Optional fileId` - **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The ID of the file that was generated. - - `Optional context` + - `Optional startIndex` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `Optional text` - - `AUTO("auto")` + The text in the message content that needs to be replaced. - - `CURRENT_TURN("current_turn")` + - `Optional value` - - `ALL_TURNS("all_turns")` + The data that makes up the text. - - `Optional effort` + - `class RefusalDeltaBlock:` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The refusal content that is part of a message. - - `NONE("none")` + - `long index` - - `MINIMAL("minimal")` + The index of the refusal part in the message. - - `LOW("low")` + - `JsonValue; type "refusal"constant` - - `MEDIUM("medium")` + Always `refusal`. - - `HIGH("high")` + - `REFUSAL("refusal")` - - `XHIGH("xhigh")` + - `Optional refusal` - - `MAX("max")` + - `class ImageUrlDeltaBlock:` - - `Optional generateSummary` + References an image URL in the content of a message. - **Deprecated:** use `summary` instead. + - `long index` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The index of the content part in the message. - - `AUTO("auto")` + - `JsonValue; type "image_url"constant` - - `CONCISE("concise")` + Always `image_url`. - - `DETAILED("detailed")` + - `IMAGE_URL("image_url")` - - `Optional mode` + - `Optional imageUrl` - Controls the reasoning execution mode for the request. + - `Optional detail` - When returned on a response, this is the effective execution mode. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `STANDARD("standard")` + - `AUTO("auto")` - - `PRO("pro")` + - `LOW("low")` - - `Optional summary` + - `HIGH("high")` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `Optional url` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `AUTO("auto")` + - `Optional role` - - `CONCISE("concise")` + The entity that produced the message. One of `user` or `assistant`. - - `DETAILED("detailed")` + - `USER("user")` - - `Optional text` + - `ASSISTANT("assistant")` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `JsonValue; object_ "thread.message.delta"constant` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The object type, which is always `thread.message.delta`. - - `Optional format` + - `THREAD_MESSAGE_DELTA("thread.message.delta")` - An object specifying the format that the model must output. +### Refusal Content Block - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). +- `class RefusalContentBlock:` - The default format is `{ "type": "text" }` with no additional options. + The refusal content generated by the assistant. - **Not recommended for gpt-4o and newer models:** + - `String refusal` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `JsonValue; type "refusal"constant` - - `JsonValue;` + Always `refusal`. - - `JsonValue; type "text"constant` + - `REFUSAL("refusal")` - The type of response format being defined. Always `text`. +### Refusal Delta Block - - `TEXT("text")` +- `class RefusalDeltaBlock:` - - `class BetaResponseFormatTextJsonSchemaConfig:` + The refusal content that is part of a message. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `long index` - - `String name` + The index of the refusal part in the message. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `JsonValue; type "refusal"constant` - - `Schema schema` + Always `refusal`. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `REFUSAL("refusal")` - - `JsonValue; type "json_schema"constant` + - `Optional refusal` - The type of response format being defined. Always `json_schema`. +### Text - - `JSON_SCHEMA("json_schema")` +- `class Text:` - - `Optional description` + - `List annotations` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `class FileCitationAnnotation:` - - `Optional strict` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `long endIndex` - - `JsonValue;` + - `FileCitation fileCitation` - - `JsonValue; type "json_object"constant` + - `String fileId` - The type of response format being defined. Always `json_object`. + The ID of the specific File the citation is from. - - `JSON_OBJECT("json_object")` + - `long startIndex` - - `Optional verbosity` + - `String text` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The text in the message content that needs to be replaced. - - `LOW("low")` + - `JsonValue; type "file_citation"constant` - - `MEDIUM("medium")` + Always `file_citation`. - - `HIGH("high")` + - `FILE_CITATION("file_citation")` - - `Optional toolChoice` + - `class FilePathAnnotation:` - Controls which tool the model should use, if any. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `enum BetaToolChoiceOptions:` + - `long endIndex` - Controls which (if any) tool is called by the model. + - `FilePath filePath` - `none` means the model will not call any tool and instead generates a message. + - `String fileId` - `auto` means the model can pick between generating a message or calling one or - more tools. + The ID of the file that was generated. - `required` means the model must call one or more tools. + - `long startIndex` - - `NONE("none")` + - `String text` - - `AUTO("auto")` + The text in the message content that needs to be replaced. - - `REQUIRED("required")` + - `JsonValue; type "file_path"constant` - - `class BetaToolChoiceAllowed:` + Always `file_path`. - Constrains the tools available to the model to a pre-defined set. + - `FILE_PATH("file_path")` - - `Mode mode` + - `String value` - Constrains the tools available to the model to a pre-defined set. + The data that makes up the text. - `auto` allows the model to pick from among the allowed tools and generate a - message. +### Text Content Block - `required` requires the model to call one or more of the allowed tools. +- `class TextContentBlock:` - - `AUTO("auto")` + The text content that is part of a message. - - `REQUIRED("required")` + - `Text text` - - `List tools` + - `List annotations` - A list of tool definitions that the model should be allowed to call. + - `class FileCitationAnnotation:` - For the Responses API, the list of tool definitions might look like: + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `long endIndex` - - `JsonValue; type "allowed_tools"constant` + - `FileCitation fileCitation` - Allowed tool configuration type. Always `allowed_tools`. + - `String fileId` - - `ALLOWED_TOOLS("allowed_tools")` + The ID of the specific File the citation is from. - - `class BetaToolChoiceTypes:` + - `long startIndex` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `String text` - - `Type type` + The text in the message content that needs to be replaced. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `JsonValue; type "file_citation"constant` - Allowed values are: + Always `file_citation`. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `FILE_CITATION("file_citation")` - - `FILE_SEARCH("file_search")` + - `class FilePathAnnotation:` - - `WEB_SEARCH_PREVIEW("web_search_preview")` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `COMPUTER("computer")` + - `long endIndex` - - `COMPUTER_USE_PREVIEW("computer_use_preview")` + - `FilePath filePath` - - `COMPUTER_USE("computer_use")` + - `String fileId` - - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` + The ID of the file that was generated. - - `IMAGE_GENERATION("image_generation")` + - `long startIndex` - - `CODE_INTERPRETER("code_interpreter")` + - `String text` - - `class BetaToolChoiceFunction:` + The text in the message content that needs to be replaced. - Use this option to force the model to call a specific function. + - `JsonValue; type "file_path"constant` - - `String name` + Always `file_path`. - The name of the function to call. + - `FILE_PATH("file_path")` - - `JsonValue; type "function"constant` + - `String value` - For function calling, the type is always `function`. + The data that makes up the text. - - `FUNCTION("function")` + - `JsonValue; type "text"constant` - - `class BetaToolChoiceMcp:` + Always `text`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `TEXT("text")` - - `String serverLabel` +### Text Content Block Param - The label of the MCP server to use. +- `class TextContentBlockParam:` - - `JsonValue; type "mcp"constant` + The text content that is part of a message. - For MCP tools, the type is always `mcp`. + - `String text` - - `MCP("mcp")` + Text content to be sent to the model - - `Optional name` + - `JsonValue; type "text"constant` - The name of the tool to call on the server. + Always `text`. - - `class BetaToolChoiceCustom:` + - `TEXT("text")` - Use this option to force the model to call a specific custom tool. +### Text Delta - - `String name` +- `class TextDelta:` - The name of the custom tool to call. + - `Optional> annotations` - - `JsonValue; type "custom"constant` + - `class FileCitationDeltaAnnotation:` - For custom tool calling, the type is always `custom`. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `CUSTOM("custom")` + - `long index` - - `JsonValue;` + The index of the annotation in the text content part. - - `JsonValue; type "programmatic_tool_calling"constant` + - `JsonValue; type "file_citation"constant` - The tool to call. Always `programmatic_tool_calling`. + Always `file_citation`. - - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` + - `FILE_CITATION("file_citation")` - - `class BetaToolChoiceApplyPatch:` + - `Optional endIndex` - Forces the model to call the apply_patch tool when executing a tool call. + - `Optional fileCitation` - - `JsonValue; type "apply_patch"constant` + - `Optional fileId` - The tool to call. Always `apply_patch`. + The ID of the specific File the citation is from. - - `APPLY_PATCH("apply_patch")` + - `Optional quote` - - `class BetaToolChoiceShell:` + The specific quote in the file. - Forces the model to call the shell tool when a tool call is required. + - `Optional startIndex` - - `JsonValue; type "shell"constant` + - `Optional text` - The tool to call. Always `shell`. + The text in the message content that needs to be replaced. - - `SHELL("shell")` + - `class FilePathDeltaAnnotation:` - - `Optional> tools` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. + - `long index` - - `class BetaFunctionTool:` + The index of the annotation in the text content part. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `JsonValue; type "file_path"constant` - - `class BetaFileSearchTool:` + Always `file_path`. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `FILE_PATH("file_path")` - - `class BetaComputerTool:` + - `Optional endIndex` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Optional filePath` - - `class BetaComputerUsePreviewTool:` + - `Optional fileId` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the file that was generated. - - `class BetaWebSearchTool:` + - `Optional startIndex` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `Optional text` - - `Mcp` + The text in the message content that needs to be replaced. - - `CodeInterpreter` + - `Optional value` - - `JsonValue;` + The data that makes up the text. - - `ImageGeneration` +### Text Delta Block - - `JsonValue;` +- `class TextDeltaBlock:` - - `class BetaFunctionShellTool:` + The text content that is part of a message. - A tool that allows the model to execute shell commands. + - `long index` - - `class BetaCustomTool:` + The index of the content part in the message. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `JsonValue; type "text"constant` - - `class BetaNamespaceTool:` + Always `text`. - Groups function/custom tools under a shared namespace. + - `TEXT("text")` - - `class BetaToolSearchTool:` + - `Optional text` - Hosted or BYOT tool search configuration for deferred tools. + - `Optional> annotations` - - `class BetaWebSearchPreviewTool:` + - `class FileCitationDeltaAnnotation:` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `class BetaApplyPatchTool:` + - `long index` - Allows the assistant to create, delete, or update files using unified diffs. + The index of the annotation in the text content part. - - `Optional truncation` + - `JsonValue; type "file_citation"constant` - The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error. + Always `file_citation`. - - `AUTO("auto")` + - `FILE_CITATION("file_citation")` - - `DISABLED("disabled")` + - `Optional endIndex` -### Returns + - `Optional fileCitation` -- `class InputTokenCountResponse:` + - `Optional fileId` - - `long inputTokens` + The ID of the specific File the citation is from. - - `JsonValue; object_ "response.input_tokens"constant` + - `Optional quote` - - `RESPONSE_INPUT_TOKENS("response.input_tokens")` + The specific quote in the file. -### Example + - `Optional startIndex` -```java -package com.openai.example; + - `Optional text` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.beta.responses.inputtokens.InputTokenCountParams; -import com.openai.models.beta.responses.inputtokens.InputTokenCountResponse; + The text in the message content that needs to be replaced. -public final class Main { - private Main() {} + - `class FilePathDeltaAnnotation:` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - InputTokenCountResponse response = client.beta().responses().inputTokens().count(); - } -} -``` + - `long index` -#### Response + The index of the annotation in the text content part. -```json -{ - "input_tokens": 123, - "object": "response.input_tokens" -} -``` + - `JsonValue; type "file_path"constant` -### Example + Always `file_path`. -```java -package com.openai.example; + - `FILE_PATH("file_path")` -import com.openai.client.OpenAIClient; -import com.openai.client.okhttp.OpenAIOkHttpClient; -import com.openai.models.responses.inputtokens.InputTokenCountParams; -import com.openai.models.responses.inputtokens.InputTokenCountResponse; + - `Optional endIndex` -public final class Main { - private Main() {} + - `Optional filePath` - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + - `Optional fileId` - InputTokenCountParams params = InputTokenCountParams.builder() - .model("gpt-5") - .input("Tell me a joke.") - .build(); + The ID of the file that was generated. - InputTokenCountResponse response = client.responses().inputTokens().count(params); - } -} -``` + - `Optional startIndex` -#### Response + - `Optional text` -```json -{ - "object": "response.input_tokens", - "input_tokens": 11 -} -``` + The text in the message content that needs to be replaced. + + - `Optional value` + + The data that makes up the text.