diff --git a/en/cli/resources/beta/subresources/responses/index.md b/en/cli/resources/beta/subresources/responses/index.md index bb442684..775e7edd 100644 --- a/en/cli/resources/beta/subresources/responses/index.md +++ b/en/cli/resources/beta/subresources/responses/index.md @@ -6,7 +6,13 @@ **post** `/responses?beta=true` -Create a model response +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. ### Parameters @@ -458,7 +464,7 @@ Create a model response - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -466,6 +472,8 @@ Create a model response - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -701,7 +709,7 @@ Create a model response The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -709,6 +717,8 @@ Create a model response - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -1819,7 +1829,7 @@ Create a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -1829,7 +1839,11 @@ Create a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -1876,7 +1890,7 @@ Create a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -1886,7 +1900,11 @@ Create a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -4180,7 +4198,7 @@ Create a model response The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -6748,7 +6766,7 @@ openai beta:responses create \ **get** `/responses/{response_id}?beta=true` -Get a model response +Retrieves a model response with the given ID. ### Parameters @@ -7004,7 +7022,7 @@ Get a model response - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -7012,6 +7030,8 @@ Get a model response - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -7247,7 +7267,7 @@ Get a model response The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -7255,6 +7275,8 @@ Get a model response - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -8365,7 +8387,7 @@ Get a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -8375,7 +8397,11 @@ Get a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -8422,7 +8448,7 @@ Get a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -8432,7 +8458,11 @@ Get a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -10726,7 +10756,7 @@ Get a model response The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -13295,7 +13325,7 @@ openai beta:responses retrieve \ **delete** `/responses/{response_id}?beta=true` -Delete a model response +Deletes a model response with the given ID. ### Parameters @@ -13321,7 +13351,9 @@ openai beta:responses delete \ **post** `/responses/{response_id}/cancel?beta=true` -Cancel a response +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 @@ -13558,7 +13590,7 @@ Cancel a response - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -13566,6 +13598,8 @@ Cancel a response - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -13801,7 +13835,7 @@ Cancel a response The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -13809,6 +13843,8 @@ Cancel a response - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -14919,7 +14955,7 @@ Cancel a response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -14929,7 +14965,11 @@ Cancel a response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -14976,7 +15016,7 @@ Cancel a response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -14986,7 +15026,11 @@ Cancel a response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -17280,7 +17324,7 @@ Cancel a response The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -19849,7 +19893,9 @@ openai beta:responses cancel \ **post** `/responses/compact?beta=true` -Compact a response +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 @@ -20081,7 +20127,7 @@ Compact a response The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -20089,6 +20135,8 @@ Compact a response - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -21348,7 +21396,7 @@ Compact a response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -21358,7 +21406,11 @@ Compact a response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -21405,7 +21457,7 @@ Compact a response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -21415,7 +21467,11 @@ Compact a response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -23536,7 +23592,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -23544,6 +23600,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -24803,7 +24861,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -24813,7 +24871,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -24860,7 +24922,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -24870,7 +24932,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -27456,7 +27522,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -27464,6 +27530,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -27525,7 +27593,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -27535,7 +27603,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -27582,7 +27654,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -27592,7 +27664,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -28259,7 +28335,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -28267,6 +28343,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -28502,7 +28580,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -28510,6 +28588,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -29620,7 +29700,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -29630,7 +29710,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -29677,7 +29761,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -29687,7 +29771,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -31981,7 +32069,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -35131,7 +35219,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -35139,6 +35227,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -35374,7 +35464,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -35382,6 +35472,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -36492,7 +36584,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -36502,7 +36594,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -36549,7 +36645,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -36559,7 +36655,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -38853,7 +38953,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -42474,7 +42574,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -42482,6 +42582,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -42717,7 +42819,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -42725,6 +42827,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -43835,7 +43939,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -43845,7 +43949,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -43892,7 +44000,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -43902,7 +44010,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -46196,7 +46308,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -49232,7 +49344,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -49240,6 +49352,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -49475,7 +49589,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -49483,6 +49597,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -50593,7 +50709,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -50603,7 +50719,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -50650,7 +50770,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -50660,7 +50780,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -52954,7 +53078,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -56818,7 +56942,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -56826,6 +56950,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -57061,7 +57187,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -57069,6 +57195,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -58179,7 +58307,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -58189,7 +58317,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -58236,7 +58368,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -58246,7 +58378,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -60540,7 +60676,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -63198,7 +63334,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -63206,6 +63342,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -63441,7 +63579,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -63449,6 +63587,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -64559,7 +64699,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -64569,7 +64709,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -64616,7 +64760,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -64626,7 +64770,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -66920,7 +67068,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -69316,12 +69464,41 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Input +### Beta Response Inject Created Event -- `beta_response_input: array of BetaResponseInputItem` +- `beta_response_inject_created_event: object { response_id, sequence_number, type, stream_id }` - A list of one or many input items to the model, containing - different content types. + Emitted when all injected input items were validated and committed to the + active response. + + - `response_id: string` + + The ID of the response that accepted the input. + + - `sequence_number: number` + + The sequence number for this event. + + - `type: "response.inject.created"` + + The event discriminator. Always `response.inject.created`. + + - `stream_id: optional string` + + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. + +### Beta Response Inject Event + +- `beta_response_inject_event: object { input, response_id, type }` + + 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. + + - `input: array of BetaResponseInputItem` + + Input items to inject into the active response. - `beta_easy_input_message: object { content, role, phase, type }` @@ -69456,7 +69633,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -69464,6 +69641,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -69699,7 +69878,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -69707,6 +69886,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -70817,7 +70998,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -70827,7 +71008,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -70874,7 +71059,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -70884,7 +71069,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -72928,214 +73117,75 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Input Audio - -- `beta_response_input_audio: object { input_audio, type }` - - An audio input to the model. - - - `input_audio: object { data, format }` - - - `data: string` - - Base64-encoded audio data. - - - `format: "mp3" or "wav"` - - The format of the audio data. Currently supported formats are `mp3` and - `wav`. - - - `"mp3"` - - - `"wav"` - - - `type: "input_audio"` - - The type of the input item. Always `input_audio`. - -### Beta Response Input Content - -- `beta_response_input_content: BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - A text input to the model. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - -### Beta Response Input File - -- `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` + - `response_id: string` - - `file_data: optional string` + The ID of the active response that should receive the input. - The content of the file to be sent to the model. + - `type: "response.inject"` - - `file_id: optional string` + The event discriminator. Always `response.inject`. - The ID of the file to be sent to the model. +### Beta Response Inject Failed Event - - `file_url: optional string` +- `beta_response_inject_failed_event: object { error, input, response_id, 3 more }` - The URL of the file to be sent to the model. + 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. - - `filename: optional string` + - `error: object { code, message }` - The name of the file to be sent to the model. + Information about why the input was not committed. - - `prompt_cache_breakpoint: optional object { mode }` + - `code: "response_already_completed" or "response_not_found"` - Marks the exact end of a reusable 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 machine-readable error code. - - `mode: "explicit"` + - `"response_already_completed"` - The breakpoint mode. Always `explicit`. + - `"response_not_found"` -### Beta Response Input File Content + - `message: string` -- `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + A human-readable description of the error. - A file input to the model. + - `input: array of BetaResponseInputItem` - - `type: "input_file"` + The raw input items that were not committed. - The type of the input item. Always `input_file`. + - `beta_easy_input_message: object { content, role, phase, type }` - - `detail: optional "auto" or "low" or "high"` + 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 detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `content: string or BetaResponseInputMessageContentList` - - `"auto"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"low"` + - `Text input: string` - - `"high"` + A text input to the model. - - `file_data: optional string` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - The base64-encoded data of the file to be sent to the model. + A list of one or many input items to the model, containing different content + types. - - `file_id: optional string` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The ID of the file to be sent to the model. + A text input to the model. - - `file_url: optional string` + - `text: string` - The URL of the file to be sent to the model. + The text input to the model. - - `filename: optional string` + - `type: "input_text"` - The name of the file to be sent to the model. + The type of the input item. Always `input_text`. - `prompt_cache_breakpoint: optional object { mode }` @@ -73145,135 +73195,7 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. -### Beta Response Input Image - -- `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - -### Beta Response Input Image Content - -- `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `detail: optional "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - -### Beta Response Input Item - -- `beta_response_input_item: BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - 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. - - - `beta_easy_input_message: object { content, role, phase, type }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: string or BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `Text input: string` - - A text input to the model. - - - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -73364,7 +73286,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -73372,6 +73294,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -73607,7 +73531,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -73615,6 +73539,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -74725,7 +74651,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -74735,7 +74661,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -74782,7 +74712,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -74792,7 +74722,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -76836,120 +76770,48 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Input Message Content List - -- `beta_response_input_message_content_list: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` + - `response_id: string` - - `file_data: optional string` + The ID of the response that rejected the input. - The content of the file to be sent to the model. + - `sequence_number: number` - - `file_id: optional string` + The sequence number for this event. - The ID of the file to be sent to the model. + - `type: "response.inject.failed"` - - `file_url: optional string` + The event discriminator. Always `response.inject.failed`. - The URL of the file to be sent to the model. + - `stream_id: optional string` - - `filename: optional string` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - The name of the file to be sent to the model. +### Beta Response Input - - `prompt_cache_breakpoint: optional object { mode }` +- `beta_response_input: array of BetaResponseInputItem` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A list of one or many input items to the model, containing + different content types. - - `mode: "explicit"` + - `beta_easy_input_message: object { content, role, phase, type }` - The breakpoint mode. Always `explicit`. + 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. -### Beta Response Input Message Item + - `content: string or BetaResponseInputMessageContentList` -- `beta_response_input_message_item: object { id, content, role, 3 more }` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `id: string` + - `Text input: string` - The unique ID of the message input. + A text input to the model. - - `content: array of BetaResponseInputContent` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` A list of one or many input items to the model, containing different content types. @@ -77052,94 +76914,40 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. - - `role: "user" or "system" or "developer"` + - `role: "user" or "assistant" or "system" or "developer"` - The role of the message input. One of `user`, `system`, or `developer`. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - `"user"` + - `"assistant"` + - `"system"` - `"developer"` - - `type: "message"` - - The type of the message input. Always set to `message`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - -### Beta Response Input Text - -- `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - -### Beta Response Input Text Content - -- `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. + - `phase: optional "commentary" or "final_answer"` - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` + 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 breakpoint mode. Always `explicit`. + - `"commentary"` -### Beta Response Item + - `"final_answer"` -- `beta_response_item: BetaResponseInputMessageItem or BetaResponseOutputMessage or BetaResponseFileSearchToolCall or 29 more` + - `type: optional "message"` - Content item used to generate a response. + The type of the message input. Always `message`. - - `beta_response_input_message_item: object { id, content, role, 3 more }` + - `"message"` - - `id: string` + - `message: object { content, role, agent, 2 more }` - The unique ID of the message input. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - `content: array of BetaResponseInputContent` @@ -77150,100 +76958,14 @@ openai beta:responses compact \ A text input to the model. - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `role: "user" or "system" or "developer"` The role of the message input. One of `user`, `system`, or `developer`. @@ -77254,10 +76976,6 @@ openai beta:responses compact \ - `"developer"` - - `type: "message"` - - The type of the message input. Always set to `message`. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -77277,6 +76995,12 @@ openai beta:responses compact \ - `"incomplete"` + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + - `beta_response_output_message: object { id, content, role, 4 more }` An output message from the model. @@ -77448,7 +77172,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -77456,6 +77180,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -77794,11 +77520,9 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - - `id: string` + - `computer_call_output: object { call_id, output, type, 4 more }` - The unique ID of the computer call tool output. + The output of a computer tool call. - `call_id: string` @@ -77821,27 +77545,17 @@ openai beta:responses compact \ The URL of the screenshot image. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `"completed"` - - - `"incomplete"` - - - `"failed"` - - - `"in_progress"` - - `type: "computer_call_output"` The type of the computer tool call output. Always `computer_call_output`. + - `id: optional string` + + The ID of the computer tool call output. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The safety checks reported by the API that have been acknowledged by the - developer. + The safety checks reported by the API that have been acknowledged by the developer. - `id: string` @@ -77863,9 +77577,15 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The identifier of the actor that created the item. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` - `beta_response_function_web_search: object { id, action, status, 2 more }` @@ -77961,16 +77681,58 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `id: optional string` The unique ID of the function tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -77981,34 +77743,27 @@ openai beta:responses compact \ - `"incomplete"` - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - - `id: string` + - `function_call_output: object { call_id, output, type, 4 more }` - The unique ID of the function call tool output. + The output of a function tool call. - `call_id: string` The unique ID of the function tool call generated by the model. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `output: string or BetaResponseFunctionCallOutputItemList` - The output from the function call generated by your code. - Can be a string or an list of output content. + Text, image, or file output of the function tool call. - - `string output: string` + - `union_member_0: string` - A string of the output of the function call. + A JSON string of the output of the function tool call. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - Text, image, or file output of the function call. + An array of content outputs (text, image, file) for the function tool call. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -78024,18 +77779,30 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The breakpoint mode. Always `explicit`. - - `detail: "low" or "high" or "auto" or "original"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` The type of the input item. Always `input_image`. + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + - `file_id: optional string` The ID of the file to be sent to the model. @@ -78048,7 +77815,11 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` A file input to the model. @@ -78060,9 +77831,15 @@ openai beta:responses compact \ The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"auto"` + + - `"low"` + + - `"high"` + - `file_data: optional string` - The content of the file to be sent to the model. + The base64-encoded data of the file to be sent to the model. - `file_id: optional string` @@ -78080,21 +77857,18 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` + - `mode: "explicit"` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - `type: "function_call_output"` The type of the function tool call output. Always `function_call_output`. + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -78119,112 +77893,68 @@ openai beta:responses compact \ The caller type. Always `program`. - - `created_by: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The identifier of the actor that created the item. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `agent_message: object { id, author, content, 3 more }` + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of the agent message. + - `"incomplete"` + + - `agent_message: object { author, content, recipient, 3 more }` + + A message routed between agents. - `author: string` The sending agent identity. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - Encrypted content sent between agents. + Plaintext, image, or encrypted content sent between agents. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `beta_response_output_text: object { annotations, text, type, logprobs }` - - A text output from the model. - - - `text: object { text, type }` - - A text content. - - - `text: string` - - - `type: "text"` - - - `summary_text: object { text, type }` - - A summary text from the model. - - - `text: string` - - A summary of the reasoning output from the model so far. - - - `type: "summary_text"` - - The type of the object. Always `summary_text`. - - - `reasoning_text: object { text, type }` - - Reasoning text from the model. - - `text: string` - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - - `beta_response_output_refusal: object { refusal, type }` - - A refusal from the model. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The text input to the model. - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `type: "input_text"` - A screenshot of a computer. + The type of the input item. Always `input_text`. - - `detail: "low" or "high" or "auto" or "original"` + - `prompt_cache_breakpoint: optional object { mode }` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"low"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `"high"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"auto"` + - `type: "input_image"` - - `"original"` + The type of the input item. Always `input_image`. - - `file_id: string` + - `detail: optional "low" or "high" or "auto" or "original"` - The identifier of an uploaded file that contains the screenshot. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `image_url: string` + - `file_id: optional string` - The URL of the screenshot image. + The ID of the file to be sent to the model. - - `type: "computer_screenshot"` + - `image_url: optional string` - 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. - `prompt_cache_breakpoint: optional object { mode }` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - `encrypted_content: object { encrypted_content, type }` Opaque encrypted content that Responses API decrypts inside trusted model execution. @@ -78243,7 +77973,11 @@ openai beta:responses compact \ - `type: "agent_message"` - The type of the item. Always `agent_message`. + The item type. Always `agent_message`. + + - `id: optional string` + + The unique ID of this agent message item. - `agent: optional object { agent_name }` @@ -78253,15 +77987,11 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { id, action, arguments, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call item. + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The multi-agent action to execute. + The multi-agent action that was executed. - `"spawn_agent"` @@ -78277,7 +78007,7 @@ openai beta:responses compact \ - `arguments: string` - The JSON string of arguments generated for the action. + The action arguments as a JSON string. - `call_id: string` @@ -78285,7 +78015,11 @@ openai beta:responses compact \ - `type: "multi_agent_call"` - The type of the multi-agent call. Always `multi_agent_call`. + The item type. Always `multi_agent_call`. + + - `id: optional string` + + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -78295,11 +78029,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` @@ -78321,71 +78051,95 @@ openai beta:responses compact \ The unique ID of the multi-agent call. - - `output: array of BetaResponseOutputText` + - `output: array of object { text, type, annotations }` Text output returned by the multi-agent action. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - The annotations of the text output. - - `text: string` - The text output from the model. + The text content. - `type: "output_text"` - The type of the output text. Always `output_text`. + The content type. Always `output_text`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `type: "multi_agent_call_output"` + Citations associated with the text content. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `union_member_0: array of object { file_id, filename, index, type }` - - `agent: optional object { agent_name }` + - `file_id: string` - The agent that produced this item. + The ID of the file. - - `agent_name: string` + - `filename: string` - The canonical name of the agent that produced this item. + The filename of the file cited. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `index: number` - - `id: string` + The index of the file in the list of files. - The unique ID of the tool search call item. + - `type: "file_citation"` - - `arguments: unknown` + The citation type. Always `file_citation`. - Arguments used for the tool search call. + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - `call_id: string` + - `end_index: number` - The unique ID of the tool search call generated by the model. + The index of the last character of the citation in the message. - - `execution: "server" or "client"` + - `start_index: number` - Whether tool search was executed by the server or by the client. + The index of the first character of the citation in the message. - - `"server"` + - `title: string` - - `"client"` + The title of the cited resource. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "url_citation"` - The status of the tool search call item that was recorded. + The citation type. Always `url_citation`. - - `"in_progress"` + - `url: string` - - `"completed"` + The URL of the cited resource. - - `"incomplete"` + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `type: "tool_search_call"` + - `container_id: string` - The type of the item. Always `tool_search_call`. + The ID of the container. + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `file_id: string` + + The ID of the container file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `type: "container_file_citation"` + + The citation type. Always `container_file_citation`. + + - `type: "multi_agent_call_output"` + + The item type. Always `multi_agent_call_output`. + + - `id: optional string` + + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -78395,21 +78149,33 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `tool_search_call: object { arguments, type, id, 4 more }` - The identifier of the actor that created the item. + - `arguments: unknown` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + The arguments supplied to the tool search call. - - `id: string` + - `type: "tool_search_call"` - The unique ID of the tool search output item. + The item type. Always `tool_search_call`. - - `call_id: string` + - `id: optional string` + + The unique ID of this tool search call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` The unique ID of the tool search call generated by the model. - - `execution: "server" or "client"` + - `execution: optional "server" or "client"` Whether tool search was executed by the server or by the client. @@ -78417,9 +78183,9 @@ openai beta:responses compact \ - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output item that was recorded. + The status of the tool search call. - `"in_progress"` @@ -78427,9 +78193,11 @@ openai beta:responses compact \ - `"incomplete"` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + - `tools: array of BetaTool` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -78524,7 +78292,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -78534,7 +78302,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -78581,7 +78353,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -78591,7 +78363,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -79463,7 +79239,11 @@ openai beta:responses compact \ - `type: "tool_search_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. + + - `id: optional string` + + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -79473,39 +79253,37 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `call_id: optional string` - - `additional_tools: object { id, role, tools, 2 more }` + The unique ID of the tool search call generated by the model. - - `id: string` + - `execution: optional "server" or "client"` - The unique ID of the additional tools item. + Whether tool search was executed by the server or by the client. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"server"` - The role that provided the additional tools. + - `"client"` - - `"unknown"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"user"` + The status of the tool search output. - - `"assistant"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"critic"` + - `"incomplete"` - - `"discriminator"` + - `additional_tools: object { role, tools, type, 2 more }` - - `"developer"` + - `role: "developer"` - - `"tool"` + The role that provided the additional tools. Only `developer` is supported. - `tools: array of BetaTool` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -79573,7 +79351,11 @@ openai beta:responses compact \ - `type: "additional_tools"` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -79646,86 +79428,22 @@ openai beta:responses compact \ - `"incomplete"` - - `program: object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of the program item. - - - `call_id: string` - - The stable call ID of the program item. - - - `code: string` - - The JavaScript source executed by programmatic tool calling. - - - `fingerprint: string` - - Opaque program replay fingerprint that must be round-tripped. - - - `type: "program"` - - The type of the item. Always `program`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `program_output: object { id, call_id, result, 3 more }` - - - `id: string` - - The unique ID of the program output item. - - - `call_id: string` - - The call ID of the program item. - - - `result: string` - - The result produced by the program item. - - - `status: "completed" or "incomplete"` - - The terminal status of the program output item. - - - `"completed"` - - - `"incomplete"` - - - `type: "program_output"` - - The type of the item. Always `program_output`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `id: string` - - The unique ID of the compaction item. - - `encrypted_content: string` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `type: "compaction"` The type of the item. Always `compaction`. + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -79734,10 +79452,6 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -79941,13 +79655,9 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: string` + - `shell_call: object { action, call_id, type, 5 more }` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - `action: object { commands, max_output_length, timeout_ms }` @@ -79955,54 +79665,28 @@ openai beta:responses compact \ - `commands: array of string` - - `max_output_length: number` + Ordered shell commands for the execution environment to run. - Optional maximum number of characters to return from each command. + - `max_output_length: optional number` - - `timeout_ms: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Optional timeout in milliseconds for the commands. + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `beta_response_local_environment: object { type }` - - Represents the use of a local environment to perform shell actions. - - - `type: "local"` - - The environment type. Always `local`. - - - `beta_response_container_reference: object { container_id, type }` - - Represents a container created with /v1/containers. - - - `container_id: string` - - - `type: "container_reference"` - - The environment type. Always `container_reference`. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: "shell_call"` The type of the item. Always `shell_call`. + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -80025,33 +79709,41 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The ID of the entity that created this tool call. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + The environment to execute the shell commands in. - The output of a shell tool call that was emitted. + - `beta_local_environment: object { type, skills }` - - `id: string` + - `beta_container_reference: object { container_id, type }` - The unique ID of the shell call output. Populated when this item is returned via API. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `call_id: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call generated by the model. + - `"in_progress"` - - `max_output_length: number` + - `"completed"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"incomplete"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `shell_call_output: object { call_id, output, type, 5 more }` - An array of shell call output contents + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: object { type } or object { exit_code, type }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `timeout: object { type }` @@ -80063,7 +79755,7 @@ openai beta:responses compact \ - `exit_code: number` - Exit code from the shell process. + The exit code returned by the shell process. - `type: "exit"` @@ -80071,29 +79763,19 @@ openai beta:responses compact \ - `stderr: string` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: string` - The standard output that was captured. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` + Captured stdout output for the shell call. - - `"completed"` + - `type: "shell_call_output"` - - `"incomplete"` + The type of the item. Always `shell_call_output`. - - `type: "shell_call_output"` + - `id: optional string` - The type of the shell call output. Always `shell_call_output`. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -80117,17 +79799,25 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The identifier of the actor that created the item. + - `max_output_length: optional number` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + The maximum number of UTF-8 characters captured for this shell call's combined output. - A tool call that applies file diffs by creating, deleting, or updating files. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the shell call output. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` @@ -80135,51 +79825,51 @@ openai beta:responses compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `create_file: object { diff, path, type }` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply when creating the file. - `path: string` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: "create_file"` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `delete_file: object { path, type }` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: string` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: "delete_file"` - Delete the specified file. + The operation type. Always `delete_file`. - `update_file: object { diff, path, type }` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply to the existing file. - `path: string` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: "update_file"` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `status: "in_progress" or "completed"` @@ -80193,6 +79883,10 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call`. + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -80215,17 +79909,7828 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` - - The ID of the entity that created this tool call. - - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - The output emitted by an apply patch tool call. + The caller type. Always `program`. - - `id: string` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the custom tool call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `compaction_trigger: object { type, agent }` + + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `item_reference: object { id, agent, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Input Audio + +- `beta_response_input_audio: object { input_audio, type }` + + An audio input to the model. + + - `input_audio: object { data, format }` + + - `data: string` + + Base64-encoded audio data. + + - `format: "mp3" or "wav"` + + The format of the audio data. Currently supported formats are `mp3` and + `wav`. + + - `"mp3"` + + - `"wav"` + + - `type: "input_audio"` + + The type of the input item. Always `input_audio`. + +### Beta Response Input Content + +- `beta_response_input_content: BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + A text input to the model. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Input File + +- `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Input File Content + +- `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Input Image + +- `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Input Image Content + +- `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Input Item + +- `beta_response_input_item: BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + + 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. + + - `beta_easy_input_message: object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `Text input: string` + + A text input to the model. + + - `beta_response_input_message_content_list: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `message: object { content, role, agent, 2 more }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + + The content of the output message. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "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"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + Set of 16 key-value pairs that can be attached to an object. 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. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `drag: object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `type: object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `wait: object { type }` + + A wait action. + + - `actions: optional array of BetaComputerAction` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `drag: object { path, type, keys }` + + A drag action. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `type: object { text, type }` + + An action to type in text. + + - `wait: object { type }` + + A wait action. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `computer_call_output: object { call_id, output, type, 4 more }` + + The output of a computer tool call. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `id: optional string` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "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"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_web_search: object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `search: object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `queries: optional array of string` + + The search queries. + + - `query: optional string` + + The search query. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `url: string` + + The URL of the source. + + - `open_page: object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `url: optional string` + + The URL opened by the model. + + - `find_in_page: object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `id: optional string` + + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `function_call_output: object { call_id, output, type, 4 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or BetaResponseFunctionCallOutputItemList` + + Text, image, or file output of the function tool call. + + - `union_member_0: string` + + A JSON string of the output of the function tool call. + + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + + An array of content outputs (text, image, file) for the function tool call. + + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `agent_message: object { author, content, recipient, 3 more }` + + A message routed between agents. + + - `author: string` + + The sending agent identity. + + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + + Plaintext, image, or encrypted content sent between agents. + + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The item type. Always `agent_message`. + + - `id: optional string` + + The unique ID of this agent message item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { action, arguments, call_id, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The action arguments as a JSON string. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. + + - `id: optional string` + + The unique ID of this multi-agent call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call_output: object { action, call_id, output, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of object { text, type, annotations }` + + Text output returned by the multi-agent action. + + - `text: string` + + The text content. + + - `type: "output_text"` + + The content type. Always `output_text`. + + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + + Citations associated with the text content. + + - `union_member_0: array of object { file_id, filename, index, type }` + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The citation type. Always `file_citation`. + + - `union_member_1: array of object { end_index, start_index, title, 2 more }` + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `title: string` + + The title of the cited resource. + + - `type: "url_citation"` + + The citation type. Always `url_citation`. + + - `url: string` + + The URL of the cited resource. + + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + + - `container_id: string` + + The ID of the container. + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `file_id: string` + + The ID of the container file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `type: "container_file_citation"` + + The citation type. Always `container_file_citation`. + + - `type: "multi_agent_call_output"` + + The item type. Always `multi_agent_call_output`. + + - `id: optional string` + + The unique ID of this multi-agent call output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `tool_search_call: object { arguments, type, id, 4 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `id: optional string` + + The unique ID of this tool search call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + + - `tools: array of BetaTool` + + The loaded tool definitions returned by the tool search output. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether strict parameter validation is enforced for this function tool. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional object { key, type, value } or object { filters, type }` + + A filter to apply. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `Compound Filter: object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of object { key, type, value } or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_1: unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + 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. + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `mcp: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `MCP allowed tools: array of string` + + A string array of allowed tool names + + - `MCP tool filter: object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `MCP tool approval filter: object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `MCP tool approval setting: "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: optional string` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `union_member_0: string` + + The container ID. + + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + + - `"gpt-image-1.5"` + + - `"chatgpt-image-latest"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `beta_skill_reference: object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `beta_inline_skill: object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: object { data, media_type, type }` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `type: "inline"` + + Defines an inline skill for this request. + + - `beta_local_environment: object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `skills: optional array of BetaLocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `beta_container_reference: object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `text: object { type }` + + Unconstrained free-form text. + + - `grammar: object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + + The function/custom tools available inside this namespace. + + - `function: object { name, type, allowed_callers, 5 more }` + + - `name: string` + + - `type: "function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: optional unknown` + + - `strict: optional boolean` + + 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. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_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). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `id: optional string` + + The unique ID of this tool search output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `additional_tools: object { role, tools, type, 2 more }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `tools: array of BetaTool` + + A list of additional tools made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + Search 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_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). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `id: optional string` + + The ID of the compaction item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call: object { action, call_id, type, 5 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `beta_local_environment: object { type, skills }` + + - `beta_container_reference: object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call_output: object { call_id, output, type, 5 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `create_file: object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `delete_file: object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `update_file: object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `apply_patch_call_output: object { call_id, status, type, 4 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the custom tool call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `compaction_trigger: object { type, agent }` + + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `item_reference: object { id, agent, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Input Message Content List + +- `beta_response_input_message_content_list: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Input Message Item + +- `beta_response_input_message_item: object { id, content, role, 3 more }` + + - `id: string` + + The unique ID of the message input. + + - `content: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `type: "message"` + + The type of the message input. Always set to `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + +### Beta Response Input Text + +- `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Input Text Content + +- `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + +### Beta Response Item + +- `beta_response_item: BetaResponseInputMessageItem or BetaResponseOutputMessage or BetaResponseFileSearchToolCall or 29 more` + + Content item used to generate a response. + + - `beta_response_input_message_item: object { id, content, role, 3 more }` + + - `id: string` + + The unique ID of the message input. + + - `content: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `type: "message"` + + The type of the message input. Always set to `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + + The content of the output message. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "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"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + Set of 16 key-value pairs that can be attached to an object. 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. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `drag: object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `type: object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `wait: object { type }` + + A wait action. + + - `actions: optional array of BetaComputerAction` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `drag: object { path, type, keys }` + + A drag action. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `type: object { text, type }` + + An action to type in text. + + - `wait: object { type }` + + A wait action. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_function_web_search: object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `search: object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `queries: optional array of string` + + The search queries. + + - `query: optional string` + + The search query. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `url: string` + + The URL of the source. + + - `open_page: object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `url: optional string` + + The URL opened by the model. + + - `find_in_page: object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `id: string` + + The unique ID of the function tool call. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the function call tool output. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the function call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the function call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `agent_message: object { id, author, content, 3 more }` + + - `id: string` + + The unique ID of the agent message. + + - `author: string` + + The sending agent identity. + + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + + Encrypted content sent between agents. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `text: object { text, type }` + + A text content. + + - `text: string` + + - `type: "text"` + + - `summary_text: object { text, type }` + + A summary text from the model. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `reasoning_text: object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: string` + + The URL of the screenshot image. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { id, action, arguments, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action to execute. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call_output: object { id, action, call_id, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call output item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of BetaResponseOutputText` + + Text output returned by the multi-agent action. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `type: "multi_agent_call_output"` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + + - `id: string` + + The unique ID of the tool search call item. + + - `arguments: unknown` + + Arguments used for the tool search call. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search call item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search output item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `tools: array of BetaTool` + + The loaded tool definitions returned by tool search. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether strict parameter validation is enforced for this function tool. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional object { key, type, value } or object { filters, type }` + + A filter to apply. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `Compound Filter: object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of object { key, type, value } or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_1: unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + 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. + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `mcp: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `MCP allowed tools: array of string` + + A string array of allowed tool names + + - `MCP tool filter: object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `MCP tool approval filter: object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `MCP tool approval setting: "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: optional string` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `union_member_0: string` + + The container ID. + + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + + - `"gpt-image-1.5"` + + - `"chatgpt-image-latest"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `beta_skill_reference: object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `beta_inline_skill: object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: object { data, media_type, type }` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `type: "inline"` + + Defines an inline skill for this request. + + - `beta_local_environment: object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `skills: optional array of BetaLocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `beta_container_reference: object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `text: object { type }` + + Unconstrained free-form text. + + - `grammar: object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + + The function/custom tools available inside this namespace. + + - `function: object { name, type, allowed_callers, 5 more }` + + - `name: string` + + - `type: "function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: optional unknown` + + - `strict: optional boolean` + + 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. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_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). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `type: "tool_search_output"` + + The type of the item. Always `tool_search_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `additional_tools: object { id, role, tools, 2 more }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of BetaTool` + + The additional tool definitions made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + Search 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_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). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + - `max_output_length: number` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: number` + + Optional timeout in milliseconds for the commands. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `beta_response_local_environment: object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + + The output of a shell tool call that was emitted. + + - `id: string` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `max_output_length: number` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents + + - `outcome: object { type } or object { exit_code, type }` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + The standard error output that was captured. + + - `stdout: string` + + The standard output that was captured. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `id: string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `create_file: object { diff, path, type }` + + Instruction describing how to create a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to create. + + - `type: "create_file"` + + Create a new file with the provided diff. + + - `delete_file: object { path, type }` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: string` + + Path of the file to delete. + + - `type: "delete_file"` + + Delete the specified file. + + - `update_file: object { diff, path, type }` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to update. + + - `type: "update_file"` + + Update an existing file with the provided diff. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: string` @@ -80943,7 +88448,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -80951,6 +88456,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -82210,7 +89717,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -82220,7 +89727,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -82267,7 +89778,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -82277,7 +89788,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -84257,7 +91772,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -84265,6 +91780,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -85524,7 +93041,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -85534,7 +93051,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -85581,7 +93102,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -85591,7 +93112,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -87591,7 +95116,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -87599,6 +95124,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -88858,7 +96385,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -88868,7 +96395,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -88915,7 +96446,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -88925,7 +96456,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -90917,7 +98452,792 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + +### Beta Response Output Refusal + +- `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + +### Beta Response Output Text + +- `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + +### Beta Response Output Text Annotation Added Event + +- `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` + + Emitted when an annotation is added to output text content. + + - `annotation: unknown` + + The annotation object being added. (See annotation schema for details.) + + - `annotation_index: number` + + The index of the annotation within the content part. + + - `content_index: number` + + The index of the content part within the output item. + + - `item_id: string` + + The unique identifier of the item to which the annotation is being added. + + - `output_index: number` + + The index of the output item in the response's output array. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.output_text.annotation.added"` + + The type of the event. Always 'response.output_text.annotation.added'. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Prompt + +- `beta_response_prompt: object { id, variables, version }` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: string` + + The unique identifier of the prompt template to use. + + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `union_member_0: string` + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `version: optional string` + + Optional version of the prompt template. + +### Beta Response Queued Event + +- `beta_response_queued_event: object { response, sequence_number, type, agent }` + + Emitted when a response is queued and waiting to be processed. + + - `response: object { id, created_at, error, 31 more }` + + The full response object that is queued. + + - `id: string` + + Unique identifier for this Response. + + - `created_at: number` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: object { code, message }` + + An error object returned when the model fails to generate a Response. + + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"bio_policy"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: string` + + A human-readable description of the error. + + - `incomplete_details: object { reason }` + + Details about why the response is incomplete. + + - `reason: optional "max_output_tokens" or "content_filter"` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: string or array of BetaResponseInputItem` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `union_member_0: string` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `Input item list: array of BetaResponseInputItem` + + A list of one or many input items to the model, containing + different content types. + + - `beta_easy_input_message: object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `Text input: string` + + A text input to the model. + + - `beta_response_input_message_content_list: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `message: object { content, role, agent, 2 more }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + + The content of the output message. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "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"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -90925,786 +99245,7 @@ openai beta:responses compact \ - `"commentary"` -### Beta Response Output Refusal - -- `beta_response_output_refusal: object { refusal, type }` - - A refusal from the model. - - - `refusal: string` - - The refusal explanation from the model. - - - `type: "refusal"` - - The type of the refusal. Always `refusal`. - -### Beta Response Output Text - -- `beta_response_output_text: object { annotations, text, type, logprobs }` - - A text output from the model. - - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - The annotations of the text output. - - - `file_citation: object { file_id, filename, index, type }` - - A citation to a file. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the file cited. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_citation"` - - The type of the file citation. Always `file_citation`. - - - `url_citation: object { end_index, start_index, title, 2 more }` - - A citation for a web resource used to generate a model response. - - - `end_index: number` - - The index of the last character of the URL citation in the message. - - - `start_index: number` - - The index of the first character of the URL citation in the message. - - - `title: string` - - The title of the web resource. - - - `type: "url_citation"` - - The type of the URL citation. Always `url_citation`. - - - `url: string` - - The URL of the web resource. - - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - A citation for a container file used to generate a model response. - - - `container_id: string` - - The ID of the container file. - - - `end_index: number` - - The index of the last character of the container file citation in the message. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the container file cited. - - - `start_index: number` - - The index of the first character of the container file citation in the message. - - - `type: "container_file_citation"` - - The type of the container file citation. Always `container_file_citation`. - - - `file_path: object { file_id, index, type }` - - A path to a file. - - - `file_id: string` - - The ID of the file. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_path"` - - The type of the file path. Always `file_path`. - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - - `token: string` - - - `bytes: array of number` - - - `logprob: number` - - - `top_logprobs: array of object { token, bytes, logprob }` - - - `token: string` - - - `bytes: array of number` - - - `logprob: number` - -### Beta Response Output Text Annotation Added Event - -- `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` - - Emitted when an annotation is added to output text content. - - - `annotation: unknown` - - The annotation object being added. (See annotation schema for details.) - - - `annotation_index: number` - - The index of the annotation within the content part. - - - `content_index: number` - - The index of the content part within the output item. - - - `item_id: string` - - The unique identifier of the item to which the annotation is being added. - - - `output_index: number` - - The index of the output item in the response's output array. - - - `sequence_number: number` - - The sequence number of this event. - - - `type: "response.output_text.annotation.added"` - - The type of the event. Always 'response.output_text.annotation.added'. - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - -### Beta Response Prompt - -- `beta_response_prompt: object { id, variables, version }` - - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - - `id: string` - - The unique identifier of the prompt template to use. - - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. - - - `union_member_0: string` - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `version: optional string` - - Optional version of the prompt template. - -### Beta Response Queued Event - -- `beta_response_queued_event: object { response, sequence_number, type, agent }` - - Emitted when a response is queued and waiting to be processed. - - - `response: object { id, created_at, error, 31 more }` - - The full response object that is queued. - - - `id: string` - - Unique identifier for this Response. - - - `created_at: number` - - Unix timestamp (in seconds) of when this Response was created. - - - `error: object { code, message }` - - An error object returned when the model fails to generate a Response. - - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - The error code for the response. - - - `"server_error"` - - - `"rate_limit_exceeded"` - - - `"invalid_prompt"` - - - `"bio_policy"` - - - `"vector_store_timeout"` - - - `"invalid_image"` - - - `"invalid_image_format"` - - - `"invalid_base64_image"` - - - `"invalid_image_url"` - - - `"image_too_large"` - - - `"image_too_small"` - - - `"image_parse_error"` - - - `"image_content_policy_violation"` - - - `"invalid_image_mode"` - - - `"image_file_too_large"` - - - `"unsupported_image_media_type"` - - - `"empty_image_file"` - - - `"failed_to_download_image"` - - - `"image_file_not_found"` - - - `message: string` - - A human-readable description of the error. - - - `incomplete_details: object { reason }` - - Details about why the response is incomplete. - - - `reason: optional "max_output_tokens" or "content_filter"` - - The reason why the response is incomplete. - - - `"max_output_tokens"` - - - `"content_filter"` - - - `instructions: string or array of BetaResponseInputItem` - - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - - - `union_member_0: string` - - A text input to the model, equivalent to a text input with the - `developer` role. - - - `Input item list: array of BetaResponseInputItem` - - A list of one or many input items to the model, containing - different content types. - - - `beta_easy_input_message: object { content, role, phase, type }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: string or BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `Text input: string` - - A text input to the model. - - - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `role: "user" or "assistant" or "system" or "developer"` - - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"developer"` - - - `phase: optional "commentary"` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` - - - `type: optional "message"` - - The type of the message input. Always `message`. - - - `"message"` - - - `message: object { content, role, agent, 2 more }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. - - - `content: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `role: "user" or "system" or "developer"` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `"user"` - - - `"system"` - - - `"developer"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: optional "message"` - - The type of the message input. Always set to `message`. - - - `"message"` - - - `beta_response_output_message: object { id, content, role, 4 more }` - - An output message from the model. - - - `id: string` - - The unique ID of the output message. - - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - The content of the output message. - - - `beta_response_output_text: object { annotations, text, type, logprobs }` - - A text output from the model. - - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - The annotations of the text output. - - - `file_citation: object { file_id, filename, index, type }` - - A citation to a file. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the file cited. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_citation"` - - The type of the file citation. Always `file_citation`. - - - `url_citation: object { end_index, start_index, title, 2 more }` - - A citation for a web resource used to generate a model response. - - - `end_index: number` - - The index of the last character of the URL citation in the message. - - - `start_index: number` - - The index of the first character of the URL citation in the message. - - - `title: string` - - The title of the web resource. - - - `type: "url_citation"` - - The type of the URL citation. Always `url_citation`. - - - `url: string` - - The URL of the web resource. - - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - A citation for a container file used to generate a model response. - - - `container_id: string` - - The ID of the container file. - - - `end_index: number` - - The index of the last character of the container file citation in the message. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the container file cited. - - - `start_index: number` - - The index of the first character of the container file citation in the message. - - - `type: "container_file_citation"` - - The type of the container file citation. Always `container_file_citation`. - - - `file_path: object { file_id, index, type }` - - A path to a file. - - - `file_id: string` - - The ID of the file. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_path"` - - The type of the file path. Always `file_path`. - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - - `token: string` - - - `bytes: array of number` - - - `logprob: number` - - - `top_logprobs: array of object { token, bytes, logprob }` - - - `token: string` - - - `bytes: array of number` - - - `logprob: number` - - - `beta_response_output_refusal: object { refusal, type }` - - A refusal from the model. - - - `refusal: string` - - The refusal explanation from the model. - - - `type: "refusal"` - - The type of the refusal. Always `refusal`. - - - `role: "assistant"` - - The role of the output message. Always `assistant`. - - - `status: "in_progress" or "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"` - - - `"completed"` - - - `"incomplete"` - - - `type: "message"` - - The type of the output message. Always `message`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `phase: optional "commentary"` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` + - `"final_answer"` - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` @@ -92816,7 +100357,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -92826,7 +100367,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -92873,7 +100418,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -92883,7 +100428,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -95177,7 +102726,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -98455,7 +106004,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -98463,6 +106012,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -98698,7 +106249,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -98706,6 +106257,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -99816,7 +107369,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -99826,7 +107379,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -99873,7 +107430,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -99883,7 +107440,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -102177,7 +109738,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -107733,7 +115294,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -107743,7 +115304,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -107790,7 +115355,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -107800,7 +115365,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -108787,7 +116356,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -108797,7 +116366,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -108844,7 +116417,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -108854,7 +116427,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -109894,7 +117471,7 @@ openai beta:responses compact \ ### Beta Responses Client Event -- `beta_responses_client_event: object { type, background, context_management, 30 more } or object { input, response_id, type }` +- `beta_responses_client_event: object { type, background, context_management, 30 more } or BetaResponseInjectEvent` Client events accepted by the Responses WebSocket server. @@ -110129,7 +117706,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -110137,6 +117714,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -110372,7 +117951,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -110380,6 +117959,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -111490,7 +119071,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -111500,7 +119081,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -111547,7 +119132,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -111557,7 +119142,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -114441,7 +122030,7 @@ openai beta:responses compact \ 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). - - `response.inject: object { input, response_id, type }` + - `beta_response_inject_event: object { input, response_id, type }` Injects input items into an active response over a WebSocket connection. The items are validated and committed atomically. Currently, the server @@ -115069,7 +122658,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -115077,6 +122666,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -115312,7 +122903,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -115320,6 +122911,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -116430,7 +124023,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -116440,7 +124033,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -116487,7 +124084,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -116497,7 +124094,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -118791,7 +126392,7 @@ openai beta:responses compact \ The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -123965,7 +131566,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `response.inject.created: object { response_id, sequence_number, type, stream_id }` + - `beta_response_inject_created_event: object { response_id, sequence_number, type, stream_id }` Emitted when all injected input items were validated and committed to the active response. @@ -123987,7 +131588,7 @@ openai beta:responses compact \ The multiplexed WebSocket stream that emitted the event. This field is present only when WebSocket multiplexing is enabled separately. - - `response.inject.failed: object { error, input, response_id, 3 more }` + - `beta_response_inject_failed_event: object { error, input, response_id, 3 more }` 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 @@ -124284,7 +131885,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -124294,7 +131895,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -124341,7 +131946,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -124351,7 +131956,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -125531,7 +133140,7 @@ openai beta:responses compact \ **get** `/responses/{response_id}/input_items?beta=true` -List input items +Returns a list of input items for a given response. ### Parameters @@ -125887,7 +133496,7 @@ List input items The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -125895,6 +133504,8 @@ List input items - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -126963,7 +134574,7 @@ List input items - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -126973,7 +134584,11 @@ List input items - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -127020,7 +134635,7 @@ List input items - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -127030,7 +134645,11 @@ List input items - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -129309,7 +136928,7 @@ openai beta:responses:input-items list \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -129317,6 +136936,8 @@ openai beta:responses:input-items list \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -130385,7 +138006,7 @@ openai beta:responses:input-items list \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -130395,7 +138016,11 @@ openai beta:responses:input-items list \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -130442,7 +138067,7 @@ openai beta:responses:input-items list \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -130452,7 +138077,11 @@ openai beta:responses:input-items list \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -132375,7 +140004,9 @@ openai beta:responses:input-items list \ **post** `/responses/input_tokens?beta=true` -Get input token counts +Returns input token counts of the request. + +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. ### Parameters @@ -132439,7 +140070,7 @@ Get input token counts ### Returns -- `InputTokenCountResponse: object { input_tokens, object }` +- `BetaResponseInputTokenCountResponse: object { input_tokens, object }` - `input_tokens: number`