GET

/v1/schemas/meta/chat/v1/responses

Accept:

kind inputactivity chathash 042c783b…extracted Nov 9, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. docs-derived Source trace `238ec411f2fb947674840ba1f46427d38b77db15a140590d781fdb2b4895836d` { "fetchedAt": 1794201665, "extractorVersion": "2", "verifiedAt": null }

Request body

28 properties · 0 required · 87 $defs

property	type	description	constraints
metadata	object		nullable
top_logprobs	integer	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)	0 ≤ n ≤ 20
temperature	number	What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1)	nullable
top_p	number	Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1)	nullable
user	string	Deprecated. 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	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)	length ≤ 64
prompt_cache_key	string	Groups similar requests to improve cache hit rates. Replaces the user field.
service_tier	enum		auto \| default \| flex \| scale \| priority · nullable
prompt_cache_retention	enum	The retention policy for the prompt cache.	in_memory \| 24h · nullable
previous_response_id	string	Identifier of a previous response to continue from. Use this to build multi-turn conversations with server-managed state. Cannot be combined with conversation.	nullable
model	string	ID of the model used to generate the response.
reasoning	reasoning		nullable
background	boolean	Whether to run the response asynchronously in the background. Cannot be combined with stream. (default: false)	nullable
max_tool_calls	integer	Maximum number of built-in tool calls allowed while generating a response, counted across all built-in tools rather than per tool. The model ignores any calls beyond this limit. (minimum: 1)	nullable
text	response-text-param
tools	tool[]
tool_choice	tool-choice-param
prompt	object		nullable
truncation	enum	Truncation strategy for the request. Only disabled (the default) is supported: if the input plus requested output tokens exceed the model's context window, the request fails with a 400 error. The auto strategy is not supported. (default: disabled)	auto \| disabled · nullable
client_metadata	object	Optional client-provided request metadata. Accepted for compatibility and ignored.	nullable
input	string \| input-item[]
include	include-enum[]	Additional output data to return in the response. Use message.output_text.logprobs to return token-level log probabilities on output text (set together with top_logprobs and a reasoning.effort of none), and reasoning.encrypted_content to return encrypted reasoning items for stateless multi-turn replay.	nullable
parallel_tool_calls	boolean	Whether the model may issue multiple tool calls in a single turn. (default: true)	nullable
store	boolean	Whether to persist the generated response so it can be retrieved later and chained from previous_response_id. (default: true)	nullable
instructions	string	Developer-level instructions inserted at the top of the model's context. When previous_response_id is set, instructions from the prior response are not carried forward, so you can change them on each turn. Top-level image models place these instructions immediately before the current user message instead, and also honor developer or system input messages that come before the first user message or after the most recent image_generation_call; those from earlier turns, and those stored with a previous response, are not carried forward. Top-level image models accept at most 12,000 characters across this field and those messages, returning a 400 error when the combined limit is exceeded.	nullable
stream	boolean	If true, the response is streamed to the client as server-sent events as it is generated. Cannot be combined with background. (default: false)	nullable
stream_options	object		nullable
max_output_tokens	integer	Upper bound on the number of tokens generated for the response, counting both visible output and reasoning tokens. Minimum is 16; values above the model's configured maximum, or that exceed the remaining context window, return a 400 error. (minimum: 16)	nullable

Types

87 $defs

annotationobject | object | object

click-button-typeenum

left | right | wheel | back | forward

click-paramobject

type*	enum	Specifies the event type. For a click action, this property is always click. (default: click)	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.

computer-actionobject | object | object | …

computer-action-listcomputer-action[]

computer-call-output-item-paramobject

id	string	The ID of the computer tool call output.	nullable
call_id*	string	The ID of the computer tool call that produced the output. (minLength: 1, maxLength: 64)	length ≥ 1 · length ≤ 64
type*	enum	The type of the computer tool call output. Always computer_call_output. (default: computer_call_output)	computer_call_output
output*	computer-screenshot-image
acknowledged_safety_checks	computer-call-safety-check-param[]	The safety checks reported by the API that have been acknowledged by the developer.	nullable
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 · nullable

computer-call-safety-check-paramobject

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

computer-screenshot-imageobject

type*	enum	Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. (default: computer_screenshot)	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.
detail	enum	The detail level of the screenshot. Always original when provided.	original

computer-toolobject

type*

enum

The type of the computer tool. Always computer. (default: computer)

computer

computer-tool-callobject

type*	enum	The type of the computer call. Always computer_call. (default: computer_call)	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	object \| object \| object \| …
actions	computer-action[]
pending_safety_checks*	computer-call-safety-check-param[]	The pending safety checks for the computer call.
meta_safety_replay_receipt	string	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; …	length ≥ 1 · length ≤ 8192
status*	enum	Item status. One of in_progress, completed, or incomplete. Populated when items are returned via API.	in_progress \| completed \| incomplete

coord-paramobject

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

detail-enumenum

low | high | auto | original

double-click-actionobject

type*	enum	Specifies the event type. For a double click action, this property is always set to double_click. (default: double_click)	double_click
x*	integer	The x-coordinate where the double click occurred.
y*	integer	The y-coordinate where the double click occurred.

drag-paramobject

type*	enum	Specifies the event type. For a drag action, this property is always set to drag. (default: drag)	drag
path*	coord-param[]	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 } ]

easy-input-messageobject

role*	enum	Role of the message author. One of user, assistant, system, or developer.	user \| assistant \| system \| developer
content*	string \| input-content[]	Message content. Either plain text or an array of content parts (text, image, file, or video). Can replay previous assistant output.
phase	enum		commentary \| final_answer · nullable
type	enum	Object type; always message.	message

empty-model-paramobject

file-citation-bodyobject

type*	enum	Annotation type; always file_citation. (default: file_citation)	file_citation
file_id*	string	Identifier of the cited file.
index*	integer	Position of the cited file in the list of files.
filename*	string	Name of the cited file.

file-detail-enumenum

low | high

file-input-detailenum

low | high

file-pathobject

type*	enum	Annotation type; always file_path.	file_path
file_id*	string	Identifier of the referenced file.
index*	integer	Position of the referenced file in the list of files.

function-call-item-statusenum

in_progress | completed | incomplete

function-call-output-content-list-paraminput-text-content-param[] | object | object

function-call-output-item-paramobject

id	string	Identifier for this function tool call output; set when the item is returned by the API.	nullable
call_id*	string	Identifier of the function tool call this output answers. (minLength: 1, maxLength: 64)	length ≥ 1 · length ≤ 64
type*	enum	Item type; always function_call_output. (default: function_call_output)	function_call_output
output*	string \| input-text-content-param[] \| input-image-content-param-auto-param \| input-file-content-param	The function tool call output, as text or content parts.
status	enum	Item status: in_progress, completed, or incomplete. Set when the item is returned by the API.	in_progress \| completed \| incomplete · nullable

function-call-output-text-paramstring

function-toolobject

type*	enum	The tool type; always function. (default: function)	function
name*	string	Name of the function the model can call.
description	string	Describes the function so the model can decide whether to call it.	nullable
parameters*	object	JSON Schema object that defines the function's parameters.	nullable
strict	boolean	Whether the model must produce arguments that match the parameters schema exactly. Defaults to true.	nullable
defer_loading	boolean	When true, defers this function so it is discovered on demand through tool search.

function-tool-callobject

id	string	Identifier for this function tool call.
type*	enum	Item type; always function_call.	function_call
call_id*	string	Identifier the model assigned to this function tool call. (minLength: 1, maxLength: 64)	length ≥ 1 · length ≤ 64
namespace	string	Namespace of the function to run.
name*	string	Name of the function to run.
arguments*	string	Arguments to pass to the function, as a JSON string.
status	enum	Item status: in_progress, completed, or incomplete. Set when the item is returned by the API.	in_progress \| completed \| incomplete

image-detailenum

low | high | auto | original

include-enumenum

input-audio-contentobject

type*	enum	Content-part type; always input_audio. (default: input_audio)	input_audio
input_audio	object	Inline base64-encoded audio and its format.
audio_url	string	URL of the audio to send to the model. Fully qualified URL or base64-encoded data URL.	nullable
file_id	string	Identifier for the uploaded audio file to send to the model.	nullable

input-contentobject | object | object | …

input-file-contentobject

type*	enum	Content-part type; always input_file. (default: input_file)	input_file
file_id	string	Identifier for the file to send to the model.	nullable
filename	string	Name of the file passed to the model.
file_data	string	Contents of the file passed to the model.
file_url	string	URL of the file passed to the model.
detail	enum	Render detail for the file: low for default rendering, high for higher quality. Defaults to low.	low \| high

input-file-content-paramobject

type*	enum	Content-part type; always input_file. (default: input_file)	input_file
file_id	string	Identifier for the file to send to the model.	nullable
filename	string	Name of the file to send to the model.	nullable
file_data	string	Base64-encoded file data to send to the model. (maxLength: 73400320)	nullable
file_url	string	URL of the file to send to the model.	nullable
detail	enum	Render detail for the file: low for default rendering, high for higher quality. Defaults to low.	low \| high

input-image-contentobject

type*	enum	Content-part type; always input_image. (default: input_image)	input_image
image_url	string	URL of the image to send to the model. Fully qualified URL or base64-encoded data URL.	nullable
file_id	string	Identifier for the file to send to the model.	nullable
detail	enum	Render detail for the image: one of high, low, auto, or original. Defaults to auto.	low \| high \| auto \| original

input-image-content-param-auto-paramobject

type*	enum	Content-part type; always input_image. (default: input_image)	input_image
image_url	string	URL of the image to send to the model. Fully qualified URL or base64-encoded data URL. (maxLength: 20971520)	nullable
file_id	string	Identifier for the file to send to the model.	nullable
detail	enum	Image detail level. One of high, low, auto, or original. Defaults to auto.	low \| high \| auto \| original · nullable

input-itemobject | input-message | output-message | computer-tool-call | object

input-messageobject

type	enum	Item type; always message.	message
role*	enum	Author role: one of user, system, or developer.	user \| system \| developer
status	enum	Item status: in_progress, completed, or incomplete. Set when the item is returned by the API.	in_progress \| completed \| incomplete
content*	input-content[]

input-message-content-listinput-content[]

input-paramstring | input-item[]

input-text-contentobject

type*	enum	Content-part type; always input_text. (default: input_text)	input_text
text*	string	The input text.

input-text-content-paramobject

type*	enum	Content-part type; always input_text. (default: input_text)	input_text
text*	string	The input text. (maxLength: 10485760)	length ≤ 10485760

input-video-contentobject

type*	enum	Object type; always input_video. (default: input_video)	input_video
video_url	string	URL of the video to send to the model. Fully qualified URL or base64-encoded data URL.	nullable
file_id	string	Identifier for the file to send to the model.	nullable
fps	number	Frames per second for video sampling. Defaults to backend-chosen rate.	nullable

itemobject | object | object | …

item-reference-paramobject

type	enum	Object type; always item_reference. (default: item_reference)	item_reference · nullable
id*	string	Identifier of the item to reference.

key-press-actionobject

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

log-probobject

token*	string
logprob	number	Log probability of this token. May be null when the backend omits the value.	nullable
bytes*	integer[]
top_logprobs*	top-log-prob[]

message-phaseenum

commentary | final_answer

metadataobject

nullable

move-paramobject

type*	enum	Specifies the event type. For a move action, this property is always set to move. (default: move)	move
x*	integer	The x-coordinate to move to.
y*	integer	The y-coordinate to move to.

output-messageobject

id	string	Identifier for this output message.
type*	enum	Item type; always message.	message
role*	enum	Author role; always assistant.	assistant
content*	output-message-content[]	The output message content.
phase	enum		commentary \| final_answer · nullable
status	enum	Item status: in_progress, completed, or incomplete. Set when the item is returned by the API.	in_progress \| completed \| incomplete

output-message-contentobject | object

output-text-contentobject

type*	enum	Content-part type; always output_text. (default: output_text)	output_text
text*	string	The generated text.
annotations	annotation[]	Annotations attached to the text output.
logprobs	log-prob[]

promptobject

nullable

reasoningobject

effort	enum		none \| minimal \| low \| medium \| high \| xhigh · +1 more · nullable
summary	enum	A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed.	auto \| concise \| detailed · nullable
generate_summary	enum	Deprecated: use summary instead. A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed.	auto \| concise \| detailed · nullable

reasoning-effortenum

reasoning-item-paramobject

type*	enum	Object type; always reasoning.	reasoning
id	string	Identifier for this reasoning item. Optional on input; required on output.
encrypted_content	string	Opaque encrypted content for stateless multi-turn replay. Populated when a response is generated with reasoning.encrypted_content in the include parameter.	nullable
summary*	summary-text-content[]	Summarized reasoning content.
content	reasoning-text-content[]	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

reasoning-text-contentobject

type*	enum	Content-part type; always reasoning_text. (default: reasoning_text)	reasoning_text
text*	string	The reasoning text.

refusal-contentobject

type*	enum	Object type; always refusal. (default: refusal)	refusal
refusal*	string	The refusal explanation from the model.

response-format-json-objectobject

type*

enum

Response-format type; always json_object.

json_object

response-format-json-schema-schemaobject

response-format-textobject

type*

enum

Response-format type; always text.

text

response-stream-optionsobject

nullable

response-text-paramobject

format

object | object | object

screenshot-paramobject

type*

enum

Specifies the event type. For a screenshot action, this property is always set to screenshot. (default: screenshot)

screenshot

scroll-paramobject

type*	enum	Specifies the event type. For a scroll action, this property is always set to scroll. (default: scroll)	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.

service-tierenum

auto | default | flex | scale | priority · nullable

summary-text-contentobject

type*	enum	Object type; always summary_text. (default: summary_text)	summary_text
text*	string	A summary of the reasoning output from the model so far.

text-response-format-configurationobject | object | object

text-response-format-json-schemaobject

type*	enum	Response-format type; always json_schema.	json_schema
description	string	Describes what the format is for; the model uses it to decide how to respond.
name*	string	Name of the response format. Allowed characters: a-z, A-Z, 0-9, underscores, and dashes, up to 64 characters.
schema*	response-format-json-schema-schema
strict	boolean	When true, the model must produce output that strictly conforms to the JSON Schema in the schema field. Only a subset of JSON Schema is supported in this mode. (default: false)	nullable

toolobject | object | object | …

tool-choice-optionsenum

auto

tool-choice-paramenum

auto

tool-search-call-item-paramobject

id	string	The unique ID of this tool search call.	nullable
call_id	string	The unique ID of the tool search call generated by the model. (minLength: 1, maxLength: 64)	nullable
type*	enum	The item type. Always tool_search_call. (default: tool_search_call)	tool_search_call
execution	enum	Whether tool search was executed by the server or by the client.	server \| client
arguments*	empty-model-param	The arguments supplied to the tool search call.
status	enum	The status of the tool search call.	in_progress \| completed \| incomplete · nullable

tool-search-execution-typeenum

server | client

tool-search-output-item-paramobject

id	string	The unique ID of this tool search output.	nullable
call_id	string	The unique ID of the tool search call generated by the model. (minLength: 1, maxLength: 64)	nullable
type*	enum	The item type. Always tool_search_output. (default: tool_search_output)	tool_search_output
execution	enum	Whether tool search was executed by the server or by the client.	server \| client
tools*	tool[]	The loaded tool definitions returned by the tool search output.
status	enum	The status of the tool search output.	in_progress \| completed \| incomplete · nullable

tool-search-tool-paramobject

type*	enum	The type of the tool. Always tool_search. (default: tool_search)	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	empty-model-param	Parameter schema for a client-executed tool search tool.	nullable

tools-arraytool[]

top-log-probobject

token*	string
logprob	number	Log probability of this token. May be null when the backend omits the value.	nullable
bytes*	integer[]

type-paramobject

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

url-citation-bodyobject

type*	enum	Annotation type; always url_citation. (default: url_citation)	url_citation
url*	string	URL of the cited web resource.
start_index*	integer	Character offset where the cited span begins in the output text.
end_index*	integer	Character offset where the cited span ends in the output text.
title*	string	Title of the cited web resource.

wait-paramobject

type*

enum

Specifies the event type. For a wait action, this property is always set to wait. (default: wait)

wait

web-search-action-findobject

type*	enum	Action type; always find_in_page.	find_in_page
url*	string	URL of the page that was searched.	format: uri
pattern*	string	Text pattern searched for within the page.

web-search-action-open-pageobject

type*	enum	Action type; always open_page.	open_page
url	string	URL the model opened.	format: uri · nullable

web-search-action-searchobject

type*	enum	Action type; always search.	search
query*	string	[DEPRECATED] The search query. Use queries instead.
queries	string[]	The search queries issued in this action.
sources	object[]	Sources consulted during the search.
downstream_request_id	string	Identifier for the downstream search request, surfaced for debugging.

web-search-approximate-locationobject

nullable

web-search-result-itemobject

type	string	The result type.
title	string	Title of the result.
url	string	URL of the result.
snippet	string	Text snippet excerpted from the result.

web-search-toolobject

type*	enum	The tool type; one of web_search or web_search_2025_08_26. (default: web_search)	web_search \| web_search_2025_08_26
filters	object	Filters that narrow the search.	nullable
user_location	object		nullable
search_context_size	enum	How much context window space the search may use; one of low, medium, or high, defaulting to medium. (default: medium)	low \| medium \| high

web-search-tool-call-paramobject

id	string	Identifier for this web search tool call. Optional on input; omit it when replaying a turn for which no identifier was issued.
type*	enum	Item type; always web_search_call.	web_search_call
status*	enum	Status of the web search tool call.	in_progress \| searching \| completed \| failed
action*	object \| object \| object	The specific action taken in this web search call, such as search, open_page, or find_in_page.
results	web-search-result-item[]	Results from the web search tool call. Populated only when the request's include array contains web_search_call.results.	nullable

Validate a payload

before you spend tokens

shell

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