GET

/v1/schemas/openrouter/chat/responses

Accept:

kind inputactivity chathash c20c301f…extracted Nov 13, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `0d19a8453874651361f64fbd51045d9d1d4868b39f7eb85b9866fee302c50de2` { "fetchedAt": 1794547804, "extractorVersion": "2", "verifiedAt": null }

Request body

43 properties · 0 required · 237 $defs

property	type	description	constraints
access_programs	object	OpenAI access programs for this request. `cyber` selects the Cyber access program: `standard`, `daybreak_blue`, or `daybreak_red`. A program other than `standard` is supported only on BYOK requests that run on your own OpenAI key enrolled in that program; any …
background	any
cache_control	AnthropicCacheControlDirective	Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also …
debug	ChatDebugOptions	Debug options for inspecting request transformations (streaming only)
deferred_tools	DeferredToolsControl	Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_chan…
frequency_penalty	any		format: double
image_config	ImageConfig	Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details.
include	any
input	string \| ReasoningItem \| EasyInputMessage \| InputMessageItem[]	Input for a response request - can be a string or array of items
instructions	any
max_output_tokens	any
max_tool_calls	any	Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set.
metadata	RequestMetadata	Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.
modalities	OutputModalityEnum[]	Output modalities for the response. Supported values are "text" and "image".
model	string
models	string[]
parallel_tool_calls	any
plugins	AutoRouterPlugin \| AutoBetaRouterPlugin \| ModerationPlugin[]	Plugins you want to enable for this request, including their settings.
presence_penalty	any		format: double
previous_response_id	any	Not supported on this proxy. Each response request is independent: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead.
prompt	StoredPromptTemplate
prompt_cache_key	any
prompt_cache_options	PromptCacheOptions	Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. `ttl` sets the minimum cache lifetime for every breakpoint the request writes: "30m" (default) or "12h"…
provider	ProviderPreferences	When multiple model providers are available, optionally indicate your routing preference.
reasoning	any \| object	Configuration for reasoning mode in the response	nullable
route	enum	DEPRECATED Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none").	fallback \| sort \| null · deprecated
safety_identifier	any	Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-le…
service_tier	enum	The service tier to use for processing this request. `fast` is accepted as an alias for `priority`. `ultrafast` prefers ultrafast endpoints and falls back to `priority`, then default endpoints.	auto \| default \| fast \| flex \| priority \| scale · +2 more · default: "auto"
session_id	string	A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for obser…	length ≤ 256
stop	string \| string[]	Stop sequences (up to 4)	nullable
stop_server_tools_when	StopServerToolsWhenCondition[]	Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final tu…	items ≥ 1
store	const		false · default: false
stream	boolean		default: false
temperature	any		format: double
text	object \| object	Text output configuration including format and verbosity
tool_choice	enum \| enum \| enum \| …
tools	any \| Preview_WebSearchServerTool \| Preview_20250311_WebSearchServerTool[]
top_k	integer
top_logprobs	any
top_p	any		format: double
trace	TraceConfig	Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.
truncation	enum		auto \| disabled \| null
user	string	A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual u…	length ≤ 256

Types

237 $defs

AdditionalToolsItemobject

Additional tools made available to the model at this point in the input

id	any
role*	enum	unknown \| user \| assistant \| system \| critic \| discriminator · +2 more
tools*	any \| Preview_WebSearchServerTool \| Preview_20250311_WebSearchServerTool[]
type*	enum	additional_tools

AdvisorReasoningobject

Reasoning configuration forwarded to the advisor call. Use this to control reasoning effort and token budget for models that support extended thinking.

effort	enum	Reasoning effort level for the advisor call.	max \| xhigh \| high \| medium \| low \| minimal · +1 more
max_tokens	integer	Maximum number of reasoning tokens the advisor may use.

AdvisorServerTool_OpenRouterobject

OpenRouter built-in server tool: consults a higher-intelligence advisor model (any OpenRouter model) for guidance mid-generation and returns its response. Include multiple entries to offer several named advisors; at most one entry may omit `name` to act as the…

parameters	AdvisorServerToolConfig	Configuration for one openrouter:advisor server tool entry.
type*	enum		openrouter:advisor

AdvisorServerToolConfigobject

Configuration for one openrouter:advisor server tool entry.

forward_transcript	boolean	When true, the full parent conversation is forwarded to the advisor so it sees the same context the executor does (and the tool-call `prompt`, if given, is appended as a final user turn). When false or omitted, the advisor receives only the `prompt` the execut…
instructions	string	System instructions for the advisor sub-agent. When omitted, the advisor responds with no system prompt of its own.
max_completion_tokens	integer	Maximum number of output tokens (including reasoning) the advisor may produce. When omitted, the provider's default applies.
model	string	Slug of the advisor model to consult (any OpenRouter model). When omitted, the executor can choose it via the tool call's `model` argument; if neither is set, the model from the outer API request is used.
name	string	Optional name for this advisor. The model sees one tool per named advisor (and one default for an unnamed entry). Names must be unique across advisor entries. Letters, digits, spaces, underscores, and dashes; trimmed; 1–64 chars.	length ≥ 1 · length ≤ 64
reasoning	AdvisorReasoning	Reasoning configuration forwarded to the advisor call. Use this to control reasoning effort and token budget for models that support extended thinking.
stream	boolean	When true, the advisor's advice streams incrementally as it is produced. In the Responses API this emits `response.output_text.delta` events targeting the advisor output item; the final `advice` field is still set on the completed item. Has no effect on the Ch…
temperature	number	Sampling temperature forwarded to the advisor call. When omitted, the provider's default applies.	format: double

AgentMessageItemobject

A message routed between agents in a multi-agent session

agent	object
author*	string
content*	InputText \| any \| object[]
id	any
recipient*	string
type*	enum	agent_message

AlignmentPluginobject

Beta. States the listed rules to the model and evaluates every turn against them; the configuration, metadata, and error shapes may change.

id*	enum		alignment
instruct	boolean	Whether the rules are stated to the model in a system message on every provider call. Default true.
max_retries	integer	Provider calls made again after a blocked turn, in enforce mode. Default 1.
mode	enum	`enforce`: a turn that breaks a rule is withheld, retried, and finally returned as an error. `audit`: every turn is evaluated and returned. Default `audit`.	enforce \| audit
rules*	AlignmentRule[]	Rules the reply must follow. Each rule is evaluated on its own.	items ≥ 1 · items ≤ 128
threshold	number	Probability at or above which a rule is broken, from 0.01 to 1. Default 0.7.	format: double

AlignmentRuleobject

rule*	string	Text that states what the reply must do or must not do.	length ≥ 1 · length ≤ 200
watch*	enum[]	Fields of the assistant message the rule applies to. The rule is evaluated on a message that has at least one of them and is not applicable to any other message.	items ≥ 1 · items ≤ 5

AnthropicCacheControlDirectiveobject

Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also …

ttl	enum		5m \| 1h
type*	enum		ephemeral

AnthropicCacheControlTtlenum

5m | 1h

ApplyPatchCallItemobject

A tool call emitted by the model requesting a V4A patch operation. The client applies the patch and echoes an `apply_patch_call_output` on the next turn.

call_id*	string
id	any
operation*	object \| object \| object	The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it.
status*	enum	Lifecycle state of an `apply_patch_call` output item.	in_progress \| completed
type*	enum		apply_patch_call

ApplyPatchCallOperationobject | object | object

The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it.

ApplyPatchCallOutputItemobject

The client's echo of an `apply_patch_call` after applying the patch. `output` is an optional human-readable log; `status` is `completed` when the patch was applied successfully, `failed` otherwise.

call_id*	string
id	any
output	any
status*	enum	completed \| failed
type*	enum	apply_patch_call_output

ApplyPatchCallStatusenum

Lifecycle state of an `apply_patch_call` output item.

in_progress | completed

ApplyPatchCreateFileOperationobject

The `create_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing the new file contents.

diff*	string
path*	string
type*	enum	create_file

ApplyPatchDeleteFileOperationobject

The `delete_file` variant of an `apply_patch_call.operation`. Identifies the file to remove; no diff is required.

path*	string
type*	enum		delete_file

ApplyPatchEngineEnumenum

Which apply_patch engine to use. "auto" (default) uses native passthrough when the endpoint advertises native apply_patch support, otherwise falls back to OpenRouter's HITL validator. "native" forces native passthrough — when the endpoint does not support nati…

auto | native | openrouter

ApplyPatchServerToolobject

Apply patch tool configuration

type*

enum

apply_patch

ApplyPatchServerTool_OpenRouterobject

OpenRouter built-in server tool: validates V4A diff patches for file operations (create, update, delete). Restricted to the Responses API.

parameters	ApplyPatchServerToolConfig	Configuration for the openrouter:apply_patch server tool
type*	enum		openrouter:apply_patch

ApplyPatchServerToolConfigobject

Configuration for the openrouter:apply_patch server tool

engine

enum

auto | native | openrouter

ApplyPatchUpdateFileOperationobject

The `update_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing edits to an existing file.

diff*	string
path*	string
type*	enum	update_file

ArmorAutoModeobject

allow	string \| ArmorRule[]
environment	string \| ArmorEnvironmentEntry[]
hard_deny	string \| ArmorRule[]
soft_deny	string \| ArmorRule[]

ArmorContextobject

The Armor context: Claude Code's `classifier_context` (v1), with `auto_mode.{hard_deny,soft_deny,allow}` rules as strings or `{ id, instructions, threshold? }` objects and `auto_mode.environment` entries as `"Name: value"` strings or `{ name, value }` objects.…

auto_mode	ArmorAutoMode
v*	enum		1

ArmorEnvironmentEntryobject

name*	string		length ≥ 1 · length ≤ 120
value*	string		length ≤ 4000

ArmorPluginobject

Evaluates every client tool call the model emits against a rule stack (hard-deny, soft-deny, allow) before it reaches the caller. The stack merges the workspace guardrail, this plugin, and any Anthropic `safeguards`; on endpoints that support Anthropic's `dang…

classifier_context	ArmorContext	The Armor context: Claude Code's `classifier_context` (v1), with `auto_mode.{hard_deny,soft_deny,allow}` rules as strings or `{ id, instructions, threshold? }` objects and `auto_mode.environment` entries as `"Name: value"` strings or `{ name, value }` objects.…
enabled	boolean	Set to false to disable Armor for this request. Defaults to true.
evaluate_native_tools	boolean	Run provider-native server tools (web search, code execution, ...) through the agent loop so Armor evaluates them too. Defaults to false: native passthrough stands and such calls are reported `skipped`.
id*	enum		armor
mode	enum	`enforce` withholds blocked calls; `audit` evaluates and reports the same verdicts without withholding any calls, regardless of `on_error`. Default `enforce`.	enforce \| audit
on_error	enum	When the classifier cannot answer (timeout, upstream error, context too long) the call is reported `unavailable`; `block` rejects it and `log` releases it. Default `block`.	log \| block
output_mode	enum	How a blocked call reaches the caller. `text` (the default): the call is withheld and an `<openrouter_armor_blocked>` marker stands in assistant text. `custom_item` (Responses API only): the call is withheld and an `openrouter:armor_blocked` output item carrie…	text \| custom_item \| claude_code_compatibility
use_cc_style_default_rules	boolean	Prepend Claude Code's built-in auto-mode rule set (1 hard-deny, 72 soft-deny, 17 allow, 21 environment slots) ahead of every configured rule. Defaults to true on the Anthropic Messages API and false elsewhere.

ArmorRuleobject

id*	string	Stable id, unique within its source; reported as the deciding rule when it fires.	length ≥ 1 · length ≤ 64
instructions*	string	What the rule matches, written for the classifier.	length ≥ 1 · length ≤ 8000
name	string	Display name shown in verdict explanations; defaults to the id.	length ≥ 1 · length ≤ 120
threshold	number	Probability at or above which the rule counts as matched. Defaults to 0.6 for hard-deny and soft-deny rules and 0.7 for allow rules (an exception needs stronger evidence to clear a matched soft deny).	format: double

AutoBetaRouterPluginobject

allowed_models	string[]	List of model patterns to filter which models the auto-beta-router can route between. Supports wildcards (e.g., "anthropic/*" matches all Anthropic models). Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. Whe…	items ≤ 1024
cost_quality_tradeoff	integer	Deprecated: Use cost_tier instead. Balances routing between cost and quality on a 0-10 scale. The auto-beta-router ranks models for the classified task type by community spend share, then filters candidates by their average cost per generation for that task. H…	0 ≤ n ≤ 10 · deprecated
cost_tier	enum	Named cost/quality setting. For auto-beta-router, tiers select cost-percentile bands: low = [0, 20), medium = [20, 40), high = [40, 60), xhigh = [60, 80), and max = [80, 100]. Takes precedence over the deprecated numeric cost_quality_tradeoff when both are pro…	low \| medium \| high \| xhigh \| max
enabled	boolean	Set to false to disable the auto-beta-router plugin for this request. Defaults to true.
excluded_models	string[]	List of model patterns to exclude from auto-beta-router selection. Supports wildcards (e.g., "meta-llama/*" excludes all Llama models). Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. Applied after allowed_mo…	items ≤ 1024
id*	enum		auto-beta-router

AutoRouterPluginobject

allowed_models	string[]	List of model patterns to filter which models the auto-router can route between. Supports wildcards (e.g., "anthropic/*" matches all Anthropic models). Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. When not…	items ≤ 1024
cost_quality_tradeoff	integer	Deprecated: Use cost_tier instead. Balances routing between cost and quality on a 0-10 scale. The auto-router ranks models for the classified task type by community spend share, then filters candidates by their average cost per generation for that task. Higher…	0 ≤ n ≤ 10 · deprecated
cost_tier	enum	Named cost/quality setting. Tiers select cost-percentile bands: low = [0, 20), medium = [20, 40), high = [40, 60), xhigh = [60, 80), and max = [80, 100]. Takes precedence over the deprecated numeric cost_quality_tradeoff when both are provided.	low \| medium \| high \| xhigh \| max
enabled	boolean	Set to false to disable the auto-router plugin for this request. Defaults to true.
excluded_models	string[]	List of model patterns to exclude from auto-router selection. Supports wildcards (e.g., "meta-llama/*" excludes all Llama models). Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. Applied after allowed_models,…	items ≤ 1024
id*	enum		auto-router
pin_model	boolean	When true, reuses the model from the most recent assistant message's `model` attribute for subsequent turns. Defaults to false.

BaseReasoningConfigobject

context	enum	Controls which reasoning is available to the model. `auto` uses the model default (same as omitting); `all_turns` includes reasoning from earlier turns passed in input; `current_turn` limits to the current turn only. Only supported by OpenAI GPT-5.6 and newer.	auto \| all_turns \| current_turn \| null
effort	enum		max \| xhigh \| high \| medium \| low \| minimal · +2 more
mode	enum	Selects the reasoning mode. `standard` is the default; `pro` engages deeper reasoning on models that support it, billed at standard token rates. Only supported by OpenAI GPT-5.6 and newer.	standard \| pro \| null
summary	enum		auto \| concise \| detailed \| null

BashServerToolobject

OpenRouter built-in server tool: runs shell commands server-side in a sandboxed container

parameters	BashServerToolConfig	Configuration for the openrouter:bash server tool
type*	enum		openrouter:bash

BashServerToolConfigobject

Configuration for the openrouter:bash server tool

engine	enum	Which bash engine to use. "openrouter" runs commands server-side in the OpenRouter sandbox. "auto" (default) and "native" use native passthrough, returning the tool call to your application to run client-side; OpenRouter does not execute the commands.	auto \| native \| openrouter
environment	object \| object	Execution environment for the bash server tool.

BashServerToolEngineenum

Which bash engine to use. "openrouter" runs commands server-side in the OpenRouter sandbox. "auto" (default) and "native" use native passthrough, returning the tool call to your application to run client-side; OpenRouter does not execute the commands.

auto | native | openrouter

BashServerToolEnvironmentobject | object

Execution environment for the bash server tool.

ChatDebugOptionsobject

Debug options for inspecting request transformations (streaming only)

echo_upstream_body

boolean

If true, includes the transformed upstream request body in a debug chunk at the start of the stream. Only works with streaming mode.

CodeInterpreterCallItemobject | object

A code interpreter execution call with outputs

CodeInterpreterFileOutputobject

download_url	string	Provider-issued download URL for the generated file. Typically signed and time-limited (see `expires_at`); fetch promptly rather than persisting the URL.
error_code	any	Provider error code when generating or persisting the file failed; null or absent on success.
expires_at	string	When the `download_url` stops working, as an ISO 8601 timestamp. After this time the file must be regenerated.
filename	string
id	string
media_type	string
sha256	string
size_bytes	integer
status	string	Provider-reported readiness of the generated file (e.g. `ready`). Values other than `ready` indicate the artifact may not be downloadable.
type*	enum		file

CodeInterpreterImageOutputobject

type*	enum		image
url*	string

CodeInterpreterLogsOutputobject

logs*	string
type*	enum		logs

CodeInterpreterServerToolobject

Code interpreter tool configuration. An existing container id or `container.file_ids` requires BYOK (your own OpenAI key); requests on OpenRouter credits must use `auto` with no `file_ids`.

container*	string \| object
type*	enum		code_interpreter

CodexLocalShellToolobject

Local shell tool configuration

type*

enum

local_shell

CompactionItemobject

A context compaction marker with encrypted summary

encrypted_content*	string
id	any
type*	enum	compaction

CompactionTriggerItemobject

Asks the model to compact the preceding input into a compaction item

type*

enum

compaction_trigger

CompoundFilterobject

A compound filter that combines multiple comparison or compound filters

filters*	object[]
type*	enum		and \| or

ComputerUseServerToolobject

Computer use preview tool configuration

display_height*	integer
display_width*	integer
environment*	enum	windows \| mac \| linux \| ubuntu \| browser
type*	enum	computer_use_preview

ConfigurationUpdateItemobject

Changes reasoning effort from this point in the conversation onward without invalidating the prompt cache for the preceding items. Place it before the user message it should apply to; it stays in effect until another configuration update. Two adjacent configur…

id	any
reasoning*	ConfigurationUpdateReasoning	Reasoning settings applied from this point in the conversation onward
type*	enum		configuration_update

ConfigurationUpdateReasoningobject

Reasoning settings applied from this point in the conversation onward

effort*

enum

Reasoning effort to apply from this point in the conversation onward

ContainerAutoEnvironmentobject

An OpenRouter-managed, auto-provisioned ephemeral container.

file_ids	string[]	Workspace file ids (or_file_…) to attach into the container before the first command runs. Each file is copied to the container home as a writable copy named {last 8 characters of the file id}-{base filename} (a file stored as data/report.csv with id or_file_……	items ≤ 20
network_policy	object \| object	Network egress policy for the container. "disabled" blocks all outbound internet; "allowlist" permits only hosts matching the listed hostnames or * glob patterns (ports 80/443, DNS via Cloudflare resolvers). The policy is fixed when a container starts: sending…
type*	enum		container_auto

ContainerFileIdsstring[]

Workspace file ids (or_file_…) to attach into the container before the first command runs. Each file is copied to the container home as a writable copy named {last 8 characters of the file id}-{base filename} (a file stored as data/report.csv with id or_file_……

items ≤ 20

ContainerNetworkPolicyobject | object

Network egress policy for the container. "disabled" blocks all outbound internet; "allowlist" permits only hosts matching the listed hostnames or * glob patterns (ports 80/443, DNS via Cloudflare resolvers). The policy is fixed when a container starts: sending…

ContainerReferenceEnvironmentobject

Reference to a container by its canonical id — a previously returned container_id or a fresh name to create a persistent container.

container_id*	string	Canonical container id to reuse (max 40 characters, letters/digits/underscores/hyphens). Any container_id previously returned by a bash or shell tool result works here and reattaches to the same container and files — including session-derived ids (sess_...) an…	length ≥ 1 · length ≤ 40
file_ids	string[]	Workspace file ids (or_file_…) to attach into the container before the first command runs. Each file is copied to the container home as a writable copy named {last 8 characters of the file id}-{base filename} (a file stored as data/report.csv with id or_file_……	items ≤ 20
network_policy	object \| object	Network egress policy for the container. "disabled" blocks all outbound internet; "allowlist" permits only hosts matching the listed hostnames or * glob patterns (ports 80/443, DNS via Cloudflare resolvers). The policy is fixed when a container starts: sending…
type*	enum		container_reference

ContextCompactionItemobject

A context compaction marker with an optional encrypted summary

encrypted_content	any
id	any
type*	enum	context_compaction

ContextCompressionEngineenum

The compression engine to use. Defaults to "middle-out".

middle-out

ContextCompressionPluginobject

enabled	boolean	Set to false to disable the context-compression plugin for this request. Defaults to true.
engine	enum	The compression engine to use. Defaults to "middle-out".	middle-out
id*	enum		context-compression

CustomToolobject

Custom tool configuration

async	boolean	Lets the model keep working after calling this tool instead of waiting for its output. The tool is still executed by the client; return the result in a later request as a `function_call_output` with the original `call_id`. Only honored by providers whose Respo…
defer_loading	boolean
description	string
format	object \| object
name*	string
type*	enum		custom

CustomToolCallItemobject

A call to a custom (freeform-grammar) tool created by the model — distinct from `function_call`. Used for tools like Codex CLI's `apply_patch` whose payload is opaque text rather than JSON arguments.

async	any	True when the model called a tool declared with `async: true` and may continue its turn before the output is returned. Return the result in a later request as a `function_call_output` with this `call_id`.
call_id*	string
id	any
input*	string
name*	string
namespace	any	Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server)
status	enum		in_progress \| completed \| incomplete · nullable
type*	enum		custom_tool_call

CustomToolCallOutputItemobject | object

The output from a custom (freeform-grammar) tool call execution. Mirrors `function_call_output` but is matched to a `custom_tool_call` rather than a `function_call`.

DatetimeServerToolobject

OpenRouter built-in server tool: returns the current date and time

parameters	DatetimeServerToolConfig	Configuration for the openrouter:datetime server tool
type*	enum		openrouter:datetime

DatetimeServerToolConfigobject

Configuration for the openrouter:datetime server tool

timezone

string

IANA timezone name (e.g. "America/New_York"). Defaults to UTC.

DeferredBm25Searchobject

Deterministic BM25 retrieval over supplied tool definitions.

max_results	integer
miss_sources	boolean	Universal profile only, for searches the router answers through the `tool_search` wrapper. Unless false, a search that matches nothing also names the deferred sources this search covers (namespaces, MCP servers, and shared `<server>_` prefixes; up to 40 names …
siblings	boolean	Universal profile only, for searches the router answers through the `tool_search` wrapper; code-mode `search()` and a client-owned tool search list the matched tools alone. When true, each result also names up to 16 other deferred tools of every source a match…
spread	boolean	Universal profile only, for keyword searches the router answers through the `tool_search` wrapper. When true, a result spreads across sources: of the 3 x limit best-scoring candidates, those scoring at least 60% of the best match take at most 2 slots per sourc…
type*	enum		bm25

DeferredCustomSearchobject

Caller-executed search returning existing tool identities under result_key.

max_results	integer
result_key*	string	length ≥ 1
tool_id*	string	length ≥ 1
type*	enum	custom

DeferredRegexSearchobject

Versioned safe-regex retrieval over supplied tool definitions.

max_results	integer
miss_sources	boolean	Universal profile only, for searches the router answers through the `tool_search` wrapper. Unless false, a search that matches nothing also names the deferred sources this search covers (namespaces, MCP servers, and shared `<server>_` prefixes; up to 40 names …
siblings	boolean	Universal profile only, for searches the router answers through the `tool_search` wrapper; code-mode `search()` and a client-owned tool search list the matched tools alone. When true, each result also names up to 16 other deferred tools of every source a match…
type*	enum		regex

DeferredToolsControlobject

Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_chan…

announce_catalog_changes	boolean	Universal profile only. When true, a catalog whose deferred tools changed between two of the model's own turns (a client that connects MCP servers while the model works) is re-announced before the next model turn, with the sources added, changed and removed si…
cascade_mode	enum	How a universal `tool_search` query reaches the client's own tool search. Absent or `keywords`: a `select:` query becomes the words of the selected names and the limit is always filled. `native`: a `select:` query passes through verbatim when the client search…	keywords \| native
hint	string	Universal profile only. Caller text announced to the model with the deferred catalog before its first turn, for example which sources the task needs. Repeated only when it changes. Trimmed before the length bounds apply. Recorded in the `catalog_index` discove…	length ≥ 1 · length ≤ 2000
interface	enum	How the universal profile exposes the hidden catalog to the provider. Absent or `wrappers`: the `tool_search` and `tool_exec` tools. `code_mode`: one `tool_code` tool that runs a short JavaScript program in which `search()` and `call()` reach the catalog, so s…	wrappers \| code_mode
min_deferred_tools	integer	Universal profile only. When fewer tools than this would be deferred, the universal profile defers none of them and sends the client tools unchanged, so a harness with a handful of non-core tools and no MCP servers pays no search turn for them. Counted after t…
profile*	enum	Loading profile. `portable` serves the `defer_loading` tools with router-built search and call wrappers on any model and keeps the catalog fixed. `universal` defers every wrappable tool behind the same wrappers so the provider-facing tool list never changes (u…	portable \| universal
protocol*	enum		v1
scope	enum	Which tools the universal profile defers. Absent or `all`: every wrappable tool outside the coding-harness core set. `mcp`: only MCP server tools (`mcp__*` names and Responses namespaces outside `functions`); the harness keeps its own built-in tools direct. Ex…	all \| mcp
search*	object \| object \| object	Router-local regex/BM25 or caller-owned custom search.
validation*	enum	Where tool-call arguments are checked against the original schema. Only `runtime` (in OpenRouter) is available in this release.	runtime

DeferredToolsSearchStrategyobject | object | object

Router-local regex/BM25 or caller-owned custom search.

DeprecatedRouteenum

**DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none").

fallback | sort | null

EasyInputMessageobject

content	InputText \| any \| InputFile[] \| string		nullable
phase	enum \| enum	The phase of an assistant message. Use `commentary` for an intermediate assistant message and `final_answer` for the final assistant message. For follow-up requests with models like `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages…	nullable
role*	enum \| enum \| enum \| …
type	enum		message

FailableToolCallStatusenum

in_progress | completed | incomplete | failed

FileCitationobject

file_id*	string
filename*	string
index*	integer
type*	enum	file_citation

FileParserPluginobject

enabled	boolean	Set to false to disable the file-parser plugin for this request. Defaults to true.
id*	enum		file-parser
pdf	PDFParserOptions	Options for PDF parsing.

FilePathobject

file_id*	string
index*	integer
type*	enum	file_path

FileSearchServerToolobject

File search tool configuration. `vector_store_ids` names OpenAI vector stores, so it requires BYOK (your own OpenAI key); requests on OpenRouter credits get a 400.

filters	object \| object	nullable
max_num_results	integer
ranking_options	object
type*	enum	file_search
vector_store_ids*	string[]

FilesServerToolobject

OpenRouter built-in server tool: read, write, edit, and list workspace files via the Files API. Requires an authenticated request; files come from the API key's workspace (or the default workspace for keys without one).

parameters	FilesServerToolConfig	Configuration for the openrouter:files server tool
type*	enum		openrouter:files

FilesServerToolConfigobject

Configuration for the openrouter:files server tool

FormatJsonObjectConfigobject

JSON object response format

type*

enum

json_object

FormatJsonSchemaConfigobject

JSON schema constrained response format

description	string
name*	string
schema*	object
strict	any
type*	enum	json_schema

Formatsobject | object | object

Text response format configuration

FormatTextConfigobject

Plain text response format

type*

enum

text

FunctionCallItemobject

A function call initiated by the model

arguments*	string
async	any	True when the model called a tool declared with `async: true` and may continue its turn before the output is returned. Return the result in a later request as a `function_call_output` with this `call_id`.
call_id*	string
id	any
name*	string
namespace	any	Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server)
status	enum		in_progress \| completed \| incomplete · nullable
subagent_id	any	EXPERIMENTAL — subject to change without notice. String id that matches the `call_id` of the `openrouter:subagent` server tool call that spawned the subagent. Present on every `function_call` item the subagent projects; absent on ordinary function calls.
subagent_items	any	EXPERIMENTAL — subject to change without notice. The subagent's output items produced on this turn. Treat this as an opaque object; you must replay it in the request so that the subagent can continue execution of the tool with the same context. If a subagent c…
type*	enum		function_call

FunctionCallOutputItemobject | object

The output from a function call execution

FunctionToolobject

Function tool definition

description	any
name*	string
parameters*	any
strict	any
type*	enum	function

FusionAnalysisResultobject

Structured analysis produced by the fusion analyst model.

blind_spots*	string[]
consensus*	string[]
contradictions*	object[]
partial_coverage*	object[]
unique_insights*	object[]

FusionPluginobject

analysis_models	string[]	For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, slugs of models to run in parallel as the "expert panel" the analyst analyzes. Each model receives the same user prompt with web_search + web_fetch enabled. Capp…	items ≥ 1 · items ≤ 8
enabled	boolean	Set to false to disable Fusion configuration for a run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool. Defaults to true.
id*	enum		fusion
max_tool_calls	integer	For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, the maximum number of tool-calling steps each panelist (analysis model) and the analyst model may take during their agentic web-research loop. Models with web_se…	1 ≤ n ≤ 16
model	string	For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, the slug of the model that performs both the analyst step (with web_search + web_fetch) and the final synthesis. When omitted, defaults to the first model in the…
preset	enum	Configuration for a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool. A curated OpenRouter preset (slugs follow `<task>-<tier>`, e.g. `general-high`). Expands server-side into the preset's analysis_models panel and an…	general-high \| general-budget \| general-fast
tools	object[]	For a Fusion run started by the `openrouter/fusion` model slug or `openrouter:fusion` server tool, server tools available to panelist and analyst inner calls. Each entry uses the same `{ type, parameters? }` shorthand as the outer Chat Completions request. Whe…	items ≤ 8

FusionServerTool_OpenRouterobject

OpenRouter built-in server tool: fans out the user prompt to a panel of analysis models, then asks an analyst model to summarize their collective output as structured JSON the outer model can synthesize from.

parameters	FusionServerToolConfig	Configuration for the openrouter:fusion server tool.
type*	enum		openrouter:fusion

FusionServerToolConfigobject

Configuration for the openrouter:fusion server tool.

analysis_models	string[]	Slugs of models to run in parallel as the analysis panel. Each model receives the user prompt with openrouter:web_search and openrouter:web_fetch enabled, then an analyst model summarizes the collective output into structured analysis JSON. Capped at 8 models …	items ≥ 1 · items ≤ 8
cache_control	AnthropicCacheControlDirective	Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also …
max_completion_tokens	integer	Maximum number of output tokens (including reasoning tokens) each panelist and the analyst model may produce per inner call. Controls the total output budget so reasoning-heavy models like GPT-5.5 do not exhaust their token allowance before producing visible t…
max_tool_calls	integer	Maximum number of tool-calling steps each panelist (analysis model) and the analyst model may take during their agentic web-research loop. Models with web_search/web_fetch enabled iterate until they produce a text response or hit this ceiling. Defaults to 4. C…	1 ≤ n ≤ 16
model	string	Slug of the analyst model that produces the structured analysis JSON. Defaults to the model used in the outer API request.
reasoning	object	Reasoning configuration forwarded to panelist and analyst inner calls. Use this to control reasoning effort and token budget for models that support extended thinking.
temperature	number	Temperature forwarded to panelist inner calls. The analyst always runs at temperature 0 regardless of this value. When omitted, the provider's default applies.	format: double
tools	object[]	Server tools available to panelist and analyst inner calls. Each entry uses the same `{ type, parameters? }` shorthand as the outer Chat Completions request. When omitted, defaults to `[{ type: "openrouter:web_search" }, { type: "openrouter:web_fetch" }]`. Pas…	items ≤ 8

FusionSourceobject

A web page retrieved via web search during a fusion run.

title*	string	Title of the retrieved web page.
url*	string	URL of the web page a panel or the analyst retrieved during the run.

ImageConfigobject

Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details.

ImageGenerationServerToolobject

Image generation tool configuration

background	enum	transparent \| opaque \| auto
input_fidelity	enum	high \| low \| null
input_image_mask	object
model	string
moderation	enum	auto \| low
output_compression	integer
output_format	enum	png \| webp \| jpeg
partial_images	integer
quality	enum	low \| medium \| high \| auto
size	string
type*	enum	image_generation

ImageGenerationServerTool_OpenRouterobject

OpenRouter built-in server tool: generates images from text prompts using an image generation model

parameters	ImageGenerationServerToolConfig	Configuration for the openrouter:image_generation server tool. Accepts all image_config params (aspect_ratio, quality, size, background, output_format, output_compression, moderation, etc.) plus a model field.
type*	enum		openrouter:image_generation

ImageGenerationServerToolConfigobject

Configuration for the openrouter:image_generation server tool. Accepts all image_config params (aspect_ratio, quality, size, background, output_format, output_compression, moderation, etc.) plus a model field.

model

string

Which image generation model to use (e.g. "openai/gpt-image-2.6-flare"). Defaults to "openai/gpt-image-2.6-flare".

ImageGenerationStatusenum

in_progress | completed | generating | failed

InputAudioobject

Audio input content item

input_audio*	object
type*	enum		input_audio

InputFileobject

File input content item

file_data	string
file_id	any
file_url	string
filename	string
type*	enum	input_file

InputImageobject

Image input content item. Provide either an image_url (a URL or a base64 data URL) or the file_id of an uploaded image.

detail*	enum	auto \| high \| low \| original
file_id	any
image_url	any
type*	enum	input_image

InputMessageItemobject

content	any
id	string
role*	enum \| enum \| enum
type	enum	message

Inputsstring | ReasoningItem | EasyInputMessage | InputMessageItem[]

Input for a response request - can be a string or array of items

InputTextobject

Text input content item

prompt_cache_breakpoint	PromptCacheBreakpoint	Marks an explicit prompt-cache boundary on this content block (OpenAI-style). Everything through the block carrying this marker is part of the candidate cached prefix. Supported natively by OpenAI GPT-5.6 and newer; on providers that use Anthropic-style `cache…
text*	string
type*	enum		input_text

InputVideoobject

Video input content item

processing	enum	Video processing mode. `agentic` enables agentic video processing and `static` forces fixed-rate frame sampling on providers that support it (currently Google Gemini).	agentic \| static
type*	enum		input_video
video_url*	string	A base64 data URL or remote URL that resolves to a video file

ItemReferenceItemobject

A reference to a previous response item by ID

id*	string
type*	enum		item_reference

JevRouterPluginobject

allowed_models	string[]	Alias of `models`, matching the auto-router field name. Entries from both fields are combined.	items ≤ 1024
cost_tier	string	Select low, medium, high, or a cost tier configured by the operator. Overrides the live-config tier and replaces the shared routing policy with that tier. Omit to use the live configuration. Model exclusions and the router kill switch still apply.
excluded_models	string[]	Remove these models from the router. Each entry is a model slug or a wildcard pattern (e.g. "xiaomi/*"). A `~author/family-latest` alias matches every revision of that family. Up to 1024 patterns, each at most 1024 characters, with 65536 total characters acros…	items ≤ 1024
id*	enum		jev-router
models	string[]	Restrict the router to these models. Each entry is a model slug or a wildcard pattern (e.g. "anthropic/*"), matched against the current pool; models outside the pool are ignored. A `~author/family-latest` alias matches every revision of that family. Up to 1024…	items ≤ 1024

Legacy_WebSearchServerToolobject

Web search tool configuration

engine	enum	Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses the Firecrawl search API. "parallel" uses the Parallel search…	native \| exa \| parallel \| firecrawl \| perplexity \| auto
filters	WebSearchDomainFilter
max_results	integer	Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped.
max_uses	integer	Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded on…
mode	enum	Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.	instant \| fast \| auto \| deep-lite \| deep \| deep-reasoning · +3 more
search_context_size	enum	Size of the search context for web search tools	low \| medium \| high
type*	enum		web_search
user_location	WebSearchUserLocation	User location information for web search
x_search	XSearchOptions	Enable SpaceXAI X (Twitter) search alongside native web search, with optional filters. Only applies to SpaceXAI endpoints with native search; omit to search the web only. X search is billed separately by SpaceXAI, per post and per user profile fetched.

LocalShellCallItemobject

A local shell command execution call

action*	object
call_id*	string
id*	string
status*	enum	in_progress \| completed \| incomplete
type*	enum	local_shell_call

LocalShellCallOutputItemobject

Output from a local shell command execution

id*	string
output*	string
status	enum	in_progress \| completed \| incomplete · nullable
type*	enum	local_shell_call_output

McpApprovalRequestItemobject

Request for approval to execute an MCP tool

arguments*	string
id*	string
name*	string
server_label*	string
type*	enum	mcp_approval_request

McpApprovalResponseItemobject

User response to an MCP tool approval request

approval_request_id*	string
approve*	boolean
id	any
reason	any
type*	enum	mcp_approval_response

McpCallItemobject

An MCP tool call with its output or error

approval_request_id	any
arguments*	string
error	string \| object \| object \| …	Error from an MCP tool call, either a plain message or a structured error	nullable
id*	string
name*	string
output	any
server_label*	string
status	enum		in_progress \| completed \| incomplete \| calling \| failed
type*	enum		mcp_call

McpHttpErrorobject

The MCP server request failed at the HTTP layer

code*	integer
message*	string
type*	enum	http_error

McpListToolsItemobject

List of available MCP tools from a server

error	any
id*	string
server_label*	string
tools*	object[]
type*	enum	mcp_list_tools

McpProtocolErrorobject

The MCP server returned a protocol-level error

code*	integer
message*	string
type*	enum	mcp_protocol_error

McpServerToolobject

MCP (Model Context Protocol) tool configuration

allowed_tools	string[] \| object	nullable
authorization	string
connector_id	string
headers	any
require_approval	object \| enum \| enum	nullable
server_description	string
server_label*	string
server_url	string
type*	enum	mcp

McpServerTool_OpenRouterobject

OpenRouter built-in server tool: connects the model to a remote MCP server and runs its tools during the response

parameters*	McpServerToolParameters	Configuration for a remote MCP server tool.
type*	enum		openrouter:mcp

McpServerToolParametersobject

Configuration for a remote MCP server tool.

allowed_tools	string[] \| object	Restrict the tools exposed to the model to this list or filter.	nullable
authorization	string	OAuth access token sent as the Authorization bearer to the server.
connector_id	string	Provider-defined connector identifier, forwarded as written to providers that run MCP themselves.
headers	any	Extra headers sent on every request to the server.
require_approval	object \| enum \| enum	Approval policy for tool calls. Defaults to always: a call that needs approval ends the response with an mcp_approval_request item, answered with an mcp_approval_response on the next request.	nullable
server_description	string	Extra context about the server, shown to the model.
server_label*	string	Label for this MCP server, used in mcp_list_tools and mcp_call items.
server_url	string	URL of the remote MCP server (streamable HTTP).

McpToolCallErrorstring | object | object | …

Error from an MCP tool call, either a plain message or a structured error

nullable

McpToolExecutionErrorobject

The MCP tool ran but reported a failure

content	any
type*	enum		mcp_tool_execution_error

ModerationPluginobject

id*

enum

moderation

NamespaceFunctionToolobject

A function tool grouped inside a namespace tool

allowed_callers	any
async	boolean	Lets the model keep working after calling this tool instead of waiting for its output. The tool is still executed by the client; return the result in a later request as a `function_call_output` with the original `call_id`. Only honored by providers whose Respo…
defer_loading	boolean
description	any
name*	string
output_schema	any
parameters	any
strict	any
type*	enum		function

NamespaceToolobject

Groups function/custom tools under a shared namespace

description*	string
name*	string
tools*	NamespaceFunctionTool \| CustomTool[]
type*	enum	namespace

OpenAIResponseCustomToolCallOutputobject

call_id*	string
id	string
output*	string \| InputText \| InputImage \| InputFile[]
type*	enum	custom_tool_call_output

OpenAIResponseFunctionToolCallOutputobject

call_id*	string
id	any
output*	string \| InputText \| InputImage \| InputFile[]
status	enum	in_progress \| completed \| incomplete · nullable
type*	enum	function_call_output

OpenAIResponsesAnnotationobject | object | object

OpenAIResponsesRefusalContentobject

refusal*	string
type*	enum		refusal

OpenAIResponsesToolChoiceenum | enum | enum | …

OpenAIResponsesTruncationenum

auto | disabled | null

OutputAdvisorServerToolItemobject

An openrouter:advisor server tool output item

advice	string	The advisor model's response (the advice text returned to the executor).
error	string	Error message when the advisor call did not produce advice. Set together with `status: 'failed'` on the terminal item.
id	string
instance_name	string	Provider-safe function name of the specific advisor instance that produced this item (e.g. `openrouter_advisor__1`). Present only when more than one advisor tool is configured; omitted for the default single advisor. Echo this field back unchanged so the advis…
model	string	Slug of the advisor model that was consulted.
prompt	string	The prompt the executor sent to the advisor.
status*	enum		in_progress \| completed \| incomplete \| failed
type*	enum		openrouter:advisor

OutputApplyPatchServerToolItemobject

An openrouter:apply_patch server tool output item. The turn halts when validation succeeds so the client can apply the patch and echo an `apply_patch_call_output` on the next turn.

call_id	string
error	string	The error message when the tool call failed before producing a result. Set together with `status: 'failed'`; absent on a successful call.
id	string
operation	object \| object \| object	The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it.
status*	enum		in_progress \| completed \| incomplete \| failed
type*	enum		openrouter:apply_patch

OutputArmorBlockedItemobject

A client tool call that OpenRouter Armor blocked. Emitted in place of the call when `plugins[armor].output_mode` is `custom_item`.

arguments*	string	The arguments exactly as the model wrote them.
call_id*	string	The call id the model chose. Use it to find this call in `safeguard_results`.
explanation*	string	The rule that blocked the call, in the same `[Rule Name]` form as `safeguard_results`.
id*	string
name*	string	The name of the tool the model called.
namespace	string	The namespace the tool belongs to, for namespaced tools such as MCP. Absent for a plain function tool.
reason*	string	The error text the model received as the result of this call. Sending this item back replays that text to the model.
status*	enum		completed
type*	enum		openrouter:armor_blocked

OutputBashServerToolItemobject

An openrouter:bash server tool output item

arguments	any	The raw tool-call arguments string as emitted by the model.
call_id	any	The model-generated tool call id from the originating turn.
command	string
container_id	string	The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed.
error	string	The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'failed'`; absent on a successful call. A non-zero `exitCode` is a command failure, not a tool failure.
exitCode	integer
files	object[]	Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API.
id	string
status*	enum		in_progress \| completed \| incomplete \| failed
stderr	string
stdout	string
type*	enum		openrouter:bash

OutputBrowserUseServerToolItemobject

An openrouter:browser_use server tool output item

action	string
id	string
screenshotB64	string
status*	enum	in_progress \| completed \| incomplete
type*	enum	openrouter:browser_use

OutputCodeInterpreterCallItemany | object

A code interpreter execution call with outputs

OutputCodeInterpreterServerToolItemobject

An openrouter:code_interpreter server tool output item

code	string
exitCode	integer
id	string
language	string
status*	enum	in_progress \| completed \| incomplete
stderr	string
stdout	string
type*	enum	openrouter:code_interpreter

OutputComputerCallItemobject

action	any
call_id*	string
id	string
pending_safety_checks*	object[]
status*	enum	completed \| incomplete \| in_progress
type*	enum	computer_call

OutputDatetimeItemobject

An openrouter:datetime server tool output item

datetime*	string	ISO 8601 datetime string
error	string	The error message when the tool call failed before producing a result. Set together with `status: 'failed'`; absent on a successful call.
id	string
status*	enum		in_progress \| completed \| incomplete \| failed
timezone*	string	IANA timezone name
type*	enum		openrouter:datetime

OutputFileSearchCallItemobject | object

OutputFileSearchServerToolItemobject

An openrouter:file_search server tool output item

id	string
queries	string[]
status*	enum	in_progress \| completed \| incomplete
type*	enum	openrouter:file_search

OutputFilesServerToolItemobject

An openrouter:files server tool output item

arguments	any	The raw tool-call arguments string as emitted by the model.
call_id	any	The model-generated tool call id from the originating turn.
error	string	Error message when the file operation failed.
file_id	string	The target file id supplied in the tool-call arguments.
filename	string	The target filename supplied in the tool-call arguments.
id	string
operation	string	The file operation performed (list, read, write, or edit).
result	string	JSON-serialized result of the file operation.
status*	enum		in_progress \| completed \| incomplete
type*	enum		openrouter:files

OutputFusionServerToolItemobject

An openrouter:fusion server tool output item

analysis	FusionAnalysisResult	Structured analysis produced by the fusion analyst model.
error	string	Error message when the fusion run did not produce an analysis result.
failed_models	object[]	Models that were requested as part of the analysis panel but did not produce a response. Present when at least one requested analysis model failed. On a completed item the fusion result is still usable but was produced from a degraded panel; on a failed item i…
failure_reason	string	Typed failure reason when the fusion run failed. Possible values include: all_panels_failed, insufficient_credits, rate_limited, invalid_model, judge_not_valid_json, judge_schema_mismatch, judge_upstream_error, judge_empty_completion. The four analysis-stage c…
id	string
responses	object[]	Analysis models that produced a response in this fusion run, with each model's full panel content.
sources	FusionSource[]	Web pages the analysis panels and analyst retrieved via web search during this fusion run, deduplicated by URL across the whole run. Present when at least one model cited a source.
status*	enum		in_progress \| completed \| incomplete
type*	enum		openrouter:fusion

OutputImageGenerationCallItemobject | object

OutputImageGenerationServerToolItemobject

An openrouter:image_generation server tool output item

error	string	The error message when the tool call failed before producing a result. Set together with `status: 'failed'`; absent on a successful call.
id	string
imageB64	string
imageUrl	string
prompt	string	The prompt (possibly rewritten) that the image was generated from.
result	any	The generated image as a base64-encoded string or URL, matching OpenAI image_generation_call format
revisedPrompt	string
status*	enum		in_progress \| completed \| incomplete \| failed
type*	enum		openrouter:image_generation

OutputItemCodeInterpreterCallobject

code	any
container_id	string
id*	string
outputs	any
status*	enum	in_progress \| completed \| incomplete \| interpreting \| failed
type*	enum	code_interpreter_call

OutputItemFileSearchCallobject

id*	string
queries*	string[]
status*	enum	completed \| searching \| in_progress \| failed \| incomplete
type*	enum	file_search_call

OutputItemImageGenerationCallobject

id*	string
result	any	default: null
status*	enum	in_progress \| completed \| generating \| failed
type*	enum	image_generation_call

OutputItemReasoningobject

content	ReasoningTextContent[]
encrypted_content	any
id*	string
status	enum \| enum \| enum
summary*	ReasoningSummaryText[]
type*	enum	reasoning

OutputItemWebSearchCallobject

action	object \| object \| object
id*	string
status*	enum	completed \| searching \| in_progress \| failed \| incomplete
type*	enum	web_search_call

OutputMemoryServerToolItemobject

An openrouter:memory server tool output item

action	enum	read \| write \| delete
id	string
key	string
status*	enum	in_progress \| completed \| incomplete
type*	enum	openrouter:memory
value	any

OutputMessageobject

content*	ResponseOutputText \| OpenAIResponsesRefusalContent[]
id*	string
phase	enum \| enum	The phase of an assistant message. Use `commentary` for an intermediate assistant message and `final_answer` for the final assistant message. For follow-up requests with models like `gpt-5.3-codex` and later, preserve and resend phase on all assistant messages…	nullable
role*	enum		assistant
status	enum \| enum \| enum
type*	enum		message

OutputMessageItemobject | object

An output message item

OutputModalityEnumenum

text | image

OutputReasoningItemobject | object

An output item containing reasoning

OutputSearchModelsServerToolItemobject

An openrouter:experimental__search_models server tool output item

arguments	string	The JSON arguments submitted to the search tool (e.g. {"query":"Claude"})
error	string	The error message when the tool call failed before producing a result. Set together with `status: 'failed'`; absent on a successful call.
id	string
query	string
status*	enum		in_progress \| completed \| incomplete \| failed
type*	enum		openrouter:experimental__search…

OutputShellServerToolItemobject

An openrouter:shell server tool output item

action	object
arguments	any	The raw tool-call arguments string as emitted by the model.
call_id	any	The model-generated tool call id from the originating turn.
container_id	string	The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed.
error	string	The error message when the sandbox call failed before producing a result (for example, the per-user container limit was reached). Set together with `status: 'failed'`; absent on a successful call. `output` is omitted when `error` is set.
files	object[]	Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API.
id	string
output	ShellCallOutputContent[]
status*	enum		in_progress \| completed \| incomplete \| failed
type*	enum		openrouter:shell

OutputSubagentServerToolItemobject

An openrouter:subagent server tool output item

call_id	string	EXPERIMENTAL — subject to change without notice. The `call_id` of the tool call that spawned this subagent. This id will also be included as the `subagent_id` on any `function_call` items created by the subagent. This must be returned in the request so the `fu…
error	string	Error message when the subagent task did not produce an outcome. Set together with `status: 'failed'` on the terminal item.
id	string
instance_name	string	Provider-safe function name of the specific subagent instance that produced this item (e.g. `openrouter_subagent__1`). Present only on items from non-default instances — the second and later subagent entries in the request `tools` array. The first (default) in…
model	string	Slug of the worker model that executed the task.
name	string	Configured name of the subagent that executed the task (the `name` on its tool entry). Present only for named subagents; omitted for an unnamed (default) subagent.
outcome	string	The worker model's result (the outcome text returned to the delegating model).
status*	enum		in_progress \| completed \| incomplete \| failed
task_description	string	The task description the delegating model sent to the worker.
task_name	string	The short task identifier the delegating model supplied.
type*	enum		openrouter:subagent

OutputTextEditorServerToolItemobject

An openrouter:text_editor server tool output item

command	enum	view \| create \| str_replace \| insert
filePath	string
id	string
status*	enum	in_progress \| completed \| incomplete
type*	enum	openrouter:text_editor

OutputToolSearchServerToolItemobject

An openrouter:tool_search server tool output item

arguments	string	The JSON arguments of the model call, verbatim. Replaying the item reuses them.
call_id	string	The ID of the model call that ran the search. Replaying the item reuses it.
catalog_changes	string	What the announced index added and removed since the previous one, when the request opted into `announce_catalog_changes` and the catalog changed between model turns. Replaying the item shows the same lines.
catalog_index	string	The deferred-tool index the router showed the model with a pre-search, listing tool sources and names. Replaying the item shows the same index.
error	string	The error message when the tool call failed before producing a result. Set together with `status: 'failed'`; absent on a successful call.
format	enum	How the model saw the matches. `compact` means each tool by name, description, and input shape, plus a call example. Replaying the item renders the same result.	compact
hint	string	The guidance the model got when the search matched no tools.
id	string
matches	object[]
query	string
sources	object	The other deferred tools of each source a match came from, by name, when the search listed siblings. Replaying the item shows the same names.
status*	enum		in_progress \| completed \| incomplete \| failed
turn_call_ids	string[]	The IDs of every tool call in the model response that ran the search, in order. Replaying the item keeps those calls in one turn.
type*	enum		openrouter:tool_search

OutputWebFetchServerToolItemobject

An openrouter:web_fetch server tool output item

content	string
error	string	The error message if the fetch failed.
httpStatus	integer	The HTTP status code returned by the upstream URL fetch.
id	string
status*	enum		in_progress \| completed \| incomplete
title	string
type*	enum		openrouter:web_fetch
url	string

OutputWebSearchCallItemobject | object

OutputWebSearchServerToolItemobject

An openrouter:web_search server tool output item

action	object	The search action performed, matching OpenAI web_search_call.action shape. Includes the query the model issued and optional source URLs returned by the search provider.
error	string	The error message when the tool call failed before producing a result. Set together with `status: 'failed'`; absent on a successful call.
id	string
status*	enum		in_progress \| completed \| incomplete \| failed
type*	enum		openrouter:web_search

ParetoRouterPluginobject

enabled	boolean	Set to false to disable the pareto-router plugin for this request. Defaults to true.
id*	enum		pareto-router
max_price	number	Maximum input price in USD per million tokens. When set, quality-tier selection (min_coding_score) is bypassed: the router computes the Pareto frontier over the top coding models and routes to the best-scoring frontier model priced at or below this cap, fallin…	n ≥ 0 · format: double
min_coding_score	number	Minimum coding quality score between 0 and 1. Maps to internal quality tiers: >= 0.66 → high (top coding models), >= 0.33 → medium (strong modern flagships), < 0.33 → low (capable coders above the median). Omit to default to the highest tier (equivalent to >= …	0 ≤ n ≤ 1 · format: double
price_source	enum	Price source for the Pareto frontier cost axis and for enforcing max_price. "prompt" uses catalog list price (endpoint.pricing.prompt). "weighted_avg" uses traffic-weighted effective input price from ClickHouse, falling back to prompt price for models without …	prompt \| weighted_avg

PDFParserEngineenum | enum

The engine to use for parsing PDF files. "pdf-text" is deprecated and automatically redirected to "cloudflare-ai".

PDFParserOptionsobject

Options for PDF parsing.

engine

enum | enum

The engine to use for parsing PDF files. "pdf-text" is deprecated and automatically redirected to "cloudflare-ai".

PercentileLatencyCutoffsobject

Percentile-based latency cutoffs. All specified cutoffs must be met for an endpoint to be preferred.

p50	any	Maximum p50 latency (seconds)	format: double
p75	any	Maximum p75 latency (seconds)	format: double
p90	any	Maximum p90 latency (seconds)	format: double
p99	any	Maximum p99 latency (seconds)	format: double

PercentileThroughputCutoffsobject

Percentile-based throughput cutoffs. All specified cutoffs must be met for an endpoint to be preferred.

p50	any	Minimum p50 throughput (tokens/sec)	format: double
p75	any	Minimum p75 throughput (tokens/sec)	format: double
p90	any	Minimum p90 throughput (tokens/sec)	format: double
p99	any	Minimum p99 throughput (tokens/sec)	format: double

PreferredMaxLatencynumber | object

Preferred maximum latency (in seconds). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints above the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback …

nullable

PreferredMinThroughputnumber | object

Preferred minimum throughput (in tokens per second). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints below the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may caus…

nullable

Preview_20250311_WebSearchServerToolobject

Web search preview tool configuration (2025-03-11 version)

engine	enum	Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses the Firecrawl search API. "parallel" uses the Parallel search…	native \| exa \| parallel \| firecrawl \| perplexity \| auto
filters	WebSearchDomainFilter
max_results	integer	Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped.
max_uses	integer	Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded on…
mode	enum	Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.	instant \| fast \| auto \| deep-lite \| deep \| deep-reasoning · +3 more
search_context_size	enum	Size of the search context for web search tools	low \| medium \| high
type*	enum		web_search_preview_2025_03_11
user_location	Preview_WebSearchUserLocation
x_search	XSearchOptions	Enable SpaceXAI X (Twitter) search alongside native web search, with optional filters. Only applies to SpaceXAI endpoints with native search; omit to search the web only. X search is billed separately by SpaceXAI, per post and per user profile fetched.

Preview_WebSearchServerToolobject

Web search preview tool configuration

engine	enum	Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses the Firecrawl search API. "parallel" uses the Parallel search…	native \| exa \| parallel \| firecrawl \| perplexity \| auto
filters	WebSearchDomainFilter
max_results	integer	Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped.
max_uses	integer	Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded on…
mode	enum	Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.	instant \| fast \| auto \| deep-lite \| deep \| deep-reasoning · +3 more
search_context_size	enum	Size of the search context for web search tools	low \| medium \| high
type*	enum		web_search_preview
user_location	Preview_WebSearchUserLocation
x_search	XSearchOptions	Enable SpaceXAI X (Twitter) search alongside native web search, with optional filters. Only applies to SpaceXAI endpoints with native search; omit to search the web only. X search is billed separately by SpaceXAI, per post and per user profile fetched.

Preview_WebSearchUserLocationobject

city	any
country	any
region	any
timezone	any
type*	enum	approximate

PromptCacheBreakpointobject

Marks an explicit prompt-cache boundary on this content block (OpenAI-style). Everything through the block carrying this marker is part of the candidate cached prefix. Supported natively by OpenAI GPT-5.6 and newer; on providers that use Anthropic-style `cache…

mode*	enum		explicit
ttl	any

PromptCacheOptionsobject

Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. `ttl` sets the minimum cache lifetime for every breakpoint the request writes: "30m" (default) or "12h"…

mode*	enum		explicit
ttl	any

ProviderNameenum

ProviderOptionsobject

Provider-specific options keyed by provider slug. The provider segment is case-insensitive; an endpoint tag after `/` must match the endpoint slug exactly. Only options for the matched provider are forwarded; the rest are ignored. Unrecognized keys are silentl…

01ai	object
ai21	object
aion-labs	object
akashml	object
alibaba	object
amazon-bedrock	object
amazon-bedrock/claude-on-aws	object
amazon-nova	object
ambient	object
antdigital	object
anthropic	object
anthropic/2	object
anyscale	object
arcee-ai	object
assemblyai	object
atlas-cloud	object
atoma	object
avian	object
azure	object
baidu	object
baseten	object
black-forest-labs	object
byteplus	object
centml	object
cerebras	object
chutes	object
cirrascale	object
clarifai	object
claude-on-aws	object
cloudflare	object
cohere	object
coreweave	object
cosine	object
crofai	object
crucible	object
crusoe	object
darkbloom	object
databricks	object
decart	object
deepgram	object
deepinfra	object
deepseek	object
dekallm	object
digitalocean	object
elevenlabs	object
enfer	object
fake-provider	object
featherless	object
fireworks	object
fish-audio	object
friendli	object
gmicloud	object
google-ai-studio	object
google-vertex	object
gopomelo	object
groq	object
heygen	object
huggingface	object
hyperbolic	object
hyperbolic-quantized	object
inception	object
inceptron	object
inferact-vllm	object
inference-net	object
infermatic	object
inflection	object
inocloud	object
io-net	object
ionstream	object
klusterai	object
krea	object
kt	object
lambda	object
lepton	object
liquid	object
lynn	object
lynn-private	object
makora	object
mancer	object
mancer-old	object
mara	object
meta	object
minimax	object
mistral	object
modal	object
modelrun	object
modular	object
moonshotai	object
morph	object
ncompass	object
near-ai	object
nebius	object
nex-agi	object
nextbit	object
nineteen	object
novita	object
nvidia	object
octoai	object
ollama	object
open-inference	object
openai	object
parallel	object
parasail	object
pareto-alpha	object
particle-ai	object
pearl-research	object
perceptron	object
perplexity	object
phala	object
poolside	object
primalabs	object
primeintellect	object
quiver	object
recraft	object
recursal	object
recursive	object
reflection	object
reka	object
relace	object
replicate	object
respan	object
river	object
runway	object
sail-research	object
sakana	object
sakana-ai	object
sambanova	object
sambanova-cloaked	object
scaledown	object
seed	object
sf-compute	object
siliconflow	object
sourceful	object
speechify	object
stealth	object
stepfun	object
streamlake	object
switchpoint	object
targon	object
tencent	object
tenstorrent	object
thinkingmachines	object
together	object
together-lite	object
typesafe	object
ubicloud	object
unbiased	object
upstage	object
venice	object
voyageai	object
wafer	object
wandb	object
wandb-legacy	object
xai	object
xiaomi	object
z-ai	object

ProviderPreferencesobject

When multiple model providers are available, optionally indicate your routing preference.

allow_fallbacks	any	Whether to allow backup providers to serve requests - true: (default) when the primary provider (or your custom providers in "order") is unavailable, use the next best provider. - false: use only the primary/custom provider, and return the upstream error if it…
data_collection	enum	Data collection setting. If no available model provider meets the requirement, your request will return an error. - allow: (default) allow providers which store user data non-transiently and may train on it	deny \| allow \| null
enforce_distillable_text	any	Whether to restrict routing to only models that allow text distillation. When true, only models where the author has allowed distillation will be used.
ignore	any	List of provider slugs to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request.
max_price	object	The object specifying the maximum price you want to pay for this request. USD price per million tokens, for prompt and completion.
only	any	List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request.
options	ProviderOptions	Provider-specific options keyed by provider slug. The provider segment is case-insensitive; an endpoint tag after `/` must match the endpoint slug exactly. Only options for the matched provider are forwarded; the rest are ignored. Unrecognized keys are silentl…
order	any	An ordered list of provider slugs. The router will attempt to use the first provider in the subset of this list that supports your requested model, and fall back to the next if it is unavailable. If no providers are available, the request will fail with an err…
preferred_max_latency	number \| object	Preferred maximum latency (in seconds). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints above the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may cause a fallback …	nullable
preferred_min_throughput	number \| object	Preferred minimum throughput (in tokens per second). Can be a number (applies to p50) or an object with percentile-specific cutoffs. Endpoints below the threshold(s) may still be used, but are deprioritized in routing. When using fallback models, this may caus…	nullable
quantizations	any	A list of quantization levels to filter the provider by.
require_parameters	any	Whether to filter providers to only those that support the parameters you've provided. If this setting is omitted or set to false, then providers will receive only the parameters they support, and ignore the rest.
sort	enum \| object	The sorting strategy to use for this request, if "order" is not specified. When set, no load balancing is performed.	nullable
zdr	any	Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. When true, only endpoints that do not retain prompts will be used.

ProviderSortenum

The provider sorting strategy (price, throughput, latency)

price | throughput | latency | exacto

ProviderSortConfigobject

The provider sorting strategy (price, throughput, latency)

by	enum	The provider sorting strategy (price, throughput, latency)	price \| throughput \| latency \| exacto \| null
partition	enum	Partitioning strategy for sorting: "model" (default) groups endpoints by model before sorting (fallback models remain fallbacks), "none" sorts all endpoints together regardless of model.	model \| none \| null

Quantizationenum

int4 | int8 | fp4 | mxfp4 | nvfp4 | fp6 · +6 more

ReasoningConfigany | object

Configuration for reasoning mode in the response

nullable

ReasoningContextenum

Controls which reasoning is available to the model. `auto` uses the model default (same as omitting); `all_turns` includes reasoning from earlier turns passed in input; `current_turn` limits to the current turn only. Only supported by OpenAI GPT-5.6 and newer.

auto | all_turns | current_turn | null

ReasoningEffortenum

ReasoningFormatenum

ReasoningItemobject | object

Reasoning output item with signature and format extensions

ReasoningModeenum

Selects the reasoning mode. `standard` is the default; `pro` engages deeper reasoning on models that support it, billed at standard token rates. Only supported by OpenAI GPT-5.6 and newer.

standard | pro | null

ReasoningSummaryTextobject

text*	string
type*	enum		summary_text

ReasoningSummaryVerbosityenum

auto | concise | detailed | null

ReasoningTextContentobject

text*	string
type*	enum		reasoning_text

RequestMetadataany

Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.

ResponseHealingPluginobject

enabled	boolean	Set to false to disable the response-healing plugin for this request. Defaults to true.
id*	enum		response-healing

ResponseIncludesEnumenum

ResponseOutputTextobject

annotations	OpenAIResponsesAnnotation[]
logprobs	object[]
text*	string
type*	enum	output_text

SearchContextSizeEnumenum

Size of the search context for web search tools

low | medium | high

SearchModelsServerTool_OpenRouterobject

OpenRouter built-in server tool: searches and filters AI models available on OpenRouter

parameters	SearchModelsServerToolConfig	Configuration for the openrouter:experimental__search_models server tool
type*	enum		openrouter:experimental__search…

SearchModelsServerToolConfigobject

Configuration for the openrouter:experimental__search_models server tool

max_results

integer

Maximum number of models to return. Defaults to 5, max 20.

SearchQualityLevelenum

How much context to retrieve per result. Applies to Exa, Parallel, and Perplexity engines; ignored with native provider search and Firecrawl. For Exa, pins a fixed per-result character cap (low=5,000, medium=15,000, high=30,000); when omitted, Exa picks an ada…

low | medium | high

ShellCallItemobject

A shell command execution call (newer variant)

action*	object
arguments	any	The raw tool-call arguments string as emitted by the model. Echo back unchanged when replaying history; used verbatim to preserve provider prompt-cache prefixes.
call_id*	string
environment	any
id	any
status	enum		in_progress \| completed \| incomplete · nullable
type*	enum		shell_call

ShellCallOutputContentobject

Captured stdout and stderr for one command of a shell call, with its exit or timeout outcome.

outcome*	object \| object
stderr*	string
stdout*	string

ShellCallOutputItemobject

Output from a shell command execution (newer variant)

call_id*	string
container_id	string	The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed.
error	string	The error message when the sandbox call failed before producing a result, as echoed from a failed `shell_call_output` emission.
files	object[]	Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API.
id	any
max_output_length	any
output*	ShellCallOutputContent[]
status	enum		in_progress \| completed \| incomplete · nullable
type*	enum		shell_call_output

ShellServerToolobject

Shell tool configuration

type*

enum

shell

ShellServerTool_OpenRouterobject

OpenRouter built-in server tool: runs shell commands server-side in a sandboxed container (a sandbox-backed clone of OpenAI's hosted shell tool)

parameters	ShellServerToolConfig	Configuration for the openrouter:shell server tool
type*	enum		openrouter:shell

ShellServerToolConfigobject

Configuration for the openrouter:shell server tool

engine	enum	Which shell engine to use. "openrouter" runs commands server-side in the OpenRouter sandbox. "auto" (default) keeps the provider's native hosted shell when available (OpenAI); on other providers the call is routed to the OpenRouter sandbox.	auto \| openrouter
environment	object \| object	Server-side execution environment for the shell tool. Only container-backed environments are supported; "local" shells are not.

ShellServerToolEngineenum

Which shell engine to use. "openrouter" runs commands server-side in the OpenRouter sandbox. "auto" (default) keeps the provider's native hosted shell when available (OpenAI); on other providers the call is routed to the OpenRouter sandbox.

auto | openrouter

ShellServerToolEnvironmentobject | object

Server-side execution environment for the shell tool. Only container-backed environments are supported; "local" shells are not.

StopServerToolsWhenStopServerToolsWhenCondition[]

Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final tu…

items ≥ 1

StopServerToolsWhenConditionobject | object | object | …

A single condition that, when met, halts the server-tool agent loop.

StopServerToolsWhenFinishReasonIsobject

Stop when the upstream model emits this finish reason (e.g. `length`).

reason*	string		length ≥ 1
type*	enum		finish_reason_is

StopServerToolsWhenHasToolCallobject

Stop after a tool with this name has been called.

tool_name*	string		length ≥ 1
type*	enum		has_tool_call

StopServerToolsWhenMaxCostobject

Stop once cumulative cost across the loop exceeds this dollar threshold.

max_cost_in_dollars*	number		format: double
type*	enum		max_cost

StopServerToolsWhenMaxTokensUsedobject

Stop once cumulative token usage across the loop exceeds this threshold.

max_tokens*	integer
type*	enum		max_tokens_used

StopServerToolsWhenStepCountIsobject

Stop after the agent loop has executed this many steps.

step_count*	integer
type*	enum		step_count_is

StoredPromptTemplateobject

id*	string
variables	any

SubagentNestedToolobject

A tool made available to the subagent. Only OpenRouter server tools (e.g. openrouter:web_search) are supported; function tools are rejected because the worker has no way to execute them. The subagent tool may not list itself.

parameters	object
type*	string

SubagentReasoningobject

Reasoning configuration forwarded to the subagent call. Use this to control reasoning effort and token budget for models that support extended thinking.

effort	enum	Reasoning effort level for the subagent call.	max \| xhigh \| high \| medium \| low \| minimal · +1 more
max_tokens	integer	Maximum number of reasoning tokens the subagent may use. Forwarded to the subagent call as `reasoning.max_tokens`.

SubagentServerTool_OpenRouterobject

OpenRouter built-in server tool: delegates self-contained tasks to a smaller, cheaper, faster worker model (any OpenRouter model) mid-generation and returns its outcome. The worker may run as a sub-agent with its own tools.

parameters	SubagentServerToolConfig	Configuration for one openrouter:subagent server tool entry.
type*	enum		openrouter:subagent

SubagentServerToolConfigobject

Configuration for one openrouter:subagent server tool entry.

inherit_functions	boolean	EXPERIMENTAL — subject to change without notice. When true, the subagent inherits every client function defined in the request's top-level `tools` list. Supported on the Responses API (`/api/v1/responses`) only; other APIs reject it with a `400`.
inherited_function_names	string[]	EXPERIMENTAL — subject to change without notice. Names of the top-level function tools that the subagent will inherit. Any tool that matches by name will be copied fully into the tools array of the subagent. When `inherit_functions` is `true`, this list does n…
instructions	string	System instructions for the subagent. When omitted, the subagent responds with no system prompt of its own.
max_completion_tokens	integer	Maximum number of output tokens (including reasoning) the subagent may produce. When omitted, the provider's default applies.
max_tool_calls	integer	Maximum number of tool-calling steps the subagent may take during its agentic loop. Capped at 25. Only relevant when the subagent is given tools. Forwarded to the subagent call as `max_tool_calls`.	1 ≤ n ≤ 25
model	string	Slug of the model that executes delegated tasks (any OpenRouter model). Typically a smaller, cheaper, faster model than the one delegating. When omitted, the model from the outer API request is used. The subagent tool itself cannot be the subagent model.
name	string	Optional name for this subagent. The model sees one tool per named subagent (and one default for an unnamed entry). Names must be unique across subagent entries. Letters, digits, spaces, underscores, and dashes; trimmed; 1–64 chars.	length ≥ 1 · length ≤ 64
reasoning	SubagentReasoning	Reasoning configuration forwarded to the subagent call. Use this to control reasoning effort and token budget for models that support extended thinking.
temperature	number	Sampling temperature forwarded to the subagent call. When omitted, the provider's default applies.	format: double
tools	SubagentNestedTool[]	Tools the subagent may use while executing a delegated task. The subagent runs as an agentic sub-agent over these tools, then returns its outcome. Only OpenRouter server tools are supported — function tools are rejected — and the list must not include the suba…

SwitchyardRouterPluginobject

algorithm	enum	Routing algorithm for this request. "capability" calls a small judge model to rate how demanding the task is, then picks the efficient or capable candidate. "stage" reads the tool-result history (errors, repeated failures, edits landing) and calls the judge on…	capability \| stage \| auto \| random \| composite \| passthrough
id*	enum		switchyard-router
judge_model	string	The model that runs the judge call for the judge-backed algorithms ("capability", "stage", and "composite"). The model must support structured outputs and have a provider that your account and request settings allow. Otherwise, the request uses the platform de…	length ≥ 1

TextConfigobject

Text output configuration including format and verbosity

format	object \| object \| object	Text response format configuration
verbosity	enum		high \| low \| medium \| null

TextExtendedConfigobject | object

Text output configuration including format and verbosity

ToolCallStatusenum

in_progress | completed | incomplete

ToolChoiceAllowedobject

Constrains the model to a pre-defined set of allowed tools

mode*	enum \| enum
tools*	object[]
type*	enum	allowed_tools

ToolChoiceMcpobject

Forces a call to the named MCP server; `name` narrows it to one of its tools

name	any
server_label*	string
type*	enum	mcp

ToolSearchCallItemobject

A tool search call the client executed

arguments	any
call_id*	string
execution*	enum	server \| client
id	any
status	enum	in_progress \| completed \| incomplete \| null
type*	enum	tool_search_call

ToolSearchOutputItemobject

The tools a client-executed tool search loaded

call_id*	string
execution*	enum	server \| client
id	any
status	enum	in_progress \| completed \| incomplete \| null
tools*	any \| Preview_WebSearchServerTool \| Preview_20250311_WebSearchServerTool[]
type*	enum	tool_search_output

ToolSearchServerToolobject

OpenRouter built-in server tool: finds tools marked `defer_loading` and makes them callable

parameters	ToolSearchServerToolConfig	Configuration for the openrouter:tool_search server tool
type*	enum		openrouter:tool_search

ToolSearchServerToolConfigobject

Configuration for the openrouter:tool_search server tool

max_results

integer

Maximum tools returned by one search. Defaults to 5.

TraceConfigobject

Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.

generation_name	string
parent_span_id	string
span_name	string
trace_id	string
trace_name	string

URLCitationobject

content	string
end_index*	integer
start_index*	integer
title*	string
type*	enum	url_citation
url*	string

WebFetchEngineEnumenum

Which fetch engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in fetch. "exa" uses Exa Contents API. "openrouter" uses direct HTTP fetch. "firecrawl" uses Firecrawl scrape. "parallel" u…

WebFetchPluginobject

allowed_domains	string[]	Only fetch from these domains.
blocked_domains	string[]	Never fetch from these domains.
id*	enum		web-fetch
max_content_tokens	integer	Maximum content length in approximate tokens. Content exceeding this limit is truncated.
max_uses	integer	Maximum number of web fetches per request. Once exceeded, the tool returns an error.

WebFetchServerToolobject

OpenRouter built-in server tool: fetches full content from a URL (web page or PDF)

parameters	WebFetchServerToolConfig	Configuration for the openrouter:web_fetch server tool
type*	enum		openrouter:web_fetch

WebFetchServerToolConfigobject

Configuration for the openrouter:web_fetch server tool

allowed_domains	string[]	Only fetch from these domains.
blocked_domains	string[]	Never fetch from these domains.
engine	enum	Which fetch engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in fetch. "exa" uses Exa Contents API. "openrouter" uses direct HTTP fetch. "firecrawl" uses Firecrawl scrape. "parallel" u…	auto \| native \| openrouter \| exa \| parallel \| firecrawl
max_content_tokens	integer	Maximum content length in approximate tokens. Content exceeding this limit is truncated.
max_uses	integer	Maximum number of web fetches per request. Once exceeded, the tool returns an error.

WebSearchDomainFilterobject

allowed_domains	any
blocked_domains	any
excluded_domains	any

WebSearchEngineenum

The search engine to use for web search.

native | exa | firecrawl | parallel | perplexity

WebSearchEngineEnumenum

Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses the Firecrawl search API. "parallel" uses the Parallel search…

WebSearchModeenum

Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.

WebSearchPluginobject

enabled	boolean	Set to false to disable the web-search plugin for this request. Defaults to true.
engine	enum	The search engine to use for web search.	native \| exa \| firecrawl \| parallel \| perplexity
exclude_domains	string[]	A list of domains to exclude from web search results. Supports wildcards (e.g. "*.substack.com") and path filtering (e.g. "openai.com/blog").
id*	enum		web
include_domains	string[]	A list of domains to restrict web search results to. Supports wildcards (e.g. "*.substack.com") and path filtering (e.g. "openai.com/blog").
max_results	integer
max_uses	integer	Maximum number of times the model can invoke web search in a single turn. Passed through to native providers that support it (e.g. Anthropic).
mode	enum	Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.	instant \| fast \| auto \| deep-lite \| deep \| deep-reasoning · +3 more
search_prompt	string
user_location	any \| any
x_search	XSearchOptions	Enable SpaceXAI X (Twitter) search alongside native web search, with optional filters. Only applies to SpaceXAI endpoints with native search; omit to search the web only. X search is billed separately by SpaceXAI, per post and per user profile fetched.

WebSearchServerToolobject

Web search tool configuration (2025-08-26 version)

engine	enum	Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses the Firecrawl search API. "parallel" uses the Parallel search…	native \| exa \| parallel \| firecrawl \| perplexity \| auto
filters	WebSearchDomainFilter
max_results	integer	Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped.
max_uses	integer	Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded on…
mode	enum	Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.	instant \| fast \| auto \| deep-lite \| deep \| deep-reasoning · +3 more
search_context_size	enum	Size of the search context for web search tools	low \| medium \| high
type*	enum		web_search_2025_08_26
user_location	WebSearchUserLocation	User location information for web search
x_search	XSearchOptions	Enable SpaceXAI X (Twitter) search alongside native web search, with optional filters. Only applies to SpaceXAI endpoints with native search; omit to search the web only. X search is billed separately by SpaceXAI, per post and per user profile fetched.

WebSearchServerTool_OpenRouterobject

OpenRouter built-in server tool: searches the web for current information

parameters	WebSearchServerToolConfig	Configuration for the openrouter:web_search server tool
type*	enum		openrouter:web_search

WebSearchServerToolConfigobject

Configuration for the openrouter:web_search server tool

allowed_domains	string[]	Limit search results to these domains. Supported by Exa, Firecrawl, Parallel, Perplexity, and most native providers (Anthropic, OpenAI, SpaceXAI). Cannot be used with excluded_domains.
engine	enum	Which search engine to use. "auto" (default) uses native if the provider supports it, otherwise Exa. "native" forces the provider's built-in search. "exa" forces the Exa search API. "firecrawl" uses the Firecrawl search API. "parallel" uses the Parallel search…	native \| exa \| parallel \| firecrawl \| perplexity \| auto
excluded_domains	string[]	Exclude search results from these domains. Supported by Exa, Firecrawl, Parallel, Perplexity, Anthropic, OpenAI, and SpaceXAI. Cannot be used with allowed_domains.
max_characters	integer	Exact maximum number of characters of content per search result. Applies to the Exa, Parallel, and Perplexity engines; ignored with native provider search and Firecrawl. For Exa, caps highlight content per result. For Parallel, caps excerpt content per result …
max_results	integer	Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped.
max_total_results	integer	Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops. Defaults to 50 when not specified.
max_uses	integer	Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded on…
mode	enum	Engine-native search mode. Exa supports instant, fast, auto (default), deep-lite, deep, and deep-reasoning. Parallel supports turbo, fast, basic (default), and advanced. Modes unsupported by the selected engine are ignored.	instant \| fast \| auto \| deep-lite \| deep \| deep-reasoning · +3 more
search_context_size	enum	How much context to retrieve per result. Applies to Exa, Parallel, and Perplexity engines; ignored with native provider search and Firecrawl. For Exa, pins a fixed per-result character cap (low=5,000, medium=15,000, high=30,000); when omitted, Exa picks an ada…	low \| medium \| high
user_location	WebSearchUserLocationServerTool	Approximate user location for location-biased results.
x_search	XSearchOptions	Enable SpaceXAI X (Twitter) search alongside native web search, with optional filters. Only applies to SpaceXAI endpoints with native search; omit to search the web only. X search is billed separately by SpaceXAI, per post and per user profile fetched.

WebSearchSourceobject

type*	enum		url
url*	string

WebSearchStatusenum

completed | searching | in_progress | failed | incomplete

WebSearchUserLocationobject

User location information for web search

city	any
country	any
region	any
timezone	any
type	enum	approximate

WebSearchUserLocationServerToolobject

Approximate user location for location-biased results.

city	any
country	any
region	any
timezone	any
type	enum	approximate

XSearchOptionsobject

Enable SpaceXAI X (Twitter) search alongside native web search, with optional filters. Only applies to SpaceXAI endpoints with native search; omit to search the web only. X search is billed separately by SpaceXAI, per post and per user profile fetched.

allowed_x_handles	string[]	Only include posts from these X handles (max 20). Cannot be used with excluded_x_handles.	items ≤ 20
enable_image_understanding	boolean	Analyze images attached to matching posts.
enable_video_understanding	boolean	Analyze videos attached to matching posts.
excluded_x_handles	string[]	Exclude posts from these X handles (max 20). Cannot be used with allowed_x_handles.	items ≤ 20
from_date	string	Start of the post date range (ISO 8601 date, e.g. "2025-01-01").	format: date
to_date	string	End of the post date range (ISO 8601 date, e.g. "2025-12-31").	format: date

Validate a payload

before you spend tokens

shell

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