diff --git a/en/ruby/resources/beta/subresources/responses/index.md b/en/ruby/resources/beta/subresources/responses/index.md index 9e51d0c6..3f3d516c 100644 --- a/en/ruby/resources/beta/subresources/responses/index.md +++ b/en/ruby/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 @@ -239,7 +245,7 @@ Create a model response - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -247,6 +253,8 @@ Create a model response - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -486,7 +494,7 @@ Create a model response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -494,6 +502,8 @@ Create a model response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -1666,7 +1676,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -1676,7 +1686,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -1723,7 +1737,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -1733,7 +1747,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -5013,7 +5031,7 @@ Create a model response - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -5021,6 +5039,8 @@ Create a model response - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -5260,7 +5280,7 @@ Create a model response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -5268,6 +5288,8 @@ Create a model response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -6440,7 +6462,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -6450,7 +6472,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -6497,7 +6523,7 @@ Create a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -6507,7 +6533,11 @@ Create a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -11395,7 +11425,7 @@ puts(beta_response) **get** `/responses/{response_id}?beta=true` -Get a model response +Retrieves a model response with the given ID. ### Parameters @@ -11684,7 +11714,7 @@ Get a model response - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -11692,6 +11722,8 @@ Get a model response - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -11931,7 +11963,7 @@ Get a model response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -11939,6 +11971,8 @@ Get a model response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -13111,7 +13145,7 @@ Get a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -13121,7 +13155,11 @@ Get a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -13168,7 +13206,7 @@ Get a model response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -13178,7 +13216,11 @@ Get a model response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -18066,7 +18108,7 @@ puts(beta_response) **delete** `/responses/{response_id}?beta=true` -Delete a model response +Deletes a model response with the given ID. ### Parameters @@ -18094,7 +18136,9 @@ puts(result) **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 @@ -18341,7 +18385,7 @@ Cancel a response - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -18349,6 +18393,8 @@ Cancel a response - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -18588,7 +18634,7 @@ Cancel a response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -18596,6 +18642,8 @@ Cancel a response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -19768,7 +19816,7 @@ Cancel a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -19778,7 +19826,11 @@ Cancel a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -19825,7 +19877,7 @@ Cancel a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -19835,7 +19887,11 @@ Cancel a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -24723,7 +24779,9 @@ puts(beta_response) **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 @@ -25084,7 +25142,7 @@ Compact a response - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -25092,6 +25150,8 @@ Compact a response - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -25331,7 +25391,7 @@ Compact a response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -25339,6 +25399,8 @@ Compact a response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -26511,7 +26573,7 @@ Compact a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -26521,7 +26583,11 @@ Compact a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -26568,7 +26634,7 @@ Compact a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -26578,7 +26644,11 @@ Compact a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -28992,7 +29062,7 @@ Compact a response The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -29000,6 +29070,8 @@ Compact a response - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -30365,7 +30437,7 @@ Compact a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -30375,7 +30447,11 @@ Compact a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -30422,7 +30498,7 @@ Compact a response - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -30432,7 +30508,11 @@ Compact a response - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -32715,7 +32795,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -32723,6 +32803,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -34088,7 +34170,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -34098,7 +34180,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -34145,7 +34231,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -34155,7 +34241,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -36977,7 +37067,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -36985,6 +37075,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -37048,7 +37140,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -37058,7 +37150,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -37105,7 +37201,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -37115,7 +37211,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -37842,7 +37942,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -37850,6 +37950,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -38089,7 +38191,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -38097,6 +38199,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -39269,7 +39373,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -39279,7 +39383,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -39326,7 +39434,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -39336,7 +39444,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -44863,7 +44975,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -44871,6 +44983,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -45110,7 +45224,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -45118,6 +45232,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -46290,7 +46406,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -46300,7 +46416,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -46347,7 +46467,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -46357,7 +46477,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -52399,7 +52523,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -52407,6 +52531,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -52646,7 +52772,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -52654,6 +52780,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -53826,7 +53954,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -53836,7 +53964,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -53883,7 +54015,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -53893,7 +54025,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -59294,7 +59430,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -59302,6 +59438,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -59541,7 +59679,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -59549,6 +59687,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -60721,7 +60861,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -60731,7 +60871,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -60778,7 +60922,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -60788,7 +60932,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -67117,7 +67265,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -67125,6 +67273,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -67364,7 +67514,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -67372,6 +67522,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -68544,7 +68696,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -68554,7 +68706,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -68601,7 +68757,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -68611,7 +68767,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -73598,7 +73758,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -73606,6 +73766,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -73845,7 +74007,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -73853,6 +74015,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -75025,7 +75189,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -75035,7 +75199,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -75082,7 +75250,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -75092,7 +75260,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -79805,12 +79977,43 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Input +### Beta Response Inject Created Event -- `BetaResponseInput = Array[BetaResponseInputItem]` +- `class BetaResponseInjectCreatedEvent` - 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: Integer` + + The sequence number for this event. + + - `type: :"response.inject.created"` + + The event discriminator. Always `response.inject.created`. + + - `:"response.inject.created"` + + - `stream_id: String` + + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. + +### Beta Response Inject Event + +- `class BetaResponseInjectEvent` + + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. + + - `input: Array[BetaResponseInputItem]` + + Input items to inject into the active response. - `class BetaEasyInputMessage` @@ -79957,7 +80160,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -79965,6 +80168,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -80204,7 +80409,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -80212,6 +80417,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -81384,7 +81591,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -81394,7 +81601,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -81441,7 +81652,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -81451,7 +81662,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -83601,234 +83816,79 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Input Audio - -- `class BetaResponseInputAudio` - - An audio input to the model. - - - `input_audio: InputAudio{ data, format_}` - - - `data: String` - - Base64-encoded audio data. - - - `format_: :mp3 | :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`. - - - `:input_audio` - -### Beta Response Input Content - -- `BetaResponseInputContent = BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile` - - A text input to the model. - - - `class BetaResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` - - - `:original` - - - `type: :input_image` - - The type of the input item. Always `input_image`. - - - `:input_image` - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `image_url: String` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: String` - - The content of the file to be sent to the model. - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `file_url: String` - - The URL of the file to be sent to the model. - - - `filename: String` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - -### Beta Response Input File - -- `class BetaResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: 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: String` + The event discriminator. Always `response.inject`. - The ID of the file to be sent to the model. + - `:"response.inject"` - - `file_url: String` +### Beta Response Inject Failed Event - The URL of the file to be sent to the model. +- `class BetaResponseInjectFailedEvent` - - `filename: String` + 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. - The name of the file to be sent to the model. + - `error: Error{ code, message}` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + Information about why the input was not committed. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `code: :response_already_completed | :response_not_found` - - `mode: :explicit` + A machine-readable error code. - The breakpoint mode. Always `explicit`. + - `:response_already_completed` - - `:explicit` + - `:response_not_found` -### Beta Response Input File Content + - `message: String` -- `class BetaResponseInputFileContent` + A human-readable description of the error. - A file input to the model. + - `input: Array[BetaResponseInputItem]` - - `type: :input_file` + The raw input items that were not committed. - The type of the input item. Always `input_file`. + - `class BetaEasyInputMessage` - - `:input_file` + 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. - - `detail: :auto | :low | :high` + - `content: String | BetaResponseInputMessageContentList` - 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`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `:auto` + - `String = String` - - `:low` + A text input to the model. - - `:high` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - `file_data: String` + A list of one or many input items to the model, containing different content + types. - The base64-encoded data of the file to be sent to the model. + - `class BetaResponseInputText` - - `file_id: String` + A text input to the model. - The ID of the file to be sent to the model. + - `text: String` - - `file_url: String` + The text input to the model. - The URL of the file to be sent to the model. + - `type: :input_text` - - `filename: String` + The type of the input item. Always `input_text`. - The name of the file to be sent to the model. + - `:input_text` - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` @@ -83840,147 +83900,7 @@ puts(beta_compacted_response) - `:explicit` -### Beta Response Input Image - -- `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` - - - `:original` - - - `type: :input_image` - - The type of the input item. Always `input_image`. - - - `:input_image` - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `image_url: String` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - -### Beta Response Input Image Content - -- `class BetaResponseInputImageContent` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: :input_image` - - The type of the input item. Always `input_image`. - - - `:input_image` - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` - - - `:original` - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `image_url: String` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - -### Beta Response Input Item - -- `BetaResponseInputItem = BetaEasyInputMessage | Message{ content, role, agent, 2 more} | BetaResponseOutputMessage | 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. - - - `class BetaEasyInputMessage` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: String | BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `String = String` - - A text input to the model. - - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputImage` + - `class BetaResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -84079,7 +83999,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -84087,6 +84007,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -84326,7 +84248,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -84334,6 +84256,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -85506,7 +85430,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -85516,7 +85440,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -85563,7 +85491,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -85573,7 +85501,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -87723,132 +87655,50 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. -### Beta Response Input Message Content List - -- `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` - - - `:original` - - - `type: :input_image` - - The type of the input item. Always `input_image`. - - - `:input_image` - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `image_url: String` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: String` + The ID of the response that rejected the input. - The content of the file to be sent to the model. + - `sequence_number: Integer` - - `file_id: String` + The sequence number for this event. - The ID of the file to be sent to the model. + - `type: :"response.inject.failed"` - - `file_url: String` + The event discriminator. Always `response.inject.failed`. - The URL of the file to be sent to the model. + - `:"response.inject.failed"` - - `filename: String` + - `stream_id: String` - The name of the file to be sent to the model. + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` +### Beta Response Input - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. +- `BetaResponseInput = Array[BetaResponseInputItem]` - - `mode: :explicit` + A list of one or many input items to the model, containing + different content types. - The breakpoint mode. Always `explicit`. + - `class BetaEasyInputMessage` - - `: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 | BetaResponseInputMessageContentList` -- `class BetaResponseInputMessageItem` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `id: String` + - `String = String` - The unique ID of the message input. + A text input to the model. - - `content: BetaResponseInputMessageContentList` + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` A list of one or many input items to the model, containing different content types. @@ -87963,220 +87813,46 @@ puts(beta_compacted_response) - `:explicit` - - `role: :user | :system | :developer` + - `role: :user | :assistant | :system | :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`. - - - `:message` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `status: :in_progress | :completed | :incomplete` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - -### Beta Response Input Text - -- `class BetaResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - -### Beta Response Input Text Content - -- `class BetaResponseInputTextContent` - - A text input to the model. - - - `text: String` + - `phase: :commentary | :final_answer` - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + 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. - - `:explicit` + - `:commentary` -### Beta Response Item + - `:final_answer` -- `BetaResponseItem = BetaResponseInputMessageItem | BetaResponseOutputMessage | BetaResponseFileSearchToolCall | 29 more` + - `type: :message` - Content item used to generate a response. + The type of the message input. Always `message`. - - `class BetaResponseInputMessageItem` + - `:message` - - `id: String` + - `class Message` - 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: BetaResponseInputMessageContentList` A list of one or many input items to the model, containing different content types. - - `class BetaResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` - - - `:original` - - - `type: :input_image` - - The type of the input item. Always `input_image`. - - - `:input_image` - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `image_url: String` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: String` - - The content of the file to be sent to the model. - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `file_url: String` - - The URL of the file to be sent to the model. - - - `filename: String` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - `role: :user | :system | :developer` The role of the message input. One of `user`, `system`, or `developer`. @@ -88187,12 +87863,6 @@ puts(beta_compacted_response) - `:developer` - - `type: :message` - - The type of the message input. Always set to `message`. - - - `:message` - - `agent: Agent{ agent_name}` The agent that produced this item. @@ -88212,6 +87882,12 @@ puts(beta_compacted_response) - `:incomplete` + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + - `class BetaResponseOutputMessage` An output message from the model. @@ -88399,7 +88075,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -88407,6 +88083,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -88773,11 +88451,9 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseComputerToolCallOutputItem` - - - `id: String` + - `class ComputerCallOutput` - The unique ID of the computer call tool output. + The output of a computer tool call. - `call_id: String` @@ -88802,29 +88478,19 @@ puts(beta_compacted_response) The URL of the screenshot image. - - `status: :completed | :incomplete | :failed | :in_progress` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `:completed` - - - `:incomplete` - - - `:failed` - - - `:in_progress` - - `type: :computer_call_output` The type of the computer tool call output. Always `computer_call_output`. - `:computer_call_output` + - `id: String` + + The ID of the computer tool call output. + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` - The safety checks reported by the API that have been acknowledged by the - developer. + The safety checks reported by the API that have been acknowledged by the developer. - `id: String` @@ -88846,9 +88512,15 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `status: :in_progress | :completed | :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` - `class BetaResponseFunctionWebSearch` @@ -88954,15 +88626,65 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class BetaResponseFunctionToolCallItem` + - `class BetaResponseFunctionToolCall` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `arguments: String` + + A JSON string of the arguments to pass to the function. + + - `call_id: String` + + The unique ID of the function tool call generated by the model. + + - `name: String` + + The name of the function to run. + + - `type: :function_call` + + The type of the function tool call. Always `function_call`. + + - `:function_call` + - `id: String` The unique ID of the function tool call. + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the function to run. + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -88974,209 +88696,207 @@ puts(beta_compacted_response) - `:incomplete` - - `created_by: String` - - The identifier of the actor that created the item. - - - `class BetaResponseFunctionToolCallOutputItem` - - - `id: String` + - `class FunctionCallOutput` - 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 | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `output: String | 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 = String` - A string of the output of the function call. + A JSON string of the output of the function tool call. - - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` - Text, image, or file output of the function call. + An array of content outputs (text, image, file) for the function tool call. - - `class BetaResponseInputText` + - `class BetaResponseInputTextContent` A text input to the model. - - `class BetaResponseInputImage` + - `text: String` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The text input to the model. - - `class BetaResponseInputFile` + - `type: :input_text` - A file input to the model. + The type of the input item. Always `input_text`. - - `status: :in_progress | :completed | :incomplete` + - `:input_text` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `:in_progress` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:completed` + - `mode: :explicit` - - `:incomplete` + The breakpoint mode. Always `explicit`. - - `type: :function_call_output` + - `:explicit` - The type of the function tool call output. Always `function_call_output`. + - `class BetaResponseInputImageContent` - - `:function_call_output` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `agent: Agent{ agent_name}` + - `type: :input_image` - The agent that produced this item. + The type of the input item. Always `input_image`. - - `agent_name: String` + - `:input_image` - The canonical name of the agent that produced this item. + - `detail: :low | :high | :auto | :original` - - `caller_: Direct{ type} | Program{ caller_id, type}` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The execution context that produced this tool call. + - `:low` - - `class Direct` + - `:high` - - `type: :direct` + - `:auto` - The caller type. Always `direct`. + - `:original` - - `:direct` + - `file_id: String` - - `class Program` + The ID of the file to be sent to the model. - - `caller_id: String` + - `image_url: String` - The call ID of the program item that produced this tool call. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: :program` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - The caller type. Always `program`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `:program` + - `mode: :explicit` - - `created_by: String` + The breakpoint mode. Always `explicit`. - The identifier of the actor that created the item. + - `:explicit` - - `class AgentMessage` + - `class BetaResponseInputFileContent` - - `id: String` + A file input to the model. - The unique ID of the agent message. + - `type: :input_file` - - `author: String` + The type of the input item. Always `input_file`. - The sending agent identity. + - `:input_file` - - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + - `detail: :auto | :low | :high` - Encrypted content sent between agents. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `class BetaResponseInputText` + - `:auto` - A text input to the model. + - `:low` - - `class BetaResponseOutputText` + - `:high` - A text output from the model. + - `file_data: String` - - `class Text` + The base64-encoded data of the file to be sent to the model. - A text content. + - `file_id: String` - - `text: String` + The ID of the file to be sent to the model. - - `type: :text` + - `file_url: String` - - `:text` + The URL of the file to be sent to the model. - - `class SummaryText` + - `filename: String` - A summary text from the model. + The name of the file to be sent to the model. - - `text: String` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - A summary of the reasoning output from the model so far. + Marks the exact end of a reusable 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: :summary_text` + - `mode: :explicit` - The type of the object. Always `summary_text`. + The breakpoint mode. Always `explicit`. - - `:summary_text` + - `:explicit` - - `class ReasoningText` + - `type: :function_call_output` - Reasoning text from the model. + The type of the function tool call output. Always `function_call_output`. - - `text: String` + - `:function_call_output` - The reasoning text from the model. + - `id: String` - - `type: :reasoning_text` + The unique ID of the function tool call output. Populated when this item is returned via API. - The type of the reasoning text. Always `reasoning_text`. + - `agent: Agent{ agent_name}` - - `:reasoning_text` + The agent that produced this item. - - `class BetaResponseOutputRefusal` + - `agent_name: String` - A refusal from the model. + The canonical name of the agent that produced this item. - - `class BetaResponseInputImage` + - `caller_: Direct{ type} | Program{ caller_id, type}` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The execution context that produced this tool call. - - `class ComputerScreenshot` + - `class Direct` - A screenshot of a computer. + - `type: :direct` - - `detail: :low | :high | :auto | :original` + The caller type. Always `direct`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `:direct` - - `:low` + - `class Program` - - `:high` + - `caller_id: String` - - `:auto` + The call ID of the program item that produced this tool call. - - `:original` + - `type: :program` - - `file_id: String` + The caller type. Always `program`. - The identifier of an uploaded file that contains the screenshot. + - `:program` - - `image_url: String` + - `status: :in_progress | :completed | :incomplete` - The URL of the screenshot image. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `type: :computer_screenshot` + - `:in_progress` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `:completed` - - `:computer_screenshot` + - `:incomplete` - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + - `class AgentMessage` - Marks the exact end of a reusable 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 message routed between agents. - - `mode: :explicit` + - `author: String` - The breakpoint mode. Always `explicit`. + The sending agent identity. - - `:explicit` + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` - - `class BetaResponseInputFile` + Plaintext, image, or encrypted content sent between agents. - A file input to the model. + - `class BetaResponseInputTextContent` + + A text input to the model. + + - `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `class EncryptedContent` @@ -89198,10 +88918,14 @@ puts(beta_compacted_response) - `type: :agent_message` - The type of the item. Always `agent_message`. + The item type. Always `agent_message`. - `:agent_message` + - `id: String` + + The unique ID of this agent message item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -89212,13 +88936,9 @@ puts(beta_compacted_response) - `class MultiAgentCall` - - `id: String` - - The unique ID of the multi-agent call item. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` - The multi-agent action to execute. + The multi-agent action that was executed. - `:spawn_agent` @@ -89234,7 +88954,7 @@ puts(beta_compacted_response) - `arguments: String` - The JSON string of arguments generated for the action. + The action arguments as a JSON string. - `call_id: String` @@ -89242,10 +88962,14 @@ puts(beta_compacted_response) - `type: :multi_agent_call` - The type of the multi-agent call. Always `multi_agent_call`. + The item type. Always `multi_agent_call`. - `:multi_agent_call` + - `id: String` + + The unique ID of this multi-agent call. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -89256,10 +88980,6 @@ puts(beta_compacted_response) - `class MultiAgentCallOutput` - - `id: String` - - The unique ID of the multi-agent call output item. - - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` The multi-agent action that produced this result. @@ -89280,75 +89000,105 @@ puts(beta_compacted_response) The unique ID of the multi-agent call. - - `output: Array[BetaResponseOutputText]` + - `output: Array[Output{ text, type, annotations}]` Text output returned by the multi-agent action. - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - The annotations of the text output. - - `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: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + - `:output_text` - - `type: :multi_agent_call_output` + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - The type of the multi-agent result. Always `multi_agent_call_output`. + Citations associated with the text content. - - `:multi_agent_call_output` + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - - `agent: Agent{ 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. - - `class BetaResponseToolSearchCall` + - `index: Integer` - - `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: untyped` + The citation type. Always `file_citation`. - Arguments used for the tool search call. + - `:file_citation` - - `call_id: String` + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - The unique ID of the tool search call generated by the model. + - `end_index: Integer` - - `execution: :server | :client` + The index of the last character of the citation in the message. - Whether tool search was executed by the server or by the client. + - `start_index: Integer` - - `:server` + The index of the first character of the citation in the message. - - `:client` + - `title: String` - - `status: :in_progress | :completed | :incomplete` + The title of the cited resource. - The status of the tool search call item that was recorded. + - `type: :url_citation` - - `:in_progress` + The citation type. Always `url_citation`. - - `:completed` + - `:url_citation` - - `:incomplete` + - `url: String` - - `type: :tool_search_call` + The URL of the cited resource. - The type of the item. Always `tool_search_call`. + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - - `:tool_search_call` + - `container_id: String` + + The ID of the container. + + - `end_index: Integer` + + 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: Integer` + + The index of the first character of the citation in the message. + + - `type: :container_file_citation` + + The citation type. Always `container_file_citation`. + + - `:container_file_citation` + + - `type: :multi_agent_call_output` + + The item type. Always `multi_agent_call_output`. + + - `:multi_agent_call_output` + + - `id: String` + + The unique ID of this multi-agent call output. - `agent: Agent{ agent_name}` @@ -89358,15 +89108,29 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `class ToolSearchCall` - The identifier of the actor that created the item. + - `arguments: untyped` - - `class BetaResponseToolSearchOutputItem` + The arguments supplied to the tool search call. + + - `type: :tool_search_call` + + The item type. Always `tool_search_call`. + + - `:tool_search_call` - `id: String` - The unique ID of the tool search output item. + The unique ID of this tool search call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. - `call_id: String` @@ -89382,7 +89146,7 @@ puts(beta_compacted_response) - `status: :in_progress | :completed | :incomplete` - The status of the tool search output item that was recorded. + The status of the tool search call. - `:in_progress` @@ -89390,9 +89154,11 @@ puts(beta_compacted_response) - `:incomplete` + - `class BetaResponseToolSearchOutputItemParam` + - `tools: Array[BetaTool]` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool` @@ -89491,7 +89257,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -89501,7 +89267,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -89548,7 +89318,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -89558,7 +89328,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -90482,10 +90256,14 @@ puts(beta_compacted_response) - `type: :tool_search_output` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `:tool_search_output` + - `id: String` + + The unique ID of this tool search output. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -90494,39 +90272,39 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` + - `call_id: String` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `class AdditionalTools` + - `execution: :server | :client` - - `id: String` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `:server` - - `role: :unknown | :user | :assistant | 5 more` + - `:client` - The role that provided the additional tools. + - `status: :in_progress | :completed | :incomplete` - - `:unknown` + The status of the tool search output. - - `:user` + - `:in_progress` - - `:assistant` + - `:completed` - - `:system` + - `:incomplete` - - `:critic` + - `class AdditionalTools` - - `:discriminator` + - `role: :developer` - - `:developer` + The role that provided the additional tools. Only `developer` is supported. - - `:tool` + - `:developer` - `tools: Array[BetaTool]` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `class BetaFunctionTool` @@ -90594,10 +90372,14 @@ puts(beta_compacted_response) - `type: :additional_tools` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `:additional_tools` + - `id: String` + + The unique ID of this additional tools item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -90675,85 +90457,13 @@ puts(beta_compacted_response) - `:incomplete` - - `class Program` - - - `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`. - - - `:program` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class ProgramOutput` - - - `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 | :incomplete` - - The terminal status of the program output item. - - - `:completed` - - - `:incomplete` - - - `type: :program_output` - - The type of the item. Always `program_output`. - - - `:program_output` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `class BetaResponseCompactionItem` + - `class BetaResponseCompactionItemParam` 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` @@ -90761,6 +90471,10 @@ puts(beta_compacted_response) - `:compaction` + - `id: String` + + The ID of the compaction item. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -90769,10 +90483,6 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `created_by: String` - - The identifier of the actor that created the item. - - `class ImageGenerationCall` An image generation request made by the model. @@ -90990,13 +90700,9 @@ puts(beta_compacted_response) - `:incomplete` - - `class BetaResponseFunctionShellToolCall` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: String` + - `class ShellCall` - 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: Action{ commands, max_output_length, timeout_ms}` @@ -91004,60 +90710,30 @@ puts(beta_compacted_response) - `commands: Array[String]` + Ordered shell commands for the execution environment to run. + - `max_output_length: Integer` - Optional maximum number of characters to return from each command. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Integer` - Optional timeout in milliseconds for the commands. + 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 | BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `class BetaResponseLocalEnvironment` - - Represents the use of a local environment to perform shell actions. - - - `type: :local` - - The environment type. Always `local`. - - - `:local` - - - `class BetaResponseContainerReference` - - Represents a container created with /v1/containers. - - - `container_id: String` - - - `type: :container_reference` - - The environment type. Always `container_reference`. - - - `:container_reference` - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - `type: :shell_call` The type of the item. Always `shell_call`. - `:shell_call` + - `id: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -91074,6 +90750,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -91084,35 +90762,43 @@ puts(beta_compacted_response) - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `environment: BetaLocalEnvironment | BetaContainerReference` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `class BetaResponseFunctionShellToolCallOutput` + - `class BetaLocalEnvironment` - The output of a shell tool call that was emitted. + - `class BetaContainerReference` - - `id: String` + - `status: :in_progress | :completed | :incomplete` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `call_id: String` + - `:in_progress` - The unique ID of the shell tool call generated by the model. + - `:completed` - - `max_output_length: Integer` + - `:incomplete` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `class ShellCallOutput` - - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + The streamed output items emitted by a shell tool call. - An array of shell call output contents + - `call_id: String` + + The unique ID of the shell tool call generated by the model. + + - `output: Array[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: Timeout{ type} | Exit{ exit_code, type}` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `class Timeout` @@ -91130,7 +90816,7 @@ puts(beta_compacted_response) - `exit_code: Integer` - Exit code from the shell process. + The exit code returned by the shell process. - `type: :exit` @@ -91140,32 +90826,22 @@ puts(beta_compacted_response) - `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: String` - - The identifier of the actor that created the item. - - - `status: :in_progress | :completed | :incomplete` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `:in_progress` - - - `:completed` - - - `:incomplete` + Captured stdout output for the shell call. - `type: :shell_call_output` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `shell_call_output`. - `:shell_call_output` + - `id: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -91182,6 +90858,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -91192,19 +90870,27 @@ puts(beta_compacted_response) - `type: :program` + The caller type. Always `program`. + - `:program` - - `created_by: String` + - `max_output_length: Integer` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `class BetaResponseApplyPatchToolCall` + - `status: :in_progress | :completed | :incomplete` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `id: String` + - `:in_progress` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `:completed` + + - `:incomplete` + + - `class ApplyPatchCall` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: String` @@ -91212,55 +90898,55 @@ puts(beta_compacted_response) - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `class CreateFile` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `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`. - `:create_file` - `class DeleteFile` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `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`. - `:delete_file` - `class UpdateFile` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `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`. - `:update_file` @@ -91278,6 +90964,10 @@ puts(beta_compacted_response) - `:apply_patch_call` + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -91294,6 +90984,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -91304,19 +90996,13 @@ puts(beta_compacted_response) - `type: :program` - - `:program` - - - `created_by: String` - - The ID of the entity that created this tool call. - - - `class BetaResponseApplyPatchToolCallOutput` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `:program` - - `id: String` + - `class ApplyPatchCallOutput` - 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` @@ -91336,6 +91022,10 @@ puts(beta_compacted_response) - `:apply_patch_call_output` + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: Agent{ agent_name}` The agent that produced this item. @@ -91352,6 +91042,8 @@ puts(beta_compacted_response) - `type: :direct` + The caller type. Always `direct`. + - `:direct` - `class Program` @@ -91362,15 +91054,8226 @@ puts(beta_compacted_response) - `type: :program` - - `:program` - - - `created_by: String` + The caller type. Always `program`. - The ID of the entity that created this tool call output. + - `:program` - `output: String` - Optional textual output returned by the apply patch tool. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools` + + A list of tools available on an MCP server. + + - `id: String` + + The unique ID of the list. + + - `server_label: String` + + The label of the MCP server. + + - `tools: Array[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + A request for human approval of a tool invocation. + + - `id: String` + + The unique ID of the approval request. + + - `arguments: String` + + A JSON string of arguments for the tool. + + - `name: String` + + The name of the tool to run. + + - `server_label: String` + + The label of the MCP server making the request. + + - `type: :mcp_approval_request` + + The type of the item. Always `mcp_approval_request`. + + - `:mcp_approval_request` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + A response to an MCP approval request. + + - `approval_request_id: String` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. + + - `class McpCall` + + An invocation of a tool on an MCP server. + + - `id: String` + + The unique ID of the tool call. + + - `arguments: String` + + A JSON string of the arguments passed to the tool. + + - `name: String` + + The name of the tool that was run. + + - `server_label: String` + + The label of the MCP server running the tool. + + - `type: :mcp_call` + + The type of the item. Always `mcp_call`. + + - `:mcp_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_id: String` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` + + - `class BetaResponseCustomToolCallOutput` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: String` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the custom tool call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :custom_tool_call_output` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `:custom_tool_call_output` + + - `id: String` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class BetaResponseCustomToolCall` + + A call to a custom tool created by the model. + + - `call_id: String` + + An identifier used to map this custom tool call to a tool call output. + + - `input: String` + + The input for the custom tool call generated by the model. + + - `name: String` + + The name of the custom tool being called. + + - `type: :custom_tool_call` + + The type of the custom tool call. Always `custom_tool_call`. + + - `:custom_tool_call` + + - `id: String` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ItemReference` + + An internal identifier for an item to reference. + + - `id: String` + + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` + + - `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`. + + - `:program` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ 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 + +- `class BetaResponseInputAudio` + + An audio input to the model. + + - `input_audio: InputAudio{ data, format_}` + + - `data: String` + + Base64-encoded audio data. + + - `format_: :mp3 | :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`. + + - `:input_audio` + +### Beta Response Input Content + +- `BetaResponseInputContent = BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile` + + A text input to the model. + + - `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Input File + +- `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Input File Content + +- `class BetaResponseInputFileContent` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Input Image + +- `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Input Image Content + +- `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Input Item + +- `BetaResponseInputItem = BetaEasyInputMessage | Message{ content, role, agent, 2 more} | BetaResponseOutputMessage | 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. + + - `class BetaEasyInputMessage` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: String | BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String = String` + + A text input to the model. + + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `role: :user | :assistant | :system | :developer` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `:user` + + - `:assistant` + + - `:system` + + - `:developer` + + - `phase: :commentary | :final_answer` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `:commentary` + + - `:final_answer` + + - `type: :message` + + The type of the message input. Always `message`. + + - `:message` + + - `class Message` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `role: :user | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `id: String` + + The unique ID of the output message. + + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + + The content of the output message. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + The index of the first character of the URL citation in the message. + + - `title: String` + + The title of the web resource. + + - `type: :url_citation` + + The type of the URL citation. Always `url_citation`. + + - `:url_citation` + + - `url: String` + + The URL of the web resource. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + The index of the last character of the container file citation in the message. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the container file cited. + + - `start_index: Integer` + + The index of the first character of the container file citation in the message. + + - `type: :container_file_citation` + + The type of the container file citation. Always `container_file_citation`. + + - `:container_file_citation` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `:file_path` + + - `text: String` + + The text output from the model. + + - `type: :output_text` + + The type of the output text. Always `output_text`. + + - `:output_text` + + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `refusal: String` + + The refusal explanation from the model. + + - `type: :refusal` + + The type of the refusal. Always `refusal`. + + - `:refusal` + + - `role: :assistant` + + The role of the output message. Always `assistant`. + + - `:assistant` + + - `status: :in_progress | :completed | :incomplete` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the output message. Always `message`. + + - `:message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `phase: :commentary | :final_answer` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `:commentary` + + - `:final_answer` + + - `class BetaResponseFileSearchToolCall` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: String` + + The unique ID of the file search tool call. + + - `queries: Array[String]` + + The queries used to search for files. + + - `status: :in_progress | :searching | :completed | 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `:in_progress` + + - `:searching` + + - `:completed` + + - `:incomplete` + + - `:failed` + + - `type: :file_search_call` + + The type of the file search tool call. Always `file_search_call`. + + - `:file_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `file_id: String` + + The unique ID of the file. + + - `filename: String` + + The name of the file. + + - `score: Float` + + The relevance score of the file - a value between 0 and 1. + + - `text: String` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: String` + + The unique ID of the computer call. + + - `call_id: String` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :computer_call` + + The type of the computer call. Always `computer_call`. + + - `:computer_call` + + - `action: BetaComputerAction` + + A click action. + + - `class Click` + + A click action. + + - `button: :left | :right | :wheel | 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `:left` + + - `:right` + + - `:wheel` + + - `:back` + + - `:forward` + + - `type: :click` + + Specifies the event type. For a click action, this property is always `click`. + + - `:click` + + - `x: Integer` + + The x-coordinate where the click occurred. + + - `y_: Integer` + + The y-coordinate where the click occurred. + + - `keys: Array[String]` + + The keys being held while clicking. + + - `class DoubleClick` + + A double click action. + + - `keys: Array[String]` + + The keys being held while double-clicking. + + - `type: :double_click` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `:double_click` + + - `x: Integer` + + The x-coordinate where the double click occurred. + + - `y_: Integer` + + The y-coordinate where the double click occurred. + + - `class Drag` + + A drag action. + + - `path: Array[Path{ x, y_}]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: Integer` + + The x-coordinate. + + - `y_: Integer` + + The y-coordinate. + + - `type: :drag` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `:drag` + + - `keys: Array[String]` + + The keys being held while dragging the mouse. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `keys: Array[String]` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: :keypress` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `:keypress` + + - `class Move` + + A mouse move action. + + - `type: :move` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `:move` + + - `x: Integer` + + The x-coordinate to move to. + + - `y_: Integer` + + The y-coordinate to move to. + + - `keys: Array[String]` + + The keys being held while moving the mouse. + + - `class Screenshot` + + A screenshot action. + + - `type: :screenshot` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `:screenshot` + + - `class Scroll` + + A scroll action. + + - `scroll_x: Integer` + + The horizontal scroll distance. + + - `scroll_y: Integer` + + The vertical scroll distance. + + - `type: :scroll` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` + + The y-coordinate where the scroll occurred. + + - `keys: Array[String]` + + The keys being held while scrolling. + + - `class Type` + + An action to type in text. + + - `text: String` + + The text to type. + + - `type: :type` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `:type` + + - `class Wait` + + A wait action. + + - `type: :wait` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `:wait` + + - `actions: BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click` + + A click action. + + - `class DoubleClick` + + A double click action. + + - `class Drag` + + A drag action. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `class Move` + + A mouse move action. + + - `class Screenshot` + + A screenshot action. + + - `class Scroll` + + A scroll action. + + - `class Type` + + An action to type in text. + + - `class Wait` + + A wait action. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ComputerCallOutput` + + The output of a computer tool call. + + - `call_id: String` + + The ID of the computer tool call that produced the output. + + - `output: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: :computer_screenshot` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `:computer_screenshot` + + - `file_id: String` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: String` + + The URL of the screenshot image. + + - `type: :computer_call_output` + + The type of the computer tool call output. Always `computer_call_output`. + + - `:computer_call_output` + + - `id: String` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseFunctionWebSearch` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: String` + + The unique ID of the web search tool call. + + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `class Search` + + Action type "search" - Performs a web search query. + + - `type: :search` + + The action type. + + - `:search` + + - `queries: Array[String]` + + The search queries. + + - `query: String` + + The search query. + + - `sources: Array[Source{ type, url}]` + + The sources used in the search. + + - `type: :url` + + The type of source. Always `url`. + + - `:url` + + - `url: String` + + The URL of the source. + + - `class OpenPage` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: :open_page` + + The action type. + + - `:open_page` + + - `url: String` + + The URL opened by the model. + + - `class FindInPage` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: String` + + The pattern or text to search for within the page. + + - `type: :find_in_page` + + The action type. + + - `:find_in_page` + + - `url: String` + + The URL of the page searched for the pattern. + + - `status: :in_progress | :searching | :completed | :failed` + + The status of the web search tool call. + + - `:in_progress` + + - `:searching` + + - `:completed` + + - `:failed` + + - `type: :web_search_call` + + The type of the web search tool call. Always `web_search_call`. + + - `:web_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCall` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: String` + + A JSON string of the arguments to pass to the function. + + - `call_id: String` + + The unique ID of the function tool call generated by the model. + + - `name: String` + + The name of the function to run. + + - `type: :function_call` + + The type of the function tool call. Always `function_call`. + + - `:function_call` + + - `id: String` + + The unique ID of the function tool call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the function to run. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class FunctionCallOutput` + + The output of a function tool call. + + - `call_id: String` + + The unique ID of the function tool call generated by the model. + + - `output: String | BetaResponseFunctionCallOutputItemList` + + Text, image, or file output of the function tool call. + + - `String = String` + + A JSON string of the output of the function tool call. + + - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` + + An array of content outputs (text, image, file) for the function tool call. + + - `class BetaResponseInputTextContent` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFileContent` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `type: :function_call_output` + + The type of the function tool call output. Always `function_call_output`. + + - `:function_call_output` + + - `id: String` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class AgentMessage` + + A message routed between agents. + + - `author: String` + + The sending agent identity. + + - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` + + Plaintext, image, or encrypted content sent between agents. + + - `class BetaResponseInputTextContent` + + A text input to the model. + + - `class BetaResponseInputImageContent` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `class EncryptedContent` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: String` + + Opaque encrypted content. + + - `type: :encrypted_content` + + The type of the input item. Always `encrypted_content`. + + - `:encrypted_content` + + - `recipient: String` + + The destination agent identity. + + - `type: :agent_message` + + The item type. Always `agent_message`. + + - `:agent_message` + + - `id: String` + + The unique ID of this agent message item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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`. + + - `:multi_agent_call` + + - `id: String` + + The unique ID of this multi-agent call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput` + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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[Output{ 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`. + + - `:output_text` + + - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + Citations associated with the text content. + + - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The citation type. Always `file_citation`. + + - `:file_citation` + + - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` + + - `end_index: Integer` + + The index of the last character of the citation in the message. + + - `start_index: Integer` + + 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_citation` + + - `url: String` + + The URL of the cited resource. + + - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` + + - `container_id: String` + + The ID of the container. + + - `end_index: Integer` + + 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: Integer` + + The index of the first character of the citation in the message. + + - `type: :container_file_citation` + + The citation type. Always `container_file_citation`. + + - `:container_file_citation` + + - `type: :multi_agent_call_output` + + The item type. Always `multi_agent_call_output`. + + - `:multi_agent_call_output` + + - `id: String` + + The unique ID of this multi-agent call output. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ToolSearchCall` + + - `arguments: untyped` + + The arguments supplied to the tool search call. + + - `type: :tool_search_call` + + The item type. Always `tool_search_call`. + + - `:tool_search_call` + + - `id: String` + + The unique ID of this tool search call. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search call. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseToolSearchOutputItemParam` + + - `tools: Array[BetaTool]` + + The loaded tool definitions returned by the tool search output. + + - `class BetaFunctionTool` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: String` + + The name of the function to call. + + - `parameters: Hash[Symbol, untyped]` + + A JSON schema object describing the parameters of the function. + + - `strict: bool` + + Whether strict parameter validation is enforced for this function tool. + + - `type: :function` + + The type of the function tool. Always `function`. + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function is deferred and loaded via tool search. + + - `description: String` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: :file_search` + + The type of the file search tool. Always `file_search`. + + - `:file_search` + + - `vector_store_ids: Array[String]` + + The IDs of the vector stores to search. + + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + + A filter to apply. + + - `class ComparisonFilter` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: String` + + The key to compare against the value. + + - `type: :eq | :ne | :gt | 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `:eq` + + - `:ne` + + - `:gt` + + - `:gte` + + - `:lt` + + - `:lte` + + - `:in` + + - `:nin` + + - `value: String | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `class CompoundFilter` + + Combine multiple filters using `and` or `or`. + + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class ComparisonFilter` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: String` + + The key to compare against the value. + + - `type: :eq | :ne | :gt | 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `:eq` + + - `:ne` + + - `:gt` + + - `:gte` + + - `:lt` + + - `:lte` + + - `:in` + + - `:nin` + + - `value: String | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `UnionMember1 = untyped` + + - `type: :and | :or` + + Type of operation: `and` or `or`. + + - `:and` + + - `:or` + + - `max_num_results: Integer` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + + Ranking options for search. + + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: Float` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: Float` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: :auto | :"default-2024-11-15"` + + The ranker to use for the file search. + + - `:auto` + + - `:"default-2024-11-15"` + + - `score_threshold: Float` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: :computer` + + The type of the computer tool. Always `computer`. + + - `:computer` + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: Integer` + + The height of the computer display. + + - `display_width: Integer` + + The width of the computer display. + + - `environment: :windows | :mac | :linux | 2 more` + + The type of computer environment to control. + + - `:windows` + + - `:mac` + + - `:linux` + + - `:ubuntu` + + - `:browser` + + - `type: :computer_use_preview` + + The type of the computer use tool. Always `computer_use_preview`. + + - `:computer_use_preview` + + - `class BetaWebSearchTool` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: :web_search | :web_search_2025_08_26` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `:web_search` + + - `:web_search_2025_08_26` + + - `filters: Filters{ allowed_domains}` + + Filters for the search. + + - `allowed_domains: Array[String]` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: :low | :medium | :high` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `:low` + + - `:medium` + + - `:high` + + - `user_location: UserLocation{ city, country, region, 2 more}` + + The approximate location of the user. + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `class Mcp` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: String` + + A label for this MCP server, used to identify it in tool calls. + + - `type: :mcp` + + The type of the MCP tool. Always `mcp`. + + - `:mcp` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = Array[String]` + + A string array of allowed tool names + + - `class McpToolFilter` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Array[String]` + + List of allowed tool names. + + - `authorization: String` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `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: bool` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: Hash[Symbol, String]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + + Specify which of the MCP server's tools require approval. + + - `class McpToolApprovalFilter` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: Always{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Array[String]` + + List of allowed tool names. + + - `never: Never{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Array[String]` + + List of allowed tool names. + + - `McpToolApprovalSetting = :always | :never` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `:always` + + - `:never` + + - `server_description: String` + + Optional description of the MCP server, used to provide more context. + + - `server_url: String` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: String` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `String = String` + + The container ID. + + - `class CodeInterpreterToolAuto` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: :auto` + + Always `auto`. + + - `:auto` + + - `file_ids: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the code interpreter container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `type: :disabled` + + Disable outbound network access. Always `disabled`. + + - `:disabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `allowed_domains: Array[String]` + + A list of allowed domains when type is `allowlist`. + + - `type: :allowlist` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `:allowlist` + + - `domain_secrets: Array[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`. + + - `:code_interpreter` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `type: :image_generation` + + The type of the image generation tool. Always `image_generation`. + + - `:image_generation` + + - `action: :generate | :edit | :auto` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `:generate` + + - `:edit` + + - `:auto` + + - `background: :transparent | :opaque | :auto` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `:transparent` + + - `:opaque` + + - `:auto` + + - `input_fidelity: :high | :low` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `:high` + + - `:low` + + - `input_image_mask: InputImageMask{ file_id, image_url}` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: String` + + File ID for the mask image. + + - `image_url: String` + + Base64-encoded mask image. + + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `String = String` + + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `:"gpt-image-1"` + + - `:"gpt-image-1-mini"` + + - `:"gpt-image-2"` + + - `:"gpt-image-2-2026-04-21"` + + - `:"gpt-image-1.5"` + + - `:"chatgpt-image-latest"` + + - `moderation: :auto | :low` + + Moderation level for the generated image. Default: `auto`. + + - `:auto` + + - `:low` + + - `output_compression: Integer` + + Compression level for the output image. Default: 100. + + - `output_format: :png | :webp | :jpeg` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `:png` + + - `:webp` + + - `:jpeg` + + - `partial_images: Integer` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: :low | :medium | :high | :auto` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `:low` + + - `:medium` + + - `:high` + + - `:auto` + + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `String = String` + + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `:"1024x1024"` + + - `:"1024x1536"` + + - `:"1536x1024"` + + - `:auto` + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: :local_shell` + + The type of the local shell tool. Always `local_shell`. + + - `:local_shell` + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `type: :shell` + + The type of the shell tool. Always `shell`. + + - `:shell` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + + - `class BetaContainerAuto` + + - `type: :container_auto` + + Automatically creates a container for this request + + - `:container_auto` + + - `file_ids: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `skills: Array[BetaSkillReference | BetaInlineSkill]` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference` + + - `skill_id: String` + + The ID of the referenced skill. + + - `type: :skill_reference` + + References a skill created with the /v1/skills endpoint. + + - `:skill_reference` + + - `version: String` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill` + + - `description: String` + + The description of the skill. + + - `name: String` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + Inline skill payload + + - `data: String` + + Base64-encoded skill zip bundle. + + - `media_type: :"application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `:"application/zip"` + + - `type: :base64` + + The type of the inline skill source. Must be `base64`. + + - `:base64` + + - `type: :inline` + + Defines an inline skill for this request. + + - `:inline` + + - `class BetaLocalEnvironment` + + - `type: :local` + + Use a local computer environment. + + - `:local` + + - `skills: Array[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. + + - `class BetaContainerReference` + + - `container_id: String` + + The ID of the referenced container. + + - `type: :container_reference` + + References a container created with the /v1/containers endpoint + + - `:container_reference` + + - `class BetaCustomTool` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: String` + + The name of the custom tool, used to identify it in tool calls. + + - `type: :custom` + + The type of the custom tool. Always `custom`. + + - `:custom` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this tool should be deferred and discovered via tool search. + + - `description: String` + + Optional description of the custom tool, used to provide more context. + + - `format_: Text{ type} | Grammar{ definition, syntax, type}` + + The input format for the custom tool. Default is unconstrained text. + + - `class Text` + + Unconstrained free-form text. + + - `type: :text` + + Unconstrained text format. Always `text`. + + - `:text` + + - `class Grammar` + + A grammar defined by the user. + + - `definition: String` + + The grammar definition. + + - `syntax: :lark | :regex` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `:lark` + + - `:regex` + + - `type: :grammar` + + Grammar format. Always `grammar`. + + - `:grammar` + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `description: String` + + A description of the namespace shown to the model. + + - `name: String` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + + The function/custom tools available inside this namespace. + + - `class Function` + + - `name: String` + + - `type: :function` + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function should be deferred and discovered via tool search. + + - `description: String` + + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: untyped` + + - `strict: bool` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `type: :namespace` + + The type of the tool. Always `namespace`. + + - `:namespace` + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: :tool_search` + + The type of the tool. Always `tool_search`. + + - `:tool_search` + + - `description: String` + + Description shown to the model for a client-executed tool search tool. + + - `execution: :server | :client` + + Whether tool search is executed by the server or by the client. + + - `:server` + + - `:client` + + - `parameters: untyped` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: :web_search_preview | :web_search_preview_2025_03_11` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `:web_search_preview` + + - `:web_search_preview_2025_03_11` + + - `search_content_types: Array[:text | :image]` + + - `:text` + + - `:image` + + - `search_context_size: :low | :medium | :high` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `:low` + + - `:medium` + + - `:high` + + - `user_location: UserLocation{ type, city, country, 2 more}` + + The user's location. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :apply_patch` + + The type of the tool. Always `apply_patch`. + + - `:apply_patch` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `type: :tool_search_output` + + The item type. Always `tool_search_output`. + + - `:tool_search_output` + + - `id: String` + + The unique ID of this tool search output. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class AdditionalTools` + + - `role: :developer` + + The role that provided the additional tools. Only `developer` is supported. + + - `:developer` + + - `tools: Array[BetaTool]` + + A list of additional tools made available at this item. + + - `class BetaFunctionTool` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :additional_tools` + + The item type. Always `additional_tools`. + + - `:additional_tools` + + - `id: String` + + The unique ID of this additional tools item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: String` + + The unique identifier of the reasoning content. + + - `summary: Array[Summary{ text, type}]` + + Reasoning summary content. + + - `text: String` + + A summary of the reasoning output from the model so far. + + - `type: :summary_text` + + The type of the object. Always `summary_text`. + + - `:summary_text` + + - `type: :reasoning` + + The type of the object. Always `reasoning`. + + - `:reasoning` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `content: Array[Content{ text, type}]` + + Reasoning text content. + + - `text: String` + + The reasoning text from the model. + + - `type: :reasoning_text` + + The type of the reasoning text. Always `reasoning_text`. + + - `:reasoning_text` + + - `encrypted_content: String` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseCompactionItemParam` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: String` + + The encrypted content of the compaction summary. + + - `type: :compaction` + + The type of the item. Always `compaction`. + + - `:compaction` + + - `id: String` + + The ID of the compaction item. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ImageGenerationCall` + + An image generation request made by the model. + + - `id: String` + + The unique ID of the image generation call. + + - `result: String` + + The generated image encoded in base64. + + - `status: :in_progress | :completed | :generating | :failed` + + The status of the image generation call. + + - `:in_progress` + + - `:completed` + + - `:generating` + + - `:failed` + + - `type: :image_generation_call` + + The type of the image generation call. Always `image_generation_call`. + + - `:image_generation_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall` + + A tool call to run code. + + - `id: String` + + The unique ID of the code interpreter tool call. + + - `code: String` + + The code to run, or null if not available. + + - `container_id: String` + + The ID of the container used to run the code. + + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class Logs` + + The logs output from the code interpreter. + + - `logs: String` + + The logs output from the code interpreter. + + - `type: :logs` + + The type of the output. Always `logs`. + + - `:logs` + + - `class Image` + + The image output from the code interpreter. + + - `type: :image` + + The type of the output. Always `image`. + + - `:image` + + - `url: String` + + The URL of the image output from the code interpreter. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:interpreting` + + - `:failed` + + - `type: :code_interpreter_call` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `:code_interpreter_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCall` + + A tool call to run a command on the local shell. + + - `id: String` + + The unique ID of the local shell call. + + - `action: Action{ command, env, type, 3 more}` + + Execute a shell command on the server. + + - `command: Array[String]` + + The command to run. + + - `env: Hash[Symbol, String]` + + Environment variables to set for the command. + + - `type: :exec` + + The type of the local shell action. Always `exec`. + + - `:exec` + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the command. + + - `user: String` + + Optional user to run the command as. + + - `working_directory: String` + + Optional working directory to run the command in. + + - `call_id: String` + + The unique ID of the local shell tool call generated by the model. + + - `status: :in_progress | :completed | :incomplete` + + The status of the local shell call. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :local_shell_call` + + The type of the local shell call. Always `local_shell_call`. + + - `:local_shell_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput` + + The output of a local shell tool call. + + - `id: String` + + The unique ID of the local shell tool call generated by the model. + + - `output: String` + + A JSON string of the output of the local shell tool call. + + - `type: :local_shell_call_output` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `:local_shell_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ShellCall` + + A tool representing a request to execute one or more shell commands. + + - `action: Action{ commands, max_output_length, timeout_ms}` + + The shell commands and limits that describe how to run the tool call. + + - `commands: Array[String]` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: Integer` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: Integer` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: String` + + The unique ID of the shell tool call generated by the model. + + - `type: :shell_call` + + The type of the item. Always `shell_call`. + + - `:shell_call` + + - `id: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `environment: BetaLocalEnvironment | BetaContainerReference` + + The environment to execute the shell commands in. + + - `class BetaLocalEnvironment` + + - `class BetaContainerReference` + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ShellCallOutput` + + The streamed output items emitted by a shell tool call. + + - `call_id: String` + + The unique ID of the shell tool call generated by the model. + + - `output: Array[BetaResponseFunctionShellCallOutputContent]` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: Timeout{ type} | Exit{ exit_code, type}` + + The exit or timeout outcome associated with this shell call. + + - `class Timeout` + + Indicates that the shell call exceeded its configured time limit. + + - `type: :timeout` + + The outcome type. Always `timeout`. + + - `:timeout` + + - `class Exit` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: Integer` + + The exit code returned by the shell process. + + - `type: :exit` + + The outcome type. Always `exit`. + + - `:exit` + + - `stderr: String` + + Captured stderr output for the shell call. + + - `stdout: String` + + Captured stdout output for the shell call. + + - `type: :shell_call_output` + + The type of the item. Always `shell_call_output`. + + - `:shell_call_output` + + - `id: String` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `max_output_length: Integer` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call output. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class ApplyPatchCall` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: String` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `class CreateFile` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: String` + + Unified diff content to apply when creating the file. + + - `path: String` + + Path of the file to create relative to the workspace root. + + - `type: :create_file` + + The operation type. Always `create_file`. + + - `:create_file` + + - `class DeleteFile` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: String` + + Path of the file to delete relative to the workspace root. + + - `type: :delete_file` + + The operation type. Always `delete_file`. + + - `:delete_file` + + - `class UpdateFile` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: String` + + Unified diff content to apply to the existing file. + + - `path: String` + + Path of the file to update relative to the workspace root. + + - `type: :update_file` + + The operation type. Always `update_file`. + + - `:update_file` + + - `status: :in_progress | :completed` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `:in_progress` + + - `:completed` + + - `type: :apply_patch_call` + + The type of the item. Always `apply_patch_call`. + + - `:apply_patch_call` + + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class ApplyPatchCallOutput` + + The streamed output emitted by an apply patch tool call. + + - `call_id: String` + + The unique ID of the apply patch tool call generated by the model. + + - `status: :completed | :failed` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `:completed` + + - `:failed` + + - `type: :apply_patch_call_output` + + The type of the item. Always `apply_patch_call_output`. + + - `:apply_patch_call_output` + + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `output: String` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `class McpListTools` + + A list of tools available on an MCP server. + + - `id: String` + + The unique ID of the list. + + - `server_label: String` + + The label of the MCP server. + + - `tools: Array[Tool{ input_schema, name, annotations, description}]` + + The tools available on the server. + + - `input_schema: untyped` + + The JSON schema describing the tool's input. + + - `name: String` + + The name of the tool. + + - `annotations: untyped` + + Additional annotations about the tool. + + - `description: String` + + The description of the tool. + + - `type: :mcp_list_tools` + + The type of the item. Always `mcp_list_tools`. + + - `:mcp_list_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `error: String` + + Error message if the server could not list tools. + + - `class McpApprovalRequest` + + A request for human approval of a tool invocation. + + - `id: String` + + The unique ID of the approval request. + + - `arguments: String` + + A JSON string of arguments for the tool. + + - `name: String` + + The name of the tool to run. + + - `server_label: String` + + The label of the MCP server making the request. + + - `type: :mcp_approval_request` + + The type of the item. Always `mcp_approval_request`. + + - `:mcp_approval_request` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class McpApprovalResponse` + + A response to an MCP approval request. + + - `approval_request_id: String` + + The ID of the approval request being answered. + + - `approve: bool` + + Whether the request was approved. + + - `type: :mcp_approval_response` + + The type of the item. Always `mcp_approval_response`. + + - `:mcp_approval_response` + + - `id: String` + + The unique ID of the approval response + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `reason: String` + + Optional reason for the decision. + + - `class McpCall` + + An invocation of a tool on an MCP server. + + - `id: String` + + The unique ID of the tool call. + + - `arguments: String` + + A JSON string of the arguments passed to the tool. + + - `name: String` + + The name of the tool that was run. + + - `server_label: String` + + The label of the MCP server running the tool. + + - `type: :mcp_call` + + The type of the item. Always `mcp_call`. + + - `:mcp_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `approval_request_id: String` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: String` + + The error from the tool call, if any. + + - `output: String` + + The output from the tool call. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:calling` + + - `:failed` + + - `class BetaResponseCustomToolCallOutput` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: String` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the custom tool call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the custom tool call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :custom_tool_call_output` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `:custom_tool_call_output` + + - `id: String` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `class BetaResponseCustomToolCall` + + A call to a custom tool created by the model. + + - `call_id: String` + + An identifier used to map this custom tool call to a tool call output. + + - `input: String` + + The input for the custom tool call generated by the model. + + - `name: String` + + The name of the custom tool being called. + + - `type: :custom_tool_call` + + The type of the custom tool call. Always `custom_tool_call`. + + - `:custom_tool_call` + + - `id: String` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `namespace: String` + + The namespace of the custom tool being called. + + - `class CompactionTrigger` + + Compacts the current context. Must be the final input item. + + - `type: :compaction_trigger` + + The type of the item. Always `compaction_trigger`. + + - `:compaction_trigger` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ItemReference` + + An internal identifier for an item to reference. + + - `id: String` + + The ID of the item to reference. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `type: :item_reference` + + The type of item to reference. Always `item_reference`. + + - `:item_reference` + + - `class Program` + + - `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`. + + - `:program` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ 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 + +- `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Input Message Item + +- `class BetaResponseInputMessageItem` + + - `id: String` + + The unique ID of the message input. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `role: :user | :system | :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`. + + - `:message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + +### Beta Response Input Text + +- `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Input Text Content + +- `class BetaResponseInputTextContent` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + +### Beta Response Item + +- `BetaResponseItem = BetaResponseInputMessageItem | BetaResponseOutputMessage | BetaResponseFileSearchToolCall | 29 more` + + Content item used to generate a response. + + - `class BetaResponseInputMessageItem` + + - `id: String` + + The unique ID of the message input. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `role: :user | :system | :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`. + + - `:message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `id: String` + + The unique ID of the output message. + + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + + The content of the output message. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + The index of the first character of the URL citation in the message. + + - `title: String` + + The title of the web resource. + + - `type: :url_citation` + + The type of the URL citation. Always `url_citation`. + + - `:url_citation` + + - `url: String` + + The URL of the web resource. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + The index of the last character of the container file citation in the message. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the container file cited. + + - `start_index: Integer` + + The index of the first character of the container file citation in the message. + + - `type: :container_file_citation` + + The type of the container file citation. Always `container_file_citation`. + + - `:container_file_citation` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `:file_path` + + - `text: String` + + The text output from the model. + + - `type: :output_text` + + The type of the output text. Always `output_text`. + + - `:output_text` + + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `refusal: String` + + The refusal explanation from the model. + + - `type: :refusal` + + The type of the refusal. Always `refusal`. + + - `:refusal` + + - `role: :assistant` + + The role of the output message. Always `assistant`. + + - `:assistant` + + - `status: :in_progress | :completed | :incomplete` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the output message. Always `message`. + + - `:message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `phase: :commentary | :final_answer` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `:commentary` + + - `:final_answer` + + - `class BetaResponseFileSearchToolCall` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: String` + + The unique ID of the file search tool call. + + - `queries: Array[String]` + + The queries used to search for files. + + - `status: :in_progress | :searching | :completed | 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `:in_progress` + + - `:searching` + + - `:completed` + + - `:incomplete` + + - `:failed` + + - `type: :file_search_call` + + The type of the file search tool call. Always `file_search_call`. + + - `:file_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `results: Array[Result{ attributes, file_id, filename, 2 more}]` + + The results of the file search tool call. + + - `attributes: Hash[Symbol, String | Float | bool]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `file_id: String` + + The unique ID of the file. + + - `filename: String` + + The name of the file. + + - `score: Float` + + The relevance score of the file - a value between 0 and 1. + + - `text: String` + + The text that was retrieved from the file. + + - `class BetaResponseComputerToolCall` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: String` + + The unique ID of the computer call. + + - `call_id: String` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]` + + The pending safety checks for the computer call. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :computer_call` + + The type of the computer call. Always `computer_call`. + + - `:computer_call` + + - `action: BetaComputerAction` + + A click action. + + - `class Click` + + A click action. + + - `button: :left | :right | :wheel | 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `:left` + + - `:right` + + - `:wheel` + + - `:back` + + - `:forward` + + - `type: :click` + + Specifies the event type. For a click action, this property is always `click`. + + - `:click` + + - `x: Integer` + + The x-coordinate where the click occurred. + + - `y_: Integer` + + The y-coordinate where the click occurred. + + - `keys: Array[String]` + + The keys being held while clicking. + + - `class DoubleClick` + + A double click action. + + - `keys: Array[String]` + + The keys being held while double-clicking. + + - `type: :double_click` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `:double_click` + + - `x: Integer` + + The x-coordinate where the double click occurred. + + - `y_: Integer` + + The y-coordinate where the double click occurred. + + - `class Drag` + + A drag action. + + - `path: Array[Path{ x, y_}]` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: Integer` + + The x-coordinate. + + - `y_: Integer` + + The y-coordinate. + + - `type: :drag` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `:drag` + + - `keys: Array[String]` + + The keys being held while dragging the mouse. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `keys: Array[String]` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: :keypress` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `:keypress` + + - `class Move` + + A mouse move action. + + - `type: :move` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `:move` + + - `x: Integer` + + The x-coordinate to move to. + + - `y_: Integer` + + The y-coordinate to move to. + + - `keys: Array[String]` + + The keys being held while moving the mouse. + + - `class Screenshot` + + A screenshot action. + + - `type: :screenshot` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `:screenshot` + + - `class Scroll` + + A scroll action. + + - `scroll_x: Integer` + + The horizontal scroll distance. + + - `scroll_y: Integer` + + The vertical scroll distance. + + - `type: :scroll` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `:scroll` + + - `x: Integer` + + The x-coordinate where the scroll occurred. + + - `y_: Integer` + + The y-coordinate where the scroll occurred. + + - `keys: Array[String]` + + The keys being held while scrolling. + + - `class Type` + + An action to type in text. + + - `text: String` + + The text to type. + + - `type: :type` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `:type` + + - `class Wait` + + A wait action. + + - `type: :wait` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `:wait` + + - `actions: BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `class Click` + + A click action. + + - `class DoubleClick` + + A double click action. + + - `class Drag` + + A drag action. + + - `class Keypress` + + A collection of keypresses the model would like to perform. + + - `class Move` + + A mouse move action. + + - `class Screenshot` + + A screenshot action. + + - `class Scroll` + + A scroll action. + + - `class Type` + + An action to type in text. + + - `class Wait` + + A wait action. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseComputerToolCallOutputItem` + + - `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: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: :computer_screenshot` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `:computer_screenshot` + + - `file_id: String` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: String` + + The URL of the screenshot image. + + - `status: :completed | :incomplete | :failed | :in_progress` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `:completed` + + - `:incomplete` + + - `:failed` + + - `:in_progress` + + - `type: :computer_call_output` + + The type of the computer tool call output. Always `computer_call_output`. + + - `:computer_call_output` + + - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: String` + + The ID of the pending safety check. + + - `code: String` + + The type of the pending safety check. + + - `message: String` + + Details about the pending safety check. + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseFunctionWebSearch` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: String` + + The unique ID of the web search tool call. + + - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `class Search` + + Action type "search" - Performs a web search query. + + - `type: :search` + + The action type. + + - `:search` + + - `queries: Array[String]` + + The search queries. + + - `query: String` + + The search query. + + - `sources: Array[Source{ type, url}]` + + The sources used in the search. + + - `type: :url` + + The type of source. Always `url`. + + - `:url` + + - `url: String` + + The URL of the source. + + - `class OpenPage` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: :open_page` + + The action type. + + - `:open_page` + + - `url: String` + + The URL opened by the model. + + - `class FindInPage` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: String` + + The pattern or text to search for within the page. + + - `type: :find_in_page` + + The action type. + + - `:find_in_page` + + - `url: String` + + The URL of the page searched for the pattern. + + - `status: :in_progress | :searching | :completed | :failed` + + The status of the web search tool call. + + - `:in_progress` + + - `:searching` + + - `:completed` + + - `:failed` + + - `type: :web_search_call` + + The type of the web search tool call. Always `web_search_call`. + + - `:web_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseFunctionToolCallItem` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `id: String` + + The unique ID of the function tool call. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseFunctionToolCallOutputItem` + + - `id: String` + + The unique ID of the function call tool output. + + - `call_id: String` + + The unique ID of the function tool call generated by the model. + + - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `String = String` + + A string of the output of the function call. + + - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` + + Text, image, or file output of the function call. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class BetaResponseInputFile` + + A file input to the model. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :function_call_output` + + The type of the function tool call output. Always `function_call_output`. + + - `:function_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class AgentMessage` + + - `id: String` + + The unique ID of the agent message. + + - `author: String` + + The sending agent identity. + + - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` + + Encrypted content sent between agents. + + - `class BetaResponseInputText` + + A text input to the model. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `class Text` + + A text content. + + - `text: String` + + - `type: :text` + + - `:text` + + - `class SummaryText` + + A summary text from the model. + + - `text: String` + + A summary of the reasoning output from the model so far. + + - `type: :summary_text` + + The type of the object. Always `summary_text`. + + - `:summary_text` + + - `class ReasoningText` + + Reasoning text from the model. + + - `text: String` + + The reasoning text from the model. + + - `type: :reasoning_text` + + The type of the reasoning text. Always `reasoning_text`. + + - `:reasoning_text` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `class ComputerScreenshot` + + A screenshot of a computer. + + - `detail: :low | :high | :auto | :original` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `file_id: String` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: String` + + The URL of the screenshot image. + + - `type: :computer_screenshot` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `:computer_screenshot` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `class EncryptedContent` + + 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`. + + - `:encrypted_content` + + - `recipient: String` + + The destination agent identity. + + - `type: :agent_message` + + The type of the item. Always `agent_message`. + + - `:agent_message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCall` + + - `id: String` + + The unique ID of the multi-agent call item. + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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`. + + - `:multi_agent_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class MultiAgentCallOutput` + + - `id: String` + + The unique ID of the multi-agent call output item. + + - `action: :spawn_agent | :interrupt_agent | :list_agents | 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[BetaResponseOutputText]` + + Text output returned by the multi-agent action. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `text: String` + + The text output from the model. + + - `type: :output_text` + + The type of the output text. Always `output_text`. + + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `type: :multi_agent_call_output` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `:multi_agent_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseToolSearchCall` + + - `id: String` + + The unique ID of the tool search call item. + + - `arguments: untyped` + + Arguments used for the tool search call. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search call item that was recorded. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :tool_search_call` + + The type of the item. Always `tool_search_call`. + + - `:tool_search_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseToolSearchOutputItem` + + - `id: String` + + The unique ID of the tool search output item. + + - `call_id: String` + + The unique ID of the tool search call generated by the model. + + - `execution: :server | :client` + + Whether tool search was executed by the server or by the client. + + - `:server` + + - `:client` + + - `status: :in_progress | :completed | :incomplete` + + The status of the tool search output item that was recorded. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `tools: Array[BetaTool]` + + The loaded tool definitions returned by tool search. + + - `class BetaFunctionTool` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: String` + + The name of the function to call. + + - `parameters: Hash[Symbol, untyped]` + + A JSON schema object describing the parameters of the function. + + - `strict: bool` + + Whether strict parameter validation is enforced for this function tool. + + - `type: :function` + + The type of the function tool. Always `function`. + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function is deferred and loaded via tool search. + + - `description: String` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `class BetaFileSearchTool` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: :file_search` + + The type of the file search tool. Always `file_search`. + + - `:file_search` + + - `vector_store_ids: Array[String]` + + The IDs of the vector stores to search. + + - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` + + A filter to apply. + + - `class ComparisonFilter` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: String` + + The key to compare against the value. + + - `type: :eq | :ne | :gt | 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `:eq` + + - `:ne` + + - `:gt` + + - `:gte` + + - `:lt` + + - `:lte` + + - `:in` + + - `:nin` + + - `value: String | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `class CompoundFilter` + + Combine multiple filters using `and` or `or`. + + - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `class ComparisonFilter` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: String` + + The key to compare against the value. + + - `type: :eq | :ne | :gt | 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `:eq` + + - `:ne` + + - `:gt` + + - `:gte` + + - `:lt` + + - `:lte` + + - `:in` + + - `:nin` + + - `value: String | Float | bool | Array[String | Float]` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `String = String` + + - `Float = Float` + + - `UnionMember2 = bool` + + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` + + - `UnionMember1 = untyped` + + - `type: :and | :or` + + Type of operation: `and` or `or`. + + - `:and` + + - `:or` + + - `max_num_results: Integer` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}` + + Ranking options for search. + + - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: Float` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: Float` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: :auto | :"default-2024-11-15"` + + The ranker to use for the file search. + + - `:auto` + + - `:"default-2024-11-15"` + + - `score_threshold: Float` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: :computer` + + The type of the computer tool. Always `computer`. + + - `:computer` + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: Integer` + + The height of the computer display. + + - `display_width: Integer` + + The width of the computer display. + + - `environment: :windows | :mac | :linux | 2 more` + + The type of computer environment to control. + + - `:windows` + + - `:mac` + + - `:linux` + + - `:ubuntu` + + - `:browser` + + - `type: :computer_use_preview` + + The type of the computer use tool. Always `computer_use_preview`. + + - `:computer_use_preview` + + - `class BetaWebSearchTool` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: :web_search | :web_search_2025_08_26` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `:web_search` + + - `:web_search_2025_08_26` + + - `filters: Filters{ allowed_domains}` + + Filters for the search. + + - `allowed_domains: Array[String]` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: :low | :medium | :high` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `:low` + + - `:medium` + + - `:high` + + - `user_location: UserLocation{ city, country, region, 2 more}` + + The approximate location of the user. + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `class Mcp` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: String` + + A label for this MCP server, used to identify it in tool calls. + + - `type: :mcp` + + The type of the MCP tool. Always `mcp`. + + - `:mcp` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = Array[String]` + + A string array of allowed tool names + + - `class McpToolFilter` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Array[String]` + + List of allowed tool names. + + - `authorization: String` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `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: bool` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: Hash[Symbol, String]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` + + Specify which of the MCP server's tools require approval. + + - `class McpToolApprovalFilter` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: Always{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Array[String]` + + List of allowed tool names. + + - `never: Never{ read_only, tool_names}` + + A filter object to specify which tools are allowed. + + - `read_only: bool` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: Array[String]` + + List of allowed tool names. + + - `McpToolApprovalSetting = :always | :never` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `:always` + + - `:never` + + - `server_description: String` + + Optional description of the MCP server, used to provide more context. + + - `server_url: String` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: String` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `String = String` + + The container ID. + + - `class CodeInterpreterToolAuto` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: :auto` + + Always `auto`. + + - `:auto` + + - `file_ids: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the code interpreter container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `type: :disabled` + + Disable outbound network access. Always `disabled`. + + - `:disabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `allowed_domains: Array[String]` + + A list of allowed domains when type is `allowlist`. + + - `type: :allowlist` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `:allowlist` + + - `domain_secrets: Array[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`. + + - `:code_interpreter` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `type: :image_generation` + + The type of the image generation tool. Always `image_generation`. + + - `:image_generation` + + - `action: :generate | :edit | :auto` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `:generate` + + - `:edit` + + - `:auto` + + - `background: :transparent | :opaque | :auto` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `:transparent` + + - `:opaque` + + - `:auto` + + - `input_fidelity: :high | :low` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `:high` + + - `:low` + + - `input_image_mask: InputImageMask{ file_id, image_url}` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: String` + + File ID for the mask image. + + - `image_url: String` + + Base64-encoded mask image. + + - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `String = String` + + - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `:"gpt-image-1"` + + - `:"gpt-image-1-mini"` + + - `:"gpt-image-2"` + + - `:"gpt-image-2-2026-04-21"` + + - `:"gpt-image-1.5"` + + - `:"chatgpt-image-latest"` + + - `moderation: :auto | :low` + + Moderation level for the generated image. Default: `auto`. + + - `:auto` + + - `:low` + + - `output_compression: Integer` + + Compression level for the output image. Default: 100. + + - `output_format: :png | :webp | :jpeg` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `:png` + + - `:webp` + + - `:jpeg` + + - `partial_images: Integer` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: :low | :medium | :high | :auto` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `:low` + + - `:medium` + + - `:high` + + - `:auto` + + - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `String = String` + + - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `:"1024x1024"` + + - `:"1024x1536"` + + - `:"1536x1024"` + + - `:auto` + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: :local_shell` + + The type of the local shell tool. Always `local_shell`. + + - `:local_shell` + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `type: :shell` + + The type of the shell tool. Always `shell`. + + - `:shell` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` + + - `class BetaContainerAuto` + + - `type: :container_auto` + + Automatically creates a container for this request + + - `:container_auto` + + - `file_ids: Array[String]` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` + + The memory limit for the container. + + - `:"1g"` + + - `:"4g"` + + - `:"16g"` + + - `:"64g"` + + - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `class BetaContainerNetworkPolicyDisabled` + + - `class BetaContainerNetworkPolicyAllowlist` + + - `skills: Array[BetaSkillReference | BetaInlineSkill]` + + An optional list of skills referenced by id or inline data. + + - `class BetaSkillReference` + + - `skill_id: String` + + The ID of the referenced skill. + + - `type: :skill_reference` + + References a skill created with the /v1/skills endpoint. + + - `:skill_reference` + + - `version: String` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `class BetaInlineSkill` + + - `description: String` + + The description of the skill. + + - `name: String` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + Inline skill payload + + - `data: String` + + Base64-encoded skill zip bundle. + + - `media_type: :"application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `:"application/zip"` + + - `type: :base64` + + The type of the inline skill source. Must be `base64`. + + - `:base64` + + - `type: :inline` + + Defines an inline skill for this request. + + - `:inline` + + - `class BetaLocalEnvironment` + + - `type: :local` + + Use a local computer environment. + + - `:local` + + - `skills: Array[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. + + - `class BetaContainerReference` + + - `container_id: String` + + The ID of the referenced container. + + - `type: :container_reference` + + References a container created with the /v1/containers endpoint + + - `:container_reference` + + - `class BetaCustomTool` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: String` + + The name of the custom tool, used to identify it in tool calls. + + - `type: :custom` + + The type of the custom tool. Always `custom`. + + - `:custom` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this tool should be deferred and discovered via tool search. + + - `description: String` + + Optional description of the custom tool, used to provide more context. + + - `format_: Text{ type} | Grammar{ definition, syntax, type}` + + The input format for the custom tool. Default is unconstrained text. + + - `class Text` + + Unconstrained free-form text. + + - `type: :text` + + Unconstrained text format. Always `text`. + + - `:text` + + - `class Grammar` + + A grammar defined by the user. + + - `definition: String` + + The grammar definition. + + - `syntax: :lark | :regex` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `:lark` + + - `:regex` + + - `type: :grammar` + + Grammar format. Always `grammar`. + + - `:grammar` + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `description: String` + + A description of the namespace shown to the model. + + - `name: String` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` + + The function/custom tools available inside this namespace. + + - `class Function` + + - `name: String` + + - `type: :function` + + - `:function` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `defer_loading: bool` + + Whether this function should be deferred and discovered via tool search. + + - `description: String` + + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: untyped` + + - `strict: bool` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `class BetaCustomTool` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `type: :namespace` + + The type of the tool. Always `namespace`. + + - `:namespace` + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: :tool_search` + + The type of the tool. Always `tool_search`. + + - `:tool_search` + + - `description: String` + + Description shown to the model for a client-executed tool search tool. + + - `execution: :server | :client` + + Whether tool search is executed by the server or by the client. + + - `:server` + + - `:client` + + - `parameters: untyped` + + Parameter schema for a client-executed tool search tool. + + - `class BetaWebSearchPreviewTool` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: :web_search_preview | :web_search_preview_2025_03_11` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `:web_search_preview` + + - `:web_search_preview_2025_03_11` + + - `search_content_types: Array[:text | :image]` + + - `:text` + + - `:image` + + - `search_context_size: :low | :medium | :high` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `:low` + + - `:medium` + + - `:high` + + - `user_location: UserLocation{ type, city, country, 2 more}` + + The user's location. + + - `type: :approximate` + + The type of location approximation. Always `approximate`. + + - `:approximate` + + - `city: String` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: String` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: String` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: String` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :apply_patch` + + The type of the tool. Always `apply_patch`. + + - `:apply_patch` + + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `type: :tool_search_output` + + The type of the item. Always `tool_search_output`. + + - `:tool_search_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class AdditionalTools` + + - `id: String` + + The unique ID of the additional tools item. + + - `role: :unknown | :user | :assistant | 5 more` + + The role that provided the additional tools. + + - `:unknown` + + - `:user` + + - `:assistant` + + - `:system` + + - `:critic` + + - `:discriminator` + + - `:developer` + + - `:tool` + + - `tools: Array[BetaTool]` + + The additional tool definitions made available at this item. + + - `class BetaFunctionTool` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class BetaFileSearchTool` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class BetaComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class BetaWebSearchTool` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class BetaFunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class BetaCustomTool` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class BetaNamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class BetaToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class BetaWebSearchPreviewTool` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class BetaApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :additional_tools` + + The type of the item. Always `additional_tools`. + + - `:additional_tools` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseReasoningItem` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: String` + + The unique identifier of the reasoning content. + + - `summary: Array[Summary{ text, type}]` + + Reasoning summary content. + + - `text: String` + + A summary of the reasoning output from the model so far. + + - `type: :summary_text` + + The type of the object. Always `summary_text`. + + - `:summary_text` + + - `type: :reasoning` + + The type of the object. Always `reasoning`. + + - `:reasoning` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `content: Array[Content{ text, type}]` + + Reasoning text content. + + - `text: String` + + The reasoning text from the model. + + - `type: :reasoning_text` + + The type of the reasoning text. Always `reasoning_text`. + + - `:reasoning_text` + + - `encrypted_content: String` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class Program` + + - `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`. + + - `:program` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class ProgramOutput` + + - `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 | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCompactionItem` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: String` + + The unique ID of the compaction item. + + - `encrypted_content: String` + + The encrypted content that was produced by compaction. + + - `type: :compaction` + + The type of the item. Always `compaction`. + + - `:compaction` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class ImageGenerationCall` + + An image generation request made by the model. + + - `id: String` + + The unique ID of the image generation call. + + - `result: String` + + The generated image encoded in base64. + + - `status: :in_progress | :completed | :generating | :failed` + + The status of the image generation call. + + - `:in_progress` + + - `:completed` + + - `:generating` + + - `:failed` + + - `type: :image_generation_call` + + The type of the image generation call. Always `image_generation_call`. + + - `:image_generation_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class BetaResponseCodeInterpreterToolCall` + + A tool call to run code. + + - `id: String` + + The unique ID of the code interpreter tool call. + + - `code: String` + + The code to run, or null if not available. + + - `container_id: String` + + The ID of the container used to run the code. + + - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `class Logs` + + The logs output from the code interpreter. + + - `logs: String` + + The logs output from the code interpreter. + + - `type: :logs` + + The type of the output. Always `logs`. + + - `:logs` + + - `class Image` + + The image output from the code interpreter. + + - `type: :image` + + The type of the output. Always `image`. + + - `:image` + + - `url: String` + + The URL of the image output from the code interpreter. + + - `status: :in_progress | :completed | :incomplete | 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `:interpreting` + + - `:failed` + + - `type: :code_interpreter_call` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `:code_interpreter_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCall` + + A tool call to run a command on the local shell. + + - `id: String` + + The unique ID of the local shell call. + + - `action: Action{ command, env, type, 3 more}` + + Execute a shell command on the server. + + - `command: Array[String]` + + The command to run. + + - `env: Hash[Symbol, String]` + + Environment variables to set for the command. + + - `type: :exec` + + The type of the local shell action. Always `exec`. + + - `:exec` + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the command. + + - `user: String` + + Optional user to run the command as. + + - `working_directory: String` + + Optional working directory to run the command in. + + - `call_id: String` + + The unique ID of the local shell tool call generated by the model. + + - `status: :in_progress | :completed | :incomplete` + + The status of the local shell call. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :local_shell_call` + + The type of the local shell call. Always `local_shell_call`. + + - `:local_shell_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `class LocalShellCallOutput` + + The output of a local shell tool call. + + - `id: String` + + The unique ID of the local shell tool call generated by the model. + + - `output: String` + + A JSON string of the output of the local shell tool call. + + - `type: :local_shell_call_output` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `:local_shell_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `class BetaResponseFunctionShellToolCall` + + A tool call that executes one or more shell commands in a managed environment. + + - `id: String` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: Action{ commands, max_output_length, timeout_ms}` + + The shell commands and limits that describe how to run the tool call. + + - `commands: Array[String]` + + - `max_output_length: Integer` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: Integer` + + Optional timeout in milliseconds for the commands. + + - `call_id: String` + + The unique ID of the shell tool call generated by the model. + + - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `class BetaResponseLocalEnvironment` + + Represents the use of a local environment to perform shell actions. + + - `type: :local` + + The environment type. Always `local`. + + - `:local` + + - `class BetaResponseContainerReference` + + Represents a container created with /v1/containers. + + - `container_id: String` + + - `type: :container_reference` + + The environment type. Always `container_reference`. + + - `:container_reference` + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :shell_call` + + The type of the item. Always `shell_call`. + + - `:shell_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseFunctionShellToolCallOutput` + + The output of a shell tool call that was emitted. + + - `id: String` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `call_id: String` + + The unique ID of the shell tool call generated by the model. + + - `max_output_length: Integer` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: Array[Output{ outcome, stderr, stdout, created_by}]` + + An array of shell call output contents + + - `outcome: Timeout{ type} | Exit{ exit_code, type}` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `class Timeout` + + Indicates that the shell call exceeded its configured time limit. + + - `type: :timeout` + + The outcome type. Always `timeout`. + + - `:timeout` + + - `class Exit` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: Integer` + + Exit code from the shell process. + + - `type: :exit` + + The outcome type. Always `exit`. + + - `:exit` + + - `stderr: String` + + The standard error output that was captured. + + - `stdout: String` + + The standard output that was captured. + + - `created_by: String` + + The identifier of the actor that created the item. + + - `status: :in_progress | :completed | :incomplete` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :shell_call_output` + + The type of the shell call output. Always `shell_call_output`. + + - `:shell_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class BetaResponseApplyPatchToolCall` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `id: String` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `call_id: String` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `class CreateFile` + + Instruction describing how to create a file via the apply_patch tool. + + - `diff: String` + + Diff to apply. + + - `path: String` + + Path of the file to create. + + - `type: :create_file` + + Create a new file with the provided diff. + + - `:create_file` + + - `class DeleteFile` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: String` + + Path of the file to delete. + + - `type: :delete_file` + + Delete the specified file. + + - `:delete_file` + + - `class UpdateFile` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: String` + + Diff to apply. + + - `path: String` + + Path of the file to update. + + - `type: :update_file` + + Update an existing file with the provided diff. + + - `:update_file` + + - `status: :in_progress | :completed` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `:in_progress` + + - `:completed` + + - `type: :apply_patch_call` + + The type of the item. Always `apply_patch_call`. + + - `:apply_patch_call` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call. + + - `class BetaResponseApplyPatchToolCallOutput` + + The output emitted by an apply patch tool call. + + - `id: String` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: String` + + The unique ID of the apply patch tool call generated by the model. + + - `status: :completed | :failed` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `:completed` + + - `:failed` + + - `type: :apply_patch_call_output` + + The type of the item. Always `apply_patch_call_output`. + + - `:apply_patch_call_output` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + + - `created_by: String` + + The ID of the entity that created this tool call output. + + - `output: String` + + Optional textual output returned by the apply patch tool. - `class McpListTools` @@ -92086,7 +99989,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -92094,6 +99997,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -93459,7 +101364,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -93469,7 +101374,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -93516,7 +101425,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -93526,7 +101435,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -95660,7 +103573,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -95668,6 +103581,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -97033,7 +104948,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -97043,7 +104958,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -97090,7 +105009,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -97100,7 +105019,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -99256,7 +107179,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -99264,6 +107187,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -100629,7 +108554,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -100639,7 +108564,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -100686,7 +108615,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -100696,7 +108625,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -102844,7 +110777,834 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `:commentary` + + - `:final_answer` + +### Beta Response Output Refusal + +- `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `refusal: String` + + The refusal explanation from the model. + + - `type: :refusal` + + The type of the refusal. Always `refusal`. + + - `:refusal` + +### Beta Response Output Text + +- `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + The index of the first character of the URL citation in the message. + + - `title: String` + + The title of the web resource. + + - `type: :url_citation` + + The type of the URL citation. Always `url_citation`. + + - `:url_citation` + + - `url: String` + + The URL of the web resource. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + The index of the last character of the container file citation in the message. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the container file cited. + + - `start_index: Integer` + + The index of the first character of the container file citation in the message. + + - `type: :container_file_citation` + + The type of the container file citation. Always `container_file_citation`. + + - `:container_file_citation` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `:file_path` + + - `text: String` + + The text output from the model. + + - `type: :output_text` + + The type of the output text. Always `output_text`. + + - `:output_text` + + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + +### Beta Response Output Text Annotation Added Event + +- `class BetaResponseOutputTextAnnotationAddedEvent` + + Emitted when an annotation is added to output text content. + + - `annotation: untyped` + + The annotation object being added. (See annotation schema for details.) + + - `annotation_index: Integer` + + The index of the annotation within the content part. + + - `content_index: Integer` + + 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: Integer` + + The index of the output item in the response's output array. + + - `sequence_number: Integer` + + The sequence number of this event. + + - `type: :"response.output_text.annotation.added"` + + The type of the event. Always 'response.output_text.annotation.added'. + + - `:"response.output_text.annotation.added"` + + - `agent: Agent{ 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 + +- `class BetaResponsePrompt` + + 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: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | 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. + + - `String = String` + + - `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `version: String` + + Optional version of the prompt template. + +### Beta Response Queued Event + +- `class BetaResponseQueuedEvent` + + Emitted when a response is queued and waiting to be processed. + + - `response: BetaResponse` + + The full response object that is queued. + + - `id: String` + + Unique identifier for this Response. + + - `created_at: Float` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: BetaResponseError` + + An error object returned when the model fails to generate a Response. + + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 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: IncompleteDetails{ reason}` + + Details about why the response is incomplete. + + - `reason: :max_output_tokens | :content_filter` + + The reason why the response is incomplete. + + - `:max_output_tokens` + + - `:content_filter` + + - `instructions: String | Array[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. + + - `String = String` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `InputItemList = Array[BetaResponseInputItem]` + + A list of one or many input items to the model, containing + different content types. + + - `class BetaEasyInputMessage` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: String | BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `String = String` + + A text input to the model. + + - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` + + A list of one or many input items to the model, containing different content + types. + + - `class BetaResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `class BetaResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :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: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. + + - `:explicit` + + - `role: :user | :assistant | :system | :developer` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `:user` + + - `:assistant` + + - `:system` + + - `:developer` + + - `phase: :commentary | :final_answer` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `:commentary` + + - `:final_answer` + + - `type: :message` + + The type of the message input. Always `message`. + + - `:message` + + - `class Message` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: BetaResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `role: :user | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + + - `class BetaResponseOutputMessage` + + An output message from the model. + + - `id: String` + + The unique ID of the output message. + + - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` + + The content of the output message. + + - `class BetaResponseOutputText` + + A text output from the model. + + - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` + + The annotations of the text output. + + - `class FileCitation` + + A citation to a file. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the file cited. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_citation` + + The type of the file citation. Always `file_citation`. + + - `:file_citation` + + - `class URLCitation` + + A citation for a web resource used to generate a model response. + + - `end_index: Integer` + + The index of the last character of the URL citation in the message. + + - `start_index: Integer` + + The index of the first character of the URL citation in the message. + + - `title: String` + + The title of the web resource. + + - `type: :url_citation` + + The type of the URL citation. Always `url_citation`. + + - `:url_citation` + + - `url: String` + + The URL of the web resource. + + - `class ContainerFileCitation` + + A citation for a container file used to generate a model response. + + - `container_id: String` + + The ID of the container file. + + - `end_index: Integer` + + The index of the last character of the container file citation in the message. + + - `file_id: String` + + The ID of the file. + + - `filename: String` + + The filename of the container file cited. + + - `start_index: Integer` + + The index of the first character of the container file citation in the message. + + - `type: :container_file_citation` + + The type of the container file citation. Always `container_file_citation`. + + - `:container_file_citation` + + - `class FilePath` + + A path to a file. + + - `file_id: String` + + The ID of the file. + + - `index: Integer` + + The index of the file in the list of files. + + - `type: :file_path` + + The type of the file path. Always `file_path`. + + - `:file_path` + + - `text: String` + + The text output from the model. + + - `type: :output_text` + + The type of the output text. Always `output_text`. + + - `:output_text` + + - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` + + - `token: String` + + - `bytes: Array[Integer]` + + - `logprob: Float` + + - `class BetaResponseOutputRefusal` + + A refusal from the model. + + - `refusal: String` + + The refusal explanation from the model. + + - `type: :refusal` + + The type of the refusal. Always `refusal`. + + - `:refusal` + + - `role: :assistant` + + The role of the output message. Always `assistant`. + + - `:assistant` + + - `status: :in_progress | :completed | :incomplete` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + + - `type: :message` + + The type of the output message. Always `message`. + + - `:message` + + - `agent: Agent{ agent_name}` + + The agent that produced this item. + + - `agent_name: String` + + The canonical name of the agent that produced this item. + + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -102852,828 +111612,7 @@ puts(beta_compacted_response) - `:commentary` -### Beta Response Output Refusal - -- `class BetaResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - -### Beta Response Output Text - -- `class BetaResponseOutputText` - - A text output from the model. - - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - The annotations of the text output. - - - `class FileCitation` - - A citation to a file. - - - `file_id: String` - - The ID of the file. - - - `filename: String` - - The filename of the file cited. - - - `index: Integer` - - The index of the file in the list of files. - - - `type: :file_citation` - - The type of the file citation. Always `file_citation`. - - - `:file_citation` - - - `class URLCitation` - - A citation for a web resource used to generate a model response. - - - `end_index: Integer` - - The index of the last character of the URL citation in the message. - - - `start_index: Integer` - - The index of the first character of the URL citation in the message. - - - `title: String` - - The title of the web resource. - - - `type: :url_citation` - - The type of the URL citation. Always `url_citation`. - - - `:url_citation` - - - `url: String` - - The URL of the web resource. - - - `class ContainerFileCitation` - - A citation for a container file used to generate a model response. - - - `container_id: String` - - The ID of the container file. - - - `end_index: Integer` - - The index of the last character of the container file citation in the message. - - - `file_id: String` - - The ID of the file. - - - `filename: String` - - The filename of the container file cited. - - - `start_index: Integer` - - The index of the first character of the container file citation in the message. - - - `type: :container_file_citation` - - The type of the container file citation. Always `container_file_citation`. - - - `:container_file_citation` - - - `class FilePath` - - A path to a file. - - - `file_id: String` - - The ID of the file. - - - `index: Integer` - - The index of the file in the list of files. - - - `type: :file_path` - - The type of the file path. Always `file_path`. - - - `:file_path` - - - `text: String` - - The text output from the model. - - - `type: :output_text` - - The type of the output text. Always `output_text`. - - - `:output_text` - - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - - `token: String` - - - `bytes: Array[Integer]` - - - `logprob: Float` - - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - - `token: String` - - - `bytes: Array[Integer]` - - - `logprob: Float` - -### Beta Response Output Text Annotation Added Event - -- `class BetaResponseOutputTextAnnotationAddedEvent` - - Emitted when an annotation is added to output text content. - - - `annotation: untyped` - - The annotation object being added. (See annotation schema for details.) - - - `annotation_index: Integer` - - The index of the annotation within the content part. - - - `content_index: Integer` - - 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: Integer` - - The index of the output item in the response's output array. - - - `sequence_number: Integer` - - The sequence number of this event. - - - `type: :"response.output_text.annotation.added"` - - The type of the event. Always 'response.output_text.annotation.added'. - - - `:"response.output_text.annotation.added"` - - - `agent: Agent{ 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 - -- `class BetaResponsePrompt` - - 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: Hash[Symbol, String | BetaResponseInputText | BetaResponseInputImage | 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. - - - `String = String` - - - `class BetaResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` - - - `:original` - - - `type: :input_image` - - The type of the input item. Always `input_image`. - - - `:input_image` - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `image_url: String` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: String` - - The content of the file to be sent to the model. - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `file_url: String` - - The URL of the file to be sent to the model. - - - `filename: String` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `version: String` - - Optional version of the prompt template. - -### Beta Response Queued Event - -- `class BetaResponseQueuedEvent` - - Emitted when a response is queued and waiting to be processed. - - - `response: BetaResponse` - - The full response object that is queued. - - - `id: String` - - Unique identifier for this Response. - - - `created_at: Float` - - Unix timestamp (in seconds) of when this Response was created. - - - `error: BetaResponseError` - - An error object returned when the model fails to generate a Response. - - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 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: IncompleteDetails{ reason}` - - Details about why the response is incomplete. - - - `reason: :max_output_tokens | :content_filter` - - The reason why the response is incomplete. - - - `:max_output_tokens` - - - `:content_filter` - - - `instructions: String | Array[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. - - - `String = String` - - A text input to the model, equivalent to a text input with the - `developer` role. - - - `InputItemList = Array[BetaResponseInputItem]` - - A list of one or many input items to the model, containing - different content types. - - - `class BetaEasyInputMessage` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: String | BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `String = String` - - A text input to the model. - - - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` - - A list of one or many input items to the model, containing different content - types. - - - `class BetaResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` - - - `:original` - - - `type: :input_image` - - The type of the input item. Always `input_image`. - - - `:input_image` - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `image_url: String` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `class BetaResponseInputFile` - - A file input to the model. - - - `type: :input_file` - - The type of the input item. Always `input_file`. - - - `:input_file` - - - `detail: :auto | :low | :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: String` - - The content of the file to be sent to the model. - - - `file_id: String` - - The ID of the file to be sent to the model. - - - `file_url: String` - - The URL of the file to be sent to the model. - - - `filename: String` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: PromptCacheBreakpoint{ 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`. - - - `:explicit` - - - `role: :user | :assistant | :system | :developer` - - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - - - `:user` - - - `:assistant` - - - `:system` - - - `:developer` - - - `phase: :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: :message` - - The type of the message input. Always `message`. - - - `:message` - - - `class Message` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. - - - `content: BetaResponseInputMessageContentList` - - A list of one or many input items to the model, containing different content - types. - - - `role: :user | :system | :developer` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `:user` - - - `:system` - - - `:developer` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `status: :in_progress | :completed | :incomplete` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `type: :message` - - The type of the message input. Always set to `message`. - - - `:message` - - - `class BetaResponseOutputMessage` - - An output message from the model. - - - `id: String` - - The unique ID of the output message. - - - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` - - The content of the output message. - - - `class BetaResponseOutputText` - - A text output from the model. - - - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]` - - The annotations of the text output. - - - `class FileCitation` - - A citation to a file. - - - `file_id: String` - - The ID of the file. - - - `filename: String` - - The filename of the file cited. - - - `index: Integer` - - The index of the file in the list of files. - - - `type: :file_citation` - - The type of the file citation. Always `file_citation`. - - - `:file_citation` - - - `class URLCitation` - - A citation for a web resource used to generate a model response. - - - `end_index: Integer` - - The index of the last character of the URL citation in the message. - - - `start_index: Integer` - - The index of the first character of the URL citation in the message. - - - `title: String` - - The title of the web resource. - - - `type: :url_citation` - - The type of the URL citation. Always `url_citation`. - - - `:url_citation` - - - `url: String` - - The URL of the web resource. - - - `class ContainerFileCitation` - - A citation for a container file used to generate a model response. - - - `container_id: String` - - The ID of the container file. - - - `end_index: Integer` - - The index of the last character of the container file citation in the message. - - - `file_id: String` - - The ID of the file. - - - `filename: String` - - The filename of the container file cited. - - - `start_index: Integer` - - The index of the first character of the container file citation in the message. - - - `type: :container_file_citation` - - The type of the container file citation. Always `container_file_citation`. - - - `:container_file_citation` - - - `class FilePath` - - A path to a file. - - - `file_id: String` - - The ID of the file. - - - `index: Integer` - - The index of the file in the list of files. - - - `type: :file_path` - - The type of the file path. Always `file_path`. - - - `:file_path` - - - `text: String` - - The text output from the model. - - - `type: :output_text` - - The type of the output text. Always `output_text`. - - - `:output_text` - - - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - - - `token: String` - - - `bytes: Array[Integer]` - - - `logprob: Float` - - - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - - - `token: String` - - - `bytes: Array[Integer]` - - - `logprob: Float` - - - `class BetaResponseOutputRefusal` - - A refusal from the model. - - - `refusal: String` - - The refusal explanation from the model. - - - `type: :refusal` - - The type of the refusal. Always `refusal`. - - - `:refusal` - - - `role: :assistant` - - The role of the output message. Always `assistant`. - - - `:assistant` - - - `status: :in_progress | :completed | :incomplete` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - - - `type: :message` - - The type of the output message. Always `message`. - - - `:message` - - - `agent: Agent{ agent_name}` - - The agent that produced this item. - - - `agent_name: String` - - The canonical name of the agent that produced this item. - - - `phase: :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` - `class BetaResponseFileSearchToolCall` @@ -104847,7 +112786,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -104857,7 +112796,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -104904,7 +112847,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -104914,7 +112857,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -110565,7 +118512,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -110573,6 +118520,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -110812,7 +118761,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -110820,6 +118769,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -111992,7 +119943,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -112002,7 +119953,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -112049,7 +120004,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -112059,7 +120014,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -118824,7 +126783,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -118834,7 +126793,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -118881,7 +126844,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -118891,7 +126854,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -119936,7 +127903,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -119946,7 +127913,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -119993,7 +127964,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -120003,7 +127974,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -121103,7 +129078,7 @@ puts(beta_compacted_response) ### Beta Responses Client Event -- `BetaResponsesClientEvent = ResponseCreate{ type, background, context_management, 30 more} | ResponseInject{ input, response_id, type}` +- `BetaResponsesClientEvent = ResponseCreate{ type, background, context_management, 30 more} | BetaResponseInjectEvent` Client events accepted by the Responses WebSocket server. @@ -121352,7 +129327,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -121360,6 +129335,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -121599,7 +129576,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -121607,6 +129584,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -122779,7 +130758,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -122789,7 +130768,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -122836,7 +130819,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -122846,7 +130829,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -125885,7 +133872,7 @@ puts(beta_compacted_response) A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `class ResponseInject` + - `class BetaResponseInjectEvent` Injects input items into an active response over a WebSocket connection. The items are validated and committed atomically. Currently, the server @@ -126545,7 +134532,7 @@ puts(beta_compacted_response) - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -126553,6 +134540,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -126792,7 +134781,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -126800,6 +134789,8 @@ puts(beta_compacted_response) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -127972,7 +135963,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -127982,7 +135973,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -128029,7 +136024,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -128039,7 +136034,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -134398,7 +142397,7 @@ puts(beta_compacted_response) The canonical name of the agent that produced this item. - - `class ResponseInjectCreated` + - `class BetaResponseInjectCreatedEvent` Emitted when all injected input items were validated and committed to the active response. @@ -134422,7 +142421,7 @@ puts(beta_compacted_response) The multiplexed WebSocket stream that emitted the event. This field is present only when WebSocket multiplexing is enabled separately. - - `class ResponseInjectFailed` + - `class BetaResponseInjectFailedEvent` 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 @@ -134727,7 +142726,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -134737,7 +142736,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -134784,7 +142787,7 @@ puts(beta_compacted_response) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -134794,7 +142797,11 @@ puts(beta_compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -136042,7 +144049,7 @@ puts(beta_compacted_response) **get** `/responses/{response_id}/input_items?beta=true` -List input items +Returns a list of input items for a given response. ### Parameters @@ -136442,7 +144449,7 @@ List input items The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -136450,6 +144457,8 @@ List input items - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -137534,7 +145543,7 @@ List input items - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -137544,7 +145553,11 @@ List input items - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -137591,7 +145604,7 @@ List input items - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -137601,7 +145614,11 @@ List input items - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -140038,7 +148055,7 @@ puts(page) The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -140046,6 +148063,8 @@ puts(page) - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -141130,7 +149149,7 @@ puts(page) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -141140,7 +149159,11 @@ puts(page) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -141187,7 +149210,7 @@ puts(page) - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -141197,7 +149220,11 @@ puts(page) - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped` @@ -143262,7 +151289,9 @@ puts(page) **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 @@ -143440,7 +151469,7 @@ Get input token counts - `:developer` - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -143448,6 +151477,8 @@ Get input token counts - `:commentary` + - `:final_answer` + - `type: :message` The type of the message input. Always `message`. @@ -143687,7 +151718,7 @@ Get input token counts The canonical name of the agent that produced this item. - - `phase: :commentary` + - `phase: :commentary | :final_answer` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -143695,6 +151726,8 @@ Get input token counts - `:commentary` + - `:final_answer` + - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the @@ -144867,7 +152900,7 @@ Get input token counts - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -144877,7 +152910,11 @@ Get input token counts - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `class CompoundFilter` @@ -144924,7 +152961,7 @@ Get input token counts - `:nin` - - `value: String | Float | bool | Array[untyped]` + - `value: String | Float | bool | Array[String | Float]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -144934,7 +152971,11 @@ Get input token counts - `UnionMember2 = bool` - - `UnionMember3 = Array[untyped]` + - `UnionMember3 = Array[String | Float]` + + - `String = String` + + - `Float = Float` - `UnionMember1 = untyped`