GET

/v1/schemas/openai/chat/conversations/{conversation_id}/items?kind=output

Accept:

kind outputactivity chathash f76b54fd…extracted Nov 5, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `898eefefea6b5dc52da42f5628a64a0ffba65d850282e1cb59ab459f7e356f92` { "fetchedAt": 1793851833, "extractorVersion": "1", "verifiedAt": null }

Response body

5 properties · 5 required · 173 $defs

property	type	description	constraints
object*	const	The type of object returned, must be `list`.	"list"
data*	ConversationItem[]	A list of conversation items.
has_more*	boolean	Whether there are more items available.
first_id*	string	The ID of the first item in the list.
last_id*	string	The ID of the last item in the list.

Types

173 $defs

AdditionalToolsobject

type*	enum	The type of the item. Always `additional_tools`.	additional_tools · default: "additional_tools"
id*	string	The unique ID of the additional tools item.
role*	enum	The role that provided the additional tools.	unknown \| user \| assistant \| system \| critic \| discriminator · +2 more
tools*	Tool[]	The additional tool definitions made available at this item.

AnnotationFile citation | URL citation | Container file citation | …

An annotation that applies to a span of output text.

ApplyPatchCallOutputStatusenum

completed | failed

ApplyPatchCreateFileOperationobject

Instruction describing how to create a file via the apply_patch tool.

type*	enum	Create a new file with the provided diff.	create_file · default: "create_file"
path*	string	Path of the file to create.
diff*	string	Diff to apply.

ApplyPatchDeleteFileOperationobject

Instruction describing how to delete a file via the apply_patch tool.

type*	enum	Delete the specified file.	delete_file · default: "delete_file"
path*	string	Path of the file to delete.

ApplyPatchToolCallobject

A tool call that applies file diffs by creating, deleting, or updating files.

type*	enum	The type of the item. Always `apply_patch_call`.	apply_patch_call · default: "apply_patch_call"
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.
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the apply patch tool call. One of `in_progress` or `completed`.	in_progress \| completed
operation*	Apply patch create file operation \| Apply patch delete file operation \| Apply patch update file operation	One of the create_file, delete_file, or update_file operations applied via apply_patch.
created_by	string	The ID of the entity that created this tool call.

ApplyPatchToolCallOutputobject

The output emitted by an apply patch tool call.

type*	enum	The type of the item. Always `apply_patch_call_output`.	apply_patch_call_output · default: "apply_patch_call_output"
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.
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the apply patch tool call output. One of `completed` or `failed`.	completed \| failed
output	string	Optional textual output returned by the apply patch tool.	nullable
created_by	string	The ID of the entity that created this tool call output.

ApplyPatchToolParamobject

Allows the assistant to create, delete, or update files using unified diffs.

type*	enum	The type of the tool. Always `apply_patch`.	apply_patch · default: "apply_patch"
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

ApplyPatchUpdateFileOperationobject

Instruction describing how to update a file via the apply_patch tool.

type*	enum	Update an existing file with the provided diff.	update_file · default: "update_file"
path*	string	Path of the file to update.
diff*	string	Diff to apply.

ApproximateLocationobject

type*	enum	The type of location approximation. Always `approximate`.	approximate · default: "approximate"
country	string	The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.	nullable
region	string	Free text input for the region of the user, e.g. `California`.	nullable
city	string	Free text input for the city of the user, e.g. `San Francisco`.	nullable
timezone	string	The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.	nullable

ClickParamobject

A click action.

type*	enum	Specifies the event type. For a click action, this property is always `click`.	click · default: "click"
button*	enum	Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.	left \| right \| wheel \| back \| forward
x*	integer	The x-coordinate where the click occurred.
y*	integer	The y-coordinate where the click occurred.
keys	string[]	The keys being held while clicking.	nullable

CodeInterpreterContainerAutoobject

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

type*	enum	Always `auto`.	auto · default: "auto"
file_ids	string[]	An optional list of uploaded files to make available to your code.	items ≤ 50
memory_limit	enum	The memory limit for the code interpreter container.	1g \| 4g \| 16g \| 64g · nullable
network_policy	object \| object	Network access policy for the container.

CodeInterpreterOutputImageobject

The image output from the code interpreter.

type*	enum	The type of the output. Always `image`.	image · default: "image"
url*	string	The URL of the image output from the code interpreter.	format: uri

CodeInterpreterOutputLogsobject

The logs output from the code interpreter.

type*	enum	The type of the output. Always `logs`.	logs · default: "logs"
logs*	string	The logs output from the code interpreter.

CodeInterpreterToolobject

A tool that runs Python code to help generate a response to a prompt.

type*	enum	The type of the code interpreter tool. Always `code_interpreter`.	code_interpreter
container*	string \| CodeInterpreterToolAuto	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.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

CodeInterpreterToolCallobject

A tool call to run code.

type*	enum	The type of the code interpreter tool call. Always `code_interpreter_call`.	code_interpreter_call · default: "code_interpreter_call"
id*	string	The unique ID of the code interpreter tool call.
status*	enum	The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.	in_progress \| completed \| incomplete \| interpreting \| failed
container_id*	string	The ID of the container used to run the code.
code*	string	The code to run, or null if not available.	nullable
outputs*	CodeInterpreterOutputLogs \| CodeInterpreterOutputImage[]	The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available.	nullable

CompactionBodyobject

A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact).

type*	enum	The type of the item. Always `compaction`.	compaction · default: "compaction"
id*	string	The unique ID of the compaction item.
encrypted_content*	string	The encrypted content that was produced by compaction.
created_by	string	The identifier of the actor that created the item.

ComparisonFilterobject

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

type*	enum	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 · +2 more · default: "eq"
key*	string	The key to compare against the value.
value*	string \| number \| boolean \| …	The value to compare against the attribute key; supports string, number, or boolean types.

ComparisonFilterValueItemsstring | number

CompoundFilterobject

Combine multiple filters using `and` or `or`.

type*	enum	Type of operation: `and` or `or`.	and \| or
filters*	ComparisonFilter \| any[]	Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.

ComputerActionClick | DoubleClick | Drag | …

ComputerActionListComputerAction[]

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

ComputerCallSafetyCheckParamobject

A pending safety check for the computer call.

id*	string	The ID of the pending safety check.
code	string	The type of the pending safety check.	nullable
message	string	Details about the pending safety check.	nullable

ComputerEnvironmentenum

windows | mac | linux | ubuntu | browser

ComputerScreenshotContentobject

A screenshot of a computer.

type*	enum	Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`.	computer_screenshot · default: "computer_screenshot"
image_url*	string	The URL of the screenshot image.	format: uri · nullable
file_id*	string	The identifier of an uploaded file that contains the screenshot.	nullable
detail*	enum	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
prompt_cache_breakpoint	PromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

ComputerScreenshotImageobject

A computer screenshot image used with the computer use tool.

type*	enum	Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`.	computer_screenshot · default: "computer_screenshot"
image_url	string	The URL of the screenshot image.	format: uri
file_id	string	The identifier of an uploaded file that contains the screenshot.

ComputerToolobject

A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).

type*

enum

The type of the computer tool. Always `computer`.

computer · default: "computer"

ComputerToolCallobject

A tool call to a computer use tool. See the [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information.

type*	enum	The type of the computer call. Always `computer_call`.	computer_call · default: "computer_call"
id*	string	The unique ID of the computer call.
call_id*	string	An identifier used when responding to the tool call with output.
action	Click \| DoubleClick \| Drag \| …
actions	ComputerAction[]	Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields.
pending_safety_checks*	ComputerCallSafetyCheckParam[]	The pending safety checks for the computer call.
status*	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

ComputerToolCallOutputobject

The output of a computer tool call.

type*	enum	The type of the computer tool call output. Always `computer_call_output`.	computer_call_output · default: "computer_call_output"
id	string	The ID of the computer tool call output.
call_id*	string	The ID of the computer tool call that produced the output.
acknowledged_safety_checks	ComputerCallSafetyCheckParam[]	The safety checks reported by the API that have been acknowledged by the developer.
output*	ComputerScreenshotImage	A computer screenshot image used with the computer use tool.
status	enum	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

ComputerToolCallOutputResourceComputer tool call output | object

ComputerUsePreviewToolobject

A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).

type*	enum	The type of the computer use tool. Always `computer_use_preview`.	computer_use_preview · default: "computer_use_preview"
environment*	enum	The type of computer environment to control.	windows \| mac \| linux \| ubuntu \| browser
display_width*	integer	The width of the computer display.
display_height*	integer	The height of the computer display.

ContainerAutoParamobject

type*	enum	Automatically creates a container for this request	container_auto · default: "container_auto"
file_ids	string[]	An optional list of uploaded files to make available to your code.	items ≤ 50
memory_limit	enum	The memory limit for the container.	1g \| 4g \| 16g \| 64g · nullable
network_policy	object \| object	Network access policy for the container.
skills	SkillReferenceParam \| InlineSkillParam[]	An optional list of skills referenced by id or inline data.	items ≤ 200

ContainerFileCitationBodyobject

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

type*	enum	The type of the container file citation. Always `container_file_citation`.	container_file_citation · default: "container_file_citation"
container_id*	string	The ID of the container file.
file_id*	string	The ID of the file.
start_index*	integer	The index of the first character of the container file citation in the message.
end_index*	integer	The index of the last character of the container file citation in the message.
filename*	string	The filename of the container file cited.

ContainerNetworkPolicyAllowlistParamobject

type*	enum	Allow outbound network access only to specified domains. Always `allowlist`.	allowlist · default: "allowlist"
allowed_domains*	string[]	A list of allowed domains when type is `allowlist`.	items ≥ 1
domain_secrets	ContainerNetworkPolicyDomainSecretParam[]	Optional domain-scoped secrets for allowlisted domains.	items ≥ 1

ContainerNetworkPolicyDisabledParamobject

type*

enum

Disable outbound network access. Always `disabled`.

disabled · default: "disabled"

ContainerNetworkPolicyDomainSecretParamobject

domain*	string	The domain associated with the secret.	length ≥ 1
name*	string	The name of the secret to inject for the domain.	length ≥ 1
value*	string	The secret value to inject for the domain.	length ≥ 1 · length ≤ 10485760

ContainerReferenceParamobject

type*	enum	References a container created with the /v1/containers endpoint	container_reference · default: "container_reference"
container_id*	string	The ID of the referenced container.

ContainerReferenceResourceobject

Represents a container created with /v1/containers.

type*	enum	The environment type. Always `container_reference`.	container_reference · default: "container_reference"
container_id*	string

ConversationItemMessage | any | any | …

A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://developers.openai.com/api/reference/resources/responses#%28resource%29%20responses%20%3E%20%28model%29%20response%20%3E%20%28schema%…

CoordParamobject

An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.

x*	integer	The x-coordinate.
y*	integer	The y-coordinate.

CustomGrammarFormatParamobject

A grammar defined by the user.

type*	enum	Grammar format. Always `grammar`.	grammar · default: "grammar"
syntax*	enum	The syntax of the grammar definition. One of `lark` or `regex`.	lark \| regex
definition*	string	The grammar definition.

CustomTextFormatParamobject

Unconstrained free-form text.

type*

enum

Unconstrained text format. Always `text`.

text · default: "text"

CustomToolCallobject

A call to a custom tool created by the model.

type*	enum	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.
call_id*	string	An identifier used to map this custom tool call to a tool call output.
caller	object \| object	The execution context that produced this tool call.	nullable
namespace	string	The namespace of the custom tool being called.
name*	string	The name of the custom tool being called.
input*	string	The input for the custom tool call generated by the model.
async	boolean	Whether the custom tool call runs asynchronously.

CustomToolCallOutputobject

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

type*	enum	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.
call_id*	string	The call ID, used to map this custom tool call output to a custom tool call.
caller	object \| object	The execution context that produced this tool call.	nullable
output*	string \| FunctionAndCustomToolCallOutput[]	The output from the custom tool call generated by your code. Can be a string or an list of output content.

CustomToolParamobject

A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)

type*	enum	The type of the custom tool. Always `custom`.	custom · default: "custom"
name*	string	The name of the custom tool, used to identify it in tool calls.
async	boolean	Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
description	string	Optional description of the custom tool, used to provide more context.
format	Text format \| Grammar format	The input format for the custom tool. Default is unconstrained text.
defer_loading	boolean	Whether this tool should be deferred and discovered via tool search.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

DirectToolCallCallerobject

type*

enum

direct · default: "direct"

DirectToolCallCallerParamobject

type*

enum

The caller type. Always `direct`.

direct · default: "direct"

DoubleClickActionobject

A double click action.

type*	enum	Specifies the event type. For a double click action, this property is always set to `double_click`.	double_click · default: "double_click"
x*	integer	The x-coordinate where the double click occurred.
y*	integer	The y-coordinate where the double click occurred.
keys*	string[]	The keys being held while double-clicking.	nullable

DragParamobject

A drag action.

type*	enum	Specifies the event type. For a drag action, this property is always set to `drag`.	drag · default: "drag"
path*	CoordParam[]	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 } ] ```
keys	string[]	The keys being held while dragging the mouse.	nullable

EmptyModelParamobject

FileCitationBodyobject

A citation to a file.

type*	enum	The type of the file citation. Always `file_citation`.	file_citation · default: "file_citation"
file_id*	string	The ID of the file.
index*	integer	The index in the output text at which to insert the file citation.
filename*	string	The filename of the file cited.

FileInputDetailenum

auto | low | high

FilePathobject

A path to a file.

type*	enum	The type of the file path. Always `file_path`.	file_path
file_id*	string	The ID of the file.
index*	integer	The index of the file in the list of files.

FileSearchToolobject

A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search).

type*	enum	The type of the file search tool. Always `file_search`.	file_search · default: "file_search"
vector_store_ids*	string[]	The IDs of the vector stores to search.
max_num_results	integer	The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options	RankingOptions	Ranking options for search.
filters	Comparison Filter \| Compound Filter	A filter to apply.	nullable

FileSearchToolCallobject

The results of a file search tool call. See the [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information.

id*	string	The unique ID of the file search tool call.
type*	enum	The type of the file search tool call. Always `file_search_call`.	file_search_call
status*	enum	The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`,	in_progress \| searching \| completed \| incomplete \| failed
queries*	string[]	The queries used to search for files.
results	object[]	The results of the file search tool call.	nullable

FiltersComparison Filter | Compound Filter

FunctionAndCustomToolCallOutputInput text | Input image | Input file

FunctionCallOutputStatusEnumenum

in_progress | completed | incomplete

FunctionCallStatusenum

in_progress | completed | incomplete

FunctionShellActionobject

Execute a shell command.

commands*	string[]
timeout_ms*	integer	Optional timeout in milliseconds for the commands.	nullable
max_output_length*	integer	Optional maximum number of characters to return from each command.	nullable

FunctionShellCallobject

A tool call that executes one or more shell commands in a managed environment.

type*	enum	The type of the item. Always `shell_call`.	shell_call · default: "shell_call"
id*	string	The unique ID of the shell tool call. Populated when this item is returned via API.
call_id*	string	The unique ID of the shell tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
action*	FunctionShellAction	The shell commands and limits that describe how to run the tool call.
status*	enum	The status of the shell call. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete
environment*	Local Environment \| Container Reference		nullable
created_by	string	The ID of the entity that created this tool call.

FunctionShellCallOutputobject

The output of a shell tool call that was emitted.

type*	enum	The type of the shell call output. Always `shell_call_output`.	shell_call_output · default: "shell_call_output"
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.
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete
output*	FunctionShellCallOutputContent[]	An array of shell call output contents
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.	nullable
created_by	string	The identifier of the actor that created the item.

FunctionShellCallOutputContentobject

The content of a shell tool call output that was emitted.

stdout*	string	The standard output that was captured.
stderr*	string	The standard error output that was captured.
outcome*	Shell call timeout outcome \| Shell call exit outcome	Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk.
created_by	string	The identifier of the actor that created the item.

FunctionShellCallOutputExitOutcomeobject

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

type*	enum	The outcome type. Always `exit`.	exit · default: "exit"
exit_code*	integer	Exit code from the shell process.

FunctionShellCallOutputStatusEnumenum

in_progress | completed | incomplete

FunctionShellCallOutputTimeoutOutcomeobject

Indicates that the shell call exceeded its configured time limit.

type*

enum

The outcome type. Always `timeout`.

timeout · default: "timeout"

FunctionShellCallStatusenum

in_progress | completed | incomplete

FunctionShellToolParamobject

A tool that allows the model to execute shell commands.

type*	enum	The type of the shell tool. Always `shell`.	shell · default: "shell"
environment	object \| object \| object		nullable
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

FunctionToolobject

Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling).

type*	enum	The type of the function tool. Always `function`.	function · default: "function"
name*	string	The name of the function to call.
async	boolean
description	string	A description of the function. Used by the model to determine whether or not to call the function.	nullable
parameters*	object	A JSON schema object describing the parameters of the function.	nullable
output_schema	object	A JSON schema object describing the JSON value encoded in string outputs for this function.	nullable
strict*	boolean	Whether strict parameter validation is enforced for this function tool.	nullable
defer_loading	boolean	Whether this function is deferred and loaded via tool search.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	nullable

FunctionToolCallobject

A tool call to run a function. See the [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information.

id	string	The unique ID of the function tool call.
type*	enum	The type of the function tool call. Always `function_call`.	function_call
call_id*	string	The unique ID of the function tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
namespace	string	The namespace of the function to run.
name*	string	The name of the function to run.
arguments*	string	A JSON string of the arguments to pass to the function.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete
async	boolean	Whether the function tool call runs asynchronously.

FunctionToolCallOutputobject

The output of a function tool call.

id	string	The unique ID of the function tool call output. Populated when this item is returned via API.
type*	enum	The type of the function tool call output. Always `function_call_output`.	function_call_output
call_id	string	The unique ID of the function tool call generated by the model.
name	string	The name of the tool that produced the output.
namespace	string	The namespace of the tool that produced the output.
caller	object \| object	The execution context that produced this tool call.	nullable
output*	string \| FunctionAndCustomToolCallOutput[]	The output from the function call generated by your code. Can be a string or an list of output content.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

FunctionToolCallOutputResourceFunction tool call output | object

FunctionToolCallResourceFunction tool call | object

FunctionToolParamobject

name*	string		length ≥ 1 · length ≤ 128
description	string		nullable
parameters	EmptyModelParam		nullable
strict	boolean	Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise.	nullable
type*	enum		function · default: "function"
async	boolean	Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
output_schema	object	A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs.	nullable
defer_loading	boolean	Whether this function should be deferred and discovered via tool search.
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

GrammarSyntax1enum

lark | regex

HTTPErrorobject

type*	enum	http_error · default: "http_error"
code*	integer
message*	string

HybridSearchOptionsobject

embedding_weight*	number	The weight of the embedding in the reciprocal ranking fusion.
text_weight*	number	The weight of the text in the reciprocal ranking fusion.

ImageBackgroundenum

transparent | opaque | auto

ImageDetailenum

low | high | auto | original

ImageGenActionEnumenum

generate | edit | auto

ImageGenToolobject

A tool that generates images using the GPT image models.

type*	enum	The type of the image generation tool. Always `image_generation`.	image_generation
model	string \| enum
complexity	enum	Computation spent planning the image, independently of rendering quality. Overrides the outer response's `reasoning.effort` for image generation. When omitted, inherits a supported outer reasoning effort or uses the image model's configured default. For SVG ou…	low \| medium \| high
quality	enum	The quality of the generated image. The GPT image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Default: `auto`.	low \| medium \| high \| xhigh \| max \| auto · default: "auto"
size	string \| enum	The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` str…	default: "auto"
output_format	enum	The output format of the generated image. One of `png`, `webp`, `jpeg`, `gif`, or `svg`. Default: `png`. GIF and SVG output require a model that supports the selected format. GIF output does not support partial image streaming (`partial_images` greater than `0…	png \| webp \| jpeg \| gif \| svg · default: "png"
frame_count	integer	Number of GIF frames. Requires `output_format` to be `gif`. Default: 9.	2 ≤ n ≤ 16 · default: 9
frame_duration_ms	integer	Duration of each GIF frame in milliseconds, rounded to 10 ms. Requires `output_format` to be `gif`. Default: 200.	20 ≤ n ≤ 2000 · default: 200
svg	SvgParam	SVG author model settings. Requires `output_format` to be `svg`. When SVG model selection is enabled, omitting this object uses the outer response model. Otherwise, the default SVG author is used and explicit model overrides are unavailable.
output_compression	integer	Compression level for the output image. Default: 100.	0 ≤ n ≤ 100 · default: 100
moderation	enum	Moderation level for the generated image. Default: `auto`.	auto \| low · default: "auto"
background	enum	Allows to set transparency for the background of the generated image(s). 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.	transparent \| opaque \| auto · default: "auto"
input_fidelity	enum	Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to…	high \| low · nullable
input_image_mask	object	Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).
partial_images	integer	Number of partial images to generate in streaming mode, from 0 (default value) to 3.	0 ≤ n ≤ 3 · default: 0
action	enum	Whether to generate a new image or edit an existing image. Default: `auto`.	generate \| edit \| auto

ImageGenToolCallobject

An image generation request made by the model.

type*	enum	The type of the image generation call. Always `image_generation_call`.	image_generation_call
id*	string	The unique ID of the image generation call.
status*	enum	The status of the image generation call.	in_progress \| completed \| generating \| failed
result*	string	The generated image encoded in base64.	nullable
error	ImageGenToolCallError	Details of a moderation failure, when available.
size	string \| enum	The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`.	nullable
quality	enum	The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`.	low \| medium \| high \| xhigh \| max \| auto · nullable
action	enum	The action used for image generation.	generate \| edit \| auto · nullable
background	enum	The background setting used for generation.	transparent \| opaque \| auto · nullable
output_format	enum	The output format used for generation.	png \| webp \| jpeg \| gif \| svg · nullable
svg_usage	SvgUsage
revised_prompt	string	The prompt that was used after any model prompt rewriting.	nullable

ImageGenToolCallErrorobject

code*	string	The error code.	nullable
type*	string	The error type.
message*	string	A description of the error.
param*	string	The related request parameter.	nullable
moderation_details	ImageGenToolCallModerationDetails	Public details for a `moderation_blocked` error, when available.

ImageGenToolCallModerationDetailsobject

moderation_stage*	enum	The stage where moderation blocked the image generation call.	input \| output \| unknown
categories*	string[]	Public moderation categories. New category values may be added over time.

ImageOutputFormatenum

png | webp | jpeg | gif | svg

InlineSkillParamobject

type*	enum	Defines an inline skill for this request.	inline · default: "inline"
name*	string	The name of the skill.
description*	string	The description of the skill.
source*	InlineSkillSourceParam	Inline skill payload

InlineSkillSourceParamobject

Inline skill payload

type*	enum	The type of the inline skill source. Must be `base64`.	base64 · default: "base64"
media_type*	enum	The media type of the inline skill payload. Must be `application/zip`.	application/zip · default: "application/zip"
data*	string	Base64-encoded skill zip bundle.	length ≥ 1 · length ≤ 70254592

InputFidelityenum

Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to…

high | low

InputFileContentobject

A file input to the model.

type*	enum	The type of the input item. Always `input_file`.	input_file · default: "input_file"
file_id	string	The ID of the file to be sent to the model.	nullable
filename	string	The name of the file to be sent to the model.
file_data	string	The content of the file to be sent to the model.
prompt_cache_breakpoint	PromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.
file_url	string	The URL of the file to be sent to the model.	format: uri
detail	enum	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…	auto \| low \| high

InputImageContentobject

An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision).

type*	enum	The type of the input item. Always `input_image`.	input_image · default: "input_image"
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.	format: uri · nullable
file_id	string	The ID of the file to be sent to the model.	nullable
detail*	enum	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
prompt_cache_breakpoint	PromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

InputTextContentobject

A text input to the model.

type*	enum	The type of the input item. Always `input_text`.	input_text · default: "input_text"
text*	string	The text input to the model.
prompt_cache_breakpoint	PromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

KeyPressActionobject

A collection of keypresses the model would like to perform.

type*	enum	Specifies the event type. For a keypress action, this property is always set to `keypress`.	keypress · default: "keypress"
keys*	string[]	The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

LegacyComputerActionClick | DoubleClick | Drag | …

LocalEnvironmentParamobject

type*	enum	Use a local computer environment.	local · default: "local"
skills	LocalSkillParam[]	An optional list of skills.	items ≤ 200

LocalEnvironmentResourceobject

Represents the use of a local environment to perform shell actions.

type*

enum

The environment type. Always `local`.

local · default: "local"

LocalShellExecActionobject

Execute a shell command on the server.

type*	enum	The type of the local shell action. Always `exec`.	exec · default: "exec"
command*	string[]	The command to run.
timeout_ms	integer	Optional timeout in milliseconds for the command.	nullable
working_directory	string	Optional working directory to run the command in.	nullable
env*	object	Environment variables to set for the command.
user	string	Optional user to run the command as.	nullable

LocalShellToolCallobject

A tool call to run a command on the local shell.

type*	enum	The type of the local shell call. Always `local_shell_call`.	local_shell_call
id*	string	The unique ID of the local shell call.
call_id*	string	The unique ID of the local shell tool call generated by the model.
action*	LocalShellExecAction	Execute a shell command on the server.
status*	enum	The status of the local shell call.	in_progress \| completed \| incomplete

LocalShellToolCallOutputobject

The output of a local shell tool call.

type*	enum	The type of the local shell tool call output. Always `local_shell_call_output`.	local_shell_call_output
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.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete · nullable

LocalShellToolParamobject

A tool that allows the model to execute shell commands in a local environment.

type*

enum

The type of the local shell tool. Always `local_shell`.

local_shell · default: "local_shell"

LocalSkillParamobject

name*	string	The name of the skill.
description*	string	The description of the skill.
path*	string	The path to the directory containing the skill.

LogProbobject

The log probability of a token.

token*	string
logprob*	number
bytes*	integer[]
top_logprobs*	TopLogProb[]

MCPApprovalRequestobject

A request for human approval of a tool invocation.

type*	enum	The type of the item. Always `mcp_approval_request`.	mcp_approval_request
id*	string	The unique ID of the approval request.
server_label*	string	The label of the MCP server making the request.
name*	string	The name of the tool to run.
arguments*	string	A JSON string of arguments for the tool.

MCPApprovalResponseResourceobject

A response to an MCP approval request.

type*	enum	The type of the item. Always `mcp_approval_response`.	mcp_approval_response
id*	string	The unique ID of the approval response
approval_request_id*	string	The ID of the approval request being answered.
approve*	boolean	Whether the request was approved.
reason	string	Optional reason for the decision.	nullable

MCPListToolsobject

A list of tools available on an MCP server.

type*	enum	The type of the item. Always `mcp_list_tools`.	mcp_list_tools
id*	string	The unique ID of the list.
server_label*	string	The label of the MCP server.
tools*	MCPListToolsTool[]	The tools available on the server.
error	string	Error message if the server could not list tools.	nullable

MCPListToolsToolobject

A tool available on an MCP server.

name*	string	The name of the tool.
description	string	The description of the tool.	nullable
input_schema*	object	The JSON schema describing the tool's input.
annotations	object	Additional annotations about the tool.	nullable

MCPProtocolErrorobject

type*	enum	mcp_protocol_error · default: "mcp_protocol_error"
code*	integer
message*	string

MCPToolobject

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).

type*	enum	The type of the MCP tool. Always `mcp`.	mcp
server_label*	string	A label for this MCP server, used to identify it in tool calls.
server_url	string	The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided.	format: uri
connector_id	enum	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://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).	connector_dropbox \| connector_gmail \| connector_googlecalendar \| connector_googledrive \| connector_microsoftteams \| connector_outlookcalendar · +2 more · deprecated
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.
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.
server_description	string	Optional description of the MCP server, used to provide more context.
headers	object	Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.	nullable
allowed_tools	string[] \| MCP tool filter	List of allowed tool names or a filter object.	nullable
allowed_callers	CallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable
require_approval	MCP tool approval filter \| enum	Specify which of the MCP server's tools require approval.	default: "always" · nullable
defer_loading	boolean	Whether this MCP tool is deferred and discovered via tool search.

MCPToolCallobject

An invocation of a tool on an MCP server.

type*	enum	The type of the item. Always `mcp_call`.	mcp_call
id*	string	The unique ID of the tool call.
server_label*	string	The label of the MCP server running the tool.
name*	string	The name of the tool that was run.
arguments*	string	A JSON string of the arguments passed to the tool.
output	string	The output from the tool call.	nullable
error	object \| object \| object	The error from the tool call, if any.	nullable
status	enum	The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`.	in_progress \| completed \| incomplete \| calling \| failed
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.	nullable

MCPToolCallErrorobject | object | object

MCPToolCallStatusenum

in_progress | completed | incomplete | calling | failed

MCPToolExecutionErrorobject

type*	enum		mcp_tool_execution_error · default: "mcp_tool_execution_error"
content*	any

MCPToolFilterobject

A filter object to specify which tools are allowed.

tool_names	string[]	List of allowed tool names.
read_only	boolean	Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter.

Messageobject

A message to or from the model.

type*	enum	The type of the message. Always set to `message`.	message · default: "message"
id*	string	The unique ID of the message.
status*	enum	The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete
role*	enum	The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`.	unknown \| user \| assistant \| system \| critic \| discriminator · +2 more
content*	InputTextContent \| OutputTextContent \| TextContent[]	The content of the message
phase	enum	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 deg…	commentary \| final_answer · nullable

MessagePhase-2enum

commentary | final_answer

MessageRoleenum

MessageStatusenum

in_progress | completed | incomplete

MoveParamobject

A mouse move action.

type*	enum	Specifies the event type. For a move action, this property is always set to `move`.	move · default: "move"
x*	integer	The x-coordinate to move to.
y*	integer	The y-coordinate to move to.
keys	string[]	The keys being held while moving the mouse.	nullable

NamespaceToolParamobject

Groups function/custom tools under a shared namespace.

type*	enum	The type of the tool. Always `namespace`.	namespace · default: "namespace"
name*	string	The namespace name used in tool calls (for example, `crm`).	length ≥ 1
description*	string	A description of the namespace shown to the model.
tools*	FunctionToolParam \| CustomToolParam[]	The function/custom tools available inside this namespace.	items ≥ 1

OutputTextContentobject

A text output from the model.

type*	enum	The type of the output text. Always `output_text`.	output_text · default: "output_text"
text*	string	The text output from the model.
annotations*	Annotation[]	The annotations of the text output.
logprobs	LogProb[]

Programobject

type*	enum	The type of the item. Always `program`.	program · default: "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.

ProgrammaticToolCallingParamobject

type*

enum

The type of the tool. Always `programmatic_tool_calling`.

programmatic_tool_calling · default: "programmatic_tool_calling"

ProgramOutputobject

type*	enum	The type of the item. Always `program_output`.	program_output · default: "program_output"
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*	enum	The terminal status of the program output item.	completed \| incomplete

ProgramOutputStatusenum

completed | incomplete

ProgramToolCallCallerobject

type*	enum		program · default: "program"
caller_id*	string	The call ID of the program item that produced this tool call.

ProgramToolCallCallerParamobject

type*	enum	The caller type. Always `program`.	program · default: "program"
caller_id*	string	The call ID of the program item that produced this tool call.	length ≥ 1 · length ≤ 64

PromptCacheBreakpointConfigobject

Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

mode*	enum	The breakpoint mode. Always `explicit`.	explicit · default: "explicit"
ttl	enum	The minimum lifetime of this cache breakpoint. Defaults to the request TTL.	30m \| 12h

RankerVersionTypeenum

auto | default-2024-11-15

RankingOptionsobject

ranker	enum	The ranker to use for the file search.	auto \| default-2024-11-15
score_threshold	number	The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.
hybrid_search	HybridSearchOptions	Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

ReasoningEffortenum

Constrains effort on reasoning for reasoning models. Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Not a…

ReasoningEffortEnumenum

ReasoningItemobject

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://developers.op…

type*	enum	The type of the object. Always `reasoning`.	reasoning
id*	string	The unique identifier of the reasoning content.
encrypted_content	string	The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests.	nullable
summary*	Summary[]	Reasoning summary content.
content	ReasoningTextContent[]	Reasoning text content.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

ReasoningTextContentobject

Reasoning text from the model.

type*	enum	The type of the reasoning text. Always `reasoning_text`.	reasoning_text · default: "reasoning_text"
text*	string	The reasoning text from the model.

RefusalContentobject

A refusal from the model.

type*	enum	The type of the refusal. Always `refusal`.	refusal · default: "refusal"
refusal*	string	The refusal explanation from the model.

ResponseConfigurationUpdateobject

A configuration update for subsequent responses. Each setting stays in effect until a later update replaces that setting.

id*	string	The unique ID of the configuration update item.
type*	enum	The item type. Always `configuration_update`.	configuration_update · default: "configuration_update"
reasoning	object	The reasoning configuration applied by this update.
text	object	The text output configuration for subsequent responses.

ResponseFormatJsonSchemaSchemaobject

The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/).

ResponseFormatTextobject

Default response format. Used to generate text responses.

type*

enum

The type of response format being defined. Always `text`.

text

ScreenshotParamobject

A screenshot action.

type*

enum

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

screenshot · default: "screenshot"

ScrollParamobject

A scroll action.

type*	enum	Specifies the event type. For a scroll action, this property is always set to `scroll`.	scroll · default: "scroll"
x*	integer	The x-coordinate where the scroll occurred.
y*	integer	The y-coordinate where the scroll occurred.
scroll_x*	integer	The horizontal scroll distance.
scroll_y*	integer	The vertical scroll distance.
keys	string[]	The keys being held while scrolling.	nullable

SearchContentTypeenum

text | image

SearchContextSizeenum

low | medium | high

SkillReferenceParamobject

type*	enum	References a skill created with the /v1/skills endpoint.	skill_reference · default: "skill_reference"
skill_id*	string	The ID of the referenced skill.	length ≥ 1 · length ≤ 64
version	string	Optional skill version. Use a positive integer or 'latest'. Omit for default.

Summaryobject

A summary text from the model.

type*	enum	The type of the object. Always `summary_text`.	summary_text · default: "summary_text"
text*	string	A summary of the reasoning output from the model so far.

SummaryTextContentobject

A summary text from the model.

type*	enum	The type of the object. Always `summary_text`.	summary_text · default: "summary_text"
text*	string	A summary of the reasoning output from the model so far.

SvgParamobject

model	string		length ≥ 1
reasoning	SvgReasoningParam	Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.	nullable

SvgReasoningParamobject

Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.

effort

enum

Controls how much effort the model should spend on reasoning for this request.

SvgUsageobject

model*	string
input_tokens*	integer
output_tokens*	integer
total_tokens*	integer
reasoning_tokens*	integer

TextContentobject

A text content.

type*	enum		text · default: "text"
text*	string

TextResponseFormatJsonSchemaobject

JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs).

type*	enum	The type of response format being defined. Always `json_schema`.	json_schema
description	string	A description of what the response format is for, used by the model to determine how to respond in the format.
name*	string	The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
schema*	ResponseFormatJsonSchemaSchema	The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/).
strict	boolean	Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Struc…	default: false · nullable

ToolFunction | File search | Computer | …

A tool that can be used to generate a response.

ToolCallCallerobject | object

The execution context that produced this tool call.

ToolCallCallerParamobject | object

The execution context that produced this tool call.

ToolSearchCallobject

type*	enum	The type of the item. Always `tool_search_call`.	tool_search_call · default: "tool_search_call"
id*	string	The unique ID of the tool search call item.
call_id*	string	The unique ID of the tool search call generated by the model.	nullable
execution*	enum	Whether tool search was executed by the server or by the client.	server \| client
arguments*	any	Arguments used for the tool search call.
status*	enum	The status of the tool search call item that was recorded.	in_progress \| completed \| incomplete
created_by	string	The identifier of the actor that created the item.

ToolSearchExecutionTypeenum

server | client

ToolSearchOutputobject

type*	enum	The type of the item. Always `tool_search_output`.	tool_search_output · default: "tool_search_output"
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.	nullable
execution*	enum	Whether tool search was executed by the server or by the client.	server \| client
tools*	Tool[]	The loaded tool definitions returned by tool search.
status*	enum	The status of the tool search output item that was recorded.	in_progress \| completed \| incomplete
created_by	string	The identifier of the actor that created the item.

ToolSearchToolParamobject

Hosted or BYOT tool search configuration for deferred tools.

type*	enum	The type of the tool. Always `tool_search`.	tool_search · default: "tool_search"
execution	enum	Whether tool search is executed by the server or by the client.	server \| client
description	string	Description shown to the model for a client-executed tool search tool.	nullable
parameters	EmptyModelParam	Parameter schema for a client-executed tool search tool.	nullable

TopLogProbobject

The top log probability of a token.

token*	string
logprob*	number
bytes*	integer[]

TypeParamobject

An action to type in text.

type*	enum	Specifies the event type. For a type action, this property is always set to `type`.	type · default: "type"
text*	string	The text to type.

UrlCitationBodyobject

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

type*	enum	The type of the URL citation. Always `url_citation`.	url_citation · default: "url_citation"
url*	string	The URL of the web resource.	format: uri
start_index*	integer	The index of the first character of the URL citation in the message.
end_index*	integer	The index of the last character of the URL citation in the message.
title*	string	The title of the web resource.

VectorStoreFileAttributesobject

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 characte…

nullable

WaitParamobject

A wait action.

type*

enum

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

wait · default: "wait"

WebSearchActionFindobject

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

type*	enum	The action type.	find_in_page
url*	string	The URL of the page searched for the pattern.	format: uri
pattern*	string	The pattern or text to search for within the page.

WebSearchActionOpenPageobject

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

type*	enum	The action type.	open_page
url	string	The URL opened by the model.	format: uri · nullable

WebSearchActionSearchobject

Action type "search" - Performs a web search query.

type*	enum	The action type.	search
query	string	The search query.	deprecated
queries	string[]	The search queries.
sources	Web search source[]	The sources used in the search.

WebSearchApproximateLocationobject

The approximate location of the user.

type	enum	The type of location approximation. Always `approximate`.	approximate · default: "approximate"
country	string	The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.	nullable
region	string	Free text input for the region of the user, e.g. `California`.	nullable
city	string	Free text input for the city of the user, e.g. `San Francisco`.	nullable
timezone	string	The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.	nullable

WebSearchCallStatusenum

in_progress | searching | completed | failed | incomplete

WebSearchPreviewToolobject

This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).

type*	enum	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 · default: "web_search_preview"
user_location	ApproximateLocation	The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass `{"type": "approximate"}` without location fields. To localize results, provide the relevant location fields.	nullable
search_context_size	enum	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
search_content_types	SearchContentType[]

WebSearchToolobject

Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).

type*	enum	The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.	web_search \| web_search_2025_08_26 · default: "web_search"
external_web_access	boolean	Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.	default: true
filters	object	Filters for the search.	nullable
user_location	object	The approximate location of the user.	nullable
search_context_size	enum	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 · default: "medium"

WebSearchToolCallobject

The results of a web search tool call. See the [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information.

id*	string	The unique ID of the web search tool call.
type*	enum	The type of the web search tool call. Always `web_search_call`.	web_search_call
status*	enum	The status of the web search tool call.	in_progress \| searching \| completed \| failed \| incomplete
action*	Search action \| Open page action \| Find action	An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page).

Validate a payload

before you spend tokens

shell

$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"openai","endpointId":"conversations/{conversation_id}/items","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}

/v1/schemas/openai/chat/conversations/{conversation_id}/items?kind=output

Response body

Types

AdditionalToolsobject

AnnotationFile citation | URL citation | Container file citation | …

ApplyPatchCallOutputStatusenum

ApplyPatchCallStatusenum

ApplyPatchCreateFileOperationobject

ApplyPatchDeleteFileOperationobject

ApplyPatchToolCallobject

ApplyPatchToolCallOutputobject

ApplyPatchToolParamobject

ApplyPatchUpdateFileOperationobject

ApproximateLocationobject

CallableToolAllowedCallerenum

ClickButtonTypeenum

ClickParamobject

CodeInterpreterContainerAutoobject

CodeInterpreterOutputImageobject

CodeInterpreterOutputLogsobject

CodeInterpreterToolobject

CodeInterpreterToolCallobject

CompactionBodyobject

ComparisonFilterobject

ComparisonFilterValueItemsstring | number

CompoundFilterobject

ComputerActionClick | DoubleClick | Drag | …

ComputerActionListComputerAction[]

ComputerCallOutputStatusenum

ComputerCallSafetyCheckParamobject

ComputerEnvironmentenum

ComputerScreenshotContentobject

ComputerScreenshotImageobject

ComputerToolobject

ComputerToolCallobject

ComputerToolCallOutputobject

ComputerToolCallOutputResourceComputer tool call output | object

ComputerUsePreviewToolobject

ContainerAutoParamobject

ContainerFileCitationBodyobject

ContainerMemoryLimitenum

ContainerNetworkPolicyAllowlistParamobject

ContainerNetworkPolicyDisabledParamobject

ContainerNetworkPolicyDomainSecretParamobject

ContainerReferenceParamobject

ContainerReferenceResourceobject

ConversationItemMessage | any | any | …

CoordParamobject

CustomGrammarFormatParamobject

CustomTextFormatParamobject

CustomToolCallobject

CustomToolCallOutputobject

CustomToolParamobject

DirectToolCallCallerobject

DirectToolCallCallerParamobject

DoubleClickActionobject

DragParamobject

EmptyModelParamobject

FileCitationBodyobject

FileInputDetailenum

FilePathobject

FileSearchToolobject

FileSearchToolCallobject

FiltersComparison Filter | Compound Filter

FunctionAndCustomToolCallOutputInput text | Input image | Input file

FunctionCallOutputStatusEnumenum

FunctionCallStatusenum

FunctionShellActionobject

FunctionShellCallobject

FunctionShellCallOutputobject

FunctionShellCallOutputContentobject

FunctionShellCallOutputExitOutcomeobject

FunctionShellCallOutputStatusEnumenum

FunctionShellCallOutputTimeoutOutcomeobject

FunctionShellCallStatusenum

FunctionShellToolParamobject

FunctionToolobject

FunctionToolCallobject

FunctionToolCallOutputobject

FunctionToolCallOutputResourceFunction tool call output | object