GET

/v1/schemas/grok/chat/v1/responses

Accept:

kind inputactivity chathash 6bca15fd…extracted Oct 28, 2026version currentsource upstream spec ↗

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

Request body

31 properties · 1 required · 50 $defs

property	type	description	constraints
input*	string \| ModelInputPart[]	The input passed to the model. Can be text, image or file.
background	any	(Unsupported) Whether to process the response asynchronously in the background.	default: false
context_management	any	Optional context-management directives (e.g. compaction). Parsed but not yet executed.
guidelines	any	Per-category instructions for model output. See [`Guideline`]. Omitted requests leave this unset. A request whose guidelines cannot be applied, for example on a multi-agent model or with `stop`, fails with 400.
include	any	What additional output data to include in the response. Supported values include `reasoning.encrypted_content` (encrypted reasoning tokens) and tool-output options. OpenAI's `message.output_text.logprobs` is accepted for compatibility but silently ignored.
instructions	any	An alternate way to specify the system prompt. Note that this cannot be used alongside `previous_response_id`, where the system prompt of the previous message will be used.
logprobs	any	Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message. Not supported by models `grok-4.20` and newer; the field will be silently ignored if set.	default: false
max_output_tokens	any	Max number of tokens that can be generated in a response. Only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls). Defaults to 128,000 when unset; set a larger value to allow longer generations.	format: int32
max_turns	any	Maximum number of agentic tool calling turns allowed for this request. If not set, defaults to the server's global cap. This parameter will be ignored for any non-agentic requests, and for agentic SLOP requests that have neither a server-side tool nor a file a…	format: int32
metadata	any	Not supported. Only maintained for compatibility reasons.
min_p	any	Min-p sampling: tokens whose probability is below `min_p` times the probability of the most likely token are excluded from sampling. Disabled when unset.	0 ≤ n ≤ 1 · format: float
model	string	Model name for the model to use. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>.
parallel_tool_calls	any	Whether to allow the model to run parallel tool calls.	default: true
previous_response_id	any	The ID of the previous response from the model.
prompt_cache_key	any	Plumbed to x-grok-conv-id for Open Responses compatibility, used for routing.
reasoning	ReasoningConfiguration	Reasoning configuration. Only for reasoning models.	nullable
reasoning_effort	any	Non-standard alternative to `reasoning.effort` that accepts the same values. We only look at this if the reasoning field is unset.
safety_identifier	any	Supplied by the API client to identify the end user behind this request. A stable string that uniquely identifies each of your users; hash your internal user id or username rather than sending an email or name. Stored with the request metadata so a usage-polic…
search_parameters	SearchParameters	Deprecated: live search has been removed, and requests that set this field fail with `410 Gone`. Use the `web_search` and `x_search` tools instead: <https://docs.x.ai/developers/tools/overview>.	nullable
service_tier	enum	Processing tier. `"fast"` and `"priority"` are interchangeable: on models with a fast deployment both use it and its rates; otherwise both mean higher scheduling priority at a higher price. Valid: `"auto"`, `"priority"`, `"fast"`.	default \| priority \| fast · nullable
store	any	Whether to store the input message(s) and model response for later retrieval.	default: true
stream	any	If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.	default: false
temperature	any	What sampling temperature to use, between 0 and 2. Values above 1 are sampled at 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.	0 ≤ n ≤ 2 · format: float · default: 1
text	ModelResponseConfiguration	Settings for customizing a text response from the model.	nullable
tool_choice	string \| object	Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one …	nullable
tools	any	A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 1000 tools are supported.	items ≤ 1000
top_k	any	Top-k sampling: only the `top_k` most probable tokens are considered at each sampling step. Disabled when unset.	n ≥ 1 · format: int32
top_logprobs	any	An integer between 0 and 8 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used. Not supported by models `grok-4.20` and newer; the field w…	0 ≤ n ≤ 8 · format: int32
top_p	any	An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally reco…	0 < n ≤ 1 · format: float · default: 0.95
truncation	any	Not supported. Only maintained for compatibility reasons.
user	any	A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

Types

50 $defs

Annotationobject

end_index	any	The end index of the annotation.	format: int32
start_index	any	The summary of the annotation.	format: int32
title	any	The title of the annotation.
type*	string	The type of the annotation. Only supported type currently is `url_citation`.
url*	string	The URL of the web resource.

CodeInterpreterCallobject

The output of a code interpreter tool call.

code	string	The code of the code interpreter tool call.
id	string	The unique ID of the code interpreter tool call.
outputs*	CodeInterpreterOutput[]	The outputs of the code interpreter tool call.
status	string	The status of the code interpreter tool call.
type*	string	The type of the code interpreter tool call. Always `code_interpreter_call`.

CodeInterpreterOutputobject | object

CompactionOutputItemobject

A compaction item from a previous `/v1/responses/compact` call.

encrypted_content*	string	The encrypted content of the compacted conversation.
id	any	The unique ID of the compaction item (e.g. `cmp_<uuid>`).
type*	string	The type of the item. Always `"compaction"`.

CustomToolCallobject

The output of a custom tool call.

call_id*	string	The unique ID of the function tool call generated by the model.
id*	string	The status of the custom tool call.
input	string	The unique ID of the custom tool call,
name*	string	An identifier used to map this custom tool call to a tool call output.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The input for the custom tool call generated by the model.

FileSearchCallobject

The output of a web search tool call.

id	string	The unique ID of the file search tool call.
queries*	string[]	The queries used to search for files.
results*	FileSearchResult[]	The results of the file search tool call.
status	string	The status of the file search tool call.
type*	string	The type of the file search tool call. Always `file_search_call`.

FileSearchResultobject

file_id*	string	The file ID of the file search result.
filename*	string	The filename of the file search result.
score	number	The score of the file search result. Proto3 omits float fields with value 0.0; default to 0.0 when absent.	format: double
text*	string	The text of the file search result.

FunctionDefinitionobject

Definition of the tool call made available to the model.

defer_loading	any	When true, the definition is hidden from the model's prompt but stays callable, loaded via a `tool_search` step (`/v1/responses` only).
description	any	A description of the function to indicate to the model when to call it.
name*	string	The name of the function. If the model calls the function, this name is used in the response.
parameters*	any	A JSON schema describing the function parameters. The model _should_ follow the schema, however, this is not enforced at the moment.
strict	any	Not supported. Only maintained for compatibility reasons.

FunctionToolCallobject

A tool call to run a function.

arguments*	string	The arguments to pass to the function, as a JSON string.
call_id*	string	The unique ID of the function tool call generated by the model.
id	string	The unique ID of the function tool call.
name*	string	The name of the function.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The type of the function tool call, which can be `"function_call"` for client-side tool calls, and `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` for server-side tool calls.

FunctionToolCallOutputobject

The output of a function tool call.

call_id*	string	The unique ID of the function tool call generated by the model.
output*	string \| ModelInputContentItem[]	The output of the function tool call. Can be a plain string or a list of content items (`input_text`, `input_image`, `input_file`).
type*	string	The type of the function tool call, which is always `function_call_output`.

Guidelineobject

One entry in [`ChatRequest::guidelines`] and [`ModelRequest::guidelines`].

behavior*	enum	How the model should handle a [`GuidelineCategory`].	decline \| allow
category*	enum	Content category a guideline applies to.	nsfw \| violence \| profanity \| cyber
type*	string	Discriminator. Must be `policy`.

GuidelineBehaviorenum

How the model should handle a [`GuidelineCategory`].

decline | allow

GuidelineCategoryenum

Content category a guideline applies to.

nsfw | violence | profanity | cyber

ImageGenerationCallobject

The output of an image generation tool call.

id	string	The unique ID of the image generation tool call.
prompt	any	The prompt used to generate the image.
result	any	The generated image encoded in base64 (OpenAI-compatible: bare base64, no data-URL prefix), or `null` while the call is still in progress or has failed. The image format can be determined from the decoded magic bytes (typically JPEG or PNG).
status	string	The status of the image generation tool call. One of `in_progress`, `generating`, `completed` or `failed`.
type*	enum	Type tag for [`ImageGenerationCall`]. Serializes as `"image_generation_call"`.	image_generation_call

LocalShellSkillobject

A skill available in the local shell environment.

description*	string	A description of what the skill does.
name*	string	The name of the skill.
path*	string	The path to the directory containing the skill (with a SKILL.md file).

McpCallobject

The output of a MCP tool call.

arguments*	string	A JSON string of the arguments passed to the tool.
error	string	The error message of the MCP tool call.
id	string	The unique ID of the MCP tool call.
name*	string	The name of the tool that was run.
output*	string	The output of the MCP tool call.
server_label*	string	The label of the MCP server running the tool.
status	string	The status of the MCP tool call.
type*	string	The type of the MCP tool call. Always `mcp_call`.

ModelInputstring | ModelInputPart[]

Content of the input passed to a `/v1/response` request.

ModelInputContentstring | ModelInputContentItem[]

ModelInputContentItemobject | object | object | …

ModelInputPartobject | any | any | …

ModelOutputany | any | any | …

ModelResponseConfigurationobject

format

object | object | object

An object specifying the format that the model must output. Specify `{ "type": "json_object" }` for JSON output, or `{ "type": "json_schema", "json_schema": {...} }` for structured outputs. If `{ \"type\": \"text\" }`, the model will return a text response.

nullable

ModelResponseFormatobject | object | object

Response format parameter for structured outputs.

ModelToolany | any | object | …

Definition of one tool that the model can call.

ModelToolChoicestring | object

Parameter to control how model chooses the tools.

OutputMessageobject

An output message from the model.

content*	OutputMessageContent[]	Content of the output message.
id	string	The unique ID of the output message.
role*	string	The role of the output message, which can be `assistant` or `tool`.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The type of the output message, which is always `message`.

OutputMessageContentobject | object

Reasoningobject

The reasoning done by the model.

content	ReasoningText[]	The reasoning text contents.
encrypted_content	any	The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`.
id	string	The unique ID of the reasoning content.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
summary*	SummaryText[]	The summarized reasoning text contents.
type*	string	The type of the object, which is always `reasoning`.

ReasoningConfigurationobject

effort	any	Constrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model.
generate_summary	any	Only included for compatibility.
summary	any	A summary of the model's reasoning process. Possible values are `auto`, `concise` and `detailed`. Only included for compatibility. The model shall always return `detailed`.

ReasoningTextobject

text*	string	Reasoning done by the model.
type*	string	The type of the object, which is always `reasoning_text`.

SearchParametersobject

Parameters to control realtime data.

from_date	any	Date from which to consider the results in ISO-8601 YYYY-MM-DD. See <https://en.wikipedia.org/wiki/ISO_8601>.	format: date
max_search_results	any	Maximum number of search results to use.	1 ≤ n ≤ 30 · format: int32 · default: 15
mode	any	Choose the mode to query realtime data: * `off`: no search performed and no external will be considered. * `on` (default): the model will search in every sources for relevant data. * `auto`: the model choose whether to search data or not and where to search th…	default: "auto"
return_citations	any	Whether to return citations in the response or not.	default: true
sources	any	List of sources to search in. If no sources specified, the model will look over the web and X by default.
to_date	any	Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See <https://en.wikipedia.org/wiki/ISO_8601>.	format: date

SearchSourceobject | object | object | …

ServiceTierenum

Processing tier for a request. `Fast` and `Priority` are interchangeable: the model's fast deployment and its rates where configured, else higher scheduling priority at a higher price.

default | priority | fast

ShellCallobject

A shell command call emitted by the model for local execution.

action*	ShellCallAction	The shell commands and limits that describe how to run the tool call.
call_id*	string	The unique ID of the shell tool call generated by the model.
environment	ShellEnvironment	The environment for the shell tool call.	nullable
id	string	The unique ID of the shell call item.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The type of the output item, which is always `shell_call`.

ShellCallActionobject

The shell commands and limits that describe how to run the tool call.

commands*	string[]	The commands to run.
max_output_length	any	Optional maximum number of characters to return from each command.	format: int32
timeout_ms	any	Optional timeout in milliseconds for the commands.	format: int64
type	any	The type of the action, which is always `exec`.

ShellCallOutcomeobject | object

The outcome of a shell command execution.

ShellCallOutputobject

The output of a shell tool call, sent by the client after local execution.

call_id*	string	The unique ID of the shell tool call generated by the model.
max_output_length	any	The maximum length of the shell command output. Generated by the model and should be passed back with the raw output.	format: int32
output*	ShellCallOutputResult[]	An array of shell call output contents.
type*	string	The type of the output item, which is always `shell_call_output`.

ShellCallOutputResultobject

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

outcome*	object \| object	The outcome of the command execution.
stderr	string	The standard error output that was captured.
stdout	string	The standard output that was captured.

ShellEnvironmentobject

The environment configuration for a shell tool.

skills	LocalShellSkill[]	An optional list of skills available in the local environment.
type*	string	The type of the environment. Currently only `local` is supported.

SummaryTextobject

text*	string	Summary of the reasoning done by the model.
type*	string	The type of the object, which is always `summary_text`.

TokenLogProbobject

bytes	any	The ASCII encoding of the output character.
logprob*	number	The log probability of returning this token.	format: float
token*	string	The token.
top_logprobs*	TopLogProb[]	An array of the most likely tokens to return at this token position.

ToolSearchCallobject

A server-side tool search call made by the model.

arguments	any	The arguments of the tool search call: `{"query": ..., "limit": ...}`.
call_id	any	Always `null`; present for OpenAI compatibility.
execution	string	Where the search runs. Always `server`.
id*	string	The unique ID of the tool search call item.
status	string	Status of the item. One of `in_progress`, `completed` or `incomplete` (a failed search).
type*	enum	Type tag for [`ToolSearchCall`]; a single-variant enum (not a `String`) for the same untagged-enum disambiguation as [`ImageGenerationCallType`].	tool_search_call

ToolSearchOutputobject

The tool definitions loaded by a completed tool search call.

call_id	any	Always `null`; present for OpenAI compatibility.
execution	string	Where the search ran. Always `server`.
id*	string	The unique ID of the tool search output item.
status	string	Status of the item. Always `completed`.
tools	any[]	The loaded tool definitions, echoed in the shape they were supplied in.
type*	enum	Type tag for [`ToolSearchOutput`]. Serializes as `"tool_search_output"`. See [`ToolSearchCallType`] for why this is a single-variant enum.	tool_search_output

TopLogProbobject

bytes	any	The ASCII encoding of the output character.
logprob*	number	The log probability of returning this token.	format: float
token*	string	The token.

WebSearchActionobject | object | object

WebSearchCallobject

The output of a web search tool call.

action*	object \| object \| object	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).
id	string	The unique ID of the web search tool call.
status	string	The status of the web search tool call.
type*	string	The type of the web search tool call. Always `web_search_call`.

WebSearchFiltersobject

allowed_domains	any	List of website domains (without protocol specification or subdomains) to restrict search results to (e.g., ["example.com"]). A maximum of 5 websites can be allowed. Use this as a whitelist to limit results to only these specific sites; no other websites will …	items ≤ 5
excluded_domains	any	List of website domains (without protocol specification or subdomains) to exclude from search results (e.g., ["example.com"]). Use this to prevent results from unwanted sites. A maximum of 5 websites can be excluded. This parameter cannot be set together with …	items ≤ 5

WebSearchOptionsobject

filters	any	Only included for compatibility.
search_context_size	any	This field included for compatibility reason with OpenAI's API. It is mapped to `max_search`.	default: "medium"
user_location	any	Only included for compatibility.

WebSearchSourceobject

type*	string	The type of source.
url	string	The URL of the source.

WebSearchUserLocationobject

city	any	City of the user's location.
country	any	Two-letter ISO 3166-1 alpha-2 country code, like US, GB, etc.
region	any	Region of the user's location.
timezone	any	Timezone of the user's location, IANA timezone like America/Chicago, Europe/London, etc.
type*	string	Type is always `"approximate"`.

Validate a payload

before you spend tokens

shell

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