Responses schemas

The full schema and model definitions referenced by the Responses endpoints. Each endpoint page links here for the detailed shape of its request and response objects.

Schemas

Annotation

Annotation attached to a span of generated output text, such as a citation or file reference.

Type: FileCitationBody | UrlCitationBody | FilePath

Cancel Response Response

The response object returned by the cancel endpoint. Only the lifecycle fields the server populates on cancel are present, and the output array is always empty.

Field	Type	Required	Description
`id`	`string`	Yes	Identifier for this response.
`object`	`enum ('response')`	Yes	Object type; always `response`.
`status`	`enum ('completed', 'failed', 'in_progress', 'cancelled', 'queued', 'incomplete')`	Yes	The status of the response generation. After a successful cancel of an in-progress response this is `cancelled`; for an already-terminal response the current terminal status is returned.
`model`	`string`	Yes	Model ID used to generate the response.
`background`	`boolean`	Yes	Whether the response was run in the background.
`output`	array of `OutputItem`	Yes	An array of content items generated by the model. Always empty on a cancelled response.

Click Button Type

Type: enum ('left', 'right', 'wheel', 'back', 'forward')

Click Param

A click action.

Field	Type	Required	Description
`type`	`enum ('click')`	Yes	Specifies the event type. For a click action, this property is always `click`. (default: click)
`button`	`ClickButtonType`	Yes	Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.
`x`	`integer`	Yes	The x-coordinate where the click occurred.
`y`	`integer`	Yes	The y-coordinate where the click occurred.

Compaction Body

A compaction item produced when earlier conversation context is compacted into an encrypted summary.

Field	Type	Required	Description
`type`	`enum ('compaction')`	Yes	Object type; always `compaction`. (default: compaction)
`id`	`string`	Yes	Identifier for the compaction item.
`encrypted_content`	`string`	Yes	Encrypted content for stateless multi-turn replay.
`created_by`	`string`	No	Identifier for the actor that created the item.

Compaction Summary Item Param

A compaction item produced when earlier conversation context is compacted into an encrypted summary.

Field	Type	Required	Description
`id`	`string` \| `null`	No
`type`	`enum ('compaction')`	Yes	Object type; always `compaction`. (default: compaction)
`encrypted_content`	`string`	Yes	Encrypted content for stateless multi-turn replay. (maxLength: 10485760)

Computer Action

Computer Action List

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

Type: array of ComputerAction

Computer Call Output Item Param

The output of a computer tool call.

Field	Type	Required	Description
`id`	`string` \| `null`	No
`call_id`	`string`	Yes	The ID of the computer tool call that produced the output. (minLength: 1, maxLength: 64)
`type`	`enum ('computer_call_output')`	Yes	The type of the computer tool call output. Always `computer_call_output`. (default: computer_call_output)
`output`	`ComputerScreenshotImage`	Yes
`acknowledged_safety_checks`	array of `ComputerCallSafetyCheckParam` \| `null`	No
`status`	`FunctionCallItemStatus` \| `null`	No

Computer Call Output Status

Type: enum ('completed', 'incomplete', 'failed')

Computer Call Safety Check Param

A pending safety check for the computer call.

Field	Type	Required	Description
`id`	`string`	Yes	The ID of the pending safety check.
`code`	`string` \| `null`	No
`message`	`string` \| `null`	No

Computer Screenshot Image

A computer screenshot image used with the computer use tool.

Field	Type	Required	Description
`type`	`enum ('computer_screenshot')`	Yes	Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. (default: computer_screenshot)
`image_url`	`string (uri)`	No	The URL of the screenshot image.
`file_id`	`string`	No	The identifier of an uploaded file that contains the screenshot.
`detail`	`enum ('original')`	No	The detail level of the screenshot. Always `original` when provided.

Computer Tool

A tool that controls a virtual computer.

Field	Type	Required	Description
`type`	`enum ('computer')`	Yes	The type of the computer tool. Always `computer`. (default: computer)

Computer Tool Call

A tool call to a computer use tool. See the computer use guide for more information.

Field	Type	Required	Description
`type`	`enum ('computer_call')`	Yes	The type of the computer call. Always `computer_call`. (default: computer_call)
`id`	`string`	Yes	The unique ID of the computer call.
`call_id`	`string`	Yes	An identifier used when responding to the tool call with output.
`action`	`ComputerAction`	No
`actions`	`ComputerActionList`	No
`pending_safety_checks`	array of `ComputerCallSafetyCheckParam`	Yes	The pending safety checks for the computer call.
`meta_safety_replay_receipt`	`string`	No	An opaque Meta wire extension containing a time-bounded receipt for the accepted native-computer safety replay prefix through this call. Stateless clients must copy it unchanged from `response.output` into the corresponding item under `input` on the next request; the matching call output still requires a fresh acknowledgement. (minLength: 1, maxLength: 8192)
`status`	`enum ('in_progress', 'completed', 'incomplete')`	Yes	Item status. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.

Computer Tool Call Output

The output of a computer tool call.

Field	Type	Required	Description
`type`	`enum ('computer_call_output')`	Yes	The type of the computer tool call output. Always `computer_call_output`. (default: computer_call_output)
`id`	`string`	No	The ID of the computer tool call output.
`call_id`	`string`	Yes	The ID of the computer tool call that produced the output.
`acknowledged_safety_checks`	array of `ComputerCallSafetyCheckParam`	No	The safety checks reported by the API that have been acknowledged by the developer.
`output`	`ComputerScreenshotImage`	Yes
`status`	`enum ('in_progress', 'completed', 'incomplete')`	No	The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API.

Computer Tool Call Output Resource

Field	Type	Required	Description
`type`	`enum ('computer_call_output')`	Yes	The type of the computer tool call output. Always `computer_call_output`. (default: computer_call_output)
`id`	`string`	Yes	The unique ID of the computer call tool output.
`call_id`	`string`	Yes	The ID of the computer tool call that produced the output.
`acknowledged_safety_checks`	array of `ComputerCallSafetyCheckParam`	No	The safety checks reported by the API that have been acknowledged by the developer.
`output`	`ComputerScreenshotImage`	Yes
`status`	`ComputerCallOutputStatus`	Yes	The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API.
`created_by`	`string`	No	Identifier for the actor that created the item.

Context Management Param

Field	Type	Required	Description
`type`	`string`	Yes	Context-management entry type; only `compaction` is currently supported.
`compact_threshold`	`integer` \| `null`	No

Conversation-2

The conversation this response belonged to. Its input and output items were added to that conversation automatically.

Field	Type	Required	Description
`id`	`string`	Yes	Identifier of the conversation this response belongs to.

Coord Param

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

Field	Type	Required	Description
`x`	`integer`	Yes	The x-coordinate.
`y`	`integer`	Yes	The y-coordinate.

Create Model Response Properties

Field	Type	Required	Description
`metadata`	`Metadata`	No
`top_logprobs`	`integer`	No	An integer between 0 and 20 giving the number of top alternative tokens to return at each position, each with its log probability. (minimum: 0, maximum: 20)
`temperature`	`number` \| `null`	No
`top_p`	`number` \| `null`	No
`user`	`string`	No	Being replaced by `safety_identifier` and `prompt_cache_key`; use `prompt_cache_key` to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse.
`safety_identifier`	`string`	No	A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64)
`prompt_cache_key`	`string`	No	Groups similar requests to improve cache hit rates. Replaces the `user` field.
`service_tier`	`ServiceTier`	No
`prompt_cache_retention`	`enum ('in_memory', '24h')` \| `null`	No

Create Response

Field	Type	Required	Description
`metadata`	`Metadata`	No
`top_logprobs`	`integer`	No	An integer between 0 and 20 giving the number of top alternative tokens to return at each position, each with its log probability. (minimum: 0, maximum: 20)
`temperature`	`number` \| `null`	No
`top_p`	`number` \| `null`	No
`user`	`string`	No	Being replaced by `safety_identifier` and `prompt_cache_key`; use `prompt_cache_key` to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse.
`safety_identifier`	`string`	No	A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64)
`prompt_cache_key`	`string`	No	Groups similar requests to improve cache hit rates. Replaces the `user` field.
`service_tier`	`ServiceTier`	No
`prompt_cache_retention`	`enum ('in_memory', '24h')` \| `null`	No
`previous_response_id`	`string` \| `null`	No
`model`	`string`	No	ID of the model used to generate the response.
`reasoning`	`Reasoning` \| `null`	No
`background`	`boolean` \| `null`	No
`max_tool_calls`	`integer` \| `null`	No
`text`	`ResponseTextParam`	No
`tools`	`ToolsArray`	No
`tool_choice`	`ToolChoiceParam`	No
`prompt`	`Prompt`	No
`truncation`	`enum ('auto', 'disabled')` \| `null`	No
`frequency_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from repeating tokens it has already used often, reducing verbatim repetition. (minimum: -2, maximum: 2, default: 0)
`presence_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from reusing tokens that have already appeared, encouraging it to introduce new topics. (minimum: -2, maximum: 2, default: 0)
`client_metadata`	`object` \| `null`	No
`input`	`InputParam`	No
`include`	array of `IncludeEnum` \| `null`	No
`parallel_tool_calls`	`boolean` \| `null`	No
`store`	`boolean` \| `null`	No
`instructions`	`string` \| `null`	No
`stream`	`boolean` \| `null`	No
`stream_options`	`ResponseStreamOptions`	No
`context_management`	array of `ContextManagementParam` \| `null`	No
`max_output_tokens`	`integer` \| `null`	No

Delete Response Response

Returned by the delete-response endpoint to confirm a response was deleted.

Field	Type	Required	Description
`id`	`string`	Yes	Identifier of the deleted response.
`object`	`enum ('response.deleted')`	Yes	Object type; always `response.deleted`.
`deleted`	`boolean`	Yes	Always `true` when the response was deleted.

Detail Enum

Type: enum ('low', 'high', 'auto', 'original')

Double Click Action

A double click action.

Field	Type	Required	Description
`type`	`enum ('double_click')`	Yes	Specifies the event type. For a double click action, this property is always set to `double_click`. (default: double_click)
`x`	`integer`	Yes	The x-coordinate where the double click occurred.
`y`	`integer`	Yes	The y-coordinate where the double click occurred.

Drag Param

A drag action.

Field	Type	Required	Description
`type`	`enum ('drag')`	Yes	Specifies the event type. For a drag action, this property is always set to `drag`. (default: drag)
`path`	array of `CoordParam`	Yes	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 } ]`

A message in a Responses input or replayed history. The developer and system roles carry instructions (developer takes precedence); user carries the caller's prompt; assistant replays prior model output.

Field	Type	Required	Description
`role`	`enum ('user', 'assistant', 'system', 'developer')`	Yes	Role of the message author. One of `user`, `assistant`, `system`, or `developer`.
`content`	`string` \| `InputMessageContentList`	Yes	Message content. Either plain text or an array of content parts (text, image, file, or video). Can replay previous assistant output.
`phase`	`MessagePhase` \| `null`	No
`type`	`enum ('message')`	No	Object type; always `message`.

Empty Model Param

Type: object

File Citation Body

Citation that points to an uploaded file used to ground the response.

Field	Type	Required	Description
`type`	`enum ('file_citation')`	Yes	Annotation type; always `file_citation`. (default: file_citation)
`file_id`	`string`	Yes	Identifier of the cited file.
`index`	`integer`	Yes	Position of the cited file in the list of files.
`filename`	`string`	Yes	Name of the cited file.

Field	Type	Required	Description
`type`	`enum ('file_path')`	Yes	Annotation type; always `file_path`.
`file_id`	`string`	Yes	Identifier of the referenced file.
`index`	`integer`	Yes	Position of the referenced file in the list of files.

Field	Type	Required	Description
`id`	`string` \| `null`	No
`call_id`	`string`	Yes	Identifier of the function tool call this output answers. (minLength: 1, maxLength: 64)
`type`	`enum ('function_call_output')`	Yes	Item type; always `function_call_output`. (default: function_call_output)