--- title: "Create a response" method: POST path: "/responses" tags: ["beta.responses"] --- # Create a response `POST /responses` Creates a streaming or non-streaming response using OpenResponses API format ## Headers - `X-OpenRouter-Metadata` 'disabled' | 'enabled' — Opt-in level for surfacing routing metadata on the response under `openrouter_metadata`. ## Request body - ResponsesRequest — Request schema for Responses endpoint - `background` boolean, nullable - `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. Currently supported for Anthropic Claude models. - `ttl` '5m' | '1h' - `type` 'ephemeral', required - `debug` ChatDebugOptions — 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. - `frequency_penalty` number, double, nullable - `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` ResponseIncludesEnum[], nullable - `input` union — Input for a response request - can be a string or array of items - string - union[] - union - ReasoningItem — Reasoning output item with signature and format extensions - `content` ReasoningTextContent[], nullable - `text` string, required - `type` 'reasoning_text', required - `encrypted_content` string, nullable - `id` string, required - `status` union - 'completed' - 'incomplete' - 'in_progress' - `summary` ReasoningSummaryText[], required - `text` string, required - `type` 'summary_text', required - `type` 'reasoning', required - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'xai-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1' | 'null', nullable - `signature` string, nullable - EasyInputMessage - `content` union - union[] - … - string - unknown - `phase` union — 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. Omitting it can degrade performance. Not used for user messages. - 'commentary' - 'final_answer' - unknown - `role` union, required - 'user' - 'system' - 'assistant' - 'developer' - `type` 'message' - InputMessageItem - `content` union[], nullable - union - … - `id` string - `role` union, required - 'user' - 'system' - 'developer' - `type` 'message' - FunctionCallItem — A function call initiated by the model - `arguments` string, required - `call_id` string, required - `id` string, required - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `status` 'in_progress' | 'completed' | 'incomplete' - `type` 'function_call', required - FunctionCallOutputItem — The output from a function call execution - `call_id` string, required - `id` string, nullable - `output` union, required - string - union[] - … - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `type` 'function_call_output', required - ApplyPatchCallItem — 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, required - `id` string, nullable - `operation` union, required — The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it. - ApplyPatchCreateFileOperation — The `create_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing the new file contents. - … - ApplyPatchUpdateFileOperation — The `update_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing edits to an existing file. - … - ApplyPatchDeleteFileOperation — The `delete_file` variant of an `apply_patch_call.operation`. Identifies the file to remove; no diff is required. - … - `status` 'in_progress' | 'completed', required — Lifecycle state of an `apply_patch_call` output item. - `type` 'apply_patch_call', required - ApplyPatchCallOutputItem — 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, required - `id` string, nullable - `output` string, nullable - `status` 'completed' | 'failed', required - `type` 'apply_patch_call_output', required - object — An output message item - `content` union, required - union[] - … - union[], nullable - … - `id` string, required - `phase` union — 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. Omitting it can degrade performance. Not used for user messages. - 'commentary' - 'final_answer' - unknown - `role` 'assistant', required - `status` union - 'completed' - 'incomplete' - 'in_progress' - `type` 'message', required - object — An output item containing reasoning - `content` ReasoningTextContent[], nullable - `text` string, required - `type` 'reasoning_text', required - `encrypted_content` string, nullable - `id` string, required - `status` union - 'completed' - 'incomplete' - 'in_progress' - `summary` ReasoningSummaryText[], nullable, required - `text` string, required - `type` 'summary_text', required - `type` 'reasoning', required - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'xai-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1' | 'null', nullable - `signature` string, nullable — A signature for the reasoning content, used for verification - OutputFunctionCallItem - `arguments` string, required - `call_id` string, required - `id` string - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `status` union - 'completed' - 'incomplete' - 'in_progress' - `type` 'function_call', required - OutputCustomToolCallItem — 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. - `call_id` string, required - `id` string - `input` string, required - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `type` 'custom_tool_call', required - OutputWebSearchCallItem - `action` union - object - … - object - … - object - … - `id` string, required - `status` 'completed' | 'searching' | 'in_progress' | 'failed', required - `type` 'web_search_call', required - OutputFileSearchCallItem - `id` string, required - `queries` string[], required - `status` 'completed' | 'searching' | 'in_progress' | 'failed', required - `type` 'file_search_call', required - OutputImageGenerationCallItem - `id` string, required - `result` string, nullable - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required - `type` 'image_generation_call', required - OutputCodeInterpreterCallItem — A code interpreter execution call with outputs - `code` string, nullable, required - `container_id` string, required - `id` string, required - `outputs` union[], nullable, required - union - … - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'code_interpreter_call', required - OutputComputerCallItem - `action` unknown - `call_id` string, required - `id` string - `pending_safety_checks` object[], required - `code` string, required - `id` string, required - `message` string, required - `status` 'completed' | 'incomplete' | 'in_progress', required - `type` 'computer_call', required - OutputDatetimeItem — An openrouter:datetime server tool output item - `datetime` string, required — ISO 8601 datetime string - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `timezone` string, required — IANA timezone name - `type` 'openrouter:datetime', required - OutputWebSearchServerToolItem — 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. - `query` string, required - `sources` object[] - … - `type` 'search', required - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:web_search', required - OutputCodeInterpreterServerToolItem — An openrouter:code_interpreter server tool output item - `code` string - `exitCode` integer - `id` string - `language` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `stderr` string - `stdout` string - `type` 'openrouter:code_interpreter', required - OutputFileSearchServerToolItem — An openrouter:file_search server tool output item - `id` string - `queries` string[] - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:file_search', required - OutputImageGenerationServerToolItem — An openrouter:image_generation server tool output item - `id` string - `imageB64` string - `imageUrl` string - `result` string, nullable — The generated image as a base64-encoded string or URL, matching OpenAI image_generation_call format - `revisedPrompt` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:image_generation', required - OutputBrowserUseServerToolItem — An openrouter:browser_use server tool output item - `action` string - `id` string - `screenshotB64` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:browser_use', required - OutputBashServerToolItem — An openrouter:bash server tool output item - `command` string - `exitCode` integer - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `stderr` string - `stdout` string - `type` 'openrouter:bash', required - OutputTextEditorServerToolItem — An openrouter:text_editor server tool output item - `command` 'view' | 'create' | 'str_replace' | 'insert' - `filePath` string - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:text_editor', required - OutputApplyPatchServerToolItem — 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 - `id` string - `operation` union — The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it. - ApplyPatchCreateFileOperation — The `create_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing the new file contents. - … - ApplyPatchUpdateFileOperation — The `update_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing edits to an existing file. - … - ApplyPatchDeleteFileOperation — The `delete_file` variant of an `apply_patch_call.operation`. Identifies the file to remove; no diff is required. - … - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:apply_patch', required - OutputWebFetchServerToolItem — 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` 'in_progress' | 'completed' | 'incomplete', required - `title` string - `type` 'openrouter:web_fetch', required - `url` string - OutputToolSearchServerToolItem — An openrouter:tool_search server tool output item - `id` string - `query` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:tool_search', required - OutputMemoryServerToolItem — An openrouter:memory server tool output item - `action` 'read' | 'write' | 'delete' - `id` string - `key` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:memory', required - `value` unknown - OutputMcpServerToolItem — An openrouter:mcp server tool output item - `id` string - `serverLabel` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `toolName` string - `type` 'openrouter:mcp', required - OutputSearchModelsServerToolItem — An openrouter:experimental__search_models server tool output item - `arguments` string — The JSON arguments submitted to the search tool (e.g. {"query":"Claude"}) - `id` string - `query` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:experimental__search_models', required - OutputFusionServerToolItem — An openrouter:fusion server tool output item - `analysis` FusionAnalysisResult — Structured analysis produced by the fusion judge model. - `blind_spots` string[], required - `consensus` string[], required - `contradictions` object[], required - … - `partial_coverage` object[], required - … - `unique_insights` object[], required - … - `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. The fusion result is still usable but was produced from a degraded panel. - `error` string, required — Error message describing why the model failed. - `model` string, required — Slug of the analysis model that failed. - `status_code` integer — HTTP status code from the upstream response, when available (e.g. 402, 429). - `failure_reason` string — Typed failure reason when the fusion run failed. Possible values include: all_panels_failed, insufficient_credits, rate_limited, judge_not_valid_json, judge_schema_mismatch, judge_upstream_error, judge_empty_completion. - `id` string - `responses` object[] — Analysis models that produced a response in this fusion run, with each model's full panel content. - `content` string - `model` string, required - `sources` FusionSource[] — Web pages the analysis panels and judge retrieved via web search during this fusion run, deduplicated by URL across the whole run. Present when at least one model cited a source. - `title` string, required — Title of the retrieved web page. - `url` string, required — URL of the web page a panel or the judge retrieved during the run. - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:fusion', required - OutputAdvisorServerToolItem — 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. - `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 advisor's cross-request memory stays namespaced to the correct instance. This identity is positional: it is derived from the index of the advisor entry in the request `tools` array, so clients must keep the order of advisor tool entries stable across requests in a conversation. Reordering or inserting advisor entries shifts these names and causes each advisor's cross-request memory to be attributed to the wrong instance. - `model` string — Slug of the advisor model that was consulted. - `prompt` string — The prompt the executor sent to the advisor. - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:advisor', required - OutputSubagentServerToolItem — An openrouter:subagent server tool output item - `error` string — Error message when the subagent task did not produce an outcome. - `id` string - `model` string — Slug of the worker model that executed the task. - `outcome` string — The worker model's result (the outcome text returned to the delegating model). - `status` 'in_progress' | 'completed' | 'incomplete', required - `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` 'openrouter:subagent', required - OutputFilesServerToolItem — An openrouter:files server tool output item - `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` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:files', required - LocalShellCallItem — A local shell command execution call - `action` object, required - `command` string[], required - `env` object, required - `timeout_ms` integer, nullable - `type` 'exec', required - `user` string, nullable - `working_directory` string, nullable - `call_id` string, required - `id` string, required - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'local_shell_call', required - LocalShellCallOutputItem — Output from a local shell command execution - `id` string, required - `output` string, required - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `type` 'local_shell_call_output', required - ShellCallItem — A shell command execution call (newer variant) - `action` object, required - `commands` string[], required - `max_output_length` integer, nullable - `timeout_ms` integer, nullable - `call_id` string, required - `environment` unknown - `id` string, nullable - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `type` 'shell_call', required - ShellCallOutputItem — Output from a shell command execution (newer variant) - `call_id` string, required - `id` string, nullable - `max_output_length` integer, nullable - `output` object[], required - `content` string, nullable - `exit_code` integer, nullable - `type` string, required - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `type` 'shell_call_output', required - McpListToolsItem — List of available MCP tools from a server - `error` string, nullable - `id` string, required - `server_label` string, required - `tools` object[], required - `annotations` unknown - `description` string, nullable - `input_schema` object, required - `name` string, required - `type` 'mcp_list_tools', required - McpApprovalRequestItem — Request for approval to execute an MCP tool - `arguments` string, required - `id` string, required - `name` string, required - `server_label` string, required - `type` 'mcp_approval_request', required - McpApprovalResponseItem — User response to an MCP tool approval request - `approval_request_id` string, required - `approve` boolean, required - `id` string, nullable - `reason` string, nullable - `type` 'mcp_approval_response', required - McpCallItem — An MCP tool call with its output or error - `arguments` string, required - `error` string, nullable - `id` string, required - `name` string, required - `output` string, nullable - `server_label` string, required - `type` 'mcp_call', required - CustomToolCallItem — 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. - `call_id` string, required - `id` string - `input` string, required - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `type` 'custom_tool_call', required - CustomToolCallOutputItem — 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`. - `call_id` string, required - `id` string - `output` union, required - string - union[] - … - `type` 'custom_tool_call_output', required - CompactionItem — A context compaction marker with encrypted summary - `encrypted_content` string, required - `id` string, nullable - `type` 'compaction', required - ContextCompactionItem — A context compaction marker with an optional encrypted summary - `encrypted_content` string, nullable - `id` string, nullable - `type` 'context_compaction', required - ItemReferenceItem — A reference to a previous response item by ID - `id` string, required - `type` 'item_reference', required - AdditionalToolsItem — Additional tools made available to the model at this point in the input - `id` string, nullable - `role` 'unknown' | 'user' | 'assistant' | 'system' | 'critic' | 'discriminator' | 'developer' | 'tool', required - `tools` union[], required - union - … - `type` 'additional_tools', required - AgentMessageItem — A message routed between agents in a multi-agent session - `agent` object, nullable - `agent_name` string, required - `author` string, required - `content` union[], required - union - … - `id` string, nullable - `recipient` string, required - `type` 'agent_message', required - `instructions` string, nullable - `max_output_tokens` integer, nullable - `max_tool_calls` integer, nullable - `metadata` RequestMetadata, nullable — 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` boolean, nullable - `plugins` union[] — Plugins you want to enable for this request, including their settings. - union - AutoRouterPlugin - `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). When not specified, uses the default supported models list. - `cost_quality_tradeoff` integer — Controls cost vs. quality routing tradeoff (0–10). 0 = pure quality (best model regardless of cost), 10 = maximize for cost (cheapest model wins). Intermediate values blend quality and cost signals continuously. Defaults to 7. - `enabled` boolean — Set to false to disable the auto-router plugin for this request. Defaults to true. - `id` 'auto-router', required - ModerationPlugin - `id` 'moderation', required - WebSearchPlugin - `enabled` boolean — Set to false to disable the web-search plugin for this request. Defaults to true. - `engine` 'native' | 'exa' | 'firecrawl' | 'parallel' | 'perplexity' — The search engine to use for web search. - `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` 'web', required - `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). - `search_prompt` string - `user_location` object, nullable — Approximate user location for location-biased search results. Passed through to native providers that support it (e.g. Anthropic). - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate', required - WebFetchPlugin - `allowed_domains` string[] — Only fetch from these domains. - `blocked_domains` string[] — Never fetch from these domains. - `id` 'web-fetch', required - `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. - FileParserPlugin - `enabled` boolean — Set to false to disable the file-parser plugin for this request. Defaults to true. - `id` 'file-parser', required - `pdf` PDFParserOptions — Options for PDF parsing. - `engine` union — The engine to use for parsing PDF files. "pdf-text" is deprecated and automatically redirected to "cloudflare-ai". - 'mistral-ocr' | 'native' | 'cloudflare-ai' - 'pdf-text' - ResponseHealingPlugin - `enabled` boolean — Set to false to disable the response-healing plugin for this request. Defaults to true. - `id` 'response-healing', required - ContextCompressionPlugin - `enabled` boolean — Set to false to disable the context-compression plugin for this request. Defaults to true. - `engine` 'middle-out' — The compression engine to use. Defaults to "middle-out". - `id` 'context-compression', required - ParetoRouterPlugin - `enabled` boolean — Set to false to disable the pareto-router plugin for this request. Defaults to true. - `id` 'pareto-router', required - `min_coding_score` number, double — 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.66). - `price_source` 'prompt' | 'weighted_avg' — Price source for the Pareto frontier cost axis. "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 traffic data. Defaults to "prompt". - FusionPlugin - `analysis_models` string[] — Slugs of models to run in parallel as the "expert panel" the judge analyzes. Each model receives the same user prompt with web_search + web_fetch enabled. Capped at 8 models to bound cost amplification. When omitted, defaults to the Quality preset from the /labs/fusion UI (~anthropic/claude-opus-latest, ~openai/gpt-latest, ~google/gemini-pro-latest). - `enabled` boolean — Set to false to disable the fusion plugin for this request. Defaults to true. - `id` 'fusion', required - `max_tool_calls` integer — Maximum number of tool-calling steps each panelist (analysis model) and the judge 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 8. Capped at 16. - `model` string — Slug of the model that performs both the judge step (with web_search + web_fetch) and the final synthesis. When omitted, defaults to the first model in the Quality preset. - `preset` 'general-high' | 'general-budget' | 'general-fast' — A curated OpenRouter fusion preset (slugs follow `-`, e.g. `general-high`). Expands server-side into the preset's analysis_models panel and judge model, so callers never name individual models. Explicitly provided `analysis_models` / `model` take precedence. - `tools` object[] — Server tools available to panelist and judge 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" }]`. Pass an empty array to disable tools entirely (panelists answer from parametric knowledge only). - `parameters` object — Optional configuration forwarded as the tool's `parameters` object. - `type` string, required — Server tool type identifier (e.g. "openrouter:web_search", "openrouter:web_fetch"). - `presence_penalty` number, double, nullable - `previous_response_id` string, nullable - `prompt` StoredPromptTemplate, nullable - `id` string, required - `variables` object, nullable - `prompt_cache_key` string, nullable - `prompt_cache_options` PromptCacheOptions, nullable — Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer. - `mode` 'explicit', required - `ttl` string, nullable - `provider` ProviderPreferences, nullable — When multiple model providers are available, optionally indicate your routing preference. - `allow_fallbacks` boolean, nullable — 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's unavailable. - `data_collection` 'deny' | 'allow' | 'null', nullable — 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: use only providers which do not collect user data. - `enforce_distillable_text` boolean, nullable — 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` union[], nullable — List of provider slugs to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request. - union - 'Meta' | 'AkashML' | 'AI21' | 'AionLabs' | 'Alibaba' | 'Ambient' | 'Baidu' | 'Amazon Bedrock' | 'Amazon Nova' | 'Anthropic' | 'Arcee AI' | 'AtlasCloud' | 'Avian' | 'Azure' | 'BaseTen' | 'BytePlus' | 'Black Forest Labs' | 'Cerebras' | 'Chutes' | 'Cirrascale' | 'Clarifai' | 'Cloudflare' | 'Cohere' | 'Crucible' | 'Crusoe' | 'Darkbloom' | 'Decart' | 'Deepgram' | 'DeepInfra' | 'DeepSeek' | 'DekaLLM' | 'DigitalOcean' | 'Featherless' | 'Fireworks' | 'Friendli' | 'GMICloud' | 'Google' | 'Google AI Studio' | 'Groq' | 'HeyGen' | 'Inception' | 'Inceptron' | 'InferenceNet' | 'Ionstream' | 'Infermatic' | 'Io Net' | 'Inferact vLLM' | 'Inflection' | 'Liquid' | 'Mara' | 'Mancer 2' | 'Minimax' | 'ModelRun' | 'Mistral' | 'Modular' | 'Moonshot AI' | 'Morph' | 'NCompass' | 'Nebius' | 'Nex AGI' | 'NextBit' | 'Novita' | 'Nvidia' | 'OpenAI' | 'OpenInference' | 'Parasail' | 'Poolside' | 'Perceptron' | 'Perplexity' | 'Phala' | 'Recraft' | 'Reka' | 'Relace' | 'Sakana AI' | 'SambaNova' | 'Seed' | 'SiliconFlow' | 'Sourceful' | 'StepFun' | 'Stealth' | 'StreamLake' | 'Switchpoint' | 'Tenstorrent' | 'Together' | 'Upstage' | 'Venice' | 'Wafer' | 'WandB' | 'Quiver' | 'Xiaomi' | 'xAI' | 'Z.AI' | 'FakeProvider' - string - `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. - `audio` string — Maximum price in USD per audio unit - `completion` string — Maximum price in USD per million completion tokens - `image` string — Maximum price in USD per image - `prompt` string — Maximum price in USD per million prompt tokens - `request` string — Maximum price in USD per request - `only` union[], nullable — List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request. - union - 'Meta' | 'AkashML' | 'AI21' | 'AionLabs' | 'Alibaba' | 'Ambient' | 'Baidu' | 'Amazon Bedrock' | 'Amazon Nova' | 'Anthropic' | 'Arcee AI' | 'AtlasCloud' | 'Avian' | 'Azure' | 'BaseTen' | 'BytePlus' | 'Black Forest Labs' | 'Cerebras' | 'Chutes' | 'Cirrascale' | 'Clarifai' | 'Cloudflare' | 'Cohere' | 'Crucible' | 'Crusoe' | 'Darkbloom' | 'Decart' | 'Deepgram' | 'DeepInfra' | 'DeepSeek' | 'DekaLLM' | 'DigitalOcean' | 'Featherless' | 'Fireworks' | 'Friendli' | 'GMICloud' | 'Google' | 'Google AI Studio' | 'Groq' | 'HeyGen' | 'Inception' | 'Inceptron' | 'InferenceNet' | 'Ionstream' | 'Infermatic' | 'Io Net' | 'Inferact vLLM' | 'Inflection' | 'Liquid' | 'Mara' | 'Mancer 2' | 'Minimax' | 'ModelRun' | 'Mistral' | 'Modular' | 'Moonshot AI' | 'Morph' | 'NCompass' | 'Nebius' | 'Nex AGI' | 'NextBit' | 'Novita' | 'Nvidia' | 'OpenAI' | 'OpenInference' | 'Parasail' | 'Poolside' | 'Perceptron' | 'Perplexity' | 'Phala' | 'Recraft' | 'Reka' | 'Relace' | 'Sakana AI' | 'SambaNova' | 'Seed' | 'SiliconFlow' | 'Sourceful' | 'StepFun' | 'Stealth' | 'StreamLake' | 'Switchpoint' | 'Tenstorrent' | 'Together' | 'Upstage' | 'Venice' | 'Wafer' | 'WandB' | 'Quiver' | 'Xiaomi' | 'xAI' | 'Z.AI' | 'FakeProvider' - string - `order` union[], nullable — 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 error message. - union - 'Meta' | 'AkashML' | 'AI21' | 'AionLabs' | 'Alibaba' | 'Ambient' | 'Baidu' | 'Amazon Bedrock' | 'Amazon Nova' | 'Anthropic' | 'Arcee AI' | 'AtlasCloud' | 'Avian' | 'Azure' | 'BaseTen' | 'BytePlus' | 'Black Forest Labs' | 'Cerebras' | 'Chutes' | 'Cirrascale' | 'Clarifai' | 'Cloudflare' | 'Cohere' | 'Crucible' | 'Crusoe' | 'Darkbloom' | 'Decart' | 'Deepgram' | 'DeepInfra' | 'DeepSeek' | 'DekaLLM' | 'DigitalOcean' | 'Featherless' | 'Fireworks' | 'Friendli' | 'GMICloud' | 'Google' | 'Google AI Studio' | 'Groq' | 'HeyGen' | 'Inception' | 'Inceptron' | 'InferenceNet' | 'Ionstream' | 'Infermatic' | 'Io Net' | 'Inferact vLLM' | 'Inflection' | 'Liquid' | 'Mara' | 'Mancer 2' | 'Minimax' | 'ModelRun' | 'Mistral' | 'Modular' | 'Moonshot AI' | 'Morph' | 'NCompass' | 'Nebius' | 'Nex AGI' | 'NextBit' | 'Novita' | 'Nvidia' | 'OpenAI' | 'OpenInference' | 'Parasail' | 'Poolside' | 'Perceptron' | 'Perplexity' | 'Phala' | 'Recraft' | 'Reka' | 'Relace' | 'Sakana AI' | 'SambaNova' | 'Seed' | 'SiliconFlow' | 'Sourceful' | 'StepFun' | 'Stealth' | 'StreamLake' | 'Switchpoint' | 'Tenstorrent' | 'Together' | 'Upstage' | 'Venice' | 'Wafer' | 'WandB' | 'Quiver' | 'Xiaomi' | 'xAI' | 'Z.AI' | 'FakeProvider' - string - `preferred_max_latency` union — 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 model to be used instead of the primary model if it meets the threshold. - number, double - PercentileLatencyCutoffs — Percentile-based latency cutoffs. All specified cutoffs must be met for an endpoint to be preferred. - `p50` number, double, nullable — Maximum p50 latency (seconds) - `p75` number, double, nullable — Maximum p75 latency (seconds) - `p90` number, double, nullable — Maximum p90 latency (seconds) - `p99` number, double, nullable — Maximum p99 latency (seconds) - unknown - `preferred_min_throughput` union — 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 cause a fallback model to be used instead of the primary model if it meets the threshold. - number, double - PercentileThroughputCutoffs — Percentile-based throughput cutoffs. All specified cutoffs must be met for an endpoint to be preferred. - `p50` number, double, nullable — Minimum p50 throughput (tokens/sec) - `p75` number, double, nullable — Minimum p75 throughput (tokens/sec) - `p90` number, double, nullable — Minimum p90 throughput (tokens/sec) - `p99` number, double, nullable — Minimum p99 throughput (tokens/sec) - unknown - `quantizations` Quantization[], nullable — A list of quantization levels to filter the provider by. - `require_parameters` boolean, nullable — 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` union — The sorting strategy to use for this request, if "order" is not specified. When set, no load balancing is performed. - 'price' | 'throughput' | 'latency' | 'exacto' — The provider sorting strategy (price, throughput, latency) - ProviderSortConfig — The provider sorting strategy (price, throughput, latency) - `by` 'price' | 'throughput' | 'latency' | 'exacto' | 'null', nullable — The provider sorting strategy (price, throughput, latency) - `partition` 'model' | 'none' | 'null', nullable — Partitioning strategy for sorting: "model" (default) groups endpoints by model before sorting (fallback models remain fallbacks), "none" sorts all endpoints together regardless of model. - unknown - `zdr` boolean, nullable — Whether to restrict routing to only ZDR (Zero Data Retention) endpoints. When true, only endpoints that do not retain prompts will be used. - `reasoning` ReasoningConfig, nullable — Configuration for reasoning mode in the response - `context` 'auto' | 'all_turns' | 'current_turn' | 'null', nullable — 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. - `effort` 'max' | 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none' | 'null', nullable - `mode` 'standard' | 'pro' | 'null', nullable — 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. - `summary` 'auto' | 'concise' | 'detailed' | 'null', nullable - `enabled` boolean, nullable - `max_tokens` integer, nullable - `route` 'fallback' | 'sort' | 'null', nullable — **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none"). - `safety_identifier` string, nullable - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'scale' | 'null', nullable - `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 observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. - `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`. - union — A single condition that, when met, halts the server-tool agent loop. - StopServerToolsWhenStepCountIs — Stop after the agent loop has executed this many steps. - `step_count` integer, required - `type` 'step_count_is', required - StopServerToolsWhenHasToolCall — Stop after a tool with this name has been called. - `tool_name` string, required - `type` 'has_tool_call', required - StopServerToolsWhenMaxTokensUsed — Stop once cumulative token usage across the loop exceeds this threshold. - `max_tokens` integer, required - `type` 'max_tokens_used', required - StopServerToolsWhenMaxCost — Stop once cumulative cost across the loop exceeds this dollar threshold. - `max_cost_in_dollars` number, double, required - `type` 'max_cost', required - StopServerToolsWhenFinishReasonIs — Stop when the upstream model emits this finish reason (e.g. `length`). - `reason` string, required - `type` 'finish_reason_is', required - `store` false - `stream` boolean - `temperature` number, double, nullable - `text` TextExtendedConfig — Text output configuration including format and verbosity - `format` union — Text response format configuration - FormatTextConfig — Plain text response format - `type` 'text', required - FormatJsonObjectConfig — JSON object response format - `type` 'json_object', required - FormatJsonSchemaConfig — JSON schema constrained response format - `description` string - `name` string, required - `schema` object, required - `strict` boolean, nullable - `type` 'json_schema', required - `verbosity` string, nullable - `tool_choice` union - 'auto' - 'none' - 'required' - object - `name` string, required - `type` 'function', required - object - `type` union, required - 'web_search_preview_2025_03_11' - 'web_search_preview' - ToolChoiceAllowed — Constrains the model to a pre-defined set of allowed tools - `mode` union, required - 'auto' - 'required' - `tools` object[], required - `type` 'allowed_tools', required - object - `type` 'apply_patch', required - object - `type` 'shell', required - `tools` union[] - union - object — Function tool definition - `description` string, nullable - `name` string, required - `parameters` object, nullable, required - `strict` boolean, nullable - `type` 'function', required - PreviewWebSearchServerTool — Web search preview tool configuration - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search_preview', required - `user_location` PreviewWebSearchUserLocation, nullable - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate', required - Preview20250311WebSearchServerTool — Web search preview tool configuration (2025-03-11 version) - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search_preview_2025_03_11', required - `user_location` PreviewWebSearchUserLocation, nullable - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate', required - LegacyWebSearchServerTool — Web search tool configuration - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search', required - `user_location` WebSearchUserLocation, nullable — User location information for web search - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate' - WebSearchServerTool — Web search tool configuration (2025-08-26 version) - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search_2025_08_26', required - `user_location` WebSearchUserLocation, nullable — User location information for web search - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate' - FileSearchServerTool — File search tool configuration - `filters` union - object - `key` string, required - `type` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte', required - `value` union, required - … - CompoundFilter — A compound filter that combines multiple comparison or compound filters - `filters` object[], required - … - `type` 'and' | 'or', required - unknown - `max_num_results` integer - `ranking_options` object - `ranker` 'auto' | 'default-2024-11-15' - `score_threshold` number, double - `type` 'file_search', required - `vector_store_ids` string[], required - ComputerUseServerTool — Computer use preview tool configuration - `display_height` integer, required - `display_width` integer, required - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required - `type` 'computer_use_preview', required - CodeInterpreterServerTool — Code interpreter tool configuration - `container` union, required - string - object - `file_ids` string[] - `memory_limit` '1g' | '4g' | '16g' | '64g' | 'null', nullable - `type` 'auto', required - `type` 'code_interpreter', required - McpServerTool — MCP (Model Context Protocol) tool configuration - `allowed_tools` union - string[] - object - `read_only` boolean - `tool_names` string[] - unknown - `authorization` string - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint' - `headers` object, nullable - `require_approval` union - object - `always` object - … - `never` object - … - 'always' - 'never' - unknown - `server_description` string - `server_label` string, required - `server_url` string - `type` 'mcp', required - ImageGenerationServerTool — Image generation tool configuration - `background` 'transparent' | 'opaque' | 'auto' - `input_fidelity` 'high' | 'low' | 'null', nullable - `input_image_mask` object - `file_id` string - `image_url` string - `model` string - `moderation` 'auto' | 'low' - `output_compression` integer - `output_format` 'png' | 'webp' | 'jpeg' - `partial_images` integer - `quality` 'low' | 'medium' | 'high' | 'auto' - `size` string - `type` 'image_generation', required - CodexLocalShellTool — Local shell tool configuration - `type` 'local_shell', required - ShellServerTool — Shell tool configuration - `type` 'shell', required - ApplyPatchServerTool — Apply patch tool configuration - `type` 'apply_patch', required - CustomTool — Custom tool configuration - `description` string - `format` union - object - `type` 'text', required - object - `definition` string, required - `syntax` 'lark' | 'regex', required - `type` 'grammar', required - `name` string, required - `type` 'custom', required - AdvisorServerToolOpenRouter — OpenRouter built-in server tool: consults a higher-intelligence advisor model (any OpenRouter model) for guidance mid-generation and returns its response. The advisor may run as a sub-agent with its own tools. Include multiple entries to offer several named advisors; at most one entry may omit `name` to act as the default advisor. - `parameters` AdvisorServerToolConfig — 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 executor passes in the tool call. - `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. - `max_tool_calls` integer — Maximum number of tool-calling steps the advisor sub-agent may take during its agentic loop. Capped at 25. Only relevant when the advisor is given tools. - `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. The advisor tool itself cannot be the advisor model. - `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. - `reasoning` AdvisorReasoning — Reasoning configuration forwarded to the advisor call. Use this to control reasoning effort and token budget for models that support extended thinking. - `effort` 'max' | 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none' — Reasoning effort level for the advisor call. - `max_tokens` integer — Maximum number of reasoning tokens the advisor may use. - `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 Chat Completions API (where the advice arrives only as the final tool result). When false or omitted, the advice arrives only as the final result. - `temperature` number, double — Sampling temperature forwarded to the advisor call. When omitted, the provider's default applies. - `tools` AdvisorNestedTool[] — Tools the advisor sub-agent may use while forming its advice. The advisor runs as an agentic sub-agent over these tools, then returns its text. Only OpenRouter server tools are supported — function tools are rejected — and the list must not include the advisor tool itself. - `parameters` object - `type` string, required - `type` 'openrouter:advisor', required - SubagentServerToolOpenRouter — 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 the openrouter:subagent server tool. - `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. Accepted and validated but not yet enforced on the subagent call. - `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. - `reasoning` SubagentReasoning — Reasoning configuration forwarded to the subagent call. Use this to control reasoning effort and token budget for models that support extended thinking. - `effort` 'max' | 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none' — Reasoning effort level for the subagent call. - `max_tokens` integer — Maximum number of reasoning tokens the subagent may use. Accepted and validated but not yet forwarded to the subagent call. - `temperature` number, double — Sampling temperature forwarded to the subagent call. When omitted, the provider's default applies. - `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 subagent tool itself. - `parameters` object - `type` string, required - `type` 'openrouter:subagent', required - DatetimeServerTool — OpenRouter built-in server tool: returns the current date and time - `parameters` DatetimeServerToolConfig — Configuration for the openrouter:datetime server tool - `timezone` string — IANA timezone name (e.g. "America/New_York"). Defaults to UTC. - `type` 'openrouter:datetime', required - FilesServerTool — OpenRouter built-in server tool: read, write, edit, and list workspace files via the Files API. Requires the `x-openrouter-file-ids: openrouter` request header. - `parameters` FilesServerToolConfig — Configuration for the openrouter:files server tool - `type` 'openrouter:files', required - FusionServerToolOpenRouter — OpenRouter built-in server tool: fans out the user prompt to a panel of analysis models, then asks a judge model to summarize their collective output as structured JSON the outer model can synthesize from. - `parameters` FusionServerToolConfig — 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 a judge model summarizes the collective output into structured analysis JSON. Capped at 8 models to bound cost amplification. Defaults to the Quality preset from /labs/fusion. - `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. Currently supported for Anthropic Claude models. - `ttl` '5m' | '1h' - `type` 'ephemeral', required - `max_completion_tokens` integer — Maximum number of output tokens (including reasoning tokens) each panelist and the judge 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 text. When omitted, panelists default to 32000 and the judge to 50000. - `max_tool_calls` integer — Maximum number of tool-calling steps each panelist (analysis model) and the judge 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 8. Capped at 16. - `model` string — Slug of the judge 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 judge inner calls. Use this to control reasoning effort and token budget for models that support extended thinking. - `effort` 'max' | 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none' — Reasoning effort level for panelist and judge inner calls. - `max_tokens` integer — Maximum number of reasoning tokens each panelist and judge model may use. Helps bound cost when models allocate too much budget to chain-of-thought. - `temperature` number, double — Temperature forwarded to panelist inner calls. The judge always runs at temperature 0 regardless of this value. When omitted, the provider's default applies. - `tools` object[] — Server tools available to panelist and judge 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" }]`. Pass an empty array to disable tools entirely (panelists answer from parametric knowledge only). - `parameters` object — Optional configuration forwarded as the tool's `parameters` object. - `type` string, required — Server tool type identifier (e.g. "openrouter:web_search", "openrouter:web_fetch"). - `type` 'openrouter:fusion', required - ImageGenerationServerToolOpenRouter — 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. - `model` string — Which image generation model to use (e.g. "openai/gpt-5-image"). Defaults to "openai/gpt-5-image". - `type` 'openrouter:image_generation', required - SearchModelsServerToolOpenRouter — OpenRouter built-in server tool: searches and filters AI models available on OpenRouter - `parameters` SearchModelsServerToolConfig — Configuration for the openrouter:experimental__search_models server tool - `max_results` integer — Maximum number of models to return. Defaults to 5, max 20. - `type` 'openrouter:experimental__search_models', required - WebFetchServerTool — 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 - `allowed_domains` string[] — Only fetch from these domains. - `blocked_domains` string[] — Never fetch from these domains. - `engine` 'auto' | 'native' | 'openrouter' | 'exa' | 'parallel' | 'firecrawl' — 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 (requires BYOK). "parallel" uses the Parallel extract API. - `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. - `type` 'openrouter:web_fetch', required - WebSearchServerToolOpenRouter — OpenRouter built-in server tool: searches the web for current information - `parameters` WebSearchServerToolConfig — 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, xAI). Cannot be used with excluded_domains. - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `excluded_domains` string[] — Exclude search results from these domains. Supported by Exa, Firecrawl, Parallel, Perplexity, Anthropic, and xAI. Not supported with OpenAI (silently ignored). 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 (default 1,500 when omitted). For Perplexity, maps to the native `max_tokens_per_page` parameter (converted from characters to tokens) and trims the response to the exact character cap. When both `max_characters` and `search_context_size` are set, `max_characters` takes precedence. When omitted, falls back to `search_context_size` mapping (Exa) or engine defaults (Parallel, Perplexity). - `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. - `search_context_size` 'low' | 'medium' | 'high' — 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 adaptive size per query and document (typically ~2,000–4,000 characters per result). For Parallel, controls the total characters across all results; when omitted, Parallel uses its own default size. For Perplexity, maps directly to the Search API's native search_context_size parameter. Overridden by `max_characters` when both are set. - `user_location` WebSearchUserLocationServerTool — Approximate user location for location-biased results. - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate' - `type` 'openrouter:web_search', required - ApplyPatchServerToolOpenRouter — 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 - `engine` 'auto' | 'native' | 'openrouter' — 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 native, the request falls back to HITL. "openrouter" always runs the HITL validator. Native passthrough streams the diff incrementally via `apply_patch_call_operation_diff.delta` events; HITL buffers the diff for atomic delivery as a single delta. - `type` 'openrouter:apply_patch', required - BashServerTool — OpenRouter built-in server tool: runs shell commands server-side in a sandboxed container - `parameters` BashServerToolConfig — Configuration for the openrouter:bash server tool - `engine` 'auto' | 'native' | 'openrouter' — 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. - `environment` union — Execution environment for the bash server tool. - ContainerAutoEnvironment — An OpenRouter-managed, auto-provisioned ephemeral container. - … - ContainerReferenceEnvironment — Reference to a previously created container to reuse. - … - `sleep_after_seconds` integer — How long (in seconds) the container stays warm after its last command before sleeping, freeing its capacity slot. Idle-based: each command renews the timer. Defaults to 900 (15 minutes); capped at 2592000 (30 days). - `type` 'openrouter:bash', required - ShellServerToolOpenRouter — 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 - `engine` 'auto' | 'openrouter' — 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. - `environment` union — Server-side execution environment for the shell tool. Only container-backed environments are supported; "local" shells are not. - ContainerAutoEnvironment — An OpenRouter-managed, auto-provisioned ephemeral container. - … - ContainerReferenceEnvironment — Reference to a previously created container to reuse. - … - `sleep_after_seconds` integer — How long (in seconds) the container stays warm after its last command before sleeping, freeing its capacity slot. Idle-based: each command renews the timer. Defaults to 900 (15 minutes); capped at 2592000 (30 days). - `type` 'openrouter:shell', required - `top_k` integer - `top_logprobs` integer, nullable - `top_p` number, double, nullable - `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. - `generation_name` string - `parent_span_id` string - `span_name` string - `trace_id` string - `trace_name` string - `truncation` 'auto' | 'disabled' | 'null', nullable - `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 users. Maximum of 256 characters. ## Response `200` Successful response - OpenResponsesResult — Complete non-streaming response from the Responses API - `background` boolean, nullable - `completed_at` integer, nullable, required - `created_at` integer, required - `error` ResponsesErrorField, nullable, required — Error information returned from the API - `code` 'server_error' | 'rate_limit_exceeded' | 'invalid_prompt' | 'vector_store_timeout' | 'invalid_image' | 'invalid_image_format' | 'invalid_base64_image' | 'invalid_image_url' | 'image_too_large' | 'image_too_small' | 'image_parse_error' | 'image_content_policy_violation' | 'invalid_image_mode' | 'image_file_too_large' | 'unsupported_image_media_type' | 'empty_image_file' | 'failed_to_download_image' | 'image_file_not_found' | 'bio_policy', required - `message` string, required - `frequency_penalty` number, double, nullable, required - `id` string, required - `incomplete_details` IncompleteDetails, nullable, required - `reason` 'max_output_tokens' | 'content_filter' - `instructions` union, required - string - union[] - union - object - `content` union, required - union[] - … - string - `phase` union - 'commentary' - 'final_answer' - unknown - `role` union, required - 'user' - 'system' - 'assistant' - 'developer' - `type` 'message' - OpenAIResponseInputMessageItem - `content` union[], required - union - … - `id` string, required - `role` union, required - 'user' - 'system' - 'developer' - `type` 'message' - OpenAIResponseFunctionToolCallOutput - `call_id` string, required - `id` string, nullable - `output` union, required - string - union[] - … - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `type` 'function_call_output', required - OpenAIResponseFunctionToolCall - `arguments` string, required - `call_id` string, required - `id` string - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `status` 'in_progress' | 'completed' | 'incomplete' - `type` 'function_call', required - OutputItemImageGenerationCall - `id` string, required - `result` string, nullable - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required - `type` 'image_generation_call', required - OutputMessage - `content` union[], required - union - … - `id` string, required - `phase` union — 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. Omitting it can degrade performance. Not used for user messages. - 'commentary' - 'final_answer' - unknown - `role` 'assistant', required - `status` union - 'completed' - 'incomplete' - 'in_progress' - `type` 'message', required - OpenAIResponseCustomToolCall - `call_id` string, required - `id` string - `input` string, required - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `type` 'custom_tool_call', required - OpenAIResponseCustomToolCallOutput - `call_id` string, required - `id` string - `output` union, required - string - union[] - … - `type` 'custom_tool_call_output', required - ApplyPatchCallItem — 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, required - `id` string, nullable - `operation` union, required — The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it. - ApplyPatchCreateFileOperation — The `create_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing the new file contents. - … - ApplyPatchUpdateFileOperation — The `update_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing edits to an existing file. - … - ApplyPatchDeleteFileOperation — The `delete_file` variant of an `apply_patch_call.operation`. Identifies the file to remove; no diff is required. - … - `status` 'in_progress' | 'completed', required — Lifecycle state of an `apply_patch_call` output item. - `type` 'apply_patch_call', required - ApplyPatchCallOutputItem — 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, required - `id` string, nullable - `output` string, nullable - `status` 'completed' | 'failed', required - `type` 'apply_patch_call_output', required - unknown - `max_output_tokens` integer, nullable - `max_tool_calls` integer, nullable - `metadata` RequestMetadata, nullable, required — 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. - `model` string, required - `object` 'response', required - `output` union[], required - union — An output item from the response - OutputMessageItem — An output message item - `content` union[], required - union - ResponseOutputText - … - OpenAIResponsesRefusalContent - … - `id` string, required - `phase` union — 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. Omitting it can degrade performance. Not used for user messages. - 'commentary' - 'final_answer' - unknown - `role` 'assistant', required - `status` union - 'completed' - 'incomplete' - 'in_progress' - `type` 'message', required - OutputReasoningItem — An output item containing reasoning - `content` ReasoningTextContent[], nullable - `text` string, required - `type` 'reasoning_text', required - `encrypted_content` string, nullable - `id` string, required - `status` union - 'completed' - 'incomplete' - 'in_progress' - `summary` ReasoningSummaryText[], required - `text` string, required - `type` 'summary_text', required - `type` 'reasoning', required - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'xai-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1' | 'null', nullable - `signature` string, nullable — A signature for the reasoning content, used for verification - OutputFunctionCallItem - `arguments` string, required - `call_id` string, required - `id` string - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `status` union - 'completed' - 'incomplete' - 'in_progress' - `type` 'function_call', required - OutputWebSearchCallItem - `action` union - object - `queries` string[] - `query` string, required - `sources` WebSearchSource[] - … - `type` 'search', required - object - `type` 'open_page', required - `url` string, nullable - object - `pattern` string, required - `type` 'find_in_page', required - `url` string, required - `id` string, required - `status` 'completed' | 'searching' | 'in_progress' | 'failed', required - `type` 'web_search_call', required - OutputFileSearchCallItem - `id` string, required - `queries` string[], required - `status` 'completed' | 'searching' | 'in_progress' | 'failed', required - `type` 'file_search_call', required - OutputImageGenerationCallItem - `id` string, required - `result` string, nullable - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required - `type` 'image_generation_call', required - OutputCodeInterpreterCallItem — A code interpreter execution call with outputs - `code` string, nullable, required - `container_id` string, required - `id` string, required - `outputs` union[], nullable, required - union - object - … - object - … - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'code_interpreter_call', required - OutputComputerCallItem - `action` unknown - `call_id` string, required - `id` string - `pending_safety_checks` object[], required - `code` string, required - `id` string, required - `message` string, required - `status` 'completed' | 'incomplete' | 'in_progress', required - `type` 'computer_call', required - OutputDatetimeItem — An openrouter:datetime server tool output item - `datetime` string, required — ISO 8601 datetime string - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `timezone` string, required — IANA timezone name - `type` 'openrouter:datetime', required - OutputWebSearchServerToolItem — 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. - `query` string, required - `sources` object[] - `type` 'url', required - `url` string, required - `type` 'search', required - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:web_search', required - OutputCodeInterpreterServerToolItem — An openrouter:code_interpreter server tool output item - `code` string - `exitCode` integer - `id` string - `language` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `stderr` string - `stdout` string - `type` 'openrouter:code_interpreter', required - OutputFileSearchServerToolItem — An openrouter:file_search server tool output item - `id` string - `queries` string[] - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:file_search', required - OutputImageGenerationServerToolItem — An openrouter:image_generation server tool output item - `id` string - `imageB64` string - `imageUrl` string - `result` string, nullable — The generated image as a base64-encoded string or URL, matching OpenAI image_generation_call format - `revisedPrompt` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:image_generation', required - OutputBrowserUseServerToolItem — An openrouter:browser_use server tool output item - `action` string - `id` string - `screenshotB64` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:browser_use', required - OutputBashServerToolItem — An openrouter:bash server tool output item - `command` string - `exitCode` integer - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `stderr` string - `stdout` string - `type` 'openrouter:bash', required - OutputTextEditorServerToolItem — An openrouter:text_editor server tool output item - `command` 'view' | 'create' | 'str_replace' | 'insert' - `filePath` string - `id` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:text_editor', required - OutputApplyPatchServerToolItem — 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 - `id` string - `operation` union — The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it. - ApplyPatchCreateFileOperation — The `create_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing the new file contents. - `diff` string, required - `path` string, required - `type` 'create_file', required - ApplyPatchUpdateFileOperation — The `update_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing edits to an existing file. - `diff` string, required - `path` string, required - `type` 'update_file', required - ApplyPatchDeleteFileOperation — The `delete_file` variant of an `apply_patch_call.operation`. Identifies the file to remove; no diff is required. - `path` string, required - `type` 'delete_file', required - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:apply_patch', required - OutputApplyPatchCallItem — A native `apply_patch_call` output item matching OpenAI's Responses API shape. Emitted when the client requested the `apply_patch` shorthand. - `call_id` string, required - `id` string, required - `operation` union, required — The patch operation requested by an `apply_patch_call`. `create_file` and `update_file` carry a V4A diff; `delete_file` omits it. - ApplyPatchCreateFileOperation — The `create_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing the new file contents. - `diff` string, required - `path` string, required - `type` 'create_file', required - ApplyPatchUpdateFileOperation — The `update_file` variant of an `apply_patch_call.operation`. Carries a V4A diff describing edits to an existing file. - `diff` string, required - `path` string, required - `type` 'update_file', required - ApplyPatchDeleteFileOperation — The `delete_file` variant of an `apply_patch_call.operation`. Identifies the file to remove; no diff is required. - `path` string, required - `type` 'delete_file', required - `status` 'in_progress' | 'completed', required — Lifecycle state of an `apply_patch_call` output item. - `type` 'apply_patch_call', required - OutputShellCallItem — A native `shell_call` output item matching OpenAI's Responses API shape. Emitted for the sandbox-backed `shell` tool. - `action` object - `commands` string[], required - `max_output_length` integer, nullable, required - `timeout_ms` integer, nullable, required - `call_id` string, required - `id` string, required - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of a shell call or its output. - `type` 'shell_call', required - OutputShellCallOutputItem — A native `shell_call_output` item matching OpenAI's Responses API shape. Carries per-command stdout, stderr, and the exit/timeout outcome. - `call_id` string, required - `id` string, required - `max_output_length` integer, nullable - `output` object[], required - `outcome` union, required - object - … - object - … - `stderr` string, required - `stdout` string, required - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of a shell call or its output. - `type` 'shell_call_output', required - OutputWebFetchServerToolItem — 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` 'in_progress' | 'completed' | 'incomplete', required - `title` string - `type` 'openrouter:web_fetch', required - `url` string - OutputToolSearchServerToolItem — An openrouter:tool_search server tool output item - `id` string - `query` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:tool_search', required - OutputMemoryServerToolItem — An openrouter:memory server tool output item - `action` 'read' | 'write' | 'delete' - `id` string - `key` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:memory', required - `value` unknown - OutputMcpServerToolItem — An openrouter:mcp server tool output item - `id` string - `serverLabel` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `toolName` string - `type` 'openrouter:mcp', required - OutputSearchModelsServerToolItem — An openrouter:experimental__search_models server tool output item - `arguments` string — The JSON arguments submitted to the search tool (e.g. {"query":"Claude"}) - `id` string - `query` string - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:experimental__search_models', required - OutputFusionServerToolItem — An openrouter:fusion server tool output item - `analysis` FusionAnalysisResult — Structured analysis produced by the fusion judge model. - `blind_spots` string[], required - `consensus` string[], required - `contradictions` object[], required - `stances` object[], required - … - `topic` string, required - `partial_coverage` object[], required - `models` string[], required - `point` string, required - `unique_insights` object[], required - `insight` string, required - `model` string, required - `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. The fusion result is still usable but was produced from a degraded panel. - `error` string, required — Error message describing why the model failed. - `model` string, required — Slug of the analysis model that failed. - `status_code` integer — HTTP status code from the upstream response, when available (e.g. 402, 429). - `failure_reason` string — Typed failure reason when the fusion run failed. Possible values include: all_panels_failed, insufficient_credits, rate_limited, judge_not_valid_json, judge_schema_mismatch, judge_upstream_error, judge_empty_completion. - `id` string - `responses` object[] — Analysis models that produced a response in this fusion run, with each model's full panel content. - `content` string - `model` string, required - `sources` FusionSource[] — Web pages the analysis panels and judge retrieved via web search during this fusion run, deduplicated by URL across the whole run. Present when at least one model cited a source. - `title` string, required — Title of the retrieved web page. - `url` string, required — URL of the web page a panel or the judge retrieved during the run. - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:fusion', required - OutputAdvisorServerToolItem — 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. - `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 advisor's cross-request memory stays namespaced to the correct instance. This identity is positional: it is derived from the index of the advisor entry in the request `tools` array, so clients must keep the order of advisor tool entries stable across requests in a conversation. Reordering or inserting advisor entries shifts these names and causes each advisor's cross-request memory to be attributed to the wrong instance. - `model` string — Slug of the advisor model that was consulted. - `prompt` string — The prompt the executor sent to the advisor. - `status` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:advisor', required - OutputSubagentServerToolItem — An openrouter:subagent server tool output item - `error` string — Error message when the subagent task did not produce an outcome. - `id` string - `model` string — Slug of the worker model that executed the task. - `outcome` string — The worker model's result (the outcome text returned to the delegating model). - `status` 'in_progress' | 'completed' | 'incomplete', required - `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` 'openrouter:subagent', required - OutputFilesServerToolItem — An openrouter:files server tool output item - `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` 'in_progress' | 'completed' | 'incomplete', required - `type` 'openrouter:files', required - OutputCustomToolCallItem — 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. - `call_id` string, required - `id` string - `input` string, required - `name` string, required - `namespace` string — Namespace qualifier for tools registered as part of a namespace tool group (e.g. an MCP server) - `type` 'custom_tool_call', required - `output_text` string - `parallel_tool_calls` boolean, required - `presence_penalty` number, double, nullable, required - `previous_response_id` string, nullable - `prompt` StoredPromptTemplate, nullable - `id` string, required - `variables` object, nullable - `prompt_cache_key` string, nullable - `reasoning` BaseReasoningConfig, nullable - `context` 'auto' | 'all_turns' | 'current_turn' | 'null', nullable — 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. - `effort` 'max' | 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none' | 'null', nullable - `mode` 'standard' | 'pro' | 'null', nullable — 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. - `summary` 'auto' | 'concise' | 'detailed' | 'null', nullable - `safety_identifier` string, nullable - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'scale' | 'null', nullable - `status` 'completed' | 'incomplete' | 'in_progress' | 'failed' | 'cancelled' | 'queued', required - `store` boolean - `temperature` number, double, nullable, required - `text` object — Text output configuration including format and verbosity - `format` union — Text response format configuration - FormatTextConfig — Plain text response format - `type` 'text', required - FormatJsonObjectConfig — JSON object response format - `type` 'json_object', required - FormatJsonSchemaConfig — JSON schema constrained response format - `description` string - `name` string, required - `schema` object, required - `strict` boolean, nullable - `type` 'json_schema', required - `verbosity` 'high' | 'low' | 'medium', nullable - `tool_choice` union, required - 'auto' - 'none' - 'required' - object - `name` string, required - `type` 'function', required - object - `type` union, required - 'web_search_preview_2025_03_11' - 'web_search_preview' - ToolChoiceAllowed — Constrains the model to a pre-defined set of allowed tools - `mode` union, required - 'auto' - 'required' - `tools` object[], required - `type` 'allowed_tools', required - object - `type` 'apply_patch', required - object - `type` 'shell', required - `tools` union[], required - union - object — Function tool definition - `description` string, nullable - `name` string, required - `parameters` object, nullable, required - `strict` boolean, nullable - `type` 'function', required - PreviewWebSearchServerTool — Web search preview tool configuration - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search_preview', required - `user_location` PreviewWebSearchUserLocation, nullable - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate', required - Preview20250311WebSearchServerTool — Web search preview tool configuration (2025-03-11 version) - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search_preview_2025_03_11', required - `user_location` PreviewWebSearchUserLocation, nullable - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate', required - LegacyWebSearchServerTool — Web search tool configuration - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search', required - `user_location` WebSearchUserLocation, nullable — User location information for web search - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate' - WebSearchServerTool — Web search tool configuration (2025-08-26 version) - `engine` 'native' | 'exa' | 'parallel' | 'firecrawl' | 'perplexity' | 'auto' — 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 Firecrawl (requires BYOK). "parallel" uses the Parallel search API. "perplexity" uses the Perplexity Search API (raw ranked results). - `filters` WebSearchDomainFilter, nullable - `allowed_domains` string[], nullable - `excluded_domains` string[], nullable - `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. - `search_context_size` 'low' | 'medium' | 'high' — Size of the search context for web search tools - `type` 'web_search_2025_08_26', required - `user_location` WebSearchUserLocation, nullable — User location information for web search - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate' - FileSearchServerTool — File search tool configuration - `filters` union - object - `key` string, required - `type` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte', required - `value` union, required - … - CompoundFilter — A compound filter that combines multiple comparison or compound filters - `filters` object[], required - … - `type` 'and' | 'or', required - unknown - `max_num_results` integer - `ranking_options` object - `ranker` 'auto' | 'default-2024-11-15' - `score_threshold` number, double - `type` 'file_search', required - `vector_store_ids` string[], required - ComputerUseServerTool — Computer use preview tool configuration - `display_height` integer, required - `display_width` integer, required - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required - `type` 'computer_use_preview', required - CodeInterpreterServerTool — Code interpreter tool configuration - `container` union, required - string - object - `file_ids` string[] - `memory_limit` '1g' | '4g' | '16g' | '64g' | 'null', nullable - `type` 'auto', required - `type` 'code_interpreter', required - McpServerTool — MCP (Model Context Protocol) tool configuration - `allowed_tools` union - string[] - object - `read_only` boolean - `tool_names` string[] - unknown - `authorization` string - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint' - `headers` object, nullable - `require_approval` union - object - `always` object - … - `never` object - … - 'always' - 'never' - unknown - `server_description` string - `server_label` string, required - `server_url` string - `type` 'mcp', required - ImageGenerationServerTool — Image generation tool configuration - `background` 'transparent' | 'opaque' | 'auto' - `input_fidelity` 'high' | 'low' | 'null', nullable - `input_image_mask` object - `file_id` string - `image_url` string - `model` string - `moderation` 'auto' | 'low' - `output_compression` integer - `output_format` 'png' | 'webp' | 'jpeg' - `partial_images` integer - `quality` 'low' | 'medium' | 'high' | 'auto' - `size` string - `type` 'image_generation', required - CodexLocalShellTool — Local shell tool configuration - `type` 'local_shell', required - ShellServerTool — Shell tool configuration - `type` 'shell', required - ApplyPatchServerTool — Apply patch tool configuration - `type` 'apply_patch', required - CustomTool — Custom tool configuration - `description` string - `format` union - object - `type` 'text', required - object - `definition` string, required - `syntax` 'lark' | 'regex', required - `type` 'grammar', required - `name` string, required - `type` 'custom', required - `top_logprobs` integer - `top_p` number, double, nullable, required - `truncation` 'auto' | 'disabled' | 'null', nullable - `usage` object, nullable — Token usage information for the response - `input_tokens` integer, required - `input_tokens_details` object, required - `cache_write_tokens` integer, nullable - `cached_tokens` integer, required - `output_tokens` integer, required - `output_tokens_details` object, required - `reasoning_tokens` integer, required - `total_tokens` integer, required - `cost` number, double, nullable — Cost of the completion - `cost_details` object - `upstream_inference_cost` number, double, nullable - `upstream_inference_input_cost` number, double, required - `upstream_inference_output_cost` number, double, required - `is_byok` boolean — Whether a request was made using a Bring Your Own Key configuration - `user` string, nullable - `error_type` 'context_length_exceeded' | 'max_tokens_exceeded' | 'token_limit_exceeded' | 'string_too_long' | 'authentication' | 'permission_denied' | 'payment_required' | 'rate_limit_exceeded' | 'provider_overloaded' | 'provider_unavailable' | 'invalid_request' | 'invalid_prompt' | 'not_found' | 'precondition_failed' | 'payload_too_large' | 'unprocessable' | 'content_policy_violation' | 'refusal' | 'invalid_image' | 'image_too_large' | 'image_too_small' | 'unsupported_image_format' | 'image_not_found' | 'image_download_failed' | 'server' | 'timeout' | 'unmapped' — Canonical OpenRouter error type, stable across all API formats - `openrouter_metadata` OpenRouterMetadata - `attempt` integer, required - `attempts` RouterAttempt[] - `model` string, required - `provider` string, required - `status` integer, required - `endpoints` EndpointsMetadata, required - `available` EndpointInfo[], required - `model` string, required - `provider` string, required - `selected` boolean, required - `total` integer, required - `is_byok` boolean, required - `params` RouterParams - `quality_floor` number, double - `throughput_floor` number, double - `version_group` string - `pipeline` PipelineStage[] - `cost_usd` number, double, nullable - `data` object - `guardrail_id` string - `guardrail_scope` string - `name` string, required - `summary` string - `type` 'guardrail' | 'plugin' | 'server_tools' | 'response_healing' | 'context_compression', required — Categorical kind of a pipeline stage. Multiple plugins can share a type (e.g. all guardrail-level plugins emit `guardrail`); the `name` field disambiguates which plugin emitted it. - `region` string, nullable, required - `requested` string, required - `strategy` 'direct' | 'auto' | 'free' | 'latest' | 'alias' | 'fallback' | 'pareto' | 'bodybuilder' | 'fusion', required - `summary` string, required ## Other responses - `400` — Bad Request - Invalid request parameters or malformed input - `401` — Unauthorized - Authentication required or invalid credentials - `402` — Payment Required - Insufficient credits or quota to complete request - `403` — Forbidden - Authentication successful but insufficient permissions, or a guardrail blocked the request. When guardrails block and the `X-OpenRouter-Metadata: enabled` header is present, the response includes `openrouter_metadata` with full routing context and a `pipeline` array containing guardrail stage details. - `404` — Not Found - Resource does not exist - `408` — Request Timeout - Operation exceeded time limit - `413` — Payload Too Large - Request payload exceeds size limits - `422` — Unprocessable Entity - Semantic validation failure - `429` — Too Many Requests - Rate limit exceeded - `500` — Internal Server Error - Unexpected server error - `502` — Bad Gateway - Provider/upstream API failure - `503` — Service Unavailable - Service temporarily unavailable - `524` — Infrastructure Timeout - Provider request timed out at edge network - `529` — Provider Overloaded - Provider is temporarily overloaded ## Changes - **2026-07-13** `9814733ca74d` — 2 breaking, 2 info - removed `#/components/schemas/ChatSearchModelsServerTool` from the `input/anyOf[subschema #2]/items/anyOf[#/components/schemas/AdditionalToolsItem]/tools/items/` request property `anyOf` list - removed `#/components/schemas/ChatSearchModelsServerTool` from the `tools/items/` request property `anyOf` list - added `#/components/schemas/SearchModelsServerTool_OpenRouter` to the `input/anyOf[subschema #2]/items/anyOf[#/components/schemas/AdditionalToolsItem]/tools/items/` request property `anyOf` list - added `#/components/schemas/SearchModelsServerTool_OpenRouter` to the `tools/items/` request property `anyOf` list - **2026-07-11** `49908263f773` — 3 info - added the new `Meta` enum value to the request property `provider/ignore/items/anyOf[#/components/schemas/ProviderName]/` - added the new `Meta` enum value to the request property `provider/only/items/anyOf[#/components/schemas/ProviderName]/` - added the new `Meta` enum value to the request property `provider/order/items/anyOf[#/components/schemas/ProviderName]/` - …earlier changes not shown [Full history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/responses/post.md) --- [API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/revisions/9814733ca74d/schema)