--- title: "Create a message" method: POST path: "/messages" tags: ["Anthropic Messages"] --- # Create a message `POST /messages` Creates a message using the Anthropic Messages API format. Supports text, images, PDFs, tools, and extended thinking. ## Headers - `X-OpenRouter-Metadata` 'disabled' | 'enabled' — Opt-in level for surfacing routing metadata on the response under `openrouter_metadata`. ## Request body - MessagesRequest — Request schema for Anthropic Messages API endpoint - `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 - `context_management` object, nullable - `edits` union[] - union - object - `clear_at_least` AnthropicInputTokensClearAtLeast, nullable - `type` 'input_tokens', required - `value` integer, required - `clear_tool_inputs` union - boolean - string[] - unknown - `exclude_tools` string[], nullable - `keep` AnthropicToolUsesKeep - `type` 'tool_uses', required - `value` integer, required - `trigger` union - AnthropicInputTokensTrigger - … - AnthropicToolUsesTrigger - … - `type` 'clear_tool_uses_20250919', required - object - `keep` union - AnthropicThinkingTurns - … - object - … - 'all' - `type` 'clear_thinking_20251015', required - object - `instructions` string, nullable - `pause_after_compaction` boolean - `trigger` object, nullable - `type` 'input_tokens', required - `value` integer, required - `type` 'compact_20260112', required - `fallbacks` MessagesFallbackParam[], nullable — Fallback models to try if the primary model fails or refuses, in order. Handled by OpenRouter multi-model routing rather than Anthropic server-side fallbacks; cannot be combined with `models`. Each entry accepts only `model`. Maximum of 3 entries. - `model` string, required - `max_tokens` integer - `messages` MessagesMessageParam[], nullable, required - `content` union, required - string - union[] - union - AnthropicTextBlockParam - `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. - … - `citations` union[], nullable - … - `text` string, required - `type` 'text', required - AnthropicImageBlockParam - `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. - … - `source` union, required - … - `type` 'image', required - AnthropicDocumentBlockParam - `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. - … - `citations` object, nullable - … - `context` string, nullable - `source` union, required - … - `title` string, nullable - `type` 'document', required - object - `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. - … - `id` string, required - `input` unknown - `name` string, required - `type` 'tool_use', required - object - `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. - … - `content` union - … - `is_error` boolean - `tool_use_id` string, required - `type` 'tool_result', required - object - `signature` string, required - `thinking` string, required - `type` 'thinking', required - object - `data` string, required - `type` 'redacted_thinking', required - object - `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. - … - `id` string, required - `input` unknown - `name` string, required - `type` 'server_tool_use', required - object - `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. - … - `content` union, required - … - `tool_use_id` string, required - `type` 'web_search_tool_result', required - AnthropicSearchResultBlockParam - `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. - … - `citations` object - … - `content` AnthropicTextBlockParam[], required - … - `source` string, required - `title` string, required - `type` 'search_result', required - object - `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. - … - `content` string, nullable, required - `type` 'compaction', required - MessagesAdvisorToolResultBlock — Advisor tool result from a prior assistant turn, replayed back to the model on the next turn. Mirrors the block Anthropic returns in assistant content when the `advisor_20260301` tool runs. - `content` object, required - `tool_use_id` string, required - `type` 'advisor_tool_result', required - `role` 'user' | 'assistant' | 'system', required - `metadata` object - `user_id` string, nullable - `model` string, required - `models` string[] - `output_config` MessagesOutputConfig — Configuration for controlling output behavior. Supports the effort parameter and structured output format. - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'null', nullable — How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer. Valid values are `low`, `medium`, `high`, `xhigh`, or `max`. - `format` object, nullable — A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs). - `schema` object, required - `type` 'json_schema', required - `task_budget` object, nullable — Task budget for an agentic turn. The model sees a countdown of remaining tokens and uses it to prioritize work and wind down gracefully. Advisory — does not enforce a hard cap. - `remaining` integer, nullable - `total` integer, required - `type` 'tokens', required - `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"). - `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. - `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"). - `service_tier` string - `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. - `speed` 'fast' | 'standard' | 'null', nullable — Controls output generation speed. When set to `fast`, uses a higher-speed inference configuration at premium pricing. Defaults to `standard` when omitted. - `stop_sequences` string[] - `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 - `stream` boolean - `system` union - string - AnthropicTextBlockParam[] - `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 - `citations` union[], nullable - union - AnthropicCitationCharLocationParam - `cited_text` string, required - `document_index` integer, required - `document_title` string, nullable, required - `end_char_index` integer, required - `start_char_index` integer, required - `type` 'char_location', required - AnthropicCitationPageLocationParam - `cited_text` string, required - `document_index` integer, required - `document_title` string, nullable, required - `end_page_number` integer, required - `start_page_number` integer, required - `type` 'page_location', required - AnthropicCitationContentBlockLocationParam - `cited_text` string, required - `document_index` integer, required - `document_title` string, nullable, required - `end_block_index` integer, required - `start_block_index` integer, required - `type` 'content_block_location', required - AnthropicCitationWebSearchResultLocationParam - `cited_text` string, required - `encrypted_index` string, required - `title` string, nullable, required - `type` 'web_search_result_location', required - `url` string, required - AnthropicCitationSearchResultLocationParam - `cited_text` string, required - `end_block_index` integer, required - `search_result_index` integer, required - `source` string, required - `start_block_index` integer, required - `title` string, nullable, required - `type` 'search_result_location', required - `text` string, required - `type` 'text', required - `temperature` number, double - `thinking` union - object - `budget_tokens` integer, required - `display` 'summarized' | 'omitted' | 'null', nullable - `type` 'enabled', required - object - `type` 'disabled', required - object - `display` 'summarized' | 'omitted' | 'null', nullable - `type` 'adaptive', required - `tool_choice` union - object - `disable_parallel_tool_use` boolean - `type` 'auto', required - object - `disable_parallel_tool_use` boolean - `type` 'any', required - object - `type` 'none', required - object - `disable_parallel_tool_use` boolean - `name` string, required - `type` 'tool', required - `tools` union[] - union - object - `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 - `description` string - `input_schema` object, required - `properties` unknown - `required` string[], nullable - `type` string - `name` string, required - `type` 'custom' - object - `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 - `name` 'bash', required - `type` 'bash_20250124', required - object - `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 - `name` 'str_replace_editor', required - `type` 'text_editor_20250124', required - object - `allowed_domains` string[], nullable - `blocked_domains` string[], 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 - `max_uses` integer, nullable - `name` 'web_search', required - `type` 'web_search_20250305', required - `user_location` AnthropicWebSearchToolUserLocation, nullable - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate', required - object - `allowed_callers` string[] - `allowed_domains` string[], nullable - `blocked_domains` string[], 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 - `max_uses` integer, nullable - `name` 'web_search', required - `type` 'web_search_20260209', required - `user_location` AnthropicWebSearchToolUserLocation, nullable - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - `type` 'approximate', required - object - `allowed_callers` string[] - `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 - `caching` object, nullable — 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 - `defer_loading` boolean - `max_uses` integer - `model` string, required - `name` 'advisor', required - `type` 'advisor_20260301', 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 - 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 - 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 - MessagesSearchModelsServerTool — 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 - OpenRouterWebSearchServerTool — OpenRouter built-in server tool: searches the web for current information - `parameters` WebSearchConfig - `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 - object - `type` string, required - `top_k` integer - `top_p` number, double - `trace` TraceConfig — Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations. - `generation_name` string - `parent_span_id` string - `span_name` string - `trace_id` string - `trace_name` string - `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 - MessagesResult — Non-streaming response from the Anthropic Messages API with OpenRouter extensions - `container` AnthropicContainer, nullable, required - `expires_at` string, required - `id` string, required - `content` ORAnthropicContentBlock[], required - union - AnthropicTextBlock - `citations` AnthropicTextCitation[], nullable, required - union - AnthropicCitationCharLocation - … - AnthropicCitationPageLocation - … - AnthropicCitationContentBlockLocation - … - AnthropicCitationWebSearchResultLocation - … - AnthropicCitationSearchResultLocation - … - `text` string, required - `type` 'text', required - AnthropicToolUseBlock - `caller` union, required - AnthropicDirectCaller - `type` 'direct', required - AnthropicCodeExecution20250825Caller - `tool_id` string, required - `type` 'code_execution_20250825', required - AnthropicCodeExecution20260120Caller - `tool_id` string, required - `type` 'code_execution_20260120', required - `id` string, required - `input` unknown - `name` string, required - `type` 'tool_use', required - AnthropicThinkingBlock - `signature` string, required - `thinking` string, required - `type` 'thinking', required - AnthropicRedactedThinkingBlock - `data` string, required - `type` 'redacted_thinking', required - ORAnthropicServerToolUseBlock - `caller` union - AnthropicDirectCaller - `type` 'direct', required - AnthropicCodeExecution20250825Caller - `tool_id` string, required - `type` 'code_execution_20250825', required - AnthropicCodeExecution20260120Caller - `tool_id` string, required - `type` 'code_execution_20260120', required - unknown - `id` string, required - `input` unknown - `name` string, required - `type` 'server_tool_use', required - AnthropicWebSearchToolResult - `caller` union, required - AnthropicDirectCaller - `type` 'direct', required - AnthropicCodeExecution20250825Caller - `tool_id` string, required - `type` 'code_execution_20250825', required - AnthropicCodeExecution20260120Caller - `tool_id` string, required - `type` 'code_execution_20260120', required - `content` union, required - AnthropicWebSearchResult[] - `encrypted_content` string, required - `page_age` string, nullable, required - `title` string, required - `type` 'web_search_result', required - `url` string, required - AnthropicWebSearchToolResultError - `error_code` 'invalid_tool_input' | 'unavailable' | 'max_uses_exceeded' | 'too_many_requests' | 'query_too_long' | 'request_too_large', required - `type` 'web_search_tool_result_error', required - `tool_use_id` string, required - `type` 'web_search_tool_result', required - AnthropicWebFetchToolResult - `caller` union, required - AnthropicDirectCaller - `type` 'direct', required - AnthropicCodeExecution20250825Caller - `tool_id` string, required - `type` 'code_execution_20250825', required - AnthropicCodeExecution20260120Caller - `tool_id` string, required - `type` 'code_execution_20260120', required - `content` union, required - AnthropicWebFetchToolResultError - `error_code` 'invalid_tool_input' | 'url_too_long' | 'url_not_allowed' | 'url_not_accessible' | 'unsupported_content_type' | 'too_many_requests' | 'max_uses_exceeded' | 'unavailable', required - `type` 'web_fetch_tool_result_error', required - AnthropicWebFetchBlock - `content` AnthropicDocumentBlock, required - … - `retrieved_at` string, nullable, required - `type` 'web_fetch_result', required - `url` string, required - `tool_use_id` string, required - `type` 'web_fetch_tool_result', required - AnthropicCodeExecutionToolResult - `content` union, required - AnthropicCodeExecutionToolResultError - `error_code` 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded', required - `type` 'code_execution_tool_result_error', required - AnthropicCodeExecutionResult - `content` AnthropicCodeExecutionOutput[], required - … - `return_code` integer, required - `stderr` string, required - `stdout` string, required - `type` 'code_execution_result', required - AnthropicEncryptedCodeExecutionResult - `content` AnthropicCodeExecutionOutput[], required - … - `encrypted_stdout` string, required - `return_code` integer, required - `stderr` string, required - `type` 'encrypted_code_execution_result', required - `tool_use_id` string, required - `type` 'code_execution_tool_result', required - AnthropicBashCodeExecutionToolResult - `content` union, required - AnthropicBashCodeExecutionToolResultError - `error_code` 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded' | 'output_file_too_large', required - `type` 'bash_code_execution_tool_result_error', required - AnthropicBashCodeExecutionResult - `content` AnthropicBashCodeExecutionOutput[], required - … - `return_code` integer, required - `stderr` string, required - `stdout` string, required - `type` 'bash_code_execution_result', required - `tool_use_id` string, required - `type` 'bash_code_execution_tool_result', required - AnthropicTextEditorCodeExecutionToolResult - `content` union, required - AnthropicTextEditorCodeExecutionToolResultError - `error_code` 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded' | 'file_not_found', required - `error_message` string, nullable, required - `type` 'text_editor_code_execution_tool_result_error', required - AnthropicTextEditorCodeExecutionViewResult - `content` string, required - `file_type` 'text' | 'image' | 'pdf', required - `num_lines` integer, nullable, required - `start_line` integer, nullable, required - `total_lines` integer, nullable, required - `type` 'text_editor_code_execution_view_result', required - AnthropicTextEditorCodeExecutionCreateResult - `is_file_update` boolean, required - `type` 'text_editor_code_execution_create_result', required - AnthropicTextEditorCodeExecutionStrReplaceResult - `lines` string[], nullable, required - `new_lines` integer, nullable, required - `new_start` integer, nullable, required - `old_lines` integer, nullable, required - `old_start` integer, nullable, required - `type` 'text_editor_code_execution_str_replace_result', required - `tool_use_id` string, required - `type` 'text_editor_code_execution_tool_result', required - AnthropicToolSearchToolResult - `content` union, required - AnthropicToolSearchResultError - `error_code` 'invalid_tool_input' | 'unavailable' | 'too_many_requests' | 'execution_time_exceeded', required - `error_message` string, nullable, required - `type` 'tool_search_tool_result_error', required - AnthropicToolSearchResult - `tool_references` AnthropicToolReference[], required - … - `type` 'tool_search_tool_search_result', required - `tool_use_id` string, required - `type` 'tool_search_tool_result', required - AnthropicContainerUpload - `file_id` string, required - `type` 'container_upload', required - AnthropicCompactionBlock - `content` string, nullable, required - `type` 'compaction', required - AnthropicAdvisorToolResult - `content` object, required - `tool_use_id` string, required - `type` 'advisor_tool_result', required - `id` string, required - `model` string, required - `role` 'assistant', required - `stop_details` AnthropicRefusalStopDetails, nullable, required — Structured information about a refusal - `category` 'cyber' | 'bio' | 'null', nullable, required - `explanation` string, nullable, required - `type` 'refusal', required - `stop_reason` 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal' | 'compaction' | 'null', nullable, required - `stop_sequence` string, nullable, required - `type` 'message', required - `usage` object, required - `cache_creation` AnthropicCacheCreation, nullable, required - `ephemeral_1h_input_tokens` integer, required - `ephemeral_5m_input_tokens` integer, required - `cache_creation_input_tokens` integer, nullable, required - `cache_read_input_tokens` integer, nullable, required - `inference_geo` string, nullable, required - `input_tokens` integer, required - `output_tokens` integer, required - `output_tokens_details` AnthropicOutputTokensDetails, nullable, required - `thinking_tokens` integer, required - `server_tool_use` AnthropicServerToolUsage, nullable, required - `web_fetch_requests` integer, required - `web_search_requests` integer, required - `service_tier` string, nullable, required - `iterations` AnthropicUsageIteration[] - union - AnthropicCompactionUsageIteration - `cache_creation` AnthropicIterationCacheCreation, nullable - `ephemeral_1h_input_tokens` integer - `ephemeral_5m_input_tokens` integer - `cache_creation_input_tokens` integer - `cache_read_input_tokens` integer - `input_tokens` integer - `output_tokens` integer - `type` 'compaction', required - AnthropicMessageUsageIteration - `cache_creation` AnthropicIterationCacheCreation, nullable - `ephemeral_1h_input_tokens` integer - `ephemeral_5m_input_tokens` integer - `cache_creation_input_tokens` integer - `cache_read_input_tokens` integer - `input_tokens` integer - `output_tokens` integer - `model` string - `type` 'message', required - AnthropicAdvisorMessageUsageIteration - `cache_creation` AnthropicIterationCacheCreation, nullable - `ephemeral_1h_input_tokens` integer - `ephemeral_5m_input_tokens` integer - `cache_creation_input_tokens` integer - `cache_read_input_tokens` integer - `input_tokens` integer - `output_tokens` integer - `model` string, required - `type` 'advisor_message', required - AnthropicUnknownUsageIteration - `cache_creation` AnthropicIterationCacheCreation, nullable - `ephemeral_1h_input_tokens` integer - `ephemeral_5m_input_tokens` integer - `cache_creation_input_tokens` integer - `cache_read_input_tokens` integer - `input_tokens` integer - `output_tokens` integer - `type` string, required - `speed` 'fast' | 'standard' | 'null', nullable - `cost` number, double, nullable - `cost_details` CostDetails, nullable — Breakdown of upstream inference costs - `upstream_inference_completions_cost` number, double, required - `upstream_inference_cost` number, double, nullable - `upstream_inference_prompt_cost` number, double, required - `is_byok` boolean - `context_management` object, nullable - `applied_edits` object[], required - `type` string, required - `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 - `provider` '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' ## Other responses - `400` — Invalid request error - `401` — Authentication error - `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 error - `429` — Rate limit error - `500` — API error - `503` — Overloaded error - `529` — Overloaded error ## Changes - **2026-07-13** `9814733ca74d` — 8 breaking, 22 info - removed `#/components/schemas/ChatSearchModelsServerTool` from the `tools/items/` request property `anyOf` list - removed `#/components/schemas/AnthropicCitationWebSearchResultLocation, #/components/schemas/AnthropicCitationSearchResultLocation` from the `messages/items/content/anyOf[subschema #2]/items/oneOf[#/components/schemas/AnthropicDocumentBlockParam]/source/oneOf[subschema #3]/content/anyOf[subschema #2]/items/oneOf[#/components/schemas/AnthropicTextBlockParam]/citations/items/` request property `oneOf` list - removed `#/components/schemas/AnthropicCitationWebSearchResultLocation, #/components/schemas/AnthropicCitationSearchResultLocation` from the `messages/items/content/anyOf[subschema #2]/items/oneOf[#/components/schemas/AnthropicSearchResultBlockParam]/content/items/citations/items/` request property `oneOf` list - removed `#/components/schemas/AnthropicCitationWebSearchResultLocation, #/components/schemas/AnthropicCitationSearchResultLocation` from the `messages/items/content/anyOf[subschema #2]/items/oneOf[#/components/schemas/AnthropicTextBlockParam]/citations/items/` request property `oneOf` list - …26 more - …earlier changes not shown [Full history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/messages/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)