{"note":"OpenAPI conversion -- returning structured metadata","name":"openrouter","description":"OpenRouter API","version":"1.0.0","base_url":"https://openrouter.ai/api/v1","endpoints":174,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api OpenRouter API\n@base https://openrouter.ai/api/v1\n@version 1.0.0\n@auth Bearer bearer | Bearer bearer\n@endpoints 174\n@hint download_for_search\n@toc activity(1), analytics(2), api(2), audio(2), auth(2), batches(4), benchmarks(1), byok(5), chat(1), classifications(1), containers(4), credits(7), datasets(3), embeddings(2), endpoints(1), external-users(5), files(5), generation(3), guardrails(36), images(3), key(1), keys(5), messages(1), model(1), models(4), oauth(2), observability(5), organization(3), presets(9), private-endpoints(9), private-providers(5), providers(1), rerank(1), responses(1), scim(8), systemone(1), tools(2), vault(9), videos(4), workspaces(12)\n\n@group activity\n@endpoint GET /activity\n@desc Get user activity grouped by endpoint\n@optional {date: str # Filter by a single UTC date in the last 30 days (YYYY-MM-DD format)., api_key_hash: str # Filter by API key hash (SHA-256 hex string, as returned by the keys API)., user_id: str # Filter by org member user ID. Only applicable for organization accounts., group_by: str # Set to 'workspace' to split each row per workspace and include `workspace_id` on every item. Omitted by default, in which case rows are aggregated across workspaces (by date, model, and endpoint) and `workspace_id` is not returned — preserving the historical response shape., workspace_id: str # Filter by workspace ID (UUID). Returns only activity attributed to that workspace. The workspace must belong to the authenticated account.}\n@returns(200) {data: [map]} # Returns user activity data grouped by endpoint\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group analytics\n@endpoint GET /analytics/meta\n@desc Get available analytics metrics and dimensions\n@returns(200) {data: map{dimensions: [map], granularities: [map], metrics: [map], operators: [map]}} # Returns analytics query metadata\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /analytics/query\n@desc Query analytics data\n@required {metrics: [str]}\n@optional {classifier_dimensions: map{classifier_id!: str(uuid), dimension_names: [str], include_nulls: bool} # Group results by custom classifier tags, breaking down metrics by the specified dimension values. Requires an active classifier on the workspace., classifier_filters: map{classifier_id!: str(uuid), filters!: [any]} # Filter results to generations with specific classifier tag values. Can be combined with classifier_dimensions (must use the same classifier_id) or used independently with standard dimensions., dimensions: [str], filters: [any], granularity: str # Time granularity, group_limit: int # Maximum rows per distinct combination of dimensions. When omitted on time-series queries (granularity + dimensions), auto-computed to avoid truncating time windows. Explicit values override the default and may truncate time buckets if set lower than the number of buckets in the range. Ignored when no dimensions are specified., limit: int # Maximum total rows returned. Defaults to 1000. On time-series queries with dimensions and no explicit group_limit, the server may raise this to accommodate the expected number of unique time-bucket/dimension combinations., order_by: map{direction!: str, field!: str}, time_range: map{end!: str(date-time), start!: str(date-time)}}\n@returns(200) {data: map{cachedAt: num(double), data: [map], metadata: map{query_time_ms: num(double), row_count: int, truncated: bool}, warnings: [str]}} # Analytics query results\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 408: Request Timeout - Operation exceeded time limit, 500: Internal Server Error - Unexpected server error}\n@example_request {\"dimensions\":[\"model\"],\"granularity\":\"day\",\"limit\":100,\"metrics\":[\"request_count\"],\"time_range\":{\"end\":\"2025-01-08T00:00:00Z\",\"start\":\"2025-01-01T00:00:00Z\"}}\n\n@endgroup\n\n@group api\n@endpoint POST /api/alpha/decisions\n@desc Submit a Decisions request\n@required {model: str, questions: map, state: any # The content to evaluate: a plain string, or a JSON object or array of related context.}\n@optional {assets: map # Images keyed by reference string, as in TypeSafe's API. Write a reference wherever the image belongs in `state`, `instructions`, or `criteria`; every asset must be referenced at least once, or the request fails with `400` naming the unused key. TypeSafe Jev endpoints receive `assets` as written and read a reference as a whole string value or inside longer text. Every other provider has each whole-string reference resolved to an `image_url` part before the request is sent, so it is accepted only where that provider reads `image_url` parts (top-level `state` items), and a reference inside longer text fails with `400`. `image_url` parts and `assets` can be mixed in one request., provider: any, session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str}\n@returns(200) {annotations: [map], answers: map, id: str, model: str, provider: str, usage: map{cost: num(double), cost_details: map?, input_tokens: int, input_tokens_details: map{cached_tokens: int}, is_byok: bool, output_tokens: int}} # Decisions response\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 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}\n@example_request {\"model\":\"typesafe/jev-1.13\",\"questions\":{\"is_bug\":{\"criteria\":{\"false\":\"The customer is asking a question or requesting a feature.\",\"true\":\"The customer describes broken or unexpected product behavior.\"},\"instructions\":\"Is the customer reporting a software defect?\",\"type\":\"noul\"},\"team\":{\"criteria\":{\"account\":\"Login, permissions, or profile issues.\",\"frontend\":\"Rendering, layout, or browser compatibility issues.\",\"payments\":\"Checkout, billing, or payment processing issues.\"},\"instructions\":\"Which team should own this ticket?\",\"type\":\"choice\"},\"urgency\":{\"criteria\":[\"Can wait for the next release\",\"Should be fixed this week\",\"Blocking revenue right now\"],\"instructions\":\"How urgent is this ticket?\",\"type\":\"score\"}},\"state\":{\"customer_tier\":\"enterprise\",\"ticket\":\"My checkout page shows a blank screen after I click Pay. I have tried two browsers.\"}}\n\n@endpoint POST /api/alpha/extractions\n@desc Submit an Extractions request\n@required {fields: map # Map of field name to typed field spec., model: str}\n@optional {assets: map # Assets keyed by reference string. Write a reference wherever the asset belongs in `state` or a field `instructions`; every asset must be referenced at least once, unless `state` is empty or omitted, in which case the assets are read without a reference. A `state` that is exactly the sole asset's key carries no text of its own and is read as file-only. A model that reads either text or a document per request, not both (ScaleDown Extract with a PDF), takes that form or an empty or omitted `state`: any other text around the key is state text and is rejected with 400., provider: any, reference_date: str # ISO date that anchors dates written without a year., session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., state: str= # The text to read from. May be empty or omitted only when the request carries assets, which are then read without being referenced by key., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str}\n@returns(200) {answers: map, id: str, model: str, provider: str, state_text: str?, truncated: bool, usage: map{cost: num(double), image_tokens: int, input_tokens: int, output_tokens: int, passes: int, schema_tokens: int, state_tokens: int}} # Extractions response\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 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}\n@example_request {\"fields\":{\"contacts\":{\"items\":\"text\",\"type\":\"list\"},\"days_to_pay\":{\"max\":120,\"min\":0,\"step\":1,\"type\":\"estimate\"},\"due_date\":{\"instructions\":\"Issue date plus the net payment days\",\"type\":\"date\"},\"invoice_number\":{\"type\":\"text\"},\"total\":{\"decimals\":2,\"type\":\"number\",\"unit\":\"USD\"}},\"model\":\"cloudflare/clairic\",\"reference_date\":\"2026-10-28\",\"state\":\"Invoice INV-2291 issued 2026-09-02, net 30. Contacts: Dana Ruiz, Priya Shah. Total $1080.\"}\n\n@endgroup\n\n@group audio\n@endpoint POST /audio/speech\n@desc Create speech\n@required {input: any # Text to synthesize, or a list of turns for multi-speaker input. Each turn has its own text, voice, and instructions. Multi-speaker input is supported by Gemini TTS models, by Fish Audio models other than S1, and by Speechify dialogue models., model: str # TTS model identifier}\n@optional {input_references: [any] # Reference content for stateless voice cloning or voice design. Audio mode: one to three `input_audio` parts, each optionally paired with a `text` part carrying its transcript (a single clip accepts its transcript before or after it; with multiple clips each transcript immediately follows its clip), plus at most one `image_url` part as a scene image on providers that condition the cloned voice on its setting; only routed to endpoints that support voice cloning (and multiple references or image references when those parts are sent). Image mode: exactly one `image_url` part; only routed to endpoints that support image references. An empty array is treated as no reference., instructions: str # Delivery instructions for the whole request, such as tone, pacing, or emotion. Supported by OpenAI gpt-4o-mini-tts, Gemini TTS, and Fish Audio models. Ignored by other providers., provider: map{allow_fallbacks: bool, data_collection: str, ignore: [any], only: [any], options: map, order: [any], zdr: bool} # Provider configuration: provider routing preferences (`order`, `only`, `ignore`, `allow_fallbacks`), data policy routing preferences (`zdr`, `data_collection`) and provider-specific passthrough options, response_format: str(mp3/pcm)=pcm # Audio output format, session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., speed: num(double) # Playback speed multiplier. Honored by models that support it (e.g. OpenAI TTS). Other providers either ignore it or return a 400 for a non-default value when the model has no speed control., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider., voice: str # Voice identifier (provider-specific). Required by most providers; only Seed Audio, HeyGen, Fish Audio, AssemblyAI, Speechify accept requests without it.}\n@returns(200) Audio bytes stream\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 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}\n@example_request {\"input\":\"Hello world\",\"model\":\"mistralai/voxtral-mini-tts-2603\",\"response_format\":\"pcm\",\"speed\":1,\"voice\":\"en_paul_neutral\"}\n\n@endpoint POST /audio/transcriptions\n@desc Create transcription\n@required {input_audio: any # Audio to transcribe: inline base64 bytes, or a URL the provider downloads directly., model: str # STT model identifier}\n@optional {diarize: bool # Label each word with the speaker who said it. Speaker labels are returned on the words array (speaker, speaker_label), so response_format must be \"verbose_json\" (a \"json\" request is rejected with a 400) and word timestamps are included even when timestamp_granularities omits \"word\". Only supported by some providers; the request is rejected with a 400 when the selected model cannot diarize. Providers may charge extra., keyterms: [str] # Domain terms, names, or phrases to bias recognition toward. Only supported by some providers; the request is rejected with a 400 when the selected model cannot use keyterms. Providers may cap the number of terms or characters per term and may charge extra., language: str # ISO-639-1 language code (e.g., \"en\", \"ja\"). Auto-detected if omitted., prompt: str # Context to guide transcription, such as domain vocabulary or a previous segment. Honored by OpenAI (except gpt-4o-transcribe-diarize), Azure OpenAI, Groq, Together, Alibaba, and AssemblyAI endpoints with prompted pricing configured. Other providers ignore it; use keyterms for supported keyword boosting. Takes precedence over provider-specific prompt options, including when empty., provider: map{allow_fallbacks: bool, data_collection: str, ignore: [any], only: [any], options: map, order: [any], zdr: bool} # Provider configuration: provider routing preferences (`order`, `only`, `ignore`, `allow_fallbacks`), data policy routing preferences (`zdr`, `data_collection`) and provider-specific passthrough options, response_format: str(json/verbose_json) # Output format. \"json\" (default) returns { text, usage }. \"verbose_json\" additionally returns task, language, duration, and segment-level timestamps; only supported by OpenAI-compatible providers., session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., temperature: num(double) # Sampling temperature for transcription, timestamp_granularities: [str] # Timestamp detail levels to include when response_format is \"verbose_json\". \"segment\" returns segment-level timestamps; \"word\" additionally returns word-level timestamps in the words array. Ignored unless response_format is \"verbose_json\"., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.}\n@returns(200) {confidence: num(double), duration: num(double), entities: [map], language: str, language_confidence: num(double), segments: [map], task: str, text: str, usage: map{cost: num(double), input_tokens: int, output_tokens: int, seconds: num(double), total_tokens: int}, words: [map]} # Transcription result\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 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, 504: Gateway Timeout - Provider did not respond before the upstream deadline, 524: Infrastructure Timeout - Provider request timed out at edge network, 529: Provider Overloaded - Provider is temporarily overloaded}\n@example_request {\"input_audio\":{\"data\":\"UklGRiQA...\",\"format\":\"wav\"},\"language\":\"en\",\"model\":\"openai/whisper-large-v3\"}\n\n@endgroup\n\n@group auth\n@endpoint POST /auth/keys\n@desc Exchange authorization code for API key\n@required {code: str # The authorization code received from the OAuth redirect}\n@optional {code_challenge_method: str(S256/plain) # The method used to generate the code challenge, code_verifier: str # The `code_verifier` whose SHA-256 hash was sent as `code_challenge` in the authorization request.}\n@returns(200) {key: str, user_id: str?} # Successfully exchanged code for an API key\n@errors {400: Bad Request - Invalid request parameters or malformed input, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n@example_request {\"code\":\"auth_code_abc123def456\",\"code_challenge_method\":\"S256\",\"code_verifier\":\"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"}\n\n@endpoint POST /auth/keys/code\n@desc Create authorization code\n@required {callback_url: str(uri) # The callback URL to redirect to after authorization. Supports https URLs and localhost/127.0.0.1 URLs on any port for local CLI tools.}\n@optional {code_challenge: str # PKCE code challenge: the base64url-encoded SHA-256 hash of your `code_verifier`. Send it with `code_challenge_method` set to `S256`., code_challenge_method: str(S256/plain) # The method used to generate the code challenge, expires_at: str(date-time) # Optional ISO 8601 UTC expiration timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected., key_label: str # Optional custom label for the API key. Defaults to the app name if not provided., limit: num(double) # Credit limit for the API key to be created, usage_limit_type: str(daily/weekly/monthly) # Optional credit limit reset interval. When set, the credit limit resets on this interval., workspace_id: str(uuid) # Optional workspace ID to associate the API key with}\n@returns(200) {data: map{app_id: int, created_at: str, id: str}} # Successfully created authorization code\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n@example_request {\"callback_url\":\"https://myapp.com/auth/callback\",\"code_challenge\":\"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM\",\"code_challenge_method\":\"S256\",\"limit\":100}\n\n@endgroup\n\n@group batches\n@endpoint GET /batches\n@desc List batches\n@optional {limit: int # Maximum number of batches to return, from 1 through 100., after: str # Batch id from the previous page's `last_id`., status: [str] # Repeat this parameter to include more than one status., created_after: any # Only include batches created strictly after this timestamp., created_before: any # Only include batches created strictly before this timestamp.}\n@returns(200) {data: [map], first_id: str?, has_more: bool, last_id: str?, object: str} # A newest-first page of batches.\n@errors {400: Malformed or unsupported batch list query parameters., 401: Missing or invalid API key., 429: Batch API rate limit exceeded for the billable entity., 500: Unexpected error in the ingress or upstream batch-api., 502: The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.}\n\n@endpoint POST /batches\n@desc Create a batch\n@required {endpoint: str(/v1/chat/completions//v1/responses//v1/messages//v1/embeddings//v1/audio/speech), model: str}\n@optional {callback_url: str(uri) # HTTPS URL that receives a `batch.completed`, `batch.failed`, `batch.cancelled` or `batch.expired` webhook event when the batch reaches a terminal status. Must appear before `requests` in the request body., completion_window: str=24h, input: map{uri!: str} # A batch input file or table in your own storage, named in place of `requests`. Available to allowlisted callers on Google Vertex BYOK endpoints only., provider: map{allow_fallbacks: bool, only: [any]} # Batch provider routing preferences. Only `provider.only` and `provider.allow_fallbacks` are supported., requests: [map{body!: map, custom_id!: str}] # The batch requests. Send exactly one of `requests` or `input`; `requests` must be the last field in the request body.}\n@returns(202) {completion_window: str, created_at: int, endpoint: str, error: map?, expires_at: int?, finalized_at: int?, id: str, model: str, object: str, output: map{uri: str}, provider: str?, request_counts: map{completed: int, failed: int, total: int}, results: [map]?, status: str, usage: map?} # Batch payload durably persisted and queued for asynchronous validation and provider submission (`status: \"validating\"`).\n@errors {400: Malformed batch input or an unknown/incompatible batch model., 401: Missing or invalid API key., 402: The estimated batch cost exceeds the available balance., 403: The resolved batch endpoint is blocked by account policy., 404: No batch exists for the given id., 413: Batch input exceeds the maximum payload size., 422: The requested model variant or custom IDs violate Batch API constraints., 429: Batch API rate limit exceeded for the billable entity., 500: Unexpected error in the ingress or upstream batch-api., 502: The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.}\n@example_request {\"endpoint\":\"/v1/chat/completions\",\"model\":\"openai/gpt-4o\",\"requests\":[{\"body\":{\"messages\":[{\"content\":\"Summarize ...\",\"role\":\"user\"}],\"model\":\"openai/gpt-4o\"},\"custom_id\":\"req-0001\"}]}\n\n@endpoint DELETE /batches/{id}\n@desc Delete a batch\n@required {id: str # The batch job id returned from submit.}\n@returns(200) {deletion: map{openrouter: str, upstream: map{provider: str, status: str}}, id: str, object: str} # The batch was deleted; per-target outcomes are reported under `deletion`.\n@errors {401: Missing or invalid API key., 404: No batch exists for the given id., 409: The batch is still processing, its required provider key is unavailable, or its state changed during deletion., 429: Batch API rate limit exceeded for the billable entity., 500: Unexpected error in the ingress or upstream batch-api., 502: The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.}\n\n@endpoint GET /batches/{id}\n@desc Get a batch\n@required {id: str # The batch job id returned from submit.}\n@returns(200) {completion_window: str, created_at: int, endpoint: str, error: map?, expires_at: int?, finalized_at: int?, id: str, model: str, object: str, output: map{uri: str}, provider: str?, request_counts: map{completed: int, failed: int, total: int}, results: [map]?, status: str, usage: map?} # The current batch job status.\n@errors {401: Missing or invalid API key., 402: The finalized batch cost exceeds the available balance; metadata is returned with `results: null`. Top up credits and poll again to receive the persisted results., 404: No batch exists for the given id., 410: The batch results were deleted after the 30-day retention window., 429: Batch API rate limit exceeded for the billable entity., 500: Unexpected error in the ingress or upstream batch-api., 502: The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.}\n\n@endgroup\n\n@group benchmarks\n@endpoint GET /benchmarks\n@desc List Benchmarks\n@optional {source: str(artificial-analysis/design-arena/openrouter) # Benchmark source to query. Determines the shape of the returned items. When omitted, returns results from all sources., task_type: str(intelligence/coding/agentic/finance-and-accounting/strategy-and-ops/legal/healthcare-and-medical/engineering/economics/cyber/multilingual/decision/search) # Filter results by task type. Every value except `search` names the Artificial Analysis index of the same name and returns only models scored on it, best first (`coding` and `agentic` are deprecated: Artificial Analysis has retired those indexes). Design Arena answers only `coding`, `intelligence` and `agentic`, and OpenRouter's own evals only `intelligence` and `agentic`. `search` returns OpenRouter search benchmark results only., benchmark_type: str(gpqa_diamond/tau_bench_verified_airline/search_browsecomp/search_hle/search_dsqa/search_widesearch) # Return results for one exact OpenRouter benchmark. A `search_*` value narrows the response to search results only; a classic value narrows the OpenRouter items and leaves other sources' items as they are., include_run_config: bool=false # Search benchmarks only: include the published lane configuration whitelist in each search item. Defaults to false. The whitelist is limited to agent turn count, reasoning effort, and temperature so future harness configuration changes do not change the public contract., search_engine: str # OpenRouter search benchmarks only: filter by the search engine used., search_surface: str(server-tool/plugin) # OpenRouter search benchmarks only: filter by the request surface the lane ran on., arena: str(models/builders/agents) # Design Arena only: arena to query. Defaults to `models` when source is `design-arena`., category: str # Design Arena only: category within the arena (e.g. `codecategories`, `uicomponent`, `gamedev`, `3d`, `dataviz`, `image`, `video`, `svg`). When omitted, returns all categories., max_results: int # Maximum number of items to return. When omitted, all matching results are returned.}\n@returns(200) {data: [any], meta: map{as_of: str, citation: str?, model_count: int, source: str?, source_url: str?, task_type: str?, version: str}} # Benchmark results filtered by the specified source and optional task type.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group byok\n@endpoint GET /byok\n@desc List BYOK provider credentials\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), workspace_id: str(uuid) # Optional workspace ID to filter by. When omitted, a workspace-scoped management key uses its own workspace. An organization management key uses the account’s default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly., provider: str(ai21/aion-labs/akashml/alibaba/amazon-bedrock/amazon-bedrock/claude-on-aws/amazon-nova/ambient/antdigital/anthropic/anthropic/2/arcee-ai/assemblyai/atlas-cloud/avian/azure/baidu/baseten/black-forest-labs/byteplus/cerebras/chutes/cirrascale/clarifai/claude-on-aws/cloudflare/cohere/coreweave/cosine/crusoe/darkbloom/databricks/decart/deepgram/deepinfra/deepseek/dekallm/digitalocean/doubleword/elevenlabs/featherless/fireworks/fish-audio/friendli/gmicloud/google-ai-studio/google-vertex/groq/heygen/inception/inceptron/inferact-vllm/inference-net/infermatic/inflection/io-net/ionstream/krea/kt/liquid/makora/mancer/mara/meta/minimax/mistral/modal/modelrun/modular/moonshotai/morph/near-ai/nebius/nex-agi/nextbit/novita/nvidia/ollama/open-inference/openai/parallel/parasail/pareto-alpha/particle-ai/pearl-research/perceptron/perplexity/phala/poolside/primalabs/primeintellect/quiver/recraft/recursive/reka/relace/respan/river/runway/sail-research/sakana/sakana-ai/sambanova/scaledown/seed/siliconflow/sourceful/speechify/stepfun/streamlake/switchpoint/tencent/tenstorrent/thinkingmachines/together/typesafe/unbiased/upstage/venice/voyageai/wafer/wandb/wandb-legacy/xai/xiaomi/z-ai) # Optional provider slug to filter by (e.g. `openai`, `anthropic`, `amazon-bedrock`).}\n@returns(200) {data: [map], total_count: int} # List of BYOK credentials\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /byok\n@desc Create a BYOK provider credential\n@required {key: str # The raw provider API key or credential. This value is encrypted at rest and never returned in API responses., provider: str(ai21/aion-labs/akashml/alibaba/amazon-bedrock/amazon-bedrock/claude-on-aws/amazon-nova/ambient/antdigital/anthropic/anthropic/2/arcee-ai/assemblyai/atlas-cloud/avian/azure/baidu/baseten/black-forest-labs/byteplus/cerebras/chutes/cirrascale/clarifai/claude-on-aws/cloudflare/cohere/coreweave/cosine/crusoe/darkbloom/databricks/decart/deepgram/deepinfra/deepseek/dekallm/digitalocean/doubleword/elevenlabs/featherless/fireworks/fish-audio/friendli/gmicloud/google-ai-studio/google-vertex/groq/heygen/inception/inceptron/inferact-vllm/inference-net/infermatic/inflection/io-net/ionstream/krea/kt/liquid/makora/mancer/mara/meta/minimax/mistral/modal/modelrun/modular/moonshotai/morph/near-ai/nebius/nex-agi/nextbit/novita/nvidia/ollama/open-inference/openai/parallel/parasail/pareto-alpha/particle-ai/pearl-research/perceptron/perplexity/phala/poolside/primalabs/primeintellect/quiver/recraft/recursive/reka/relace/respan/river/runway/sail-research/sakana/sakana-ai/sambanova/scaledown/seed/siliconflow/sourceful/speechify/stepfun/streamlake/switchpoint/tencent/tenstorrent/thinkingmachines/together/typesafe/unbiased/upstage/venice/voyageai/wafer/wandb/wandb-legacy/xai/xiaomi/z-ai) # The upstream provider this credential authenticates against, as a lowercase slug (e.g. `openai`, `anthropic`, `amazon-bedrock`).}\n@optional {allowed_api_key_hashes: [str] # Optional allowlist of OpenRouter API key hashes (`api_keys.hash`) that may use this credential. `null` means no restriction. Must contain at least one hash if provided. Hashes that do not belong to your account return a 400; for a credential pinned to a workspace, so do hashes of API keys outside that workspace., allowed_models: [str] # Optional allowlist of model slugs this credential may be used for. `null` means no restriction., allowed_user_ids: [str] # Optional allowlist of user IDs that may use this credential. `null` means no restriction., declared_region: str(global/europe/us) # Your declaration of the data region in which the upstream provider account behind this credential processes requests, used for routing eligibility on OpenRouter's regional hosts. `null` means undeclared and `global` is behaviorally identical: the credential follows the region OpenRouter records for the endpoint. `europe` or `us` lets requests to `eu.openrouter.ai` or `us.openrouter.ai` use this credential for that provider (private endpoints, endpoints pinned to another cloud region, cross-region inference profiles and video models are excluded). Self-declared and not verified by OpenRouter. For OpenAI and Fireworks the region comes from the key material (a `{\"api_key\": ..., \"region\": ...}` key), so the value must match the key's region. Among other providers, Azure accepts `europe` or `us` and Anthropic accepts `us` only. Defaults to the key's region for OpenAI and Fireworks, otherwise `null`., declared_zdr: bool # Your declaration of whether the upstream provider account behind this credential has zero data retention (ZDR). `null` inherits OpenRouter's data policy for the provider's endpoint; `true` declares the account ZDR so requests that require ZDR may route to this credential even when the shared endpoint retains data; `false` declares it non-ZDR so such requests never route to it. Self-declared and not verified by OpenRouter. Defaults to `null`., disabled: bool # Whether this credential should be created in a disabled state., is_byok_only: bool # Whether OpenRouter's shared endpoints on this provider are removed for every model, including models outside `allowed_models` and after all of your keys for the provider fail. The provider is skipped instead of spending OpenRouter credits. Only valid on non-fallback credentials. Defaults to `false`., is_fallback: bool # Whether this credential is treated as a fallback — used only after non-fallback keys for the same provider have been tried. Cannot be combined with `is_byok_only`., is_required: bool # Whether OpenRouter's shared endpoints on this provider are removed for the models this credential applies to (its `allowed_models`, or every model when `null`). Requests for those models run only on your keys; models outside the allowlist may still fall back to shared capacity on this provider. Defaults to `false`., name: str # Optional human-readable name for the credential., workspace_id: str(uuid) # Optional workspace ID to scope the credential to. When omitted, a workspace-scoped management key creates it in its own workspace. An organization management key creates it in the account's default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly.}\n@returns(201) {data: any} # BYOK credential created successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n@example_request {\"key\":\"sk-proj-abc123...\",\"name\":\"Production OpenAI Key\",\"provider\":\"openai\"}\n\n@endpoint DELETE /byok/{id}\n@desc Delete a BYOK provider credential\n@required {id: str(uuid) # The BYOK credential ID (UUID).}\n@returns(200) {deleted: bool} # BYOK credential deleted successfully\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /byok/{id}\n@desc Get a BYOK provider credential\n@required {id: str(uuid) # The BYOK credential ID (UUID).}\n@returns(200) {data: any} # BYOK credential details\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /byok/{id}\n@desc Update a BYOK provider credential\n@required {id: str(uuid) # The BYOK credential ID (UUID).}\n@optional {allowed_api_key_hashes: [str] # Optional allowlist of OpenRouter API key hashes (`api_keys.hash`) that may use this credential. `null` clears the restriction. Must contain at least one hash if provided. Hashes that do not belong to your account return a 400; for a credential pinned to a workspace, so do hashes of API keys outside that workspace, unless the credential already lists them (a listed key that has since moved to another workspace stays listed and can be written back)., allowed_models: [str] # Optional allowlist of model slugs this credential may be used for. `null` means no restriction., allowed_user_ids: [str] # Optional allowlist of user IDs that may use this credential. `null` means no restriction., declared_region: str(global/europe/us) # Your declaration of the data region in which the upstream provider account behind this credential processes requests, used for routing eligibility on OpenRouter's regional hosts. `null` means undeclared and `global` is behaviorally identical: the credential follows the region OpenRouter records for the endpoint. `europe` or `us` lets requests to `eu.openrouter.ai` or `us.openrouter.ai` use this credential for that provider (private endpoints, endpoints pinned to another cloud region, cross-region inference profiles and video models are excluded). Self-declared and not verified by OpenRouter. For OpenAI and Fireworks the region comes from the key material (a `{\"api_key\": ..., \"region\": ...}` key), so the value must match the key's region. Among other providers, Azure accepts `europe` or `us` and Anthropic accepts `us` only. Omit to leave the stored value unchanged (rotating an OpenAI or Fireworks `key` re-derives it from the new key); `null` clears the declaration., declared_zdr: bool # Your declaration of whether the upstream provider account behind this credential has zero data retention (ZDR). `null` inherits OpenRouter's data policy for the provider's endpoint; `true` declares the account ZDR so requests that require ZDR may route to this credential even when the shared endpoint retains data; `false` declares it non-ZDR so such requests never route to it. Self-declared and not verified by OpenRouter. Omit to leave the stored value unchanged; `null` clears the declaration., disabled: bool # Whether this credential is disabled., is_byok_only: bool # Whether OpenRouter's shared endpoints on this provider are removed for every model, including models outside `allowed_models` and after all of your keys for the provider fail. The provider is skipped instead of spending OpenRouter credits. Only valid on non-fallback credentials. Omit to leave the stored value unchanged., is_fallback: bool # Whether this credential is treated as a fallback — used only after non-fallback keys for the same provider have been tried. Cannot be combined with `is_byok_only`. Omit to leave the stored value unchanged., is_required: bool # Whether OpenRouter's shared endpoints on this provider are removed for the models this credential applies to (its `allowed_models`, or every model when `null`). Requests for those models run only on your keys; models outside the allowlist may still fall back to shared capacity on this provider. Omit to leave the stored value unchanged., key: str # A new raw provider API key to rotate the credential in-place. The previous key material is overwritten and the masked label is regenerated. Encrypted at rest and never returned in API responses., name: str # Optional human-readable name for the credential.}\n@returns(200) {data: any} # BYOK credential updated successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n@example_request {\"disabled\":false,\"name\":\"Updated OpenAI Key\"}\n\n@endgroup\n\n@group chat\n@endpoint POST /chat/completions\n@desc Create a chat completion\n@required {messages: [any] # List of messages for the conversation}\n@optional {X-OpenRouter-Metadata: str # Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility., cache_control: map{ttl: str, type!: str} # Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format., debug: map{echo_upstream_body: bool} # Debug options for inspecting request transformations (streaming only), deferred_tools: map{announce_catalog_changes: bool, cascade_mode: str, hint: str, interface: str, min_deferred_tools: int, profile!: str, protocol!: str, scope: str, search!: any, validation!: str} # Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_changes`, tells the model about it., frequency_penalty: num(double) # Frequency penalty (-2.0 to 2.0), image_config: map # 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., logit_bias: map # Token logit bias adjustments, logprobs: bool # Return log probabilities, max_completion_tokens: int # Maximum tokens in completion, max_tokens: int # Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16., metadata: map # Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values), min_p: num(double) # Minimum probability threshold relative to the most likely token. Tokens with probability below min_p * (probability of top token) are filtered out. Not all providers support this parameter., modalities: [str] # Output modalities for the response. Supported values are \"text\", \"image\", and \"audio\"., model: str # Model to use for completion, models: [any] # Models to use for completion, parallel_tool_calls: bool # Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response., plugins: [any] # Plugins you want to enable for this request, including their settings., prediction: map{content!: any, type!: str} # Static predicted output content. Supported models can use this to reduce latency when much of the response is known in advance., presence_penalty: num(double) # Presence penalty (-2.0 to 2.0), prompt_cache_key: str, prompt_cache_options: map{mode!: str, ttl: str} # Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. `ttl` sets the minimum cache lifetime for every breakpoint the request writes: \"30m\" (default) or \"12h\" (billed at the higher 12h cache-write rate). Only supported by OpenAI GPT-5.6 and newer., provider: map{allow_fallbacks: bool, data_collection: str, enforce_distillable_text: bool, ignore: [any], max_price: map, only: [any], options: map, order: [any], preferred_max_latency: any, preferred_min_throughput: any, quantizations: [str], require_parameters: bool, sort: any, zdr: bool} # When multiple model providers are available, optionally indicate your routing preference., reasoning: map{context: str, effort: str, enabled: bool, exclude: bool, max_tokens: int, mode: str, summary: str} # Configuration options for reasoning models, reasoning_effort: str(max/xhigh/high/medium/low/minimal/none) # Shorthand for setting reasoning effort. Equivalent to setting reasoning.effort. Cannot be used simultaneously with reasoning.effort if they differ., repetition_penalty: num(double) # Penalizes tokens based on how much they have already appeared in the text. A value of 1.0 means no penalty. Values above 1.0 penalize repeated tokens more strongly. Not all providers support this parameter., response_format: any # Response format configuration, route: str(fallback/sort) # **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: \"fallback\" (maps to \"model\"), \"sort\" (maps to \"none\")., seed: int # Random seed for deterministic outputs, service_tier: str(auto/default/fast/flex/priority/scale/ultrafast) # The service tier to use for processing this request. `fast` is accepted as an alias for `priority`. `ultrafast` prefers ultrafast endpoints and falls back to `priority`, then default endpoints., session_id: str # 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: any # Stop sequences (up to 4), stop_server_tools_when: [any] # Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call., stream: bool=false # Enable streaming response, stream_options: map{include_usage: bool} # Streaming configuration options, temperature: num(double) # Sampling temperature (0-2), tool_choice: any # Tool choice configuration, tools: [any] # Available tools for function calling, top_a: num(double) # Consider only tokens with \"sufficiently high\" probabilities based on the probability of the most likely token. Not all providers support this parameter., top_k: int # Limits the model to choose from the top K most likely tokens at each step. A value of 1 means the model will always pick the most likely next token. Not all providers support this parameter., top_logprobs: int # Number of top log probabilities to return (0-20), top_p: num(double) # Nucleus sampling parameter (0-1), trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # Per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account.}\n@returns(200) {alignment: map{calls: [any]}, choices: [map], created: int, id: str, model: str, object: str, openrouter_metadata: map{attempt: int, attempts: [map], endpoints: map{available: [map], total: int}, generation_time: int, is_byok: bool, params: map{quality_floor: num(double), throughput_floor: num(double), version_group: str}, pipeline: [map], region: str?, requested: str, strategy: str, summary: str}, safeguard_results: [map], service_tier: str?, system_fingerprint: str?, usage: map{completion_tokens: int, completion_tokens_details: map?, cost: num(double)?, cost_details: map?, deferred_tools_details: map{completion_tokens: int, prompt_tokens: int, total_tokens: int, turns: int}, is_byok: bool, prompt_tokens: int, prompt_tokens_details: map?, server_tool_use_details: map?, total_tokens: int}} # Successful chat completion response\n@errors {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}\n@example_request {\"max_tokens\":150,\"messages\":[{\"content\":\"You are a helpful assistant.\",\"role\":\"system\"},{\"content\":\"What is the capital of France?\",\"role\":\"user\"}],\"model\":\"openai/gpt-4\",\"temperature\":0.7}\n\n@endgroup\n\n@group classifications\n@endpoint GET /classifications/task\n@desc Task classification market share\n@optional {window: str=7d # Trailing time window for the classification data. Currently only `7d` (trailing 7 days) is supported.}\n@returns(200) {data: map{as_of: str, classifications: [map], macro_categories: [map], window_days: int}} # Task classification market-share data for the requested trailing window.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group containers\n@endpoint GET /containers/{container_id}/files\n@desc List container files\n@required {container_id: str # The canonical container id, exactly as returned in a bash/shell tool result — a restarted session has its own `-r`-suffixed id. A session-derived id is always `sess_` + the sanitized session key, which is not necessarily the raw session id that was sent.}\n@optional {limit: int=100 # Maximum number of files to return (1-1000). Defaults to 100 when absent., after: str # Forward cursor: the previous page’s `last_id` (or any container file id); listing resumes strictly after that path. A `last_id` from a page that stopped at the scan bound may name a directory-marker path (trailing `/`) that was never listed as a file; such cursors are accepted.}\n@returns(200) {data: [map], first_id: str?, has_more: bool, last_id: str?, object: str} # The files in the container.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint GET /containers/{container_id}/files/{file_id}\n@desc Retrieve a container file\n@required {container_id: str # The canonical container id, exactly as returned in a bash/shell tool result — a restarted session has its own `-r`-suffixed id. A session-derived id is always `sess_` + the sanitized session key, which is not necessarily the raw session id that was sent., file_id: str # Container file id (`cfile_` + base64url of the file path).}\n@returns(200) {bytes: int, container_id: str, created_at: int, id: str, object: str, path: str, source: str} # The container file.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint GET /containers/{container_id}/files/{file_id}/content\n@desc Download container file content\n@required {container_id: str # The canonical container id, exactly as returned in a bash/shell tool result — a restarted session has its own `-r`-suffixed id. A session-derived id is always `sess_` + the sanitized session key, which is not necessarily the raw session id that was sent., file_id: str # Container file id (`cfile_` + base64url of the file path).}\n@returns(200) The raw file content.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint POST /containers/{container_id}/files/{file_id}/promote\n@desc Promote a container file into workspace documents\n@required {container_id: str # The canonical container id, exactly as returned in a bash/shell tool result — a restarted session has its own `-r`-suffixed id. A session-derived id is always `sess_` + the sanitized session key, which is not necessarily the raw session id that was sent., file_id: str # Container file id (`cfile_` + base64url of the file path).}\n@returns(200) The promoted file, as a workspace document.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 429: Too Many Requests - Rate limit exceeded, 499: Client Closed Request - The caller cancelled the request, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endgroup\n\n@group credits\n@endpoint GET /credits\n@desc Get remaining credits\n@returns(200) {data: map{total_credits: num(double), total_usage: num(double)}} # Returns the total credits purchased and used\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /credits/coinbase\n@desc Deprecated Coinbase Commerce charge endpoint\n@returns(200) This endpoint is deprecated and will never return a 200 response.\n@errors {410: Gone - Endpoint has been permanently removed or deprecated}\n\n@endpoint GET /credits/purchases\n@desc Agent setup guide, served at the purchases collection\n@returns(200) Markdown document, readable without a key.\n\n@endpoint POST /credits/purchases\n@desc Buy credits with a machine payment\n@required {idempotency-key: str # Identifies the purchase. Send the same value on the unpaid request and on the paid retry; use a new value for a new purchase., credit_amount_usd: str # Credits to buy, in USD with at most two decimals. The platform fee is added on top and shown in the challenge and the receipt.}\n@returns(202) {data: map{created_at: str, credit_amount_usd: str, failure_reason: str?, id: str, network: str, platform_fee_usd: str, protocol: str, status: str, total_charged_usd: str}} # Payment accepted; credits are minted when the PaymentIntent succeeds.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment required. An unpaid request carries the MPP challenge in `WWW-Authenticate`, and a `Link: rel=\"help\"` header plus a `setup` field pointing at the agent setup guide, `GET /api/v1/credits/purchases/setup`., 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Temporarily unavailable, or the outcome of a paid request is unknown. When the outcome is unknown and the purchase is known, `Location` and `error.metadata.purchase_id` name the purchase: poll it before paying again.}\n\n@endpoint GET /credits/purchases/{id}\n@desc Get a credit purchase\n@required {id: str}\n@returns(200) {data: map{created_at: str, credit_amount_usd: str, failure_reason: str?, id: str, network: str, platform_fee_usd: str, protocol: str, status: str, total_charged_usd: str}} # The purchase.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint GET /credits/purchases/setup\n@desc Agent setup guide for buying credits with a machine payment\n@returns(200) Markdown document, readable without a key.\n\n@endpoint GET /credits/purchases/SKILL.md\n@desc Agent skill for buying OpenRouter credits\n@returns(200) Markdown document, readable without a key.\n\n@endgroup\n\n@group datasets\n@endpoint GET /datasets/app-rankings\n@desc Top apps by token usage\n@optional {category: str(coding/creative/productivity/entertainment) # Marketplace category group to filter by (e.g. `coding`). Only apps tagged with a subcategory inside this group are returned. Mutually combinable with `subcategory` — when both are supplied the `subcategory` must belong to the `category` group., subcategory: str(cli-agent/ide-extension/cloud-agent/programming-app/native-app-builder/creative-writing/video-gen/image-gen/audio-gen/roleplay/game/writing-assistant/general-chat/personal-agent/legal) # Marketplace subcategory to filter by (e.g. `cli-agent`). Takes precedence over `category` for the actual filter; when `category` is also supplied the pair must be consistent., sort: str(popular/trending)=popular # `popular` ranks apps by total token volume inside the date window. `trending` ranks apps by absolute excess token growth: window volume minus the average volume of the three equal-length periods immediately preceding the window. Apps with no excess growth are omitted from `trending` results., start_date: str # Start of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to 30 days before `end_date`. The dataset begins at 2025-01-01; earlier values are clamped forward to that floor and the resolved value is echoed in `meta.start_date`., end_date: str # End of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to the most recent completed UTC day. Must be on or after 2025-01-01; earlier values are rejected with a 400., limit: int=50 # Maximum number of apps to return (1-100). Defaults to 50., offset: int=0 # Number of ranked apps to skip before the first returned row (0-100). Defaults to 0. `rank` stays absolute, so the first row of `offset=50` is `rank: 51`.}\n@returns(200) {data: [map], meta: map{as_of: str, end_date: str, start_date: str, version: str}} # Apps ranked per the requested `sort`, re-numbered 1..N. `popular` sorts by `total_tokens` descending; `trending` sorts by absolute excess token growth descending and may return fewer than `limit` rows.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /datasets/rankings-daily\n@desc Daily token totals for top 50 models\n@optional {start_date: str # Start of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to 30 days before `end_date`. The dataset begins at 2025-01-01; earlier values are clamped forward to that floor and the resolved value is echoed in `meta.start_date`., end_date: str # End of the date window in YYYY-MM-DD (UTC), inclusive. Defaults to the most recent completed UTC day. Must be on or after 2025-01-01; earlier values are rejected with a 400., period: str(day/week/month) # Time grain of each row. `day` (default) returns the per-UTC-day series; `week` buckets by ISO week start; `month` buckets by month start. With `category` or `language_type` only `week` (default) and `month` are available — `day` is rejected with a 400 because those datasets are aggregated weekly. For those sampled datasets `period=month` buckets each week by its week-start month, so totals are approximate at month boundaries., modality: str(text/image/image_output/audio/tool_calling) # Restrict to models for a modality surface: `text` / `image_output` match output modality, `image` / `audio` match input modality, and `tool_calling` keeps only rows that recorded at least one tool call. Exact dataset — cannot be combined with `category` or `language_type`., context_bucket: str(1K/10K/100K/1M/10M) # Restrict to requests whose context length falls in this bucket (`1K`, `10K`, `100K`, `1M`, or `10M`). Exact dataset — cannot be combined with `category` or `language_type`., category: str(programming/roleplay/marketing/marketing/seo/technology/science/translation/legal/finance/health/trivia/academia) # Restrict to a use-case category (e.g. `programming`, `roleplay`). Sourced from a sampled, upsampled dataset, so `total_tokens` is an estimate and is aggregated weekly (the trailing weekly bucket may include traffic past `end_date`). Cannot be combined with `modality`, `context_bucket`, or `language_type`., language_type: str(natural/programming) # Restrict to natural-language or programming-language tagged activity. Sourced from a sampled, upsampled dataset, so `total_tokens` is an estimate and is aggregated weekly (the trailing weekly bucket may include traffic past `end_date`). Cannot be combined with `modality`, `context_bucket`, or `category`.}\n@returns(200) {data: [map], meta: map{as_of: str, end_date: str, start_date: str, version: str}} # Up to 51 rows per day — the top 50 public models by `total_tokens` plus a single aggregated `other` row covering every model outside that top 50. Sorted by `date` ascending, then by `total_tokens` descending, with `other` pinned last within its date.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /datasets/session-cost\n@desc Cost per session by harness and model\n@optional {app_slug: str # Filter to one published harness slug., model: str # Exact model permaslug filter. Works across all harness apps., turn_range: str(1-turn/2-9-turns/10-49-turns/50-plus-turns) # Filter by the inclusive number of turns in a session., limit: int=100 # Maximum number of cells to return (1-500). Defaults to 100., offset: int=0 # Number of sorted cells to skip (0-5000). Defaults to 0.}\n@returns(200) {data: [map], meta: map{as_of: str, version: str, window_days: int?, window_end_date: str?}} # Aggregated cost-per-session cells for the requested filters.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group embeddings\n@endpoint POST /embeddings\n@desc Submit an embedding request\n@required {input: any # Text, token, or multimodal input(s) to embed, model: str # The model to use for embeddings}\n@optional {dimensions: int # The number of dimensions for the output embeddings, encoding_format: str(float/base64) # The format of the output embeddings, input_type: str # The type of input (e.g. search_query, search_document). Document-chunk input (`string[][]`) is only valid with a document input type., provider: any, session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # A unique identifier for the end-user}\n@returns(200) {data: [map], id: str, model: str, object: str, usage: map{cost: num(double), cost_details: map?, is_byok: bool, prompt_tokens: int, prompt_tokens_details: map{audio_tokens: int, file_tokens: int, image_tokens: int, text_tokens: int, video_tokens: int}, total_tokens: int}} # Embedding response\n@errors {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, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 413: Payload Too Large - Request payload exceeds size limits, 429: Too Many Requests - Rate limit exceeded, 499: Client Closed Request - The caller cancelled the request, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 503: Service Unavailable - Service temporarily unavailable, 504: Gateway Timeout - Provider did not respond before the upstream deadline, 524: Infrastructure Timeout - Provider request timed out at edge network, 529: Provider Overloaded - Provider is temporarily overloaded}\n\n@endpoint GET /embeddings/models\n@desc List all embeddings models\n@optional {offset: int=0 # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int=500 # Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned}\n@returns(200) {data: [map], links: map{next: str?}, total_count: int} # Returns a list of embeddings models\n@errors {400: Bad Request - Invalid request parameters or malformed input, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group endpoints\n@endpoint GET /endpoints/zdr\n@desc Preview the impact of ZDR on the available endpoints\n@returns(200) {data: [any]} # Returns a list of endpoints\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endgroup\n\n@group external-users\n@endpoint GET /external-users\n@desc List registered external users\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), user: str # Immutable case-sensitive tracking string supplied as user on inference requests or as external.user on API keys: 1 to 512 characters, well-formed Unicode, no NUL, no surrounding whitespace. URL-encode it in resource paths; an ID of `.` or `..` cannot be addressed by path, so look it up with the list filter., include_inactive: bool=false # Include deactivated registrations.}\n@returns(200) {data: [map], total_count: int} # Matching registrations and their total count.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /external-users\n@desc Register an external user\n@required {user: str # Immutable case-sensitive tracking string supplied as user on inference requests or as external.user on API keys: 1 to 512 characters, well-formed Unicode, no NUL, no surrounding whitespace. URL-encode it in resource paths; an ID of `.` or `..` cannot be addressed by path, so look it up with the list filter.}\n@returns(201) {data: map{created_at: str(date-time), is_active: bool, updated_at: str(date-time), user: str}} # The registered external user. No generated public identifier is returned.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 404: Not Found - Resource does not exist, 409: The tracking ID is already registered in this organization, active or not., 500: Internal Server Error - Unexpected server error}\n@example_request {\"user\":\"employee_123\"}\n\n@endpoint DELETE /external-users/{user}\n@desc Deactivate a registered external user\n@required {user: str # Immutable case-sensitive tracking string supplied as user on inference requests or as external.user on API keys: 1 to 512 characters, well-formed Unicode, no NUL, no surrounding whitespace. URL-encode it in resource paths; an ID of `.` or `..` cannot be addressed by path, so look it up with the list filter.}\n@returns(204) Registration is inactive.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /external-users/{user}\n@desc Get a registered external user\n@required {user: str # Immutable case-sensitive tracking string supplied as user on inference requests or as external.user on API keys: 1 to 512 characters, well-formed Unicode, no NUL, no surrounding whitespace. URL-encode it in resource paths; an ID of `.` or `..` cannot be addressed by path, so look it up with the list filter.}\n@returns(200) {data: map{created_at: str(date-time), is_active: bool, updated_at: str(date-time), user: str}} # The registered external user. No generated public identifier is returned.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /external-users/{user}\n@desc Update a registered external user\n@required {user: str # Immutable case-sensitive tracking string supplied as user on inference requests or as external.user on API keys: 1 to 512 characters, well-formed Unicode, no NUL, no surrounding whitespace. URL-encode it in resource paths; an ID of `.` or `..` cannot be addressed by path, so look it up with the list filter., is_active: bool # Registration state only; does not enforce inference access.}\n@returns(200) {data: map{created_at: str(date-time), is_active: bool, updated_at: str(date-time), user: str}} # The registered external user. No generated public identifier is returned.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"is_active\":true}\n\n@endgroup\n\n@group files\n@endpoint GET /files\n@desc List files\n@optional {limit: int # Maximum number of files to return (1–1000)., cursor: str # Opaque pagination cursor from a previous response., workspace_id: str(uuid) # Workspace to scope the request to. Defaults to the caller’s default workspace., provider: str # Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage., after: str # OpenAI-style forward cursor: the id to list after., after_id: str # Anthropic-style forward cursor: the id to list after., before_id: str # Anthropic-style reverse cursor. Not supported by OpenRouter storage., order: str(asc/desc) # Sort direction. Only `asc` is supported by OpenRouter storage.}\n@returns(200) A page of files.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 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}\n\n@endpoint POST /files\n@desc Upload a file\n@optional {workspace_id: str(uuid) # Workspace to scope the request to. Defaults to the caller’s default workspace., provider: str # Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.}\n@returns(200) The uploaded file metadata.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 413: Payload Too Large - Request payload exceeds size limits, 429: Too Many Requests - Rate limit exceeded, 499: Client Closed Request - The caller cancelled the request, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint DELETE /files/{file_id}\n@desc Delete a file\n@required {file_id: str}\n@optional {workspace_id: str(uuid) # Workspace to scope the request to. Defaults to the caller’s default workspace., provider: str # Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.}\n@returns(200) The file was deleted.\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 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}\n\n@endpoint GET /files/{file_id}\n@desc Get file metadata\n@required {file_id: str}\n@optional {workspace_id: str(uuid) # Workspace to scope the request to. Defaults to the caller’s default workspace., provider: str # Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.}\n@returns(200) The file metadata.\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 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}\n\n@endpoint GET /files/{file_id}/content\n@desc Download file content\n@required {file_id: str}\n@optional {workspace_id: str(uuid) # Workspace to scope the request to. Defaults to the caller’s default workspace., provider: str # Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.}\n@returns(200) The raw file content.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 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}\n\n@endgroup\n\n@group generation\n@endpoint GET /generation\n@desc Get request & usage metadata for a generation\n@required {id: str # The generation ID}\n@returns(200) {data: map{api_type: str?, app_id: int?, cache_discount: num(double)?, cancelled: bool?, created_at: str, data_region: str, external_user: str?, finish_reason: str?, generation_time: num(double)?, http_referer: str?, id: str, is_byok: bool, latency: num(double)?, model: str, moderation_latency: num(double)?, native_finish_reason: str?, native_tokens_cached: int?, native_tokens_completion: int?, native_tokens_completion_images: int?, native_tokens_prompt: int?, native_tokens_reasoning: int?, num_fetches: int?, num_input_audio_prompt: int?, num_media_completion: int?, num_media_prompt: int?, num_search_results: int?, origin: str, preset_id: str?, provider_name: str?, provider_responses: [map]?, request_id: str?, response_cache_source_id: str?, router: str?, service_tier: str?, session_id: str?, streamed: bool?, tokens_completion: int?, tokens_prompt: int?, total_cost: num(double), upstream_id: str?, upstream_inference_cost: num(double)?, usage: num(double), user_agent: str?, web_search_engine: str?, workspace_id: str?}} # Returns the request metadata for this generation\n@errors {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 - The management key does not have permission for this request, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 524: Infrastructure Timeout - Provider request timed out at edge network, 529: Provider Overloaded - Provider is temporarily overloaded}\n\n@endpoint GET /generation/content\n@desc Get stored prompt, completion, and error content for a generation\n@required {id: str # The generation ID}\n@returns(200) {data: map{error: map?, input: any, output: map{completion: str?, reasoning: str?}}} # Returns the stored prompt and completion content, plus the failure error when the generation failed\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 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}\n\n@endpoint POST /generation/feedback\n@desc Submit feedback for a generation\n@required {category: str(latency/incoherence/incorrect_response/formatting/billing/api_error/other) # The category of feedback being reported, generation_id: str # The generation to submit feedback on}\n@optional {comment: str # An optional free-text comment describing the feedback}\n@returns(200) {data: map{success: bool}} # Feedback recorded successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Feedback was already submitted for this generation by this account. The first submission is kept., 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n@example_request {\"category\":\"incorrect_response\",\"comment\":\"The model repeated the same paragraph three times.\",\"generation_id\":\"gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG\"}\n\n@endgroup\n\n@group guardrails\n@endpoint GET /guardrails\n@desc List guardrails\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), workspace_id: str(uuid) # Filter guardrails by workspace ID. When omitted, an organization management key gets guardrails in the default workspace and a workspace-scoped key gets guardrails in its own workspace. A workspace-scoped key gets 403 for any other workspace.}\n@returns(200) {data: [map], total_count: int} # List of guardrails\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /guardrails\n@desc Create a guardrail\n@required {name: str # Name for the new guardrail}\n@optional {allow_safety_retention_google: bool # Whether ZDR-only requests to google/* models may also use Safety Retention endpoints, which may retain prompts and responses from any request, only to prevent abuse, and do not use them for training. false allows only ZDR endpoints. A guardrail can only be more restrictive than the account setting. Inherits the account setting when not provided., allow_safety_retention_other: bool # Whether ZDR-only requests to models outside the named providers (for example open-weight models on Vertex) may also use Safety Retention endpoints, which may retain prompts and responses from any request, only to prevent abuse, and do not use them for training. false allows only ZDR endpoints. A guardrail can only be more restrictive than the account setting. Inherits the account setting when not provided., allowed_data_regions: [str] # Data regions through which requests governed by this guardrail must arrive. `global` is https://openrouter.ai, `europe` is https://eu.openrouter.ai, and `us` is https://us.openrouter.ai. Requests arriving through any other region are rejected. `null` leaves the ingress region unrestricted. When several guardrails apply (workspace default, member, API key), the effective regions are the intersection of every non-null value. An empty array is rejected., allowed_models: [str] # Array of model identifiers (slug or canonical_slug accepted), allowed_providers: [str] # List of allowed provider IDs, content_filter_builtins: [map{action!: str, label: str, scan_scope: str, slug!: str}] # Builtin content filters to apply. Every builtin slug supports \"block\", \"redact\", and the detect-only \"flag\" action., content_filters: [map{action!: str, label: str, pattern!: str}] # Custom regex content filters to apply to request messages, description: str # Description of the guardrail, enable_free_model_publication: bool # Whether this guardrail allows free endpoints that publish prompts., enable_free_model_training: bool # Whether this guardrail allows free endpoints that train on request data., enable_paid_model_training: bool # Whether this guardrail allows paid endpoints that train on request data., enforce_first_party_harness_models: bool # Whether coding harnesses list only their vendor's own models: Codex lists OpenAI models and Claude Code and Claude Desktop list Anthropic models. Affects only the model list those harnesses request from GET /models; a model the client names directly is still routed. Any true across the workspace default, member, and API key guardrails applies., enforce_zdr: bool # Deprecated. Use enforce_zdr_anthropic, enforce_zdr_openai, enforce_zdr_google, enforce_zdr_xai, and enforce_zdr_other instead. When provided, its value is copied into any of those per-provider fields that are not explicitly specified on the request., enforce_zdr_anthropic: bool # Whether to enforce zero data retention for Anthropic models. Falls back to enforce_zdr when not provided., enforce_zdr_google: bool # Whether to enforce zero data retention for Google models. Falls back to enforce_zdr when not provided., enforce_zdr_openai: bool # Whether to enforce zero data retention for OpenAI models. Falls back to enforce_zdr when not provided., enforce_zdr_other: bool # Whether to enforce zero data retention for models that are not from Anthropic, OpenAI, Google, or xAI. Falls back to enforce_zdr when not provided., enforce_zdr_xai: bool # Whether to enforce zero data retention for xAI models. Falls back to enforce_zdr when not provided., ignored_models: [str] # Array of model identifiers to exclude from routing (slug or canonical_slug accepted), ignored_providers: [str] # List of provider IDs to exclude from routing, include_byok_in_budgets: bool # Whether BYOK (bring-your-own-key) inference spend counts toward this guardrail's limit_usd, in addition to OpenRouter credit spend. Defaults to false., limit_usd: num(double) # Spending limit in USD. Must be provided together with `reset_interval`: a request that sets only one of the two is rejected with a 400., reset_interval: str(daily/weekly/monthly) # Interval at which the limit resets (daily, weekly, monthly), workspace_id: str(uuid) # The workspace to create the guardrail in. When omitted, an organization management key creates the guardrail in the default workspace (a 400 if that default has been deleted, so pass `workspace_id` explicitly) and a workspace-scoped key creates it in its own workspace. A workspace-scoped key gets a 403 for any other workspace. This only places the guardrail in the workspace; the created guardrail enforces nothing for that workspace's traffic until it is assigned to API keys or members. To restrict all traffic in a workspace, update the workspace's default guardrail instead.}\n@returns(201) {data: any} # Guardrail created successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: The management key does not have permission for this request, the workspace is not owned by this account, or the workspace does not allow a person-name or address sensitive-info filter., 500: Internal Server Error - Unexpected server error}\n@example_request {\"allowed_data_regions\":[\"europe\"],\"allowed_models\":null,\"allowed_providers\":[\"openai\",\"anthropic\",\"deepseek\"],\"description\":\"A guardrail for limiting API usage\",\"enforce_zdr_anthropic\":true,\"enforce_zdr_google\":false,\"enforce_zdr_openai\":true,\"enforce_zdr_other\":false,\"enforce_zdr_xai\":false,\"ignored_models\":null,\"ignored_providers\":null,\"limit_usd\":50,\"name\":\"My New Guardrail\",\"reset_interval\":\"monthly\"}\n\n@endpoint DELETE /guardrails/{id}\n@desc Delete a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail to delete}\n@returns(200) {deleted: bool} # Guardrail deleted successfully\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/{id}\n@desc Get a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail to retrieve}\n@returns(200) {data: any} # Guardrail details\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Guardrail not found, or the workspace default guardrail has not been configured yet., 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /guardrails/{id}\n@desc Update a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail to update}\n@optional {allow_safety_retention_google: bool # Whether ZDR-only requests to google/* models may also use Safety Retention endpoints, which may retain prompts and responses from any request, only to prevent abuse, and do not use them for training. false allows only ZDR endpoints. A guardrail can only be more restrictive than the account setting. Inherits the account setting when not provided., allow_safety_retention_other: bool # Whether ZDR-only requests to models outside the named providers (for example open-weight models on Vertex) may also use Safety Retention endpoints, which may retain prompts and responses from any request, only to prevent abuse, and do not use them for training. false allows only ZDR endpoints. A guardrail can only be more restrictive than the account setting. Inherits the account setting when not provided., allowed_data_regions: [str] # Data regions through which requests governed by this guardrail must arrive. `global` is https://openrouter.ai, `europe` is https://eu.openrouter.ai, and `us` is https://us.openrouter.ai. Requests arriving through any other region are rejected. `null` leaves the ingress region unrestricted. When several guardrails apply (workspace default, member, API key), the effective regions are the intersection of every non-null value. An empty array is rejected., allowed_models: [str] # Array of model identifiers (slug or canonical_slug accepted), allowed_providers: [str] # New list of allowed provider IDs, content_filter_builtins: [map{action!: str, label: str, scan_scope: str, slug!: str}] # Builtin content filters to apply. Set to null to remove. Every builtin slug supports \"block\", \"redact\", and the detect-only \"flag\" action., content_filters: [map{action!: str, label: str, pattern!: str}] # Custom regex content filters to apply. Set to null to remove., description: str # New description for the guardrail, enable_free_model_publication: bool # Whether this guardrail allows free endpoints that publish prompts., enable_free_model_training: bool # Whether this guardrail allows free endpoints that train on request data., enable_paid_model_training: bool # Whether this guardrail allows paid endpoints that train on request data., enforce_first_party_harness_models: bool # Whether coding harnesses list only their vendor's own models: Codex lists OpenAI models and Claude Code and Claude Desktop list Anthropic models. Affects only the model list those harnesses request from GET /models; a model the client names directly is still routed. Any true across the workspace default, member, and API key guardrails applies., enforce_zdr: bool # Deprecated. Use enforce_zdr_anthropic, enforce_zdr_openai, enforce_zdr_google, enforce_zdr_xai, and enforce_zdr_other instead. When provided, its value is copied into any of those per-provider fields that are not explicitly specified on the request., enforce_zdr_anthropic: bool # Whether to enforce zero data retention for Anthropic models. Falls back to enforce_zdr when not provided., enforce_zdr_google: bool # Whether to enforce zero data retention for Google models. Falls back to enforce_zdr when not provided., enforce_zdr_openai: bool # Whether to enforce zero data retention for OpenAI models. Falls back to enforce_zdr when not provided., enforce_zdr_other: bool # Whether to enforce zero data retention for models that are not from Anthropic, OpenAI, Google, or xAI. Falls back to enforce_zdr when not provided., enforce_zdr_xai: bool # Whether to enforce zero data retention for xAI models. Falls back to enforce_zdr when not provided., ignored_models: [str] # Array of model identifiers to exclude from routing (slug or canonical_slug accepted), ignored_providers: [str] # List of provider IDs to exclude from routing, include_byok_in_budgets: bool # Whether BYOK (bring-your-own-key) inference spend counts toward this guardrail's limit_usd, in addition to OpenRouter credit spend. Omit to leave unchanged., limit_usd: num(double) # New spending limit in USD, name: str # New name for the guardrail, reset_interval: str(daily/weekly/monthly) # Interval at which the limit resets (daily, weekly, monthly)}\n@returns(200) {data: any} # Guardrail updated successfully\n@errors {400: Invalid request, or an attempt to change a workspace default guardrail's name (which is derived from its workspace and not editable; sending the current name unchanged is accepted)., 401: Unauthorized - Authentication required or invalid credentials, 403: The management key does not have permission for this request, or the update would add a person-name or address sensitive-info filter to a workspace that does not allow it., 404: Not Found - Resource does not exist, 409: Guardrail name conflict — another guardrail in this workspace already uses the requested name., 500: Internal Server Error - Unexpected server error}\n@example_request {\"description\":\"Updated description\",\"limit_usd\":75,\"name\":\"Updated Guardrail Name\",\"reset_interval\":\"weekly\"}\n\n@endpoint GET /guardrails/{id}/assignments/keys\n@desc List key assignments for a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail}\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: int} # List of key assignments\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /guardrails/{id}/assignments/keys\n@desc Bulk assign keys to a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, key_hashes: [str] # Array of API key hashes to assign to the guardrail}\n@returns(200) {assigned_count: int} # Assignment result\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: The management key does not have permission for this request, or the guardrail has no workspace and carries a person-name or address sensitive-info filter, and at least one target key belongs to a workspace that does not allow that filter., 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"key_hashes\":[\"c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93\"]}\n\n@endpoint POST /guardrails/{id}/assignments/keys/remove\n@desc Bulk unassign keys from a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, key_hashes: [str] # Array of API key hashes to unassign from the guardrail}\n@returns(200) {unassigned_count: int} # Unassignment result\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"key_hashes\":[\"c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93\"]}\n\n@endpoint GET /guardrails/{id}/assignments/members\n@desc List member assignments for a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail}\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: int} # List of member assignments\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /guardrails/{id}/assignments/members\n@desc Bulk assign members to a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, member_user_ids: [str] # Array of member user IDs to assign to the guardrail}\n@returns(200) {assigned_count: int} # Assignment result\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"member_user_ids\":[\"user_abc123\",\"user_def456\"]}\n\n@endpoint POST /guardrails/{id}/assignments/members/remove\n@desc Bulk unassign members from a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, member_user_ids: [str] # Array of member user IDs to unassign from the guardrail}\n@returns(200) {unassigned_count: int} # Unassignment result\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"member_user_ids\":[\"user_abc123\",\"user_def456\"]}\n\n@endpoint GET /guardrails/assignments/keys\n@desc List all key assignments\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), workspace_id: str(uuid) # Only list assignments of guardrails in this workspace. When omitted, an organization management key lists every workspace and a workspace-scoped key lists its own workspace. A workspace-scoped key gets 403 for any other workspace.}\n@returns(200) {data: [map], total_count: int} # List of key assignments\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/assignments/members\n@desc List all member assignments\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), workspace_id: str(uuid) # Only list assignments of guardrails in this workspace. When omitted, an organization management key lists every workspace and a workspace-scoped key lists its own workspace. A workspace-scoped key gets 403 for any other workspace.}\n@returns(200) {data: [map], total_count: int} # List of member assignments\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/account\n@desc List workspace-wide policies\n@optional {offset: int # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int # Maximum number of records to return (max 100). When both offset and limit are omitted, the full list is returned}\n@returns(200) {data: [any], total_count: int} # List of workspace-wide policies\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /guardrails/policies/account\n@desc Create a workspace-wide policy\n@returns(201) {data: any} # Workspace-wide policy created\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint DELETE /guardrails/policies/account/{id}\n@desc Delete a workspace-wide policy\n@required {id: str(uuid) # Policy ID}\n@returns(200) {data: bool} # Workspace-wide policy deleted\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PUT /guardrails/policies/account/{id}\n@desc Update a workspace-wide policy\n@required {id: str(uuid) # Policy ID}\n@returns(200) {data: any} # Workspace-wide policy updated\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/assignments/api-keys/{hash}\n@desc Get an API key policy assignment\n@required {hash: str # API key hash, policy_type: str(budget/model_availability/moderation/rate_limit) # Policy type the assignment is read or changed for}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{opted_out: bool, policy_ids: [str(uuid)], workspace_default_policy_ids: [str(uuid)]}} # Assignment state\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PUT /guardrails/policies/assignments/api-keys/{hash}\n@desc Change an API key policy assignment\n@required {hash: str # API key hash, assigned: bool # `true` assigns the policy to the subject, `false` removes it, expected_assignment: any, policy_id: str(uuid) # Policy ID, policy_type: str(budget/model_availability/moderation/rate_limit) # Policy type the assignment is read or changed for}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: bool} # Assignment changed\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/assignments/members/{member_id}\n@desc Get a member policy assignment\n@required {member_id: str # Organization member user ID, policy_type: str(budget/model_availability/moderation/rate_limit) # Policy type the assignment is read or changed for}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{opted_out: bool, policy_ids: [str(uuid)], workspace_default_policy_ids: [str(uuid)]}} # Assignment state\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PUT /guardrails/policies/assignments/members/{member_id}\n@desc Change a member policy assignment\n@required {member_id: str # Organization member user ID, assigned: bool # `true` assigns the policy to the subject, `false` removes it, expected_assignment: any, policy_id: str(uuid) # Policy ID, policy_type: str(budget/model_availability/moderation/rate_limit) # Policy type the assignment is read or changed for}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: bool} # Assignment changed\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/budget\n@desc List budget policies\n@optional {offset: int # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int # Maximum number of records to return (max 100). When both offset and limit are omitted, the full list is returned, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: [map], total_count: int} # List of budget policies\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /guardrails/policies/budget\n@desc Create a budget policy\n@required {config: map{include_byok_in_budgets!: bool, limit_usd!: num, reset_interval!: str}, name: str # Policy name, policy_type: str}\n@optional {api_key_hashes: [str] # API key hashes, is_workspace_default: bool # Make this the workspace default for its policy type. Defaults to `false`., member_ids: [str] # Organization member user IDs, opted_out_api_key_hashes: [str] # API keys that should not inherit the policy when it is the workspace default, opted_out_member_ids: [str] # Members that should not inherit the policy when it is the workspace default, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(201) {data: map{config: map{include_byok_in_budgets: bool, limit_usd: num(double)?, reset_interval: str?}, id: str(uuid), name: str, policy_type: str}} # budget policy created\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint DELETE /guardrails/policies/budget/{id}\n@desc Delete a budget policy\n@required {id: str(uuid) # Policy ID}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: bool} # budget policy deleted\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/budget/{id}\n@desc Get a budget policy\n@required {id: str(uuid) # Policy ID}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{api_key_hashes: [str], config: map{include_byok_in_budgets: bool, limit_usd: num(double)?, reset_interval: str?}, id: str(uuid), is_workspace_default: bool, member_ids: [str], name: str, opted_out_api_key_hashes: [str], opted_out_member_ids: [str], overridden_api_key_hashes: [str], overridden_member_ids: [str], policy_type: str, reference: str?, replaces_legacy_default: bool, updated_at: str?}} # budget policy details\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PUT /guardrails/policies/budget/{id}\n@desc Update a budget policy\n@required {id: str(uuid) # Policy ID, config: map{include_byok_in_budgets!: bool, limit_usd!: num, reset_interval!: str}, name: str # Policy name}\n@optional {api_key_hashes: [str] # Complete new list of assigned API keys. Send together with `member_ids`, or omit both to keep the stored assignments., is_workspace_default: bool # Omit to keep the stored default status; `false` unsets the policy as the workspace default., member_ids: [str] # Complete new list of assigned members. Send together with `api_key_hashes`, or omit both to keep the stored assignments., opted_out_api_key_hashes: [str] # API key hashes, opted_out_member_ids: [str] # Organization member user IDs, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{config: map{include_byok_in_budgets: bool, limit_usd: num(double)?, reset_interval: str?}, id: str(uuid), name: str, policy_type: str}} # budget policy updated\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/model-availability\n@desc List model availability policies\n@optional {offset: int # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int # Maximum number of records to return (max 100). When both offset and limit are omitted, the full list is returned, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: [map], total_count: int} # List of model availability policies\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /guardrails/policies/model-availability\n@desc Create a model availability policy\n@required {config: map{allow_safety_retention_google: bool, allow_safety_retention_other: bool, allowed_data_regions: [str], allowed_models: [str], allowed_providers: [str], enable_free_model_publication: bool, enable_free_model_training: bool, enable_paid_model_training: bool, enforce_first_party_harness_models: bool, enforce_zdr: bool, enforce_zdr_anthropic: bool, enforce_zdr_google: bool, enforce_zdr_openai: bool, enforce_zdr_other: bool, enforce_zdr_xai: bool, ignored_models: [str], ignored_providers: [str], platform_banned_authors: [str], platform_banned_models: [str], platform_banned_providers: [str], require_eu_data_region: bool}, name: str # Policy name, policy_type: str}\n@optional {api_key_hashes: [str] # API key hashes, is_workspace_default: bool # Make this the workspace default for its policy type. Defaults to `false`., member_ids: [str] # Organization member user IDs, opted_out_api_key_hashes: [str] # API keys that should not inherit the policy when it is the workspace default, opted_out_member_ids: [str] # Members that should not inherit the policy when it is the workspace default, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(201) {data: map{config: map{allow_safety_retention_google: bool?, allow_safety_retention_other: bool?, allowed_data_regions: [str]?, allowed_models: [str]?, allowed_providers: [str]?, enable_free_model_publication: bool?, enable_free_model_training: bool?, enable_paid_model_training: bool?, enforce_first_party_harness_models: bool?, enforce_zdr: bool?, enforce_zdr_anthropic: bool?, enforce_zdr_google: bool?, enforce_zdr_openai: bool?, enforce_zdr_other: bool?, enforce_zdr_xai: bool?, ignored_models: [str]?, ignored_providers: [str]?, platform_banned_authors: [str]?, platform_banned_models: [str]?, platform_banned_providers: [str]?, require_eu_data_region: bool?}, id: str(uuid), name: str, policy_type: str}} # model availability policy created\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint DELETE /guardrails/policies/model-availability/{id}\n@desc Delete a model availability policy\n@required {id: str(uuid) # Policy ID}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: bool} # model availability policy deleted\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/model-availability/{id}\n@desc Get a model availability policy\n@required {id: str(uuid) # Policy ID}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{api_key_hashes: [str], config: map{allow_safety_retention_google: bool?, allow_safety_retention_other: bool?, allowed_data_regions: [str]?, allowed_models: [str]?, allowed_providers: [str]?, enable_free_model_publication: bool?, enable_free_model_training: bool?, enable_paid_model_training: bool?, enforce_first_party_harness_models: bool?, enforce_zdr: bool?, enforce_zdr_anthropic: bool?, enforce_zdr_google: bool?, enforce_zdr_openai: bool?, enforce_zdr_other: bool?, enforce_zdr_xai: bool?, ignored_models: [str]?, ignored_providers: [str]?, platform_banned_authors: [str]?, platform_banned_models: [str]?, platform_banned_providers: [str]?, require_eu_data_region: bool?}, id: str(uuid), is_workspace_default: bool, member_ids: [str], name: str, opted_out_api_key_hashes: [str], opted_out_member_ids: [str], overridden_api_key_hashes: [str], overridden_member_ids: [str], policy_type: str, reference: str?, replaces_legacy_default: bool, updated_at: str?}} # model availability policy details\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PUT /guardrails/policies/model-availability/{id}\n@desc Update a model availability policy\n@required {id: str(uuid) # Policy ID, config: map{allow_safety_retention_google: bool, allow_safety_retention_other: bool, allowed_data_regions: [str], allowed_models: [str], allowed_providers: [str], enable_free_model_publication: bool, enable_free_model_training: bool, enable_paid_model_training: bool, enforce_first_party_harness_models: bool, enforce_zdr: bool, enforce_zdr_anthropic: bool, enforce_zdr_google: bool, enforce_zdr_openai: bool, enforce_zdr_other: bool, enforce_zdr_xai: bool, ignored_models: [str], ignored_providers: [str], platform_banned_authors: [str], platform_banned_models: [str], platform_banned_providers: [str], require_eu_data_region: bool}, name: str # Policy name}\n@optional {api_key_hashes: [str] # Complete new list of assigned API keys. Send together with `member_ids`, or omit both to keep the stored assignments., is_workspace_default: bool # Omit to keep the stored default status; `false` unsets the policy as the workspace default., member_ids: [str] # Complete new list of assigned members. Send together with `api_key_hashes`, or omit both to keep the stored assignments., opted_out_api_key_hashes: [str] # API key hashes, opted_out_member_ids: [str] # Organization member user IDs, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{config: map{allow_safety_retention_google: bool?, allow_safety_retention_other: bool?, allowed_data_regions: [str]?, allowed_models: [str]?, allowed_providers: [str]?, enable_free_model_publication: bool?, enable_free_model_training: bool?, enable_paid_model_training: bool?, enforce_first_party_harness_models: bool?, enforce_zdr: bool?, enforce_zdr_anthropic: bool?, enforce_zdr_google: bool?, enforce_zdr_openai: bool?, enforce_zdr_other: bool?, enforce_zdr_xai: bool?, ignored_models: [str]?, ignored_providers: [str]?, platform_banned_authors: [str]?, platform_banned_models: [str]?, platform_banned_providers: [str]?, require_eu_data_region: bool?}, id: str(uuid), name: str, policy_type: str}} # model availability policy updated\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/moderation\n@desc List moderation policies\n@optional {offset: int # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int # Maximum number of records to return (max 100). When both offset and limit are omitted, the full list is returned, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: [map], total_count: int} # List of moderation policies\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /guardrails/policies/moderation\n@desc Create a moderation policy\n@required {config: map{armor: map, broadcast_model_armor_flagged_requests: bool, content_filter_blocks_requests: bool, content_filter_builtins: [map], content_filter_patterns: [str], content_filters: [map], enable_model_armor_injection_protection: bool, lakera_injection_protection_mode: str, model_armor_injection_confidence_level: str, model_armor_injection_protection_mode: str, pii_filters: [map], platform_image_moderated_providers: [str], platform_moderated_providers: [str]}, name: str # Policy name, policy_type: str}\n@optional {api_key_hashes: [str] # API key hashes, is_workspace_default: bool # Make this the workspace default for its policy type. Defaults to `false`., member_ids: [str] # Organization member user IDs, opted_out_api_key_hashes: [str] # API keys that should not inherit the policy when it is the workspace default, opted_out_member_ids: [str] # Members that should not inherit the policy when it is the workspace default, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(201) {data: map{config: map{armor: map?, broadcast_model_armor_flagged_requests: bool?, content_filter_blocks_requests: bool, content_filter_builtins: [map]?, content_filter_patterns: [str]?, content_filters: [map]?, enable_model_armor_injection_protection: bool?, lakera_injection_protection_mode: str?, model_armor_injection_confidence_level: str, model_armor_injection_protection_mode: str?, pii_filters: [map]?, platform_image_moderated_providers: [str]?, platform_moderated_providers: [str]?}, id: str(uuid), name: str, policy_type: str}} # moderation policy created\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint DELETE /guardrails/policies/moderation/{id}\n@desc Delete a moderation policy\n@required {id: str(uuid) # Policy ID}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: bool} # moderation policy deleted\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /guardrails/policies/moderation/{id}\n@desc Get a moderation policy\n@required {id: str(uuid) # Policy ID}\n@optional {workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{api_key_hashes: [str], config: map{armor: map?, broadcast_model_armor_flagged_requests: bool?, content_filter_blocks_requests: bool, content_filter_builtins: [map]?, content_filter_patterns: [str]?, content_filters: [map]?, enable_model_armor_injection_protection: bool?, lakera_injection_protection_mode: str?, model_armor_injection_confidence_level: str, model_armor_injection_protection_mode: str?, pii_filters: [map]?, platform_image_moderated_providers: [str]?, platform_moderated_providers: [str]?}, id: str(uuid), is_account_policy: bool, is_workspace_default: bool, member_ids: [str], name: str, opted_out_api_key_hashes: [str], opted_out_member_ids: [str], overridden_api_key_hashes: [str], overridden_member_ids: [str], policy_type: str, reference: str?, replaces_legacy_default: bool, updated_at: str?}} # moderation policy details\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PUT /guardrails/policies/moderation/{id}\n@desc Update a moderation policy\n@required {id: str(uuid) # Policy ID, config: map{armor: map, broadcast_model_armor_flagged_requests: bool, content_filter_blocks_requests: bool, content_filter_builtins: [map], content_filter_patterns: [str], content_filters: [map], enable_model_armor_injection_protection: bool, lakera_injection_protection_mode: str, model_armor_injection_confidence_level: str, model_armor_injection_protection_mode: str, pii_filters: [map], platform_image_moderated_providers: [str], platform_moderated_providers: [str]}, name: str # Policy name}\n@optional {api_key_hashes: [str] # Complete new list of assigned API keys. Send together with `member_ids`, or omit both to keep the stored assignments., is_workspace_default: bool # Omit to keep the stored default status; `false` unsets the policy as the workspace default., member_ids: [str] # Complete new list of assigned members. Send together with `api_key_hashes`, or omit both to keep the stored assignments., opted_out_api_key_hashes: [str] # API key hashes, opted_out_member_ids: [str] # Organization member user IDs, workspace_id: str(uuid) # Workspace the policy belongs to. Required for an organization management key; a workspace-scoped key defaults to its own workspace and gets 403 for any other.}\n@returns(200) {data: map{config: map{armor: map?, broadcast_model_armor_flagged_requests: bool?, content_filter_blocks_requests: bool, content_filter_builtins: [map]?, content_filter_patterns: [str]?, content_filters: [map]?, enable_model_armor_injection_protection: bool?, lakera_injection_protection_mode: str?, model_armor_injection_confidence_level: str, model_armor_injection_protection_mode: str?, pii_filters: [map]?, platform_image_moderated_providers: [str]?, platform_moderated_providers: [str]?}, id: str(uuid), name: str, policy_type: str}} # moderation policy updated\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group images\n@endpoint POST /images\n@desc Generate an image\n@required {model: str # The image generation model to use, prompt: str # Text description of the desired image}\n@optional {aspect_ratio: str(1:1/1:2/1:3/1:4/1:8/2:1/2:3/3:1/2.35:1/3:2/3:4/4:1/4:3/4:5/5:2/5:4/5:7/7:5/8:1/9:16/16:9/9:19.5/19.5:9/9:20/20:9/9:21/21:9/auto) # Normalized aspect ratio of the generated image. Providers clamp to their supported subset., background: str(auto/transparent/opaque) # Background treatment. `transparent` requires an output_format that supports alpha (png or webp)., frame_count: int # Number of animation frames (2-64) when `output_format` is `gif`. Only honored by models that produce animations; each accepts its own range and rejects values outside it. Ignored otherwise., frame_duration_ms: int # Display time of each animation frame in milliseconds (20-2000) when `output_format` is `gif`. Ignored by models that do not produce animations., input_references: [map{image_url!: map, type!: str}] # Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs., markup: any # A transparent PNG overlay (arrows, circles, annotations) with the same dimensions as the first reference image, as a base64 data URL or HTTP(S) URL, guiding where an edit applies. Image-to-image requests only; honored by models with markup-guided editing (OpenAI gpt-image-2.6) and ignored otherwise., n: int # Upper bound on the number of images to generate (1-10). Providers may return fewer images, and providers that only support single-image generation reject n > 1., output_compression: int # Compression level (0-100) for jpeg/webp output. Ignored by providers without a compression knob; providers that honor it may reject it with other output formats (e.g. OpenAI requires output_format \"jpeg\" or \"webp\")., output_format: str(png/jpeg/webp/svg/gif) # Encoding of the returned image bytes. Most models produce raster formats (png, jpeg, webp). SVG is supported by vectorization models (e.g. Quiver) — the SVG markup is UTF-8 base64-encoded in `b64_json`. GIF produces an animation on models that support it (OpenAI gpt-image-2.6; see `frame_count`)., provider: map{allow_fallbacks: bool, data_collection: str, ignore: [any], only: [any], options: any, order: [any], sort: any, zdr: bool} # Provider routing preferences and provider-specific passthrough configuration., quality: str(auto/low/medium/high/xhigh/max) # Rendering quality. Providers without a quality knob ignore this., resolution: str(512/768/1K/1.5K/2K/4K) # Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider., seed: int # If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers., session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., size: str # Optional. A convenience shorthand for output dimensions — pass a tier (\"2K\", \"4K\") or explicit pixels (\"2048x2048\"). A tier size is equivalent to setting `resolution` and combines with `aspect_ratio`. Explicit pixel sizes are provider-dependent: providers that accept them treat the value as authoritative and reject a mismatched `resolution` or `aspect_ratio` alongside it with a 400. xAI and Sourceful V2/V2.5 reject explicit pixel sizes (use `resolution` and `aspect_ratio` there); Sourceful V2.6 supports them within its dimension limits and does not allow combining them with `resolution` or `aspect_ratio`., stream: bool # If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # A stable identifier for your end-users. Used to help detect and prevent abuse. Never sent to providers verbatim: for providers whose data policy requires user IDs, it is folded into a hashed, per-account upstream user identifier.}\n@returns(200) {created: int, data: [map], usage: map{cache_creation: map?, completion_tokens: int, completion_tokens_details: map?, cost: num(double)?, cost_details: map?, is_byok: bool, iterations: [any]?, prompt_tokens: int, prompt_tokens_details: map?, server_tool_use: map?, service_tier: str?, speed: str?, total_tokens: int}} # Image generation response\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 524: Infrastructure Timeout - Provider request timed out at edge network, 529: Provider Overloaded - Provider is temporarily overloaded}\n@example_request {\"model\":\"bytedance-seed/seedream-4.5\",\"prompt\":\"a red panda astronaut floating in space, studio lighting\"}\n\n@endpoint GET /images/models\n@desc List image generation models\n@returns(200) {data: [map]} # List of image generation models\n@errors {500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /images/models/{author}/{slug}/endpoints\n@desc List endpoints for an image model\n@required {author: str # Model author/organization, slug: str # Model slug}\n@returns(200) {endpoints: [map], id: str} # The full per-endpoint records for an image model\n@errors {404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group key\n@endpoint GET /key\n@desc Get current API key\n@returns(200) {data: map{allowed_data_regions: [str], budgets: [map], byok_usage: num(double), byok_usage_daily: num(double), byok_usage_monthly: num(double), byok_usage_weekly: num(double), creator_user_id: str?, effective_budget: any, expires_at: str(date-time)?, free_model_daily_requests: map{limit: int, remaining: int, used: int}, include_byok_in_limit: bool, is_free_tier: bool, is_management_key: bool, is_provisioning_key: bool, label: str, limit: num(double)?, limit_remaining: num(double)?, limit_reset: str?, organization_id: str?, rate_limit: map{interval: str, note: str, requests: int}, usage: num(double), usage_daily: num(double), usage_monthly: num(double), usage_weekly: num(double), workspace_id: str?}} # API key details\n@errors {401: Unauthorized - Authentication required or invalid credentials, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group keys\n@endpoint GET /keys\n@desc List API keys\n@optional {include_disabled: bool # Whether to include disabled API keys in the response, include_expired: bool # Whether to include expired API keys in the response. Expired keys are excluded by default and returned only when this is true., offset: int # Number of API keys to skip for pagination, workspace_id: str(uuid) # Filter API keys by workspace ID. By default an organization-scoped management key gets the default workspace; a workspace-scoped management key always gets its own workspace and cannot list another.}\n@returns(200) {data: [map]} # List of API keys\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /keys\n@desc Create a new API key\n@required {name: str # Name for the new API key}\n@optional {creator_user_id: str # Optional user ID of the key creator. Only meaningful for organization-owned keys where a specific member is creating the key. A workspace-scoped management key may only name a member of its own workspace., expires_at: str(date-time) # Optional ISO 8601 UTC expiration timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected., external: map{api_key: str, user!: str} # Optional partner-defined identity associated with the created API key., include_byok_in_limit: bool # Whether to include BYOK usage in the limit, limit: num(double) # Optional spending limit for the API key in USD, limit_reset: str(daily/weekly/monthly) # Type of limit reset for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday., workspace_id: str(uuid) # The workspace to create the API key in. Defaults to the default workspace for an organization-scoped management key, or to the management key's own workspace for a workspace-scoped one, which cannot create keys elsewhere.}\n@returns(201) {data: map{byok_usage: num(double), byok_usage_daily: num(double), byok_usage_monthly: num(double), byok_usage_weekly: num(double), created_at: str, creator_user_id: str?, disabled: bool, expires_at: str(date-time)?, external_user: str?, hash: str, include_byok_in_limit: bool, label: str, last_used_at: str(date-time)?, limit: num(double)?, limit_remaining: num(double)?, limit_reset: str?, name: str, updated_at: str?, usage: num(double), usage_daily: num(double), usage_monthly: num(double), usage_weekly: num(double), workspace_id: str}, key: str} # API key created successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n@example_request {\"expires_at\":\"2027-12-31T23:59:59Z\",\"include_byok_in_limit\":true,\"limit\":50,\"limit_reset\":\"monthly\",\"name\":\"My New API Key\"}\n\n@endpoint DELETE /keys/{hash}\n@desc Delete an API key\n@required {hash: str # The hash identifier of the API key to delete}\n@returns(200) {deleted: bool} # API key deleted successfully\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /keys/{hash}\n@desc Get a single API key\n@required {hash: str # The hash identifier of the API key to retrieve}\n@returns(200) {data: map{byok_usage: num(double), byok_usage_daily: num(double), byok_usage_monthly: num(double), byok_usage_weekly: num(double), created_at: str, creator_user_id: str?, disabled: bool, expires_at: str(date-time)?, external_user: str?, hash: str, include_byok_in_limit: bool, label: str, last_used_at: str(date-time)?, limit: num(double)?, limit_remaining: num(double)?, limit_reset: str?, name: str, updated_at: str?, usage: num(double), usage_daily: num(double), usage_monthly: num(double), usage_weekly: num(double), workspace_id: str}} # API key details\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /keys/{hash}\n@desc Update an API key\n@required {hash: str # The hash identifier of the API key to update}\n@optional {disabled: bool # Whether to disable the API key, include_byok_in_limit: bool # Whether to include BYOK usage in the limit, limit: num(double) # New spending limit for the API key in USD, limit_reset: str(daily/weekly/monthly) # New limit reset type for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday., name: str # New name for the API key, workspace_id: str(uuid) # Move the API key to this workspace. The key keeps its value; guardrail selections move with it, except direct guardrail assignments owned by the key's current workspace, which are removed along with the selections derived from them, while other workspace-scoped settings (presets, BYOK keys, broadcast destinations, routing rules) do not. Sending the key's current workspace is a no-op.}\n@returns(200) {data: map{byok_usage: num(double), byok_usage_daily: num(double), byok_usage_monthly: num(double), byok_usage_weekly: num(double), created_at: str, creator_user_id: str?, disabled: bool, expires_at: str(date-time)?, external_user: str?, hash: str, include_byok_in_limit: bool, label: str, last_used_at: str(date-time)?, limit: num(double)?, limit_remaining: num(double)?, limit_reset: str?, name: str, updated_at: str?, usage: num(double), usage_daily: num(double), usage_monthly: num(double), usage_weekly: num(double), workspace_id: str}} # API key updated successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n@example_request {\"disabled\":false,\"include_byok_in_limit\":true,\"limit\":75,\"limit_reset\":\"daily\",\"name\":\"Updated API Key Name\"}\n\n@endgroup\n\n@group messages\n@endpoint POST /messages\n@desc Create a message\n@required {messages: [map{clear_at: str, content!: any, output_config: map, role!: str}], model: str}\n@optional {X-OpenRouter-Metadata: str # Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility., cache_control: map{ttl: str, type!: str} # Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format., context_management: map{edits: [any]}, deferred_tools: map{announce_catalog_changes: bool, cascade_mode: str, hint: str, interface: str, min_deferred_tools: int, profile!: str, protocol!: str, scope: str, search!: any, validation!: str} # Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_changes`, tells the model about it., fallbacks: [map{model!: str}] # 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., max_tokens: int, metadata: map{user_id: str}, models: [str], output_config: map{effort: str, format: map, task_budget: map} # Configuration for controlling output behavior. Supports the effort parameter and structured output format., plugins: [any] # Plugins you want to enable for this request, including their settings., provider: map{allow_fallbacks: bool, data_collection: str, enforce_distillable_text: bool, ignore: [any], max_price: map, only: [any], options: map, order: [any], preferred_max_latency: any, preferred_min_throughput: any, quantizations: [str], require_parameters: bool, sort: any, zdr: bool} # When multiple model providers are available, optionally indicate your routing preference., route: str(fallback/sort) # **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: \"fallback\" (maps to \"model\"), \"sort\" (maps to \"none\")., safeguards: [map{classifier_context: map, type!: str}], service_tier: str, session_id: str # 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: any, stop_sequences: [str], stop_server_tools_when: [any] # Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call., stream: bool, system: any, temperature: num(double), thinking: any, tool_choice: any, tools: [any], top_k: int, top_p: num(double), trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # 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.}\n@returns(200) Successful response\n@errors {400: Invalid request error, 401: Authentication error, 403: Forbidden error, 404: Not found error, 429: Rate limit error, 500: API error, 503: Overloaded error, 529: Overloaded error}\n@example_request {\"max_tokens\":1024,\"messages\":[{\"content\":\"Hello, how are you?\",\"role\":\"user\"}],\"model\":\"anthropic/claude-sonnet-4\"}\n\n@endgroup\n\n@group model\n@endpoint GET /model/{author}/{slug}\n@desc Get a model by its slug\n@required {author: str # The author/organization of the model, slug: str # The model slug, optionally including a variant suffix (e.g. gpt-4 or gpt-4:free)}\n@returns(200) {data: map{alias_target: map{name: str, slug: str}, architecture: map{input_modalities: [str], instruct_type: str?, modality: str?, output_modalities: [str], tokenizer: str}, benchmarks: map{artificial_analysis: map{agentic_index: num(double)?, coding_index: num(double)?, cyber_index: num(double)?, decision_index: num(double)?, economics_index: num(double)?, engineering_index: num(double)?, finance_and_accounting_index: num(double)?, healthcare_and_medical_index: num(double)?, intelligence_index: num(double)?, legal_index: num(double)?, multilingual_index: num(double)?, openness_index: num(double)?, strategy_and_ops_index: num(double)?}, design_arena: [map]}, canonical_slug: str, context_length: int?, created: int, default_parameters: map?, description: str, endpoints: [str], expiration_date: str?, hugging_face_id: str?, id: str, knowledge_cutoff: str?, links: map{details: str}, name: str, per_request_limits: map?, pricing: map{audio: str, audio_output: str, completion: str, discount: num(double), image: str, image_output: str, image_token: str, input_audio_cache: str, input_cache_read: str, input_cache_write: str, input_cache_write_1h: str, internal_reasoning: str, overrides: [map], prompt: str, request: str, web_search: str}, reasoning: map{default_effort: any, default_enabled: bool, mandatory: bool, supported_efforts: [str]?, supports_max_tokens: bool}, supported_parameters: [str], supported_voices: [str]?, top_provider: map{context_length: int?, is_moderated: bool, max_completion_tokens: int?}}} # Returns the model details\n@errors {403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group models\n@endpoint GET /models\n@desc List all models and their properties\n@optional {offset: int=0 # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int=500 # Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned, category: str(programming/roleplay/marketing/marketing/seo/technology/science/translation/legal/finance/health/trivia/academia) # Filter models by use case category, supported_parameters: str # Filter models by supported parameter (comma-separated), output_modalities: str # Filter models by output modality. Accepts a comma-separated list of modalities (text, image, embeddings, audio, video, rerank, decisions, speech, transcription) or \"all\" to include all models. Defaults to \"text\"., sort: str(most-popular/newest/top-weekly/pricing-low-to-high/pricing-high-to-low/context-high-to-low/throughput-high-to-low/latency-low-to-high/intelligence-high-to-low/coding-high-to-low/agentic-high-to-low/finance-and-accounting-high-to-low/strategy-and-ops-high-to-low/legal-high-to-low/healthcare-and-medical-high-to-low/engineering-high-to-low/economics-high-to-low/cyber-high-to-low/openness-high-to-low/multilingual-high-to-low/decision-high-to-low/design-arena-elo-high-to-low) # Sort the returned models server-side. Prefer this over fetching the full list and sorting client-side. Options: pricing-low-to-high, pricing-high-to-low (average prompt/completion price), context-high-to-low (context length), throughput-high-to-low, latency-low-to-high (recent median performance), most-popular, top-weekly (tokens processed in the last week), newest (creation date), -high-to-low for each Artificial Analysis index (the coding and agentic sorts are deprecated: Artificial Analysis has retired those indexes), design-arena-elo-high-to-low (best Design Arena ELO across arenas). Models without a score for the chosen benchmark are placed last. The decision sort ranks decision models, so pass output_modalities=decisions or all with it. When omitted, the existing default ordering is preserved., q: str # Free-text search by model name or slug., input_modalities: str # Filter models by input modality. Comma-separated list of: text, image, audio, file., endpoints: str # Filter models by the request API paths they serve, as listed in each model's `endpoints` field. Comma-separated; a model must serve every listed path. Valid values: /api/v1/chat/completions, /api/v1/completions, /api/v1/messages, /api/v1/responses, /api/v1/embeddings, /api/v1/rerank, /api/alpha/decisions, /api/alpha/extractions, /api/v1/videos, /api/v1/audio/speech, /api/v1/audio/transcriptions, /api/v1/images, /api/v1/batches. When set without `output_modalities`, models of every output modality are considered (the companion `/api/alpha/extractions` route is served by text and decisions models alike)., context: int # Minimum context length (tokens). Models with smaller context are excluded., min_price: num # Minimum prompt price in $/M tokens., max_price: num # Maximum prompt price in $/M tokens., arch: str # Filter models by architecture/model family (e.g. GPT, Claude, Gemini, Llama)., model_authors: str # Filter models by the organization that created the model. Comma-separated list of author slugs., providers: str # Filter models by hosting provider. Comma-separated list of provider names., distillable: str(true/false) # Filter by distillation capability. \"true\" returns only distillable models, \"false\" excludes them., zdr: str # When set to \"true\", return only models with zero data retention endpoints., region: str(eu/us) # Filter to models with endpoints in the given data region (\"eu\" or \"us\")., min_output_price: num # Minimum completion (output) price in $/M tokens., max_output_price: num # Maximum completion (output) price in $/M tokens., min_age_days: int # Minimum model age in days since its creation date., max_age_days: int # Maximum model age in days since its creation date., min_intelligence_index: num # Minimum Artificial Analysis Intelligence Index score (0-100); unscored models are excluded., max_intelligence_index: num # Maximum Artificial Analysis Intelligence Index score (0-100); unscored models are excluded., min_coding_index: num # Deprecated: Artificial Analysis has retired its Coding Index. Minimum score (0-100); unscored models are excluded., max_coding_index: num # Deprecated: Artificial Analysis has retired its Coding Index. Maximum score (0-100); unscored models are excluded., min_agentic_index: num # Deprecated: Artificial Analysis has retired its Agentic Index. Minimum score (0-100); unscored models are excluded., max_agentic_index: num # Deprecated: Artificial Analysis has retired its Agentic Index. Maximum score (0-100); unscored models are excluded., min_finance_and_accounting_index: num # Minimum Artificial Analysis Finance & Accounting Index score (0-100); unscored models are excluded., max_finance_and_accounting_index: num # Maximum Artificial Analysis Finance & Accounting Index score (0-100); unscored models are excluded., min_strategy_and_ops_index: num # Minimum Artificial Analysis Strategy & Ops Index score (0-100); unscored models are excluded., max_strategy_and_ops_index: num # Maximum Artificial Analysis Strategy & Ops Index score (0-100); unscored models are excluded., min_legal_index: num # Minimum Artificial Analysis Legal Index score (0-100); unscored models are excluded., max_legal_index: num # Maximum Artificial Analysis Legal Index score (0-100); unscored models are excluded., min_healthcare_and_medical_index: num # Minimum Artificial Analysis Healthcare & Medical Index score (0-100); unscored models are excluded., max_healthcare_and_medical_index: num # Maximum Artificial Analysis Healthcare & Medical Index score (0-100); unscored models are excluded., min_engineering_index: num # Minimum Artificial Analysis Engineering Index score (0-100); unscored models are excluded., max_engineering_index: num # Maximum Artificial Analysis Engineering Index score (0-100); unscored models are excluded., min_economics_index: num # Minimum Artificial Analysis Economics Index score (0-100); unscored models are excluded., max_economics_index: num # Maximum Artificial Analysis Economics Index score (0-100); unscored models are excluded., min_cyber_index: num # Minimum Artificial Analysis Cyber Index score (0-100); unscored models are excluded., max_cyber_index: num # Maximum Artificial Analysis Cyber Index score (0-100); unscored models are excluded., min_openness_index: num # Minimum Artificial Analysis Openness Index score (0-100); unscored models are excluded., max_openness_index: num # Maximum Artificial Analysis Openness Index score (0-100); unscored models are excluded., min_multilingual_index: num # Minimum Artificial Analysis Multilingual Index score (0-1); unscored models are excluded., max_multilingual_index: num # Maximum Artificial Analysis Multilingual Index score (0-1); unscored models are excluded., min_decision_index: num # Minimum Artificial Analysis Decision Index score (0-100); unscored models are excluded., max_decision_index: num # Maximum Artificial Analysis Decision Index score (0-100); unscored models are excluded., min_tool_success_rate: num # Minimum tool-calling success rate, as a fraction in [0, 1] (e.g. 0.9 = 90% of requests finishing with a tool_calls finish reason)., max_tool_success_rate: num # Maximum tool-calling success rate, as a fraction in [0, 1].}\n@returns(200) {data: [map], links: map{next: str?}, total_count: int} # Returns a list of models or RSS feed\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint GET /models/{author}/{slug}/endpoints\n@desc List all endpoints for a model\n@required {author: str # The author/organization of the model, slug: str # The model slug}\n@returns(200) {data: map{architecture: any, created: int, description: str, endpoints: [map], id: str, name: str}} # Returns a list of endpoints\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint GET /models/count\n@desc Get total count of available models\n@optional {output_modalities: str # Filter models by output modality. Accepts a comma-separated list of modalities (text, image, embeddings, audio, video, rerank, decisions, speech, transcription) or \"all\" to include all models. Defaults to \"text\".}\n@returns(200) {data: map{count: int}} # Returns the total count of available models\n@errors {400: Bad Request - Invalid request parameters or malformed input, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /models/user\n@desc List models filtered by user provider preferences, privacy settings, and guardrails\n@optional {offset: int=0 # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int=500 # Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned, output_modalities: str # Filter models by output modality. Accepts a comma-separated list of modalities (text, image, embeddings, audio, video, rerank, decisions, speech, transcription) or \"all\" to include all models. Defaults to \"text\"., sort: str(most-popular/newest/top-weekly/pricing-low-to-high/pricing-high-to-low/context-high-to-low/throughput-high-to-low/latency-low-to-high/intelligence-high-to-low/coding-high-to-low/agentic-high-to-low/finance-and-accounting-high-to-low/strategy-and-ops-high-to-low/legal-high-to-low/healthcare-and-medical-high-to-low/engineering-high-to-low/economics-high-to-low/cyber-high-to-low/openness-high-to-low/multilingual-high-to-low/decision-high-to-low/design-arena-elo-high-to-low) # Sort the returned models server-side. Prefer this over fetching the full list and sorting client-side. Options: pricing-low-to-high, pricing-high-to-low (average prompt/completion price), context-high-to-low (context length), throughput-high-to-low, latency-low-to-high (recent median performance), most-popular, top-weekly (tokens processed in the last week), newest (creation date), -high-to-low for each Artificial Analysis index (the coding and agentic sorts are deprecated: Artificial Analysis has retired those indexes), design-arena-elo-high-to-low (best Design Arena ELO across arenas). Models without a score for the chosen benchmark are placed last. The decision sort ranks decision models, so pass output_modalities=decisions or all with it. When omitted, the existing default ordering is preserved., client: str(claude_code/claude_desktop/codex) # Filter models and presets by the named harness's eligibility policy: tool calling is required, and when one of your guardrails sets `enforce_first_party_harness_models`, only the harness vendor's own models remain (OpenAI for codex, Anthropic for claude_code and claude_desktop). When your workspace's Managed Machines policy sets a model list for that harness, only the listed models remain, and a preset remains only while every model it routes to is listed. This filter doesn't apply the harness's ranking, caps or Claude Desktop model ID aliases, so returned IDs stay routable. One of: claude_code, claude_desktop, codex. Omit it to get every model you can use.}\n@returns(200) {data: [map], links: map{next: str?}, total_count: int} # Returns a list of models filtered by user provider preferences\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endgroup\n\n@group oauth\n@endpoint GET /oauth/jwks\n@desc OpenRouter access token signing keys\n@returns(200) {keys: [map]} # JWK Set\n@errors {500: Signing keys are not configured}\n\n@endpoint POST /oauth/token\n@desc Exchange a workload identity token\n@returns(200) {access_token: str, expires_in: int, issued_token_type: str, scope: str, token_type: str} # Access token issued\n@errors {400: Malformed request, unsupported grant, or the subject token was not accepted, 429: Rate limited, 500: The token could not be issued, 503: The issuer’s discovery document or JWKS could not be fetched}\n\n@endgroup\n\n@group observability\n@endpoint GET /observability/destinations\n@desc List observability destinations\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), workspace_id: str(uuid) # Optional workspace ID to filter by. Defaults to the authenticated entity's default workspace, or a workspace-scoped management key's own workspace.}\n@returns(200) {data: [any], total_count: int} # List of observability destinations\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /observability/destinations\n@desc Create an observability destination\n@required {config: map # Provider-specific configuration. The shape depends on `type` and is validated server-side., name: str # Human-readable name for the destination., type: str(arize/braintrust/clickhouse/datadog/grafana/langfuse/langsmith/newrelic/opik/otel-collector/posthog/ramp/s3/sentry/snowflake/weave/webhook) # The destination type. Only stable destination types are accepted.}\n@optional {api_key_hashes: [str] # Optional allowlist of OpenRouter API key hashes whose traffic is forwarded. `null` or omitted means all keys. Must contain at least one hash if provided. Every hash must belong to an API key in the destination's workspace; any other hash returns 400., broadcast_generation_cost: bool=false # When true, include cost and billing generation metadata., broadcast_generation_cost_allocation: bool=false # Beta. When true, include openrouter_cost_allocation: per-token-kind usage and cost, sent only when they reconcile with the billed cost., broadcast_generation_identity: bool=false # When true, include identity generation metadata., broadcast_generation_request_context: bool=false # When true, include request-context generation metadata., enabled: bool=true # Whether this destination should be enabled immediately., filter_rules: map{enabled: bool, groups!: [map]} # Optional structured filter rules controlling which events are forwarded., privacy_mode: bool=false # When true, request/response bodies are not forwarded — only metadata., regions: [str]=global # Data regions this destination applies to. `eu` is accepted as an alias for `europe` and normalizes to `europe`. Omitting this field defaults to ['global']; the array must be non-empty., sampling_rate: num(double) # Sampling rate between 0.0001 and 1 (1 = 100%)., workspace_id: str(uuid) # Optional workspace ID. Defaults to the authenticated entity's default workspace, or a workspace-scoped management key's own workspace.}\n@returns(201) {data: any} # Destination created successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n@example_request {\"config\":{\"baseUrl\":\"https://us.cloud.langfuse.com\",\"publicKey\":\"pk-l...EfGh\",\"secretKey\":\"sk-l...AbCd\"},\"name\":\"Production Langfuse\",\"type\":\"langfuse\"}\n\n@endpoint DELETE /observability/destinations/{id}\n@desc Delete an observability destination\n@required {id: str(uuid) # The destination ID (UUID).}\n@returns(200) {deleted: bool} # Destination deleted successfully\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /observability/destinations/{id}\n@desc Get an observability destination\n@required {id: str(uuid) # The destination ID (UUID).}\n@returns(200) {data: any} # The observability destination\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /observability/destinations/{id}\n@desc Update an observability destination\n@required {id: str(uuid) # The destination ID (UUID).}\n@optional {api_key_hashes: [str] # Optional allowlist of OpenRouter API key hashes. `null` clears the filter (all keys). Omitting leaves the current value. Must contain at least one hash if provided. Every hash must belong to an API key in the destination's workspace; any other hash returns 400. A hash the destination already lists is kept even if that key has since moved to another workspace, so an already-listed hash can always be written back., broadcast_generation_cost: bool # Whether to include cost and billing generation metadata., broadcast_generation_cost_allocation: bool # Beta. When true, include openrouter_cost_allocation: per-token-kind usage and cost, sent only when they reconcile with the billed cost., broadcast_generation_identity: bool # Whether to include identity generation metadata., broadcast_generation_request_context: bool # Whether to include request-context generation metadata., config: map # Provider-specific configuration fields to update. Masked values are ignored; unset fields keep their current value., enabled: bool # Whether the destination is enabled., filter_rules: any, name: str # Human-readable name for the destination., privacy_mode: bool # When true, request/response bodies are not forwarded — only metadata., regions: [str] # Data regions this destination applies to. `eu` is accepted as an alias for `europe` and normalizes to `europe`. Omitting this field keeps the current value; it cannot be cleared., sampling_rate: num(double) # Sampling rate between 0.0001 and 1 (1 = 100%).}\n@returns(200) {data: any} # Destination updated successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n@example_request {\"enabled\":false,\"name\":\"Updated Langfuse\"}\n\n@endgroup\n\n@group organization\n@endpoint GET /organization/members\n@desc List organization members\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: int} # List of organization members\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /organization/settings\n@desc Get organization settings\n@returns(200) {data: map{id: str, is_filtered_model_catalog_enabled: bool}} # Organization settings\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /organization/settings\n@desc Update organization settings\n@required {is_filtered_model_catalog_enabled: bool # When true, the signed-in dashboard lists only the models the organization can use. `GET /api/v1/models` called with an API key always returns only the models that key can use, whatever this setting says; anonymous requests receive the public catalog.}\n@returns(200) {data: map{id: str, is_filtered_model_catalog_enabled: bool}} # Organization settings updated successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"is_filtered_model_catalog_enabled\":true}\n\n@endgroup\n\n@group presets\n@endpoint GET /presets\n@desc List presets\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace.}\n@returns(200) {data: [map], total_count: int} # Paginated list of presets.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint DELETE /presets/{slug}\n@desc Delete a preset\n@required {slug: str # URL-safe slug identifying the preset.}\n@optional {workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace.}\n@returns(200) {data: any} # The archived preset with its designated version.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /presets/{slug}\n@desc Get a preset\n@required {slug: str # URL-safe slug identifying the preset.}\n@optional {workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace.}\n@returns(200) {data: any} # Preset with its designated version.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint POST /presets/{slug}/chat/completions\n@desc Create a preset from a chat-completions request body\n@required {slug: str # URL-safe slug identifying the preset. Created if it does not exist., messages: [any] # List of messages for the conversation}\n@optional {workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace., cache_control: map{ttl: str, type!: str} # Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format., debug: map{echo_upstream_body: bool} # Debug options for inspecting request transformations (streaming only), deferred_tools: map{announce_catalog_changes: bool, cascade_mode: str, hint: str, interface: str, min_deferred_tools: int, profile!: str, protocol!: str, scope: str, search!: any, validation!: str} # Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_changes`, tells the model about it., frequency_penalty: num(double) # Frequency penalty (-2.0 to 2.0), image_config: map # 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., logit_bias: map # Token logit bias adjustments, logprobs: bool # Return log probabilities, max_completion_tokens: int # Maximum tokens in completion, max_tokens: int # Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16., metadata: map # Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values), min_p: num(double) # Minimum probability threshold relative to the most likely token. Tokens with probability below min_p * (probability of top token) are filtered out. Not all providers support this parameter., modalities: [str] # Output modalities for the response. Supported values are \"text\", \"image\", and \"audio\"., model: str # Model to use for completion, models: [any] # Models to use for completion, parallel_tool_calls: bool # Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response., plugins: [any] # Plugins you want to enable for this request, including their settings., prediction: map{content!: any, type!: str} # Static predicted output content. Supported models can use this to reduce latency when much of the response is known in advance., presence_penalty: num(double) # Presence penalty (-2.0 to 2.0), prompt_cache_key: str, prompt_cache_options: map{mode!: str, ttl: str} # Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. `ttl` sets the minimum cache lifetime for every breakpoint the request writes: \"30m\" (default) or \"12h\" (billed at the higher 12h cache-write rate). Only supported by OpenAI GPT-5.6 and newer., provider: map{allow_fallbacks: bool, data_collection: str, enforce_distillable_text: bool, ignore: [any], max_price: map, only: [any], options: map, order: [any], preferred_max_latency: any, preferred_min_throughput: any, quantizations: [str], require_parameters: bool, sort: any, zdr: bool} # When multiple model providers are available, optionally indicate your routing preference., reasoning: map{context: str, effort: str, enabled: bool, exclude: bool, max_tokens: int, mode: str, summary: str} # Configuration options for reasoning models, reasoning_effort: str(max/xhigh/high/medium/low/minimal/none) # Shorthand for setting reasoning effort. Equivalent to setting reasoning.effort. Cannot be used simultaneously with reasoning.effort if they differ., repetition_penalty: num(double) # Penalizes tokens based on how much they have already appeared in the text. A value of 1.0 means no penalty. Values above 1.0 penalize repeated tokens more strongly. Not all providers support this parameter., response_format: any # Response format configuration, route: str(fallback/sort) # **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: \"fallback\" (maps to \"model\"), \"sort\" (maps to \"none\")., seed: int # Random seed for deterministic outputs, service_tier: str(auto/default/fast/flex/priority/scale/ultrafast) # The service tier to use for processing this request. `fast` is accepted as an alias for `priority`. `ultrafast` prefers ultrafast endpoints and falls back to `priority`, then default endpoints., session_id: str # 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: any # Stop sequences (up to 4), stop_server_tools_when: [any] # Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call., stream: bool=false # Enable streaming response, stream_options: map{include_usage: bool} # Streaming configuration options, temperature: num(double) # Sampling temperature (0-2), tool_choice: any # Tool choice configuration, tools: [any] # Available tools for function calling, top_a: num(double) # Consider only tokens with \"sufficiently high\" probabilities based on the probability of the most likely token. Not all providers support this parameter., top_k: int # Limits the model to choose from the top K most likely tokens at each step. A value of 1 means the model will always pick the most likely next token. Not all providers support this parameter., top_logprobs: int # Number of top log probabilities to return (0-20), top_p: num(double) # Nucleus sampling parameter (0-1), trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # Per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account.}\n@returns(200) {data: any} # Preset created or updated successfully.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n@example_request {\"messages\":[{\"content\":\"You are a helpful assistant.\",\"role\":\"system\"},{\"content\":\"Hello!\",\"role\":\"user\"}],\"model\":\"openai/gpt-5.4\",\"temperature\":0.7}\n\n@endpoint POST /presets/{slug}/messages\n@desc Create a preset from a messages request body\n@required {slug: str # URL-safe slug identifying the preset. Created if it does not exist., messages: [map{clear_at: str, content!: any, output_config: map, role!: str}], model: str}\n@optional {workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace., cache_control: map{ttl: str, type!: str} # Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format., context_management: map{edits: [any]}, deferred_tools: map{announce_catalog_changes: bool, cascade_mode: str, hint: str, interface: str, min_deferred_tools: int, profile!: str, protocol!: str, scope: str, search!: any, validation!: str} # Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_changes`, tells the model about it., fallbacks: [map{model!: str}] # 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., max_tokens: int, metadata: map{user_id: str}, models: [str], output_config: map{effort: str, format: map, task_budget: map} # Configuration for controlling output behavior. Supports the effort parameter and structured output format., plugins: [any] # Plugins you want to enable for this request, including their settings., provider: map{allow_fallbacks: bool, data_collection: str, enforce_distillable_text: bool, ignore: [any], max_price: map, only: [any], options: map, order: [any], preferred_max_latency: any, preferred_min_throughput: any, quantizations: [str], require_parameters: bool, sort: any, zdr: bool} # When multiple model providers are available, optionally indicate your routing preference., route: str(fallback/sort) # **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: \"fallback\" (maps to \"model\"), \"sort\" (maps to \"none\")., safeguards: [map{classifier_context: map, type!: str}], service_tier: str, session_id: str # 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: any, stop_sequences: [str], stop_server_tools_when: [any] # Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call., stream: bool, system: any, temperature: num(double), thinking: any, tool_choice: any, tools: [any], top_k: int, top_p: num(double), trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # 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.}\n@returns(200) {data: any} # Preset created or updated successfully.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n@example_request {\"max_tokens\":1024,\"messages\":[{\"content\":\"Hello!\",\"role\":\"user\"}],\"model\":\"anthropic/claude-4.6-sonnet\",\"system\":\"You are a helpful assistant.\"}\n\n@endpoint POST /presets/{slug}/responses\n@desc Create a preset from a responses request body\n@required {slug: str # URL-safe slug identifying the preset. Created if it does not exist.}\n@optional {workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace., access_programs: map{cyber: str} # OpenAI access programs for this request. `cyber` selects the Cyber access program: `standard`, `daybreak_blue`, or `daybreak_red`. A program other than `standard` is supported only on BYOK requests that run on your own OpenAI key enrolled in that program; any other endpoint, including OpenRouter's own OpenAI credentials, rejects it with a 400 error. Requests on OpenRouter's OpenAI credentials always run `standard`. Omit the field unless your key is enrolled in a Daybreak program., background: bool, cache_control: map{ttl: str, type!: str} # Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format., debug: map{echo_upstream_body: bool} # Debug options for inspecting request transformations (streaming only), deferred_tools: map{announce_catalog_changes: bool, cascade_mode: str, hint: str, interface: str, min_deferred_tools: int, profile!: str, protocol!: str, scope: str, search!: any, validation!: str} # Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_changes`, tells the model about it., frequency_penalty: num(double), image_config: map # 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: [str], input: any # Input for a response request - can be a string or array of items, instructions: str, max_output_tokens: int, max_tool_calls: int # Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set., metadata: map # 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: [str] # Output modalities for the response. Supported values are \"text\" and \"image\"., model: str, models: [str], parallel_tool_calls: bool, plugins: [any] # Plugins you want to enable for this request, including their settings., presence_penalty: num(double), previous_response_id: any # Not supported on this proxy. Each response request is independent: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead., prompt: map{id!: str, variables: map}, prompt_cache_key: str, prompt_cache_options: map{mode!: str, ttl: str} # Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. `ttl` sets the minimum cache lifetime for every breakpoint the request writes: \"30m\" (default) or \"12h\" (billed at the higher 12h cache-write rate). Only supported by OpenAI GPT-5.6 and newer., provider: map{allow_fallbacks: bool, data_collection: str, enforce_distillable_text: bool, ignore: [any], max_price: map, only: [any], options: map, order: [any], preferred_max_latency: any, preferred_min_throughput: any, quantizations: [str], require_parameters: bool, sort: any, zdr: bool} # When multiple model providers are available, optionally indicate your routing preference., reasoning: any # Configuration for reasoning mode in the response, route: str(fallback/sort) # **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: str # Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account., service_tier: str(auto/default/fast/flex/priority/scale/ultrafast)=auto # The service tier to use for processing this request. `fast` is accepted as an alias for `priority`. `ultrafast` prefers ultrafast endpoints and falls back to `priority`, then default endpoints., session_id: str # 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: any # Stop sequences (up to 4), stop_server_tools_when: [any] # Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call., store: bool=false, stream: bool=false, temperature: num(double), text: any # Text output configuration including format and verbosity, tool_choice: any, tools: [any], top_k: int, top_logprobs: int, top_p: num(double), trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations., truncation: str(auto/disabled), user: str # 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.}\n@returns(200) {data: any} # Preset created or updated successfully.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n@example_request {\"input\":\"Hello!\",\"instructions\":\"You are a helpful assistant.\",\"model\":\"openai/gpt-5.4\"}\n\n@endpoint POST /presets/{slug}/restore\n@desc Restore a preset\n@required {slug: str # URL-safe slug identifying the preset.}\n@optional {workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace.}\n@returns(200) {data: any} # The restored preset with its designated version.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /presets/{slug}/versions\n@desc List versions of a preset\n@required {slug: str # URL-safe slug identifying the preset.}\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace.}\n@returns(200) {data: [map], total_count: int} # Paginated list of preset versions.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endpoint GET /presets/{slug}/versions/{version}\n@desc Get a specific version of a preset\n@required {slug: str # URL-safe slug identifying the preset., version: str # Version number of the preset.}\n@optional {workspace_id: str(uuid) # Workspace to act in. Also accepted as a `workspace_id` field in a JSON request body. Defaults to the key's workspace for a key limited to one workspace, otherwise to the account's default workspace.}\n@returns(200) {data: map?} # The requested preset version.\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n\n@endgroup\n\n@group private-endpoints\n@endpoint GET /private-endpoints\n@desc List private endpoints\n@returns(200) {data: [map]} # Private endpoints for the organization\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 408: Request Timeout - Operation exceeded time limit, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /private-endpoints\n@desc Create a private endpoint\n@required {model_permaslug: str # Permanent slug of the model this endpoint serves., provider_slug: str # Slug of the upstream provider., upstream_model_id: str # Model or deployment identifier sent to the upstream provider.}\n@optional {idempotency-key: str # Retry-safe create: a repeated create with the same key from the same organization returns the endpoint the first request created instead of creating another. The endpoint is returned as it is now. Reusing a key with a different request body (model, provider, base URL, upstream model ID, declared ZDR or region, pricing, or declared parameters) is rejected with 422 `idempotency_key_reused`. Declared parameters are compared as a set, so a retry that reorders or repeats a name replays the endpoint. `activate` and `settings` are not compared, and later edits to the endpoint do not affect the comparison. `settings` is still validated before the replay, so a retry with invalid settings returns 400 `settings_invalid` instead of the endpoint., activate: map{workspace_id!: str(uuid)} # Validate and activate in the same call. On a failed validation the draft is kept and returned with a 422, so fix it and call `/validate` and `/activate` instead of creating it again., base_url: str # HTTPS base URL of your deployment. Required unless the provider derives its URL from the BYOK credential (Azure, Amazon Bedrock, Google Vertex)., declared_parameters: [str] # Parameters the upstream supports beyond the tested ones. Replaces the earlier declaration; tested parameters stay. Order and repeated names are ignored, but the list holds at most as many entries as there are declarable parameters, repeats included. `tool_choice` requires `tools` to be tested or declared., declared_region: str(global/europe/us) # Attest where this deployment processes data., declared_zdr: bool # Attest that this deployment retains no prompt or completion data., pricing: map{cache_read: str, cache_write: str, completion!: str, prompt!: str} # Negotiated per-token rates reported for requests routed to this endpoint., settings: map{completions: map, context_length: int, excluded_parameters: [str], inputs: map, max_completion_tokens: int, max_prompt_tokens: int, quantization: str, reasoning: map, tool_choice: map} # Capabilities and limits to set over the ones copied from the public endpoint for this model and provider (or from the model). Omitted fields keep the copied values.}\n@returns(201) {data: any} # The created endpoint: a draft, or active when `activate` was passed\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: The model, provider, or validation workspace was not found. When `activate` was passed and the draft was created, `data` carries it and any validation checks., 408: Request Timeout - Operation exceeded time limit, 409: The request conflicts with the endpoint state, such as a stale validation. When `activate` was passed and the draft was created, `data` carries it and any validation checks., 422: The request was invalid, or validation failed. When `activate` was passed and the draft was created, `data` carries it and any validation checks., 500: Internal server error. When `activate` was passed and the draft was created, `data` carries it and any validation checks., 502: An upstream dependency failed. When `activate` was passed and the draft was created, `data` carries it and any validation checks.}\n\n@endpoint DELETE /private-endpoints/{id}\n@desc Delete a private endpoint\n@required {id: str(uuid) # Stable identifier of the private endpoint.}\n@optional {draft_only: str(true/false) # When `true`, only delete the endpoint if it is still a draft (409 otherwise).}\n@returns(200) {data: map{id: str(uuid)}} # The endpoint was deleted\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 422: Unprocessable Entity - Semantic validation failure, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure}\n\n@endpoint GET /private-endpoints/{id}\n@desc Get a private endpoint\n@required {id: str(uuid) # Stable identifier of the private endpoint.}\n@returns(200) {data: map{base_url: str?, declared_parameters: [str], declared_region: str?, declared_zdr: bool?, id: str(uuid), max_completion_tokens: int?, model_name: str?, model_permaslug: str, model_slug: str?, pricing: map{cache_read: str, cache_write: str, completion: str, prompt: str}, provider_name: str, provider_slug: str?, settings: map{completions: map{chat: bool?, text: bool?}, context_length: int?, excluded_parameters: [str], inputs: map{audio: bool?, base64_files: bool?, base64_images: bool?, file_urls: bool?, image_urls: bool?}, max_completion_tokens: int?, max_prompt_tokens: int?, quantization: str, reasoning: map{return_mechanism: str?, supported: bool}, tool_choice: map{auto: bool, function: bool, none: bool, required: bool}}, status: str, tested_parameters: [str], upstream_model_id: str}} # The private endpoint\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /private-endpoints/{id}\n@desc Update a private endpoint\n@required {id: str(uuid) # Stable identifier of the private endpoint.}\n@optional {base_url: str # HTTPS base URL of your deployment. Required unless the provider derives its URL from the BYOK credential (Azure, Amazon Bedrock, Google Vertex)., declared_parameters: [str] # Parameters the upstream supports beyond the tested ones. Replaces the earlier declaration; tested parameters stay. Order and repeated names are ignored, but the list holds at most as many entries as there are declarable parameters, repeats included. `tool_choice` requires `tools` to be tested or declared., declared_region: str(global/europe/us) # Attest where this deployment processes data., declared_zdr: bool # Attest that this deployment retains no prompt or completion data., pricing: any, settings: any, upstream_model_id: str # Model or deployment identifier sent to the upstream provider.}\n@returns(200) {data: map{base_url: str?, declared_parameters: [str], declared_region: str?, declared_zdr: bool?, id: str(uuid), max_completion_tokens: int?, model_name: str?, model_permaslug: str, model_slug: str?, pricing: map{cache_read: str, cache_write: str, completion: str, prompt: str}, provider_name: str, provider_slug: str?, settings: map{completions: map{chat: bool?, text: bool?}, context_length: int?, excluded_parameters: [str], inputs: map{audio: bool?, base64_files: bool?, base64_images: bool?, file_urls: bool?, image_urls: bool?}, max_completion_tokens: int?, max_prompt_tokens: int?, quantization: str, reasoning: map{return_mechanism: str?, supported: bool}, tool_choice: map{auto: bool, function: bool, none: bool, required: bool}}, status: str, tested_parameters: [str], upstream_model_id: str}} # The updated endpoint\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 422: Unprocessable Entity - Semantic validation failure, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure}\n\n@endpoint POST /private-endpoints/{id}/activate\n@desc Activate a validated private endpoint\n@required {id: str(uuid) # Stable identifier of the private endpoint.}\n@returns(200) {data: any} # The endpoint after the change\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 422: Unprocessable Entity - Semantic validation failure, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure}\n\n@endpoint POST /private-endpoints/{id}/disable\n@desc Disable a private endpoint\n@required {id: str(uuid) # Stable identifier of the private endpoint.}\n@returns(200) {data: any} # The endpoint after the change\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 422: Unprocessable Entity - Semantic validation failure, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure}\n\n@endpoint POST /private-endpoints/{id}/enable\n@desc Enable a private endpoint\n@required {id: str(uuid) # Stable identifier of the private endpoint.}\n@returns(200) {data: any} # The endpoint after the change\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 422: Unprocessable Entity - Semantic validation failure, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure}\n\n@endpoint POST /private-endpoints/{id}/validate\n@desc Validate a draft private endpoint\n@required {id: str(uuid) # Stable identifier of the private endpoint., workspace_id: str(uuid) # Workspace whose BYOK credential is used for the live validation call. The workspace must belong to your account.}\n@returns(200) {data: map{checks: [map], parameters: [map], passed: bool}} # Validation checks\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 422: Unprocessable Entity - Semantic validation failure, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure}\n\n@endgroup\n\n@group private-providers\n@endpoint GET /private-providers\n@desc List private providers\n@returns(200) {data: [map]} # Private providers for the organization\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /private-providers\n@desc Create a private provider\n@required {name: str # Provider name, shown in your activity, logs and Broadcast output. 2-64 letters, numbers, spaces, dots, underscores or hyphens. Cannot be changed later. Neither the name nor its slug may match a public provider name or slug (case-insensitive); other customers may use the same name.}\n@optional {base_url: str # HTTPS base URL of an OpenAI-compatible API, used by private endpoints under this provider that set no URL of their own. Without it, each endpoint must set its own. Private, internal, metadata and OpenRouter hosts are rejected., display_name: str # Defaults to `name`., slug: str # 2-64 lowercase letters and numbers, separated by single hyphens. Cannot be changed later. Defaults to the name lowercased, with every run of other characters replaced by a hyphen (`Acme Inference` becomes `acme-inference`).}\n@returns(201) {data: map{base_url: str?, created_at: str, display_name: str, name: str, slug: str}} # The provider was created\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 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}\n\n@endpoint DELETE /private-providers/{slug}\n@desc Delete a private provider\n@required {slug: str}\n@returns(200) {data: map{slug: str}} # The provider was deleted\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 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}\n\n@endpoint GET /private-providers/{slug}\n@desc Get a private provider\n@required {slug: str}\n@returns(200) {data: map{base_url: str?, created_at: str, display_name: str, name: str, slug: str}} # The private provider\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /private-providers/{slug}\n@desc Update a private provider\n@required {slug: str}\n@optional {base_url: str # HTTPS base URL of an OpenAI-compatible API, used by private endpoints under this provider that set no URL of their own. Without it, each endpoint must set its own. Private, internal, metadata and OpenRouter hosts are rejected., display_name: str}\n@returns(200) {data: map{base_url: str?, created_at: str, display_name: str, name: str, slug: str}} # The updated provider\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 409: Conflict - Resource conflict or concurrent modification, 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}\n\n@endgroup\n\n@group providers\n@endpoint GET /providers\n@desc List all providers\n@returns(200) {data: [map]} # Returns a list of providers\n@errors {500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group rerank\n@endpoint POST /rerank\n@desc Submit a rerank request\n@required {documents: [any] # The list of documents to rerank. Documents may be plain strings, or structured objects with `text` and/or `image` for multimodal models., model: str # The rerank model to use, query: str # The search query to rerank documents against}\n@optional {provider: any, session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., top_n: int # Number of most relevant documents to return, trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str # A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.}\n@returns(200) {id: str, model: str, provider: str, results: [map], usage: map{cost: num(double), search_units: int, total_tokens: int}} # Rerank response\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 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}\n\n@endgroup\n\n@group responses\n@endpoint POST /responses\n@desc Create a response\n@optional {X-OpenRouter-Metadata: str # Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility., access_programs: map{cyber: str} # OpenAI access programs for this request. `cyber` selects the Cyber access program: `standard`, `daybreak_blue`, or `daybreak_red`. A program other than `standard` is supported only on BYOK requests that run on your own OpenAI key enrolled in that program; any other endpoint, including OpenRouter's own OpenAI credentials, rejects it with a 400 error. Requests on OpenRouter's OpenAI credentials always run `standard`. Omit the field unless your key is enrolled in a Daybreak program., background: bool, cache_control: map{ttl: str, type!: str} # Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format., debug: map{echo_upstream_body: bool} # Debug options for inspecting request transformations (streaming only), deferred_tools: map{announce_catalog_changes: bool, cascade_mode: str, hint: str, interface: str, min_deferred_tools: int, profile!: str, protocol!: str, scope: str, search!: any, validation!: str} # Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation. The portable profile needs the catalog unchanged across a continuation; the universal profile accepts a changed catalog and, with `announce_catalog_changes`, tells the model about it., frequency_penalty: num(double), image_config: map # 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: [str], input: any # Input for a response request - can be a string or array of items, instructions: str, max_output_tokens: int, max_tool_calls: int # Maximum number of server-tool (e.g. `openrouter:web_search`) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when `stop_server_tools_when` is set., metadata: map # 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: [str] # Output modalities for the response. Supported values are \"text\" and \"image\"., model: str, models: [str], parallel_tool_calls: bool, plugins: [any] # Plugins you want to enable for this request, including their settings., presence_penalty: num(double), previous_response_id: any # Not supported on this proxy. Each response request is independent: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in `input` instead., prompt: map{id!: str, variables: map}, prompt_cache_key: str, prompt_cache_options: map{mode!: str, ttl: str} # Request-level prompt-cache controls. `mode: \"explicit\"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. `ttl` sets the minimum cache lifetime for every breakpoint the request writes: \"30m\" (default) or \"12h\" (billed at the higher 12h cache-write rate). Only supported by OpenAI GPT-5.6 and newer., provider: map{allow_fallbacks: bool, data_collection: str, enforce_distillable_text: bool, ignore: [any], max_price: map, only: [any], options: map, order: [any], preferred_max_latency: any, preferred_min_throughput: any, quantizations: [str], require_parameters: bool, sort: any, zdr: bool} # When multiple model providers are available, optionally indicate your routing preference., reasoning: any # Configuration for reasoning mode in the response, route: str(fallback/sort) # **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: str # Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account., service_tier: str(auto/default/fast/flex/priority/scale/ultrafast)=auto # The service tier to use for processing this request. `fast` is accepted as an alias for `priority`. `ultrafast` prefers ultrafast endpoints and falls back to `priority`, then default endpoints., session_id: str # 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: any # Stop sequences (up to 4), stop_server_tools_when: [any] # Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call., store: bool=false, stream: bool=false, temperature: num(double), text: any # Text output configuration including format and verbosity, tool_choice: any, tools: [any], top_k: int, top_logprobs: int, top_p: num(double), trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations., truncation: str(auto/disabled), user: str # 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.}\n@returns(200) Successful response\n@errors {400: Bad Request - Invalid request parameters or malformed input. Request-shape validation failures carry a Responses API string code (e.g. `invalid_prompt`) with details in the top-level `metadata`; all other failures carry the integer HTTP status., 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}\n@example_request {\"input\":\"Tell me a joke\",\"model\":\"openai/gpt-4o\"}\n\n@endgroup\n\n@group scim\n@endpoint GET /scim/group-mappings\n@desc List SCIM group mappings\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: int} # List of SCIM group mappings\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /scim/group-mappings\n@desc Create a SCIM group mapping\n@required {role: str(admin/member), scim_group_id: str(uuid), workspace_id: str(uuid)}\n@returns(201) {data: map{created_at: str, id: str(uuid), organization_id: str, role: str, scim_group_id: str(uuid), updated_at: str, workspace_id: str(uuid)}} # SCIM group mapping created\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 500: Internal Server Error - Unexpected server error}\n\n@endpoint DELETE /scim/group-mappings/{id}\n@desc Delete a SCIM group mapping\n@required {id: str(uuid), keep_members: any # Required. Whether to keep workspace members after deleting the mapping. `false` **removes** the members this mapping granted access to; `true` deletes the mapping while leaving membership intact as manually-managed. There is deliberately no default — omitting it returns `400` so the destructive path cannot be reached by accident. Mirrors the dashboard, whose `DeleteMappingSchema.keepMembers` is likewise required.}\n@returns(200) {deleted: bool} # SCIM group mapping deleted\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /scim/group-mappings/{id}\n@desc Get a SCIM group mapping\n@required {id: str(uuid)}\n@returns(200) {data: map{created_at: str, id: str(uuid), organization_id: str, role: str, scim_group_id: str(uuid), updated_at: str, workspace_id: str(uuid)}} # SCIM group mapping\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /scim/group-mappings/{id}\n@desc Update a SCIM group mapping\n@required {id: str(uuid), role: str(admin/member)}\n@returns(200) {data: map{created_at: str, id: str(uuid), organization_id: str, role: str, scim_group_id: str(uuid), updated_at: str, workspace_id: str(uuid)}} # SCIM group mapping updated\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /scim/groups\n@desc List SCIM groups\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100), display_name: str # Exact match filter on display_name. Omitted or empty returns groups unfiltered by name (subject to offset/limit). When external_id is also present, both must match., external_id: str # Exact match filter on external_id, e.g. the identity provider (such as Entra ID) group object ID. Omitted or empty returns groups unfiltered by external_id (subject to offset/limit). When display_name is also present, both must match.}\n@returns(200) {data: [map], total_count: int} # List of SCIM groups\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /scim/sync-jobs\n@desc Start a SCIM directory sync\n@returns(202) {data: map{created_at: str, deleted_groups: int?, error_message: str?, finished_at: str?, id: str(uuid), started_at: str?, status: str, synced_groups: int?}} # SCIM directory sync job queued\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /scim/sync-jobs/{id}\n@desc Get SCIM directory sync status\n@required {id: str(uuid)}\n@returns(200) {data: map{created_at: str, deleted_groups: int?, error_message: str?, finished_at: str?, id: str(uuid), started_at: str?, status: str, synced_groups: int?}} # SCIM directory sync job\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group systemone\n@endpoint POST /systemone\n@desc Submit a System One request\n@required {model: str, questions: map, state: any # The content to evaluate: a plain string, or a JSON object or array of related context.}\n@optional {assets: map # Images keyed by reference string, as in TypeSafe's API. Write a reference wherever the image belongs in `state`, `instructions`, or `criteria`; every asset must be referenced at least once, or the request fails with `400` naming the unused key. TypeSafe Jev endpoints receive `assets` as written and read a reference as a whole string value or inside longer text. Every other provider has each whole-string reference resolved to an `image_url` part before the request is sent, so it is accepted only where that provider reads `image_url` parts (top-level `state` items), and a reference inside longer text fails with `400`. `image_url` parts and `assets` can be mixed in one request., provider: any, session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., user: str}\n@returns(200) {annotations: [map], answers: map, id: str, model: str, provider: str, usage: map{cost: num(double), cost_details: map?, input_tokens: int, input_tokens_details: map{cached_tokens: int}, is_byok: bool, output_tokens: int}} # Decisions response\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 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}\n@example_request {\"model\":\"typesafe/jev-1.13\",\"questions\":{\"is_bug\":{\"criteria\":{\"false\":\"The customer is asking a question or requesting a feature.\",\"true\":\"The customer describes broken or unexpected product behavior.\"},\"instructions\":\"Is the customer reporting a software defect?\",\"type\":\"noul\"},\"team\":{\"criteria\":{\"account\":\"Login, permissions, or profile issues.\",\"frontend\":\"Rendering, layout, or browser compatibility issues.\",\"payments\":\"Checkout, billing, or payment processing issues.\"},\"instructions\":\"Which team should own this ticket?\",\"type\":\"choice\"},\"urgency\":{\"criteria\":[\"Can wait for the next release\",\"Should be fixed this week\",\"Blocking revenue right now\"],\"instructions\":\"How urgent is this ticket?\",\"type\":\"score\"}},\"state\":{\"customer_tier\":\"enterprise\",\"ticket\":\"My checkout page shows a blank screen after I click Pay. I have tried two browsers.\"}}\n\n@endgroup\n\n@group tools\n@endpoint GET /tools\n@desc List server tools\n@optional {offset: int=0 # Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned, limit: int=50 # Maximum number of records to return (max 100). When both offset and limit are omitted, the full list is returned, api_format: str(responses/chat-completions/anthropic-messages) # Only tools usable on this API format}\n@returns(200) {data: [map], links: map{next: str?}, total_count: int} # The server tool catalog\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /tools/{name}\n@desc Get a server tool\n@required {name: str # Canonical `openrouter:*` name or any accepted `tools[].type` alias}\n@returns(200) {data: any} # The server tool\n@errors {308: An alias was given; `Location` is the canonical tool URL, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group vault\n@endpoint GET /vault/interns/{internId}/connections\n@desc List the connections an intern can use\n@required {internId: str(uuid) # UUID of an intern in the workspace selected by the API key.}\n@returns(200) {data: [map], routing: map?, routing_text: str?} # The connections the intern can use.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n\n@endpoint GET /vault/interns/{internId}/effective-secrets\n@desc List the secrets an intern receives\n@required {internId: str(uuid) # UUID of an intern in the workspace selected by the API key.}\n@optional {limit: int=100 # Page size, 1 to 100. Defaults to 100., offset: int=0 # Number of secrets to skip, 0 to 10000. Defaults to 0.}\n@returns(200) {data: [map], has_more: bool} # One page of the secrets the intern receives.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n\n@endpoint GET /vault/interns/{internId}/secrets\n@desc List intern secrets\n@required {internId: str(uuid) # UUID of an intern in the workspace selected by the API key.}\n@optional {limit: int=100 # Page size, 1 to 100. Defaults to 100., offset: int=0 # Number of secrets to skip, 0 to 10000. Defaults to 0.}\n@returns(200) {data: [map], has_more: bool} # One page of secret metadata.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n\n@endpoint DELETE /vault/interns/{internId}/secrets/{name}\n@desc Delete an intern secret\n@required {internId: str(uuid) # UUID of an intern in the workspace selected by the API key., name: str # Existing secret name. Accepts legacy names stored before the 255-character write bound; new writes still require the documented name format.}\n@returns(204) Secret deleted. The response has no body.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 409: Conflict - The secret belongs to a connection (for example an MCP or GitHub connection) and can only be replaced or removed by reconnecting or disconnecting it., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n\n@endpoint PUT /vault/interns/{internId}/secrets/{name}\n@desc Store an intern secret\n@required {internId: str(uuid) # UUID of an intern in the workspace selected by the API key., name: str # Secret name. Lowercase letters, digits and single underscores, starting with a letter and not ending with an underscore, 1 to 255 characters., hosts: [str] # Exact DNS hostnames the secret may be sent to, 1 to 100 entries. Each entry is lowercased and a trailing dot is removed, so `API.Example.com.` is stored as `api.example.com`. Schemes, ports, paths, wildcards and empty values are rejected. Duplicates after normalization are collapsed. Matching is exact: a secret bound to `api.example.com` is never released to `example.com` or any other hostname., value: str # Secret value, 1 to 65536 characters; a header-set credential (a JSON object of header name to value) may run to 985721 characters. It is encrypted at rest and never returned.}\n@returns(200) {data: map{created_at: str(date-time), fingerprint: str?, hosts: [str]?, name: str}} # Metadata for the stored secret.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 409: Conflict - The secret belongs to a connection (for example an MCP or GitHub connection) and can only be replaced or removed by reconnecting or disconnecting it. Also returned while the intern is being transferred to another workspace and its vault has not moved yet., 413: Payload Too Large - The JSON body exceeds 1309643 bytes., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n@example_request {\"hosts\":[\"api.github.com\"],\"value\":\"ghp_exampleTokenValue\"}\n\n@endpoint POST /vault/interns/{internId}/secrets/copy\n@desc Copy workspace secrets to an intern\n@required {internId: str(uuid) # UUID of an intern in the workspace selected by the API key., names: [str] # Names of workspace secrets to copy, 1 to 100 unique entries. Every name must exist in the workspace scope.}\n@returns(200) {data: [map]} # Metadata for the copied secrets.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 409: Conflict - A named workspace secret has no hosts yet, the intern already holds a secret of that name that belongs to a connection, or the intern is being transferred to another workspace. Nothing is copied., 413: Payload Too Large - The JSON body exceeds 1309643 bytes., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n@example_request {\"names\":[\"github_token\"]}\n\n@endpoint GET /vault/secrets\n@desc List workspace secrets\n@optional {limit: int=100 # Page size, 1 to 100. Defaults to 100., offset: int=0 # Number of secrets to skip, 0 to 10000. Defaults to 0.}\n@returns(200) {data: [map], has_more: bool} # One page of secret metadata.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n\n@endpoint DELETE /vault/secrets/{name}\n@desc Delete a workspace secret\n@required {name: str # Existing secret name. Accepts legacy names stored before the 255-character write bound; new writes still require the documented name format.}\n@returns(204) Secret deleted. The response has no body.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 409: Conflict - The secret belongs to a connection (for example an MCP or GitHub connection) and can only be replaced or removed by reconnecting or disconnecting it., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n\n@endpoint PUT /vault/secrets/{name}\n@desc Store a workspace secret\n@required {name: str # Secret name. Lowercase letters, digits and single underscores, starting with a letter and not ending with an underscore, 1 to 255 characters., hosts: [str] # Exact DNS hostnames the secret may be sent to, 1 to 100 entries. Each entry is lowercased and a trailing dot is removed, so `API.Example.com.` is stored as `api.example.com`. Schemes, ports, paths, wildcards and empty values are rejected. Duplicates after normalization are collapsed. Matching is exact: a secret bound to `api.example.com` is never released to `example.com` or any other hostname., value: str # Secret value, 1 to 65536 characters; a header-set credential (a JSON object of header name to value) may run to 985721 characters. It is encrypted at rest and never returned.}\n@returns(200) {data: map{created_at: str(date-time), fingerprint: str?, hosts: [str]?, name: str}} # Metadata for the stored secret.\n@errors {400: Bad Request - The secret name, path, query or JSON body failed validation. The vault returns 400 for a malformed request as well., 401: Unauthorized - Missing or unknown API key. Provisioning keys cannot call vault routes., 403: Forbidden - The key has no usable workspace scope, or the request arrived on a regional hostname., 404: Not Found - The intern is not in the selected workspace or is not visible to the key (a member key without an admin role sees only interns its member created or interns in workspaces they administer), the secret does not exist in the selected scope, or the caller is outside the intern programme., 408: Request Timeout - The route deadline passed before the request completed, or the request body stopped arriving., 409: Conflict - The secret belongs to a connection (for example an MCP or GitHub connection) and can only be replaced or removed by reconnecting or disconnecting it., 413: Payload Too Large - The JSON body exceeds 1309643 bytes., 429: Too Many Requests - The vault rate limit was reached., 500: Internal Server Error - Scope lookup failed., 502: Bad Gateway - The vault could not be reached or returned an unexpected response., 503: Service Unavailable - Vault writes are disabled for the caller, or the vault is not configured., 504: Gateway Timeout - The vault did not answer in time.}\n@example_request {\"hosts\":[\"api.github.com\"],\"value\":\"ghp_exampleTokenValue\"}\n\n@endgroup\n\n@group videos\n@endpoint POST /videos\n@desc Submit a video generation request\n@required {model: str}\n@optional {aspect_ratio: str(16:9/9:16/1:1/4:3/3:4/3:2/2:3/21:9/9:21/2:1/5:2) # Aspect ratio of the generated video. Omit it to use the model default, which on models with adaptive aspect ratio (e.g. BytePlus Seedance) follows the input image or video., callback_url: str(uri) # URL to receive a webhook notification when the video generation job completes. Overrides the workspace-level default callback URL if set. Must be HTTPS., creativity: int # Creativity level for video upscaling models only. This parameter is not supported by video generation models., duration: int # Duration of the generated video in seconds, or -1 to let the provider choose the length (e.g. following an input video). -1 is only accepted by models that list it in supported_durations., frame_images: [any] # Images to use as the first and/or last frame of the generated video. Each image must specify a frame_type of first_frame or last_frame., generate_audio: bool # Whether to generate audio alongside the video. Defaults to the endpoint's generate_audio capability flag, false if not set. When neither is set, some providers (such as xAI) apply their own default and generate audio, so send false to request a silent video. Some models always include audio and ignore false., input_references: [any] # Reference assets to guide video generation. Accepts image, audio, and video references. Audio and video references are only honored by providers that support them (including BytePlus Seedance generation 2 and newer); other providers use image references and ignore the rest., previous_job_id: str # ID of a completed video job to edit or extend, as returned by the submit response. The new job runs on the same model and endpoint that produced the previous one. Only models that support continuation accept this field., prompt: str # Text prompt describing the video to generate. Optional for models that support generating a video from image input alone; required by all other models., provider: map{data_collection: str, ignore: [any], only: [any], options: any, order: [any], zdr: bool} # Provider routing preferences (order, only, ignore), request-level data policy (zdr, data_collection) and provider-specific passthrough configuration. No video endpoint currently offers Zero Data Retention, so `zdr: true` fails routing., resolution: str(360p/480p/720p/768p/1080p/1K/2K/4K) # Resolution of the generated video, seed: int # If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers., session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., size: str # Exact pixel dimensions of the generated video in \"WIDTHxHEIGHT\" format (e.g. \"1280x720\"). Interchangeable with resolution + aspect_ratio., trace: map{generation_name: str, parent_span_id: str, span_name: str, trace_id: str, trace_name: str} # 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., upscale_factor: num(double) # Upscale factor for video upscaling models only. This parameter is not supported by video generation models., user: str # A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.}\n@returns(202) {error: str, expires_at: int, generation_id: str, id: str, polling_url: str, status: str, unsigned_urls: [str], urls: [str], usage: map{cost: num(double)?, is_byok: bool}} # Video generation request accepted\n@errors {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, 404: Not Found - Resource does not exist, 413: Payload Too Large - Request payload exceeds size limits, 429: Too Many Requests - Rate limit exceeded, 499: Client Closed Request - The caller cancelled the request, 500: Internal Server Error - Unexpected server error, 503: Service Unavailable - Service temporarily unavailable}\n@example_request {\"aspect_ratio\":\"16:9\",\"duration\":8,\"model\":\"google/veo-3.1\",\"prompt\":\"A serene mountain landscape at sunset\",\"resolution\":\"720p\"}\n\n@endpoint GET /videos/{jobId}\n@desc Poll video generation status\n@required {jobId: str}\n@returns(200) {error: str, expires_at: int, generation_id: str, id: str, polling_url: str, status: str, unsigned_urls: [str], urls: [str], usage: map{cost: num(double)?, is_byok: bool}} # Video generation status\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /videos/{jobId}/content\n@desc Download generated video content\n@required {jobId: str}\n@optional {index: int=0}\n@returns(200) Video content stream. The body is the raw video bytes proxied from the upstream provider, and the Content-Type reflects the provider media type (video/mp4).\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 409: Conflict - Resource conflict or concurrent modification, 410: Gone - Endpoint has been permanently removed or deprecated, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure}\n\n@endpoint GET /videos/models\n@desc List all video generation models\n@returns(200) {data: [map]} # Returns a list of video generation models\n@errors {400: Bad Request - Invalid request parameters or malformed input, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group workspaces\n@endpoint GET /workspaces\n@desc List workspaces\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: int} # List of workspaces\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /workspaces\n@desc Create a workspace\n@required {name: str # Name for the new workspace, slug: str # URL-friendly slug (lowercase alphanumeric segments separated by single hyphens, no leading/trailing hyphens)}\n@optional {default_image_model: str # Default image model for this workspace, default_provider_sort: str # Default provider sort preference (price, throughput, latency, exacto), default_text_model: str # Default text model for this workspace, description: str # Description of the workspace, disabled_server_tools: [str] # OpenRouter server tools that requests in this workspace may not invoke. Requests naming a disabled tool are rejected with 403. An empty array or null clears the list., io_logging_api_key_ids: [int] # Optional array of API key IDs to filter I/O logging, io_logging_sampling_rate: num(double) # Sampling rate for I/O logging (0.0001-1), is_data_discount_logging_enabled: bool # Whether data discount logging is enabled. Enabling it requires the account to allow workspace data-discount logging; otherwise the request returns 403., is_observability_broadcast_enabled: bool # Whether broadcast is enabled, is_observability_io_logging_enabled: bool # Whether private logging is enabled}\n@returns(201) {data: any} # Workspace created successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n@example_request {\"default_image_model\":\"openai/dall-e-3\",\"default_provider_sort\":\"price\",\"default_text_model\":\"openai/gpt-4o\",\"description\":\"Production environment workspace\",\"name\":\"Production\",\"slug\":\"production\"}\n\n@endpoint DELETE /workspaces/{id}\n@desc Delete a workspace\n@required {id: str # The workspace ID (UUID) or slug}\n@optional {confirm_default_workspace_deletion: bool(true/false) # Required to delete the default workspace. Deleting it permanently disables the account’s unscoped inference API keys (management/provisioning keys are retained) and its budgets, guardrails, classifiers, and broadcast destinations. Ignored for non-default workspaces.}\n@returns(200) {deleted: bool} # Workspace deleted successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /workspaces/{id}\n@desc Get a workspace\n@required {id: str # The workspace ID (UUID) or slug}\n@returns(200) {data: any} # Workspace details\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PATCH /workspaces/{id}\n@desc Update a workspace\n@required {id: str # The workspace ID (UUID) or slug}\n@optional {default_image_model: str # Default image model for this workspace, default_provider_sort: str # Default provider sort preference (price, throughput, latency, exacto), default_text_model: str # Default text model for this workspace, description: str # New description for the workspace, disabled_server_tools: [str] # OpenRouter server tools that requests in this workspace may not invoke. Requests naming a disabled tool are rejected with 403. An empty array or null clears the list., io_logging_api_key_ids: [int] # Optional array of API key IDs to filter I/O logging, io_logging_sampling_rate: num(double) # Sampling rate for I/O logging (0.0001-1), is_data_discount_logging_enabled: bool # Whether data discount logging is enabled. Enabling it requires the account to allow workspace data-discount logging; otherwise the request returns 403., is_observability_broadcast_enabled: bool # Whether broadcast is enabled, is_observability_io_logging_enabled: bool # Whether private logging is enabled, name: str # New name for the workspace, slug: str # New URL-friendly slug (lowercase alphanumeric segments separated by single hyphens, no leading/trailing hyphens)}\n@returns(200) {data: any} # Workspace updated successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"name\":\"Updated Workspace\",\"slug\":\"updated-workspace\"}\n\n@endpoint GET /workspaces/{id}/members\n@desc List workspace members\n@required {id: str # The workspace ID (UUID) or slug}\n@optional {offset: int=0 # Number of records to skip for pagination, limit: int=50 # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: int} # List of workspace members\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /workspaces/{id}/members/add\n@desc Bulk add members to a workspace\n@required {id: str # The workspace ID (UUID) or slug, user_ids: [str] # List of user IDs to add to the workspace. New members are assigned the workspace role that matches their organization role; users already in the workspace keep their current role.}\n@returns(200) {added_count: int, data: [map]} # Members added successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"user_ids\":[\"user_abc123\",\"user_def456\"]}\n\n@endpoint POST /workspaces/{id}/members/remove\n@desc Bulk remove members from a workspace\n@required {id: str # The workspace ID (UUID) or slug, user_ids: [str] # List of user IDs to remove from the workspace}\n@returns(200) {removed_count: int} # Members removed successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"user_ids\":[\"user_abc123\",\"user_def456\"]}\n\n@endpoint GET /workspaces/{workspace_ref}/budgets\n@desc List workspace budgets\n@required {workspace_ref: str # The workspace ID (UUID) or slug}\n@returns(200) {data: [map], include_byok_in_budgets: bool} # Budgets retrieved successfully\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint DELETE /workspaces/{workspace_ref}/budgets/{interval}\n@desc Delete a workspace budget\n@required {workspace_ref: str # The workspace ID (UUID) or slug, interval: str # Budget reset interval. Use \"lifetime\" for a one-time budget that never resets.}\n@returns(200) {deleted: bool} # Budget deleted successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint GET /workspaces/{workspace_ref}/budgets/{interval}\n@desc Get a workspace budget\n@required {workspace_ref: str # The workspace ID (UUID) or slug, interval: str # Budget reset interval. Use \"lifetime\" for a one-time budget that never resets.}\n@returns(200) {data: any, include_byok_in_budgets: bool} # Budget retrieved successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endpoint PUT /workspaces/{workspace_ref}/budgets/{interval}\n@desc Create or update a workspace budget\n@required {workspace_ref: str # The workspace ID (UUID) or slug, interval: str # Budget reset interval. Use \"lifetime\" for a one-time budget that never resets., limit_usd: num(double) # Spending limit in USD. Must be greater than 0.}\n@optional {include_byok_in_budgets: bool # Whether to include BYOK (bring-your-own-key) spend when enforcing the workspace's budgets. This is a workspace-wide setting: it applies to every budget interval (daily, weekly, monthly, and lifetime), not just the interval being upserted in this request. Omit to leave the current setting unchanged.}\n@returns(200) {data: any, include_byok_in_budgets: bool} # Budget created or updated successfully\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Authentication successful but insufficient permissions, 404: Not Found - Resource does not exist, 500: Internal Server Error - Unexpected server error}\n@example_request {\"include_byok_in_budgets\":true,\"limit_usd\":100}\n\n@endgroup\n\n@end\n"}