From 50a58bf870680e0910348e1d9a952f7d56ade6ca Mon Sep 17 00:00:00 2001 From: OpenRouter SDK Bot Date: Fri, 23 Oct 2026 17:56:09 +0000 Subject: [PATCH] chore: update OpenAPI spec [sdk-bot] --- .speakeasy/in.openapi.yaml | 17696 ++++++++++++++--------------------- 1 file changed, 7159 insertions(+), 10537 deletions(-) diff --git a/.speakeasy/in.openapi.yaml b/.speakeasy/in.openapi.yaml index 447d4728..924e2ab1 100644 --- a/.speakeasy/in.openapi.yaml +++ b/.speakeasy/in.openapi.yaml @@ -8093,6 +8093,7 @@ components: type: 'string' required: - 'error_type' + title: 'ChatStreamChunkMetadata' type: 'object' required: - 'message' @@ -9969,47 +9970,6 @@ components: required: - 'data' type: 'object' - CreateInternRequest: - additionalProperties: false - description: 'Settings for a new intern.' - example: - name: 'research-assistant' - provision: true - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - properties: - description: - description: 'Free-form description, or null.' - maxLength: 2000 - type: - - 'string' - - 'null' - instructions: - description: 'Standing instructions the intern boots with, or null.' - maxLength: 100000 - type: - - 'string' - - 'null' - name: - description: 'Intern name, unique per creator within the workspace.' - maxLength: 17 - minLength: 2 - pattern: '^[a-z][a-z0-9]*(-[a-z0-9]+)*$' - type: 'string' - provision: - default: false - description: 'Start provisioning during this create operation. Defaults to false.' - type: 'boolean' - vault_id: - description: 'Vault owned by another intern in this workspace to attach as a borrowed vault.' - format: 'uuid' - type: 'string' - workspace_id: - description: 'Workspace that will own the intern. Defaults to the workspace the API key resolves to. When given, it must match the API key workspace.' - format: 'uuid' - type: 'string' - required: - - 'name' - type: 'object' CreateObservabilityDestinationRequest: example: config: @@ -11145,26 +11105,6 @@ components: required: - 'deleted' type: 'object' - DeleteInternRequest: - additionalProperties: false - description: 'Optional consent for a teardown that discards the workspace.' - example: - acknowledge_workspace_loss: true - properties: - acknowledge_workspace_loss: - default: false - description: 'Delete even though the workspace backup was not confirmed. Defaults to false, which refuses the teardown when a workspace archive is missing.' - type: 'boolean' - type: 'object' - DeleteInternResponse: - additionalProperties: false - properties: - deleting: - const: true - type: 'boolean' - required: - - 'deleting' - type: 'object' DeleteObservabilityDestinationResponse: example: deleted: true @@ -15038,135 +14978,6 @@ components: type: - 'string' - 'null' - Intern: - description: 'Public lifecycle state and settings for one intern.' - example: - attached_vault_id: null - can_edit: true - created_at: '2026-09-16T08:30:00.000Z' - created_by_you: true - description: 'Researches customer questions' - hostname: 'research-assistant.openrouter.ai' - icon_sha256: null - id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - instructions: null - last_failure_message: null - model: 'openai/gpt-5.4' - name: 'research-assistant' - progress: null - status: 'running' - updated_at: '2026-09-16T08:45:00.000Z' - vault_id: 'b431c59d-6eed-41ac-bc89-9a89be79a121' - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - properties: - attached_vault_id: - description: 'Vault the intern borrows from another intern, or null when it borrows none.' - type: - - 'string' - - 'null' - can_edit: - description: 'Whether this key may change the intern (update, provision, suspend, delete). Present on list and retrieve; false while lifecycle writes are closed for the account.' - type: 'boolean' - created_at: - description: 'ISO 8601 creation time.' - type: 'string' - created_by_you: - description: 'Whether the user behind the key created the intern. Present on list and retrieve; absent for organization keys, which act for no user.' - type: 'boolean' - description: - description: 'Free-form description.' - type: - - 'string' - - 'null' - hostname: - description: 'Public hostname the intern is reachable at, or null until provisioning has assigned one.' - type: - - 'string' - - 'null' - icon_sha256: - description: 'SHA-256 of the intern icon, or null when it has none. Present on list and retrieve; fetch the bytes from `GET /api/v1/interns/{intern_id}/icon`.' - type: - - 'string' - - 'null' - id: - description: 'Intern id.' - type: 'string' - instructions: - description: 'Standing instructions the intern boots with.' - type: - - 'string' - - 'null' - last_failure_message: - description: 'Why the last provisioning attempt failed, when status is failed.' - type: - - 'string' - - 'null' - model: - description: 'OpenRouter model slug the intern runs, or null for the workspace default.' - type: - - 'string' - - 'null' - name: - description: 'Intern name, unique per creator within a workspace.' - type: 'string' - progress: - description: 'Active provisioning step, or null once provisioning has settled.' - properties: - step_label: - description: 'Human-readable label of the active provisioning step.' - type: 'string' - step_number: - description: 'One-based index of the active step.' - type: 'integer' - total_steps: - description: 'Number of provisioning steps.' - type: 'integer' - required: - - 'step_label' - - 'step_number' - - 'total_steps' - type: - - 'object' - - 'null' - status: - description: 'Lifecycle status.' - enum: - - 'awaiting_slack_install' - - 'queued' - - 'provisioning' - - 'running' - - 'failed' - - 'stopped' - - 'destroying' - - 'destroy_failed' - type: 'string' - updated_at: - description: 'ISO 8601 last update time.' - type: 'string' - vault_id: - description: 'Vault the intern owns, or null before it has been created.' - type: - - 'string' - - 'null' - workspace_id: - description: 'Workspace that owns the intern and scopes its secrets.' - type: 'string' - required: - - 'id' - - 'name' - - 'description' - - 'instructions' - - 'model' - - 'status' - - 'last_failure_message' - - 'progress' - - 'hostname' - - 'workspace_id' - - 'vault_id' - - 'attached_vault_id' - - 'created_at' - - 'updated_at' - type: 'object' InternalServerResponse: description: 'Internal Server Error - Unexpected server error' example: @@ -15207,3742 +15018,2942 @@ components: - 'code' - 'message' type: 'object' - InternApprovalMode: - description: 'How the run started by this prompt handles tool approvals. `self-drive` (the default when omitted) consents on your behalf and runs the shell unsandboxed. `manual` asks you before an approval-bearing tool runs, as an `openrouter.provide_input` permission request, and keeps the shell sandboxed until an escalation is allowed. The mode applies to the run this prompt starts and is not remembered by the session. Repeat it on each new prompt that should use it. A `tool` reply continues the run under the mode it started with.' - enum: - - 'manual' - - 'self-drive' - example: 'manual' - type: 'string' - InternChatAssistantMessage: - description: 'An assistant message from an earlier response. When answering an interaction, echo the streamed `tool_calls` here before the `tool` message.' - example: - content: null - role: 'assistant' - tool_calls: - - function: - arguments: '{"kind":"permission","operation":"shell","options":["allow_once","reject_once"]}' - name: 'openrouter.provide_input' - id: '15e90ad6-5320-4a59-af4f-b371428154fa' - properties: - content: - $ref: '#/components/schemas/InternChatMessageContent' - role: - enum: - - 'assistant' - type: 'string' - tool_calls: - items: - $ref: '#/components/schemas/InternChatEchoedToolCall' - type: 'array' - required: - - 'role' - type: 'object' - InternChatChoice: - description: 'The single choice this endpoint streams.' - example: - delta: - content: 'Hello' - finish_reason: null - index: 0 - properties: - delta: - $ref: '#/components/schemas/InternChatDelta' - finish_reason: - description: '`null` while streaming. `stop` when the run completed, `tool_calls` when the run is waiting for the caller to answer the streamed tool call, `error` on the terminal error chunk.' - enum: - - 'error' - - 'stop' - - 'tool_calls' - - null - type: - - 'string' - - 'null' - index: - type: 'integer' - required: - - 'delta' - - 'finish_reason' - - 'index' - type: 'object' - InternChatCompletionChunk: - description: 'One `data:` line of the stream. A run streams a role chunk, content and reasoning chunks, then a finish chunk: `stop`, `tool_calls` (the run is paused for input) or `error` (with an `error` object). A final chunk with empty `choices` follows in every case, carrying `session_id` and `usage` (`null` unless the daemon reported usage, and always `null` after `tool_calls`). Every stream ends with `[DONE]`.' + ItemReferenceItem: + description: 'A reference to a previous response item by ID' example: - choices: - - delta: - content: 'Hello' - finish_reason: null - index: 0 - created: 1789537541 - id: 'chatcmpl-f727571a-3bad-4e0d-8a9e-f18f8cda9750' - model: 'openrouter/intern' - object: 'chat.completion.chunk' + id: 'msg-abc123' + type: 'item_reference' properties: - choices: - description: 'One choice on content, tool-call and error chunks. Empty on the final chunk that carries `session_id`.' - items: - $ref: '#/components/schemas/InternChatChoice' - type: 'array' - created: - type: 'integer' - error: - $ref: '#/components/schemas/InternChatStreamError' id: - description: 'The completion id, constant for the whole response.' - example: 'chatcmpl-f727571a-3bad-4e0d-8a9e-f18f8cda9750' - type: 'string' - model: - description: 'The runtime''s identifier for the model the intern is running, as the intern reports it. Each chunk carries the model from the event behind it: `openrouter/intern` on chunks emitted before the intern has reported one and on chunks the API emits itself (timeout, run-ended and severed-stream errors and their final usage chunk), even after an earlier chunk named a model. It can change within a stream. It is not an OpenRouter model slug, and the request `model` is never used.' type: 'string' - object: + type: enum: - - 'chat.completion.chunk' + - 'item_reference' type: 'string' - session_id: - description: 'On the final chunk of every response, the daemon session to continue with, or `null` when the run failed before the intern reported one. Send it as `session_id` on the next request, including the `tool` reply to an interaction. Session ids are client-visible and scoped to the intern''s own daemon.' - example: 'ses_7f3c9a' - type: - - 'string' - - 'null' - usage: - $ref: '#/components/schemas/InternChatUsage' required: - - 'choices' - - 'created' + - 'type' - 'id' - - 'model' - - 'object' type: 'object' - InternChatCompletionRequest: - description: 'An OpenAI-compatible streaming chat completion request for one intern. Other OpenAI fields such as `temperature` or `tools` are ignored. The intern owns its sampling and its tools.' + JevRouterPlugin: + additionalProperties: false example: - approval_mode: 'manual' - messages: - - content: 'Summarize the open pull requests.' - role: 'user' - stream: true + excluded_models: + - 'openai/gpt-6-astra' + id: 'jev-router' + models: + - 'anthropic/*' + - 'openai/gpt-5.6-sol' properties: - approval_mode: - $ref: '#/components/schemas/InternApprovalMode' - messages: - description: 'The conversation. Only the last message is read. A last `user` message starts a run. A last `tool` message answers the interaction named by its `tool_call_id` and requires `session_id`.' + allowed_models: + description: 'Alias of `models`, matching the auto-router field name. Entries from both fields are combined.' + example: + - 'anthropic/*' items: - $ref: '#/components/schemas/InternChatMessage' - minItems: 1 + maxLength: 1024 + type: 'string' + maxItems: 1024 type: 'array' - model: - description: 'Accepted for OpenAI compatibility and never used. The intern runs the model configured on it (`PATCH` the intern to change it). Streamed chunks report the runtime''s identifier for that model as the intern reports it, or `openrouter/intern` on chunks whose event carries no model (before the intern reports one, and on the chunks the API emits itself: the timeout, run-ended and severed-stream error chunks, the stop chunk of a replay that ends without a terminal daemon event, and the final usage chunk after any of them). A usage chunk that follows a daemon completion event carries the model the intern reported.' - example: 'openrouter/intern' - maxLength: 256 - minLength: 1 - type: 'string' - session_id: - description: 'The daemon session to continue, as returned in `session_id` on the final chunk of an earlier response. Omit it to start a new session. An id the intern has not seen before is not an error: it starts a new session under that id, so a mistyped id forks the conversation. Sessions are scoped to the intern''s own daemon. Required when the last message has role `tool`.' - example: 'ses_7f3c9a' - maxLength: 256 - minLength: 1 - type: 'string' - stream: - const: true - description: 'Must be `true`. This endpoint only streams. `false` or an omitted `stream` is refused with `400` and reason `bad_request`.' - example: true - type: 'boolean' - required: - - 'messages' - - 'stream' - type: 'object' - InternChatDelta: - description: 'The incremental content of one chunk. The first chunk carries `role`, text chunks carry `content`, reasoning chunks carry `reasoning`, and an interaction chunk carries one complete `tool_calls` entry.' - example: - content: 'Hello' - properties: - content: - type: 'string' - reasoning: - type: 'string' - role: - enum: - - 'assistant' + cost_tier: + description: 'Select low, medium, high, or a cost tier configured by the operator. Overrides the live-config tier and replaces the shared routing policy with that tier. Omit to use the live configuration. Model exclusions and the router kill switch still apply.' + example: 'medium' + pattern: '^[a-z][a-z0-9_-]{0,31}$' type: 'string' - tool_calls: + excluded_models: + description: 'Remove these models from the router. Each entry is a model slug or a wildcard pattern (e.g. "xiaomi/*"). A `~author/family-latest` alias matches every revision of that family. Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. Applied after `models`, so an excluded pattern always wins over an included one; when the lists leave no model the request can use, it fails with 404 rather than routing outside them.' + example: + - 'openai/gpt-6-astra' + - 'xiaomi/*' items: - $ref: '#/components/schemas/InternChatToolCall' + maxLength: 1024 + type: 'string' + maxItems: 1024 type: 'array' - type: 'object' - InternChatDeveloperMessage: - description: 'A developer message. Accepted for client compatibility and not forwarded.' - example: - content: 'Answer briefly.' - role: 'developer' - properties: - content: - $ref: '#/components/schemas/InternChatMessageContent' - role: + id: enum: - - 'developer' + - 'jev-router' type: 'string' + models: + description: 'Restrict the router to these models. Each entry is a model slug or a wildcard pattern (e.g. "anthropic/*"), matched against the current pool; models outside the pool are ignored. A `~author/family-latest` alias matches every revision of that family. Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. When omitted or empty, every model in the pool is a candidate; when no pool model matches, the list is ignored and the whole pool is used (`excluded_models` still apply). `allowed_models` is an alias; entries from both fields are combined.' + example: + - 'anthropic/*' + - 'openai/gpt-5.6-sol' + items: + maxLength: 1024 + type: 'string' + maxItems: 1024 + type: 'array' required: - - 'content' - - 'role' + - 'id' type: 'object' - InternChatEchoedToolCall: - description: 'The `openrouter.provide_input` tool call from the previous response, echoed back unchanged. Its `id` is the interaction the following `tool` message answers.' + KeyAssignment: example: - function: - arguments: '{"kind":"permission","operation":"shell","options":["allow_once","reject_once"]}' - name: 'openrouter.provide_input' - id: '15e90ad6-5320-4a59-af4f-b371428154fa' + assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' + key_label: 'prod-key' + key_name: 'Production Key' properties: - function: - $ref: '#/components/schemas/InternChatEchoedToolCallFunction' + assigned_by: + description: 'User ID of who made the assignment' + example: 'user_abc123' + type: + - 'string' + - 'null' + created_at: + description: 'ISO 8601 timestamp of when the assignment was created' + example: '2025-08-24T10:30:00Z' + type: 'string' + guardrail_id: + description: 'ID of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440001' + format: 'uuid' + type: 'string' id: - maxLength: 128 - minLength: 1 + description: 'Unique identifier for the assignment' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' - required: - - 'function' - - 'id' - type: 'object' - InternChatEchoedToolCallFunction: - description: 'The function name and JSON arguments string exactly as streamed.' - example: - arguments: '{"kind":"permission","operation":"shell","options":["allow_once","reject_once"]}' - name: 'openrouter.provide_input' - properties: - arguments: + key_hash: + description: 'Hash of the assigned API key' + example: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' type: 'string' - name: + key_label: + description: 'Label of the API key' + example: 'prod-key' type: 'string' - required: - - 'arguments' - - 'name' - type: 'object' - InternChatError: - description: 'The OpenAI-compatible error object. `metadata` is present on refusals from the chat route. Authentication refusals (`401`), the departed-creator `403` and the programme `404` carry only `code` and `message`.' - example: - code: 409 - message: 'That question is no longer waiting for an answer.' - metadata: - reason: 'interaction_not_pending' - retryable: false - properties: - code: - description: 'The HTTP status of the response.' - type: 'integer' - message: + key_name: + description: 'Name of the API key' + example: 'Production Key' type: 'string' - metadata: - $ref: '#/components/schemas/InternChatErrorMetadata' required: - - 'code' - - 'message' + - 'id' + - 'key_hash' + - 'guardrail_id' + - 'key_name' + - 'key_label' + - 'assigned_by' + - 'created_at' type: 'object' - InternChatErrorMetadata: - description: 'Machine-readable detail for the failure.' + KeyBudget: + description: 'One budget layer that applies to requests made with this key, with the spend enforcement compares against it.' example: - reason: 'interaction_not_pending' - retryable: false + budget_id: null + guardrail_id: '0df9e665-d932-5740-b2c7-b52af166bc11' + include_byok: false + limit_usd: 50 + remaining_usd: 17.5 + reset_interval: 'weekly' + resets_at: '2026-10-12T00:00:00.000Z' + scope: 'member' + spend_usd: 32.5 properties: - reason: - description: 'A stable reason a client can branch on.' - enum: - - 'attachment_failed' - - 'bad_request' - - 'busy' - - 'client_closed_request' - - 'interaction_not_pending' - - 'interaction_unknown' - - 'intern_not_ready' - - 'intern_rejected' - - 'intern_unreachable' - - 'not_found' - - 'payload_too_large' - - 'rate_limited' - - 'run_ended' - - 'stream_severed' - - 'timeout' - - 'turn_failed' - type: 'string' - retryable: - description: 'Whether the same request may be sent again unchanged. Always `true` for the transient refusals — `busy`, `intern_not_ready`, `intern_unreachable`, `rate_limited`, `stream_severed` and `timeout` — and always `false` for the ones a retry cannot fix. For `turn_failed` it varies by failure and is the intern''s own classification of what went wrong: `true` for an upstream overload, rate limit, timeout or transport fault, `false` for an authentication or bad-request failure that would be rejected the same way again. Branch on this field rather than on `reason` when deciding whether to retry. A `429`, and a `409` or `503` with reason `busy`, also carry a `Retry-After` header saying how long to wait.' + budget_id: + description: 'ID of the workspace budget for the `workspace` scope; null for other scopes.' + example: null + type: + - 'string' + - 'null' + guardrail_id: + description: 'ID of the guardrail that carries this budget; null for other scopes.' + example: '0df9e665-d932-5740-b2c7-b52af166bc11' + type: + - 'string' + - 'null' + include_byok: + description: 'Whether external BYOK inference spend counts toward this budget.' + example: false type: 'boolean' + limit_usd: + description: 'Budget limit in USD for the current window.' + example: 50 + format: 'double' + type: 'number' + remaining_usd: + description: '`limit_usd - spend_usd`. Zero or negative means this layer rejects requests with a 403 until it resets.' + example: 17.5 + format: 'double' + type: 'number' + reset_interval: + description: 'UTC window the spend is counted over (weeks start Monday); null for a lifetime budget that never resets.' + enum: + - 'daily' + - 'weekly' + - 'monthly' + - null + example: 'weekly' + type: + - 'string' + - 'null' + resets_at: + description: 'ISO 8601 UTC instant at which the window rolls over and spend returns to zero; null for a lifetime budget.' + example: '2026-10-12T00:00:00.000Z' + format: 'date-time' + type: + - 'string' + - 'null' + scope: + description: 'Which budget layer this is, in the order enforcement checks them: the workspace default guardrail against the member aggregate (`workspace_default_member`) and against this key (`workspace_default_key`), the member guardrail (`member`), the API key guardrail (`api_key`), a workspace budget (`workspace`), or the key''s own limit (`key_limit`).' + enum: + - 'workspace_default_member' + - 'workspace_default_key' + - 'member' + - 'api_key' + - 'workspace' + - 'key_limit' + example: 'member' + type: 'string' + spend_usd: + description: 'Spend in USD that enforcement counts against this limit in the current window: the member aggregate for member-scoped layers, otherwise this key or workspace.' + example: 32.5 + format: 'double' + type: 'number' required: - - 'reason' - - 'retryable' - type: 'object' - InternChatErrorResponse: - description: 'A refusal before the stream opens. Once the response is `200` and streaming, failures arrive as a chunk with `finish_reason: "error"` instead.' - example: - error: - code: 409 - message: 'That question is no longer waiting for an answer.' - metadata: - reason: 'interaction_not_pending' - retryable: false - properties: - error: - $ref: '#/components/schemas/InternChatError' - required: - - 'error' + - 'scope' + - 'guardrail_id' + - 'budget_id' + - 'limit_usd' + - 'spend_usd' + - 'remaining_usd' + - 'reset_interval' + - 'resets_at' + - 'include_byok' type: 'object' - InternChatMessage: - description: 'One OpenAI-compatible chat message, discriminated by `role`.' - discriminator: - mapping: - assistant: '#/components/schemas/InternChatAssistantMessage' - developer: '#/components/schemas/InternChatDeveloperMessage' - system: '#/components/schemas/InternChatSystemMessage' - tool: '#/components/schemas/InternChatToolMessage' - user: '#/components/schemas/InternChatUserMessage' - propertyName: 'role' - example: - content: 'Summarize the open pull requests.' - role: 'user' - oneOf: - - $ref: '#/components/schemas/InternChatSystemMessage' - - $ref: '#/components/schemas/InternChatDeveloperMessage' - - $ref: '#/components/schemas/InternChatUserMessage' - - $ref: '#/components/schemas/InternChatAssistantMessage' - - $ref: '#/components/schemas/InternChatToolMessage' - InternChatMessageContent: - anyOf: - - type: 'string' - - items: - $ref: '#/components/schemas/InternChatTextPart' - type: 'array' - - type: 'null' - description: 'Message text as a string or a list of text parts. Assistant history may carry null. Only the last message is read; earlier messages are accepted so ordinary clients can resend history.' - example: 'Summarize the open pull requests.' - InternChatPromptTokensDetails: - description: 'Prompt tokens served from cache, when the daemon reported them.' + Legacy_ChatContentVideo: + deprecated: true + description: 'Video input content part (legacy format - deprecated)' example: - cached_tokens: 1024 + type: 'input_video' + video_url: + url: 'https://example.com/video.mp4' properties: - cached_tokens: - type: 'integer' + type: + enum: + - 'input_video' + type: 'string' + video_url: + $ref: '#/components/schemas/Legacy_ChatContentVideoInput' required: - - 'cached_tokens' + - 'type' + - 'video_url' type: 'object' - InternChatSteeredResponse: - description: 'The message was delivered into the turn already running on the same session. Its effect is streamed on that turn, not here.' + Legacy_ChatContentVideoInput: + description: 'Video input object' example: - session_id: 'sess_01j9x0k4q7v8r2t3m6n5p8w9y1' - status: 'steered' + url: 'https://example.com/video.mp4' properties: - session_id: - description: 'The session of the running turn the message was delivered to.' - example: 'sess_01j9x0k4q7v8r2t3m6n5p8w9y1' - type: 'string' - status: - description: 'The message was handed to the turn already running on this session.' + processing: + description: 'Video processing mode. `agentic` enables agentic video processing and `static` forces fixed-rate frame sampling on providers that support it (currently Google Gemini).' enum: - - 'steered' + - 'agentic' + - 'static' + example: 'agentic' + type: 'string' + url: + description: 'URL of the video (data: URLs supported)' type: 'string' required: - - 'session_id' - - 'status' + - 'url' type: 'object' - InternChatStreamError: - description: 'A failure after the response headers were sent. The chunk that carries it has `finish_reason: "error"`, then the final empty-`choices` chunk and `[DONE]` follow. Reasons here are `attachment_failed`, `busy`, `client_closed_request`, `interaction_not_pending`, `interaction_unknown`, `intern_unreachable`, `run_ended`, `stream_severed`, `timeout` or `turn_failed`. `run_ended` reports an ending the intern confirmed, such as a cancellation or a deadline, while `stream_severed` reports a connection lost without that confirmation.' + Legacy_WebSearchServerTool: + description: 'Web search tool configuration' example: - code: 502 - message: 'The intern could not continue this run.' - metadata: - reason: 'attachment_failed' - retryable: false + engine: 'auto' + filters: + allowed_domains: + - 'example.com' + type: 'web_search' properties: - code: - description: 'The HTTP status this failure would have had before the stream opened.' + engine: + $ref: '#/components/schemas/WebSearchEngineEnum' + filters: + $ref: '#/components/schemas/WebSearchDomainFilter' + max_results: + description: 'Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped.' + example: 5 type: 'integer' - message: + max_uses: + description: 'Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded only to Anthropic (as `max_uses`); other native search providers have no equivalent parameter and ignore it.' + example: 3 + type: 'integer' + mode: + $ref: '#/components/schemas/WebSearchMode' + search_context_size: + $ref: '#/components/schemas/SearchContextSizeEnum' + type: + enum: + - 'web_search' type: 'string' - metadata: - $ref: '#/components/schemas/InternChatErrorMetadata' + user_location: + $ref: '#/components/schemas/WebSearchUserLocation' + x_search: + $ref: '#/components/schemas/XSearchOptions' required: - - 'code' - - 'message' - - 'metadata' + - 'type' type: 'object' - InternChatStreamingResponse: - description: 'A server-sent event carrying one chunk. The stream ends with `data: [DONE]`.' + ListBYOKKeysResponse: example: data: - choices: - - delta: - tool_calls: - - function: - arguments: '{"fields":[{"name":"answer","options":["red","blue","Other"],"required":true,"type":"string"}],"kind":"elicitation","message":"Which colour do you prefer?"}' - name: 'openrouter.provide_input' - id: '15e90ad6-5320-4a59-af4f-b371428154fa' - index: 0 - type: 'function' - finish_reason: null - index: 0 - created: 1789537541 - id: 'chatcmpl-f727571a-3bad-4e0d-8a9e-f18f8cda9750' - model: 'openrouter/intern' - object: 'chat.completion.chunk' + - allowed_api_key_hashes: null + allowed_models: null + allowed_user_ids: null + created_at: '2025-08-24T10:30:00Z' + declared_region: null + declared_zdr: null + disabled: false + id: '11111111-2222-3333-4444-555555555555' + is_byok_only: false + is_fallback: false + is_required: false + label: 'sk-...AbCd' + name: 'Production OpenAI Key' + provider: 'openai' + sort_order: 0 + workspace_id: '550e8400-e29b-41d4-a716-446655440000' + total_count: 1 properties: data: - $ref: '#/components/schemas/InternChatCompletionChunk' + description: 'List of BYOK credentials.' + items: + $ref: '#/components/schemas/BYOKKey' + type: 'array' + total_count: + description: 'Total number of BYOK credentials matching the filters.' + example: 1 + type: 'integer' required: - 'data' + - 'total_count' type: 'object' - InternChatSystemMessage: - description: 'A system message. Accepted for client compatibility and not forwarded.' - example: - content: 'You are a helpful assistant.' - role: 'system' - properties: - content: - $ref: '#/components/schemas/InternChatMessageContent' - role: - enum: - - 'system' - type: 'string' - required: - - 'content' - - 'role' - type: 'object' - InternChatTextPart: - description: 'One text part of a message.' + ListEndpointsResponse: + description: 'List of available endpoints for a model' example: - text: 'Summarize the open pull requests.' - type: 'text' - properties: - text: - type: 'string' - type: - enum: + architecture: + input_modalities: - 'text' - type: 'string' - required: - - 'text' - - 'type' - type: 'object' - InternChatToolCall: - description: 'An `openrouter.provide_input` request. The run pauses on the daemon until a `tool` message answers it, the caller cancels it, or its interaction deadline passes.' - example: - function: - arguments: '{"fields":[{"name":"answer","options":["red","blue","Other"],"required":true,"type":"string"}],"kind":"elicitation","message":"Which colour do you prefer?"}' - name: 'openrouter.provide_input' - id: '15e90ad6-5320-4a59-af4f-b371428154fa' - index: 0 - type: 'function' + instruct_type: 'chatml' + modality: 'text->text' + output_modalities: + - 'text' + tokenizer: 'GPT' + created: 1692901234 + description: 'GPT-4 is a large multimodal model that can solve difficult problems with greater accuracy.' + endpoints: + - context_length: 8192 + latency_last_30m: + p50: 0.25 + p75: 0.35 + p90: 0.48 + p99: 0.85 + max_completion_tokens: 4096 + max_prompt_tokens: 8192 + model_id: 'openai/gpt-4' + model_name: 'GPT-4' + name: 'OpenAI: GPT-4' + pricing: + completion: '0.00006' + image: '0' + prompt: '0.00003' + request: '0' + provider_name: 'OpenAI' + quantization: 'fp16' + status: 0 + supported_parameters: + - 'temperature' + - 'top_p' + - 'max_tokens' + - 'frequency_penalty' + - 'presence_penalty' + supports_diarization: false + supports_implicit_caching: true + tag: 'openai' + throughput_last_30m: + p50: 45.2 + p75: 38.5 + p90: 28.3 + p99: 15.1 + uptime_last_1d: 99.8 + uptime_last_30m: 99.5 + uptime_last_5m: 100 + id: 'openai/gpt-4' + name: 'GPT-4' properties: - function: - $ref: '#/components/schemas/InternChatToolCallFunction' - id: - description: 'The interaction id. Send it back as `tool_call_id` on the `tool` message that answers it.' - example: '15e90ad6-5320-4a59-af4f-b371428154fa' - type: 'string' - index: + architecture: + allOf: + - $ref: '#/components/schemas/ModelArchitecture' + - properties: + input_modalities: + description: 'Supported input modalities' + items: + $ref: '#/components/schemas/InputModality' + type: 'array' + instruct_type: + $ref: '#/components/schemas/InstructType' + modality: + description: 'Primary modality of the model' + example: 'text' + type: + - 'string' + - 'null' + output_modalities: + description: 'Supported output modalities' + items: + $ref: '#/components/schemas/OutputModality' + type: 'array' + tokenizer: + anyOf: + - $ref: '#/components/schemas/ModelGroup' + - type: 'null' + required: + - 'tokenizer' + - 'instruct_type' + - 'modality' + - 'input_modalities' + - 'output_modalities' + created: + description: 'Unix timestamp of when the model was created' + example: 1692901234 type: 'integer' - type: - enum: - - 'function' + description: + description: 'Description of the model' + example: 'GPT-4 is a large multimodal model that can solve difficult problems with greater accuracy.' type: 'string' - required: - - 'function' - - 'id' - - 'index' - - 'type' - type: 'object' - InternChatToolCallFunction: - description: 'The single tool this endpoint calls, asking the caller for input.' - example: - arguments: '{"fields":[{"name":"answer","options":["red","blue","Other"],"required":true,"type":"string"}],"kind":"elicitation","message":"Which colour do you prefer?"}' - name: 'openrouter.provide_input' - properties: - arguments: - description: 'A JSON object string describing the interaction. A permission request is `{"kind":"permission","operation":,"options":[]}`. A question is `{"kind":"elicitation","message":,"fields":[]}`.' - example: '{"fields":[{"name":"answer","options":["red","blue","Other"],"required":true,"type":"string"}],"kind":"elicitation","message":"Which colour do you prefer?"}' + endpoints: + description: 'List of available endpoints for this model' + items: + $ref: '#/components/schemas/PublicEndpoint' + type: 'array' + id: + description: 'Unique identifier for the model' + example: 'openai/gpt-4' type: 'string' name: - enum: - - 'openrouter.provide_input' + description: 'Display name of the model' + example: 'GPT-4' type: 'string' required: - - 'arguments' + - 'id' - 'name' + - 'created' + - 'description' + - 'architecture' + - 'endpoints' type: 'object' - InternChatToolMessage: - description: 'The answer to an `openrouter.provide_input` tool call. `tool_call_id` is the streamed tool call id and `session_id` must name the same session. For a permission, `content` is one of the offered option kinds (`allow_once`, `allow_always`, `reject_once`, `reject_always`) or `cancel`. For a question (elicitation), `content` is a JSON object string with `action` (`accept`, `decline` or `cancel`) and, for `accept`, `content` holding the field values. The answer is delivered to the run that asked. It never starts a new run.' + ListExternalUsersResponse: example: - content: 'allow_once' - role: 'tool' - tool_call_id: '15e90ad6-5320-4a59-af4f-b371428154fa' + data: + - created_at: '2026-09-16T12:00:00Z' + is_active: true + updated_at: '2026-09-16T12:00:00Z' + user: 'employee_123' + total_count: 1 properties: - content: - $ref: '#/components/schemas/InternChatMessageContent' - role: - enum: - - 'tool' - type: 'string' - tool_call_id: - maxLength: 128 - minLength: 1 - type: 'string' + data: + items: + $ref: '#/components/schemas/ExternalUser' + type: 'array' + total_count: + description: 'Number of registrations matching the filters before pagination.' + example: 1 + type: 'integer' required: - - 'content' - - 'role' - - 'tool_call_id' + - 'data' + - 'total_count' type: 'object' - InternChatUsage: - description: 'Token usage for the run as the daemon reported it, on the final chunk before `[DONE]`. `null` when the daemon reported none, and always `null` after `tool_calls` because the turn is not over.' + ListGuardrailsResponse: example: - completion_tokens: 12 - prompt_tokens: 40 - total_tokens: 52 + data: + - allowed_models: null + allowed_providers: + - 'openai' + - 'anthropic' + - 'google' + content_filter_builtins: + - action: 'redact' + label: '[EMAIL]' + slug: 'email' + content_filters: null + created_at: '2025-08-24T10:30:00Z' + description: 'Guardrail for production environment' + enable_free_model_publication: false + enable_free_model_training: true + enable_paid_model_training: true + enforce_zdr: null + enforce_zdr_anthropic: true + enforce_zdr_google: false + enforce_zdr_openai: true + enforce_zdr_other: false + enforce_zdr_xai: false + id: '550e8400-e29b-41d4-a716-446655440000' + ignored_models: null + ignored_providers: null + include_byok_in_budgets: false + limit_usd: 100 + name: 'Production Guardrail' + reset_interval: 'monthly' + updated_at: '2025-08-24T15:45:00Z' + workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' + total_count: 1 properties: - completion_tokens: - type: 'integer' - cost: - description: 'The cost of the run in USD, when the daemon reported one.' - format: 'double' - type: 'number' - prompt_tokens: - type: 'integer' - prompt_tokens_details: - $ref: '#/components/schemas/InternChatPromptTokensDetails' - total_tokens: + data: + description: 'List of guardrails' + items: + $ref: '#/components/schemas/Guardrail' + type: 'array' + total_count: + description: 'Total number of guardrails' + example: 25 type: 'integer' required: - - 'completion_tokens' - - 'prompt_tokens' - - 'total_tokens' - type: - - 'object' - - 'null' - InternChatUserMessage: - description: 'A user message. When it is the last message its text is the prompt for a new run, at most 32000 characters.' - example: - content: 'Summarize the open pull requests.' - role: 'user' - properties: - content: - $ref: '#/components/schemas/InternChatMessageContent' - role: - enum: - - 'user' - type: 'string' - required: - - 'content' - - 'role' + - 'data' + - 'total_count' type: 'object' - InternConnection: + ListKeyAssignmentsResponse: + example: + data: + - assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' + key_label: 'prod-key' + key_name: 'Production Key' + total_count: 1 properties: - account: - properties: - acts_as: - description: 'Whose account it acts as, when known.' - type: - - 'string' - - 'null' - is_your_account_linked: - type: - - 'boolean' - - 'null' - note: - type: - - 'string' - - 'null' - scope: - description: '`workspace` for a shared connection, `yours` for the key user''s personal account, `shared` for a teammate''s.' - enum: - - 'workspace' - - 'yours' - - 'shared' - type: 'string' - required: - - 'acts_as' - - 'is_your_account_linked' - - 'note' - - 'scope' - type: 'object' - id: - description: 'Stable id: the credential id of an MCP server, else the kind (`slack`, `github`, `google`).' - type: 'string' - is_enabled: - description: 'Whether the intern reaches it now.' - type: 'boolean' - is_intern_only: - description: 'Scoped to this intern rather than shared by the workspace.' - type: 'boolean' - kind: - enum: - - 'slack' - - 'github' - - 'google' - - 'mcp' - type: 'string' - mcp_server_name: - description: 'The name the intern''s MCP config keys the server by; null when it is not an MCP server or is off.' - type: - - 'string' - - 'null' - name: - description: 'Display name.' - type: 'string' - off_reason: - description: '`switched_off` for this intern, `disabled` for the whole workspace; null while on.' - enum: - - 'switched_off' - - 'disabled' - - null - type: - - 'string' - - 'null' - server: - properties: - host: - type: - - 'string' - - 'null' - surface: - type: 'string' - transport: - type: 'string' - url: - type: - - 'string' - - 'null' - required: - - 'host' - - 'surface' - - 'transport' - - 'url' - type: - - 'object' - - 'null' - status: - properties: - reason: - type: - - 'string' - - 'null' - state: - enum: - - 'connected' - - 'needs_reconnect' - - 'not_tested' - - 'error' - type: 'string' - required: - - 'state' - - 'reason' - type: 'object' - tool_count: - description: 'Tools found by the last successful test.' - type: - - 'integer' - - 'null' + data: + description: 'List of key assignments' + items: + $ref: '#/components/schemas/KeyAssignment' + type: 'array' + total_count: + description: 'Total number of key assignments for this guardrail' + example: 25 + type: 'integer' required: - - 'id' - - 'kind' - - 'name' - - 'is_enabled' - - 'is_intern_only' - - 'off_reason' - - 'mcp_server_name' - - 'server' - - 'status' - - 'tool_count' - - 'account' + - 'data' + - 'total_count' type: 'object' - InternConnectionList: + ListMemberAssignmentsResponse: + example: + data: + - assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + organization_id: 'org_xyz789' + user_id: 'user_abc123' + total_count: 1 properties: data: + description: 'List of member assignments' items: - $ref: '#/components/schemas/InternConnection' + $ref: '#/components/schemas/MemberAssignment' type: 'array' + total_count: + description: 'Total number of member assignments' + example: 10 + type: 'integer' required: - 'data' + - 'total_count' type: 'object' - InternDaemonAccess: - description: 'The intern daemon''s origin, the bearer `ori tui --host` sends to it as `ORI_DAEMON_TOKEN`, and who the caller is on the intern.' + ListObservabilityDestinationsResponse: example: - origin: 'https://research-assistant-7c9e6679.or.bot' - token: 'daemon_token' - viewer: - principals: - - 'clerk:user_2abc' - - 'slack:T0123:U0456' + data: + - api_key_hashes: null + broadcast_generation_cost: false + broadcast_generation_cost_allocation: false + broadcast_generation_identity: false + broadcast_generation_request_context: false + config: + baseUrl: 'https://us.cloud.langfuse.com' + publicKey: 'pk-l...EfGh' + secretKey: 'sk-l...AbCd' + created_at: '2025-08-24T10:30:00Z' + enabled: true + filter_rules: null + id: '99999999-aaaa-bbbb-cccc-dddddddddddd' + name: 'Production Langfuse' + privacy_mode: false + regions: + - 'global' + sampling_rate: 1 + type: 'langfuse' + updated_at: '2025-08-24T15:45:00Z' + workspace_id: '550e8400-e29b-41d4-a716-446655440000' + total_count: 1 properties: - origin: - pattern: '^https?:\/\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*)(?::(\d{1,5}))?$/iu' - type: 'string' - token: - pattern: '^[\w-]+$/u' - type: 'string' - viewer: - properties: - principals: - description: 'The caller''s Ori principals on this intern: `clerk:`, and, when the grant carries `vault:read`, `slack::` for each Slack account they linked to it. A session started by one of them in a one-to-one Slack DM is the caller''s to see.' - items: - type: 'string' - type: 'array' - required: - - 'principals' - type: 'object' + data: + description: 'List of observability destinations.' + items: + $ref: '#/components/schemas/ObservabilityDestination' + type: 'array' + total_count: + description: 'Total number of destinations matching the filters.' + example: 1 + type: 'integer' required: - - 'origin' - - 'token' - - 'viewer' + - 'data' + - 'total_count' type: 'object' - InternInvokeAcceptedResponse: - description: 'The intern admitted the prompt. The run continues on the intern.' + ListPresetsResponse: + description: 'A paginated list of presets.' example: - session_id: 'b51a0e21-368b-4780-a220-14655bf28c55' - status: 'started' + data: + - created_at: '2026-04-20T10:00:00Z' + creator_user_id: 'user_2dHFtVWx2n56w6HkM0000000000' + description: null + designated_version_id: '550e8400-e29b-41d4-a716-446655440000' + id: '650e8400-e29b-41d4-a716-446655440001' + name: 'my-preset' + slug: 'my-preset' + status: 'active' + status_updated_at: null + updated_at: '2026-04-20T10:00:00Z' + workspace_id: '750e8400-e29b-41d4-a716-446655440002' + total_count: 1 properties: - session_id: - description: 'The session the run belongs to. Send it back to continue the conversation.' - example: 'b51a0e21-368b-4780-a220-14655bf28c55' - type: 'string' - status: - description: '`started` when a new run began. `steered` when the session already had a run going and the prompt was delivered into it instead.' - enum: - - 'started' - - 'steered' - example: 'started' - type: 'string' + data: + items: + $ref: '#/components/schemas/Preset' + type: 'array' + total_count: + type: 'integer' required: - - 'session_id' - - 'status' + - 'data' + - 'total_count' type: 'object' - InternInvokeRequest: - description: 'A prompt to run on the intern without holding a connection open.' + ListPresetVersionsResponse: + description: 'A paginated list of preset versions.' example: - input: 'New support ticket 48213. Case token: ct_9f2c. Investigate and reply.' + data: + - config: + model: 'openai/gpt-4o' + temperature: 0.7 + created_at: '2026-04-20T10:00:00Z' + creator_id: 'user_2dHFtVWx2n56w6HkM0000000000' + id: '550e8400-e29b-41d4-a716-446655440000' + preset_id: '650e8400-e29b-41d4-a716-446655440001' + system_prompt: 'You are a helpful assistant.' + updated_at: '2026-04-20T10:00:00Z' + version: 1 + total_count: 1 properties: - input: - description: 'The prompt for the run, at most 32000 characters.' - example: 'New support ticket 48213. Case token: ct_9f2c. Investigate and reply.' - maxLength: 32000 - minLength: 1 - type: 'string' - session_id: - description: 'The session to run in. Send the `session_id` from an earlier `202` to continue that conversation, for example to hand the intern a decision on a case it is working. Omit it to start a new session. Only a `session_id` this endpoint issued to the same caller on the same intern is accepted; any other is refused with `404`.' - example: 'b51a0e21-368b-4780-a220-14655bf28c55' - maxLength: 256 - minLength: 1 - type: 'string' + data: + items: + $ref: '#/components/schemas/PresetDesignatedVersion' + type: 'array' + total_count: + type: 'integer' required: - - 'input' + - 'data' + - 'total_count' type: 'object' - InternLifecycleError: - additionalProperties: false - description: 'Intern lifecycle request failure.' - example: - error: - code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + ListPrivateEndpointsResponse: properties: - error: - additionalProperties: false - properties: - code: - anyOf: - - type: 'string' - - type: 'integer' - message: - type: 'string' - metadata: - additionalProperties: false - properties: - reason: - type: 'string' - retryable: - type: 'boolean' - required: - - 'reason' - - 'retryable' - type: 'object' - required: - - 'code' - - 'message' - type: 'object' + data: + items: + $ref: '#/components/schemas/PrivateEndpointSummary' + type: 'array' required: - - 'error' + - 'data' type: 'object' - InternListResponse: - additionalProperties: false - description: 'Interns visible to the authenticated API key.' - example: - data: - - attached_vault_id: null - can_edit: true - created_at: '2026-09-16T08:30:00.000Z' - created_by_you: true - description: 'Researches customer questions' - hostname: 'research-assistant.openrouter.ai' - icon_sha256: null - id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - instructions: null - last_failure_message: null - model: 'openai/gpt-5.4' - name: 'research-assistant' - progress: null - status: 'running' - updated_at: '2026-09-16T08:45:00.000Z' - vault_id: 'b431c59d-6eed-41ac-bc89-9a89be79a121' - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - has_more: false + ListScimGroupMappingsResponse: properties: data: items: - $ref: '#/components/schemas/Intern' + $ref: '#/components/schemas/ScimGroupMapping' type: 'array' - has_more: - description: 'True when more interns match the current filters.' - type: 'boolean' - next_cursor: - description: 'Opaque cursor, present when `has_more` is true. Pass it as `starting_after` to fetch the next page.' - example: 'MjAyNi0wOS0xNlQwODozMDowMC4wMDAwMDBafDdjOWU2Njc5LTc0MjUtNDBkZS05NDRiLWUwN2ZjMWY5MGFlNw' - type: 'string' + total_count: + type: 'integer' required: - 'data' - - 'has_more' + - 'total_count' type: 'object' - ItemReferenceItem: - description: 'A reference to a previous response item by ID' - example: - id: 'msg-abc123' - type: 'item_reference' + ListScimGroupsResponse: properties: + data: + items: + $ref: '#/components/schemas/ScimGroup' + type: 'array' + total_count: + type: 'integer' + required: + - 'data' + - 'total_count' + type: 'object' + ListToolsResponse: + properties: + data: + items: + $ref: '#/components/schemas/ServerTool' + type: 'array' + links: + properties: + next: + description: 'URL for the next page of results, or null if this is the last page' + example: null + type: + - 'string' + - 'null' + required: + - 'next' + type: 'object' + total_count: + description: 'Total number of tools' + example: 12 + type: 'integer' + required: + - 'data' + - 'total_count' + - 'links' + type: 'object' + ListWorkspaceBudgetsResponse: + example: + data: + - created_at: '2025-08-24T10:30:00Z' + id: '770e8400-e29b-41d4-a716-446655440000' + limit_usd: 100 + reset_interval: 'monthly' + updated_at: '2025-08-24T15:45:00Z' + workspace_id: '550e8400-e29b-41d4-a716-446655440000' + include_byok_in_budgets: false + properties: + data: + description: 'List of budgets configured for the workspace' + items: + $ref: '#/components/schemas/WorkspaceBudget' + type: 'array' + include_byok_in_budgets: + description: 'Whether BYOK (bring-your-own-key) spend is included when enforcing the workspace''s budgets. This is a workspace-wide setting that applies to all budget intervals (daily, weekly, monthly, and lifetime).' + example: false + type: 'boolean' + required: + - 'data' + type: 'object' + ListWorkspaceMembersResponse: + example: + data: + - created_at: '2025-08-24T10:30:00Z' + id: '660e8400-e29b-41d4-a716-446655440000' + role: 'member' + user_id: 'user_abc123' + workspace_id: '550e8400-e29b-41d4-a716-446655440000' + total_count: 1 + properties: + data: + description: 'List of workspace members' + items: + $ref: '#/components/schemas/WorkspaceMember' + type: 'array' + total_count: + description: 'Total number of members in the workspace' + example: 5 + type: 'integer' + required: + - 'data' + - 'total_count' + type: 'object' + ListWorkspacesResponse: + example: + data: + - created_at: '2025-08-24T10:30:00Z' + created_by: 'user_abc123' + default_guardrail_id: '595d5849-7e86-51fd-a7c0-705c34e4afff' + default_image_model: 'openai/dall-e-3' + default_provider_sort: 'price' + default_text_model: 'openai/gpt-4o' + description: 'Production environment workspace' + disabled_server_tools: null + id: '550e8400-e29b-41d4-a716-446655440000' + include_byok_in_budgets: false + io_logging_api_key_ids: null + io_logging_sampling_rate: 1 + is_data_discount_logging_enabled: true + is_observability_broadcast_enabled: false + is_observability_io_logging_enabled: false + name: 'Production' + slug: 'production' + updated_at: '2025-08-24T15:45:00Z' + total_count: 1 + properties: + data: + description: 'List of workspaces' + items: + $ref: '#/components/schemas/Workspace' + type: 'array' + total_count: + description: 'Total number of workspaces' + example: 5 + type: 'integer' + required: + - 'data' + - 'total_count' + type: 'object' + LocalShellCallItem: + description: 'A local shell command execution call' + example: + action: + command: + - 'ls' + - '-la' + env: + PATH: '/usr/bin' + timeout_ms: 5000 + type: 'exec' + call_id: 'call-abc123' + id: 'shell-abc123' + status: 'completed' + type: 'local_shell_call' + properties: + action: + properties: + command: + items: + type: 'string' + type: 'array' + env: + additionalProperties: + type: 'string' + type: 'object' + timeout_ms: + type: + - 'integer' + - 'null' + type: + enum: + - 'exec' + type: 'string' + user: + type: + - 'string' + - 'null' + working_directory: + type: + - 'string' + - 'null' + required: + - 'type' + - 'command' + - 'env' + type: 'object' + call_id: + type: 'string' id: type: 'string' + status: + $ref: '#/components/schemas/ToolCallStatus' type: enum: - - 'item_reference' + - 'local_shell_call' type: 'string' required: - 'type' - 'id' + - 'call_id' + - 'action' + - 'status' type: 'object' - JevRouterPlugin: - additionalProperties: false + LocalShellCallOutputItem: + description: 'Output from a local shell command execution' example: - excluded_models: - - 'openai/gpt-6-astra' - id: 'jev-router' - models: - - 'anthropic/*' - - 'openai/gpt-5.6-sol' + id: 'output-abc123' + output: "total 24\ndrwxr-xr-x 5 user staff 160 Jan 1 12:00 ." + status: 'completed' + type: 'local_shell_call_output' properties: - allowed_models: - description: 'Alias of `models`, matching the auto-router field name. Entries from both fields are combined.' - example: - - 'anthropic/*' - items: - maxLength: 1024 - type: 'string' - maxItems: 1024 - type: 'array' - cost_tier: - description: 'Select low, medium, high, or a cost tier configured by the operator. Overrides the live-config tier and replaces the shared routing policy with that tier. Omit to use the live configuration. Model exclusions and the router kill switch still apply.' - example: 'medium' - pattern: '^[a-z][a-z0-9_-]{0,31}$' - type: 'string' - excluded_models: - description: 'Remove these models from the router. Each entry is a model slug or a wildcard pattern (e.g. "xiaomi/*"). A `~author/family-latest` alias matches every revision of that family. Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. Applied after `models`, so an excluded pattern always wins over an included one; when the lists leave no model the request can use, it fails with 404 rather than routing outside them.' - example: - - 'openai/gpt-6-astra' - - 'xiaomi/*' - items: - maxLength: 1024 - type: 'string' - maxItems: 1024 - type: 'array' id: + type: 'string' + output: + type: 'string' + status: + anyOf: + - $ref: '#/components/schemas/ToolCallStatus' + - type: 'null' + type: enum: - - 'jev-router' + - 'local_shell_call_output' type: 'string' - models: - description: 'Restrict the router to these models. Each entry is a model slug or a wildcard pattern (e.g. "anthropic/*"), matched against the current pool; models outside the pool are ignored. A `~author/family-latest` alias matches every revision of that family. Up to 1024 patterns, each at most 1024 characters, with 65536 total characters across all patterns. When omitted or empty, every model in the pool is a candidate; when no pool model matches, the list is ignored and the whole pool is used (`excluded_models` still apply). `allowed_models` is an alias; entries from both fields are combined.' - example: - - 'anthropic/*' - - 'openai/gpt-5.6-sol' - items: - maxLength: 1024 - type: 'string' - maxItems: 1024 - type: 'array' required: + - 'type' - 'id' + - 'output' type: 'object' - KeyAssignment: + ManagedPrivateEndpoint: + allOf: + - $ref: '#/components/schemas/PrivateEndpointSummary' + - properties: + declared_region: + $ref: '#/components/schemas/PrivateEndpointDeclaredRegion' + declared_zdr: + description: 'Whether you attest this deployment retains no prompt or completion data. `null` means undeclared.' + example: true + type: + - 'boolean' + - 'null' + required: + - 'declared_zdr' + - 'declared_region' + type: 'object' + ManagedPrivateEndpointResponse: + properties: + data: + $ref: '#/components/schemas/ManagedPrivateEndpoint' + required: + - 'data' + type: 'object' + McpApprovalRequestItem: + description: 'Request for approval to execute an MCP tool' example: - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' - key_label: 'prod-key' - key_name: 'Production Key' + arguments: '{"id":"123"}' + id: 'approval-abc123' + name: 'delete_record' + server_label: 'database-server' + type: 'mcp_approval_request' properties: - assigned_by: - description: 'User ID of who made the assignment' - example: 'user_abc123' - type: - - 'string' - - 'null' - created_at: - description: 'ISO 8601 timestamp of when the assignment was created' - example: '2025-08-24T10:30:00Z' - type: 'string' - guardrail_id: - description: 'ID of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440001' - format: 'uuid' + arguments: type: 'string' id: - description: 'Unique identifier for the assignment' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' type: 'string' - key_hash: - description: 'Hash of the assigned API key' - example: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' + name: type: 'string' - key_label: - description: 'Label of the API key' - example: 'prod-key' + server_label: type: 'string' - key_name: - description: 'Name of the API key' - example: 'Production Key' + type: + enum: + - 'mcp_approval_request' type: 'string' required: + - 'type' - 'id' - - 'key_hash' - - 'guardrail_id' - - 'key_name' - - 'key_label' - - 'assigned_by' - - 'created_at' + - 'name' + - 'arguments' + - 'server_label' type: 'object' - KeyBudget: - description: 'One budget layer that applies to requests made with this key, with the spend enforcement compares against it.' + McpApprovalResponseItem: + description: 'User response to an MCP tool approval request' example: - budget_id: null - guardrail_id: '0df9e665-d932-5740-b2c7-b52af166bc11' - include_byok: false - limit_usd: 50 - remaining_usd: 17.5 - reset_interval: 'weekly' - resets_at: '2026-10-12T00:00:00.000Z' - scope: 'member' - spend_usd: 32.5 + approval_request_id: 'approval-abc123' + approve: true + reason: 'Approved for execution' + type: 'mcp_approval_response' properties: - budget_id: - description: 'ID of the workspace budget for the `workspace` scope; null for other scopes.' - example: null - type: - - 'string' - - 'null' - guardrail_id: - description: 'ID of the guardrail that carries this budget; null for other scopes.' - example: '0df9e665-d932-5740-b2c7-b52af166bc11' - type: - - 'string' - - 'null' - include_byok: - description: 'Whether external BYOK inference spend counts toward this budget.' - example: false + approval_request_id: + type: 'string' + approve: type: 'boolean' - limit_usd: - description: 'Budget limit in USD for the current window.' - example: 50 - format: 'double' - type: 'number' - remaining_usd: - description: '`limit_usd - spend_usd`. Zero or negative means this layer rejects requests with a 403 until it resets.' - example: 17.5 - format: 'double' - type: 'number' - reset_interval: - description: 'UTC window the spend is counted over (weeks start Monday); null for a lifetime budget that never resets.' - enum: - - 'daily' - - 'weekly' - - 'monthly' - - null - example: 'weekly' + id: type: - 'string' - 'null' - resets_at: - description: 'ISO 8601 UTC instant at which the window rolls over and spend returns to zero; null for a lifetime budget.' - example: '2026-10-12T00:00:00.000Z' - format: 'date-time' + reason: type: - 'string' - 'null' - scope: - description: 'Which budget layer this is, in the order enforcement checks them: the workspace default guardrail against the member aggregate (`workspace_default_member`) and against this key (`workspace_default_key`), the member guardrail (`member`), the API key guardrail (`api_key`), a workspace budget (`workspace`), or the key''s own limit (`key_limit`).' - enum: - - 'workspace_default_member' - - 'workspace_default_key' - - 'member' - - 'api_key' - - 'workspace' - - 'key_limit' - example: 'member' - type: 'string' - spend_usd: - description: 'Spend in USD that enforcement counts against this limit in the current window: the member aggregate for member-scoped layers, otherwise this key or workspace.' - example: 32.5 - format: 'double' - type: 'number' - required: - - 'scope' - - 'guardrail_id' - - 'budget_id' - - 'limit_usd' - - 'spend_usd' - - 'remaining_usd' - - 'reset_interval' - - 'resets_at' - - 'include_byok' - type: 'object' - Legacy_ChatContentVideo: - deprecated: true - description: 'Video input content part (legacy format - deprecated)' - example: - type: 'input_video' - video_url: - url: 'https://example.com/video.mp4' - properties: type: enum: - - 'input_video' + - 'mcp_approval_response' type: 'string' - video_url: - $ref: '#/components/schemas/Legacy_ChatContentVideoInput' required: - 'type' - - 'video_url' + - 'approval_request_id' + - 'approve' type: 'object' - Legacy_ChatContentVideoInput: - description: 'Video input object' + McpCallItem: + description: 'An MCP tool call with its output or error' example: - url: 'https://example.com/video.mp4' + arguments: '{"query":"SELECT * FROM users"}' + id: 'mcp-call-abc123' + name: 'query_database' + output: '[{"id":1,"name":"Alice"}]' + server_label: 'database-server' + type: 'mcp_call' properties: - processing: - description: 'Video processing mode. `agentic` enables agentic video processing and `static` forces fixed-rate frame sampling on providers that support it (currently Google Gemini).' - enum: - - 'agentic' - - 'static' - example: 'agentic' + arguments: type: 'string' - url: - description: 'URL of the video (data: URLs supported)' + error: + $ref: '#/components/schemas/McpToolCallError' + id: + type: 'string' + name: + type: 'string' + output: + type: + - 'string' + - 'null' + server_label: + type: 'string' + type: + enum: + - 'mcp_call' type: 'string' required: - - 'url' + - 'type' + - 'id' + - 'name' + - 'arguments' + - 'server_label' type: 'object' - Legacy_WebSearchServerTool: - description: 'Web search tool configuration' + McpHttpError: + description: 'The MCP server request failed at the HTTP layer' example: - engine: 'auto' - filters: - allowed_domains: - - 'example.com' - type: 'web_search' + code: 503 + message: 'Service Unavailable' + type: 'http_error' properties: - engine: - $ref: '#/components/schemas/WebSearchEngineEnum' - filters: - $ref: '#/components/schemas/WebSearchDomainFilter' - max_results: - description: 'Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, Parallel, and Perplexity engines; ignored with native provider search. Perplexity supports a maximum of 20; values above 20 are clamped.' - example: 5 - type: 'integer' - max_uses: - description: 'Maximum number of web searches the model may perform in a single request. Once reached, further search calls return an error result instead of executing. Applies to the Exa, Firecrawl, Parallel, and Perplexity engines. With native provider search, forwarded only to Anthropic (as `max_uses`); other native search providers have no equivalent parameter and ignore it.' - example: 3 + code: type: 'integer' - mode: - $ref: '#/components/schemas/WebSearchMode' - search_context_size: - $ref: '#/components/schemas/SearchContextSizeEnum' + message: + type: 'string' type: enum: - - 'web_search' + - 'http_error' type: 'string' - user_location: - $ref: '#/components/schemas/WebSearchUserLocation' - x_search: - $ref: '#/components/schemas/XSearchOptions' required: - 'type' + - 'code' + - 'message' type: 'object' - ListBYOKKeysResponse: + McpListToolsItem: + description: 'List of available MCP tools from a server' example: - data: - - allowed_api_key_hashes: null - allowed_models: null - allowed_user_ids: null - created_at: '2025-08-24T10:30:00Z' - declared_region: null - declared_zdr: null - disabled: false - id: '11111111-2222-3333-4444-555555555555' - is_byok_only: false - is_fallback: false - is_required: false - label: 'sk-...AbCd' - name: 'Production OpenAI Key' - provider: 'openai' - sort_order: 0 - workspace_id: '550e8400-e29b-41d4-a716-446655440000' - total_count: 1 + id: 'mcp-list-abc123' + server_label: 'database-server' + tools: + - description: 'Execute a database query' + input_schema: + properties: + query: + type: 'string' + type: 'object' + name: 'query_database' + type: 'mcp_list_tools' properties: - data: - description: 'List of BYOK credentials.' + error: + type: + - 'string' + - 'null' + id: + type: 'string' + server_label: + type: 'string' + tools: items: - $ref: '#/components/schemas/BYOKKey' + properties: + annotations: {} + description: + type: + - 'string' + - 'null' + input_schema: + additionalProperties: {} + type: 'object' + name: + type: 'string' + required: + - 'name' + - 'input_schema' + type: 'object' type: 'array' - total_count: - description: 'Total number of BYOK credentials matching the filters.' - example: 1 + type: + enum: + - 'mcp_list_tools' + type: 'string' + required: + - 'type' + - 'id' + - 'server_label' + - 'tools' + type: 'object' + McpProtocolError: + description: 'The MCP server returned a protocol-level error' + example: + code: -32601 + message: 'Method not found' + type: 'mcp_protocol_error' + properties: + code: type: 'integer' + message: + type: 'string' + type: + enum: + - 'mcp_protocol_error' + type: 'string' required: - - 'data' - - 'total_count' + - 'type' + - 'code' + - 'message' type: 'object' - ListEndpointsResponse: - description: 'List of available endpoints for a model' + McpServerTool: + description: 'MCP (Model Context Protocol) tool configuration' example: - architecture: - input_modalities: - - 'text' - instruct_type: 'chatml' - modality: 'text->text' - output_modalities: - - 'text' - tokenizer: 'GPT' - created: 1692901234 - description: 'GPT-4 is a large multimodal model that can solve difficult problems with greater accuracy.' - endpoints: - - context_length: 8192 - latency_last_30m: - p50: 0.25 - p75: 0.35 - p90: 0.48 - p99: 0.85 - max_completion_tokens: 4096 - max_prompt_tokens: 8192 - model_id: 'openai/gpt-4' - model_name: 'GPT-4' - name: 'OpenAI: GPT-4' - pricing: - completion: '0.00006' - image: '0' - prompt: '0.00003' - request: '0' - provider_name: 'OpenAI' - quantization: 'fp16' - status: 0 - supported_parameters: - - 'temperature' - - 'top_p' - - 'max_tokens' - - 'frequency_penalty' - - 'presence_penalty' - supports_diarization: false - supports_implicit_caching: true - tag: 'openai' - throughput_last_30m: - p50: 45.2 - p75: 38.5 - p90: 28.3 - p99: 15.1 - uptime_last_1d: 99.8 - uptime_last_30m: 99.5 - uptime_last_5m: 100 - id: 'openai/gpt-4' - name: 'GPT-4' + server_label: 'my-server' + server_url: 'https://example.com/mcp' + type: 'mcp' properties: - architecture: - allOf: - - $ref: '#/components/schemas/ModelArchitecture' + allowed_tools: + anyOf: + - items: + type: 'string' + type: 'array' - properties: - input_modalities: - description: 'Supported input modalities' - items: - $ref: '#/components/schemas/InputModality' - type: 'array' - instruct_type: - $ref: '#/components/schemas/InstructType' - modality: - description: 'Primary modality of the model' - example: 'text' - type: - - 'string' - - 'null' - output_modalities: - description: 'Supported output modalities' + read_only: + type: 'boolean' + tool_names: items: - $ref: '#/components/schemas/OutputModality' + type: 'string' type: 'array' - tokenizer: - anyOf: - - $ref: '#/components/schemas/ModelGroup' - - type: 'null' - required: - - 'tokenizer' - - 'instruct_type' - - 'modality' - - 'input_modalities' - - 'output_modalities' - created: - description: 'Unix timestamp of when the model was created' - example: 1692901234 - type: 'integer' - description: - description: 'Description of the model' - example: 'GPT-4 is a large multimodal model that can solve difficult problems with greater accuracy.' + type: 'object' + - type: 'null' + authorization: type: 'string' - endpoints: - description: 'List of available endpoints for this model' - items: - $ref: '#/components/schemas/PublicEndpoint' - type: 'array' - id: - description: 'Unique identifier for the model' - example: 'openai/gpt-4' + connector_id: + enum: + - 'connector_dropbox' + - 'connector_gmail' + - 'connector_googlecalendar' + - 'connector_googledrive' + - 'connector_microsoftteams' + - 'connector_outlookcalendar' + - 'connector_outlookemail' + - 'connector_sharepoint' type: 'string' - name: - description: 'Display name of the model' - example: 'GPT-4' + headers: + additionalProperties: + type: 'string' + type: + - 'object' + - 'null' + require_approval: + anyOf: + - properties: + always: + properties: + tool_names: + items: + type: 'string' + type: 'array' + type: 'object' + never: + properties: + tool_names: + items: + type: 'string' + type: 'array' + type: 'object' + type: 'object' + - enum: + - 'always' + type: 'string' + - enum: + - 'never' + type: 'string' + - type: 'null' + server_description: + type: 'string' + server_label: + type: 'string' + server_url: + type: 'string' + type: + enum: + - 'mcp' type: 'string' required: - - 'id' - - 'name' - - 'created' - - 'description' - - 'architecture' - - 'endpoints' + - 'type' + - 'server_label' type: 'object' - ListExternalUsersResponse: + McpToolCallError: + anyOf: + - type: 'string' + - $ref: '#/components/schemas/McpProtocolError' + - $ref: '#/components/schemas/McpToolExecutionError' + - $ref: '#/components/schemas/McpHttpError' + - type: 'null' + description: 'Error from an MCP tool call, either a plain message or a structured error' example: - data: - - created_at: '2026-09-16T12:00:00Z' - is_active: true - updated_at: '2026-09-16T12:00:00Z' - user: 'employee_123' - total_count: 1 + code: 503 + message: 'Service Unavailable' + type: 'http_error' + McpToolExecutionError: + description: 'The MCP tool ran but reported a failure' + example: + content: 'Connection refused' + type: 'mcp_tool_execution_error' properties: - data: - items: - $ref: '#/components/schemas/ExternalUser' - type: 'array' - total_count: - description: 'Number of registrations matching the filters before pagination.' - example: 1 - type: 'integer' + content: {} + type: + enum: + - 'mcp_tool_execution_error' + type: 'string' required: - - 'data' - - 'total_count' + - 'type' type: 'object' - ListGuardrailsResponse: + MemberAssignment: example: - data: - - allowed_models: null - allowed_providers: - - 'openai' - - 'anthropic' - - 'google' - content_filter_builtins: - - action: 'redact' - label: '[EMAIL]' - slug: 'email' - content_filters: null - created_at: '2025-08-24T10:30:00Z' - description: 'Guardrail for production environment' - enable_free_model_publication: false - enable_free_model_training: true - enable_paid_model_training: true - enforce_zdr: null - enforce_zdr_anthropic: true - enforce_zdr_google: false - enforce_zdr_openai: true - enforce_zdr_other: false - enforce_zdr_xai: false - id: '550e8400-e29b-41d4-a716-446655440000' - ignored_models: null - ignored_providers: null - include_byok_in_budgets: false - limit_usd: 100 - name: 'Production Guardrail' - reset_interval: 'monthly' - updated_at: '2025-08-24T15:45:00Z' - workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' - total_count: 1 + assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + organization_id: 'org_xyz789' + user_id: 'user_abc123' properties: - data: - description: 'List of guardrails' - items: - $ref: '#/components/schemas/Guardrail' - type: 'array' - total_count: - description: 'Total number of guardrails' - example: 25 - type: 'integer' + assigned_by: + description: 'User ID of who made the assignment' + example: 'user_abc123' + type: + - 'string' + - 'null' + created_at: + description: 'ISO 8601 timestamp of when the assignment was created' + example: '2025-08-24T10:30:00Z' + type: 'string' + guardrail_id: + description: 'ID of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440001' + format: 'uuid' + type: 'string' + id: + description: 'Unique identifier for the assignment' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' + type: 'string' + organization_id: + description: 'Organization ID' + example: 'org_xyz789' + type: 'string' + user_id: + description: 'Clerk user ID of the assigned member' + example: 'user_abc123' + type: 'string' required: - - 'data' - - 'total_count' + - 'id' + - 'user_id' + - 'organization_id' + - 'guardrail_id' + - 'assigned_by' + - 'created_at' type: 'object' - ListKeyAssignmentsResponse: + MessagesAdvisorToolResultBlock: + description: 'Advisor tool result from a prior assistant turn, replayed back to the model on the next turn. Mirrors the block Anthropic returns in assistant content when the `advisor_20260301` tool runs.' example: - data: - - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' - key_label: 'prod-key' - key_name: 'Production Key' - total_count: 1 + content: + text: 'Advisor response text' + type: 'advisor_result' + tool_use_id: 'srvtoolu_01abc' + type: 'advisor_tool_result' properties: - data: - description: 'List of key assignments' - items: - $ref: '#/components/schemas/KeyAssignment' - type: 'array' - total_count: - description: 'Total number of key assignments for this guardrail' - example: 25 - type: 'integer' + content: + additionalProperties: {} + type: 'object' + tool_use_id: + type: 'string' + type: + enum: + - 'advisor_tool_result' + type: 'string' required: - - 'data' - - 'total_count' + - 'type' + - 'tool_use_id' + - 'content' type: 'object' - ListMemberAssignmentsResponse: + MessagesBashToolResultBlock: + description: 'Output of a sandbox-executed `openrouter:bash` call from a prior assistant turn. Accepted on replay and dropped before the provider request — Anthropic has no equivalent block.' example: - data: - - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - organization_id: 'org_xyz789' - user_id: 'user_abc123' - total_count: 1 + content: + command: 'ls' + exitCode: 0 + stderr: '' + stdout: "README.md\n" + tool_use_id: 'srvtoolu_01abc' + type: 'openrouter_bash_tool_result' properties: - data: - description: 'List of member assignments' + container_id: + description: 'The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed.' + type: 'string' + content: + additionalProperties: {} + type: 'object' + files: + description: 'Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API.' items: - $ref: '#/components/schemas/MemberAssignment' + properties: + container_id: + type: 'string' + end_index: + type: 'integer' + file_id: + type: 'string' + filename: + type: 'string' + start_index: + type: 'integer' + type: + enum: + - 'container_file_citation' + type: 'string' + required: + - 'type' + - 'container_id' + - 'file_id' + - 'filename' + - 'start_index' + - 'end_index' + type: 'object' type: 'array' - total_count: - description: 'Total number of member assignments' - example: 10 - type: 'integer' + tool_use_id: + type: 'string' + type: + enum: + - 'openrouter_bash_tool_result' + type: 'string' required: - - 'data' - - 'total_count' + - 'type' + - 'tool_use_id' + - 'content' type: 'object' - ListObservabilityDestinationsResponse: + MessagesContentBlockDeltaEvent: + description: 'Event sent when content is added to a content block' example: - data: - - api_key_hashes: null - broadcast_generation_cost: false - broadcast_generation_cost_allocation: false - broadcast_generation_identity: false - broadcast_generation_request_context: false - config: - baseUrl: 'https://us.cloud.langfuse.com' - publicKey: 'pk-l...EfGh' - secretKey: 'sk-l...AbCd' - created_at: '2025-08-24T10:30:00Z' - enabled: true - filter_rules: null - id: '99999999-aaaa-bbbb-cccc-dddddddddddd' - name: 'Production Langfuse' - privacy_mode: false - regions: - - 'global' - sampling_rate: 1 - type: 'langfuse' - updated_at: '2025-08-24T15:45:00Z' - workspace_id: '550e8400-e29b-41d4-a716-446655440000' - total_count: 1 + delta: + text: 'Hello' + type: 'text_delta' + index: 0 + type: 'content_block_delta' properties: - data: - description: 'List of observability destinations.' - items: - $ref: '#/components/schemas/ObservabilityDestination' - type: 'array' - total_count: - description: 'Total number of destinations matching the filters.' - example: 1 + delta: + oneOf: + - properties: + text: + type: 'string' + type: + enum: + - 'text_delta' + type: 'string' + required: + - 'type' + - 'text' + type: 'object' + - properties: + partial_json: + type: 'string' + type: + enum: + - 'input_json_delta' + type: 'string' + required: + - 'type' + - 'partial_json' + type: 'object' + - properties: + thinking: + type: 'string' + type: + enum: + - 'thinking_delta' + type: 'string' + required: + - 'type' + - 'thinking' + type: 'object' + - properties: + signature: + type: 'string' + type: + enum: + - 'signature_delta' + type: 'string' + required: + - 'type' + - 'signature' + type: 'object' + - properties: + citation: + discriminator: + mapping: + char_location: '#/components/schemas/AnthropicCitationCharLocation' + content_block_location: '#/components/schemas/AnthropicCitationContentBlockLocation' + page_location: '#/components/schemas/AnthropicCitationPageLocation' + search_result_location: '#/components/schemas/AnthropicCitationSearchResultLocation' + web_search_result_location: '#/components/schemas/AnthropicCitationWebSearchResultLocation' + propertyName: 'type' + oneOf: + - $ref: '#/components/schemas/AnthropicCitationCharLocation' + - $ref: '#/components/schemas/AnthropicCitationPageLocation' + - $ref: '#/components/schemas/AnthropicCitationContentBlockLocation' + - $ref: '#/components/schemas/AnthropicCitationWebSearchResultLocation' + - $ref: '#/components/schemas/AnthropicCitationSearchResultLocation' + type: + enum: + - 'citations_delta' + type: 'string' + required: + - 'type' + - 'citation' + type: 'object' + - properties: + content: + type: + - 'string' + - 'null' + encrypted_content: + type: + - 'string' + - 'null' + type: + enum: + - 'compaction_delta' + type: 'string' + required: + - 'type' + - 'content' + type: 'object' + index: type: 'integer' + type: + enum: + - 'content_block_delta' + type: 'string' required: - - 'data' - - 'total_count' + - 'type' + - 'index' + - 'delta' type: 'object' - ListPresetsResponse: - description: 'A paginated list of presets.' + MessagesContentBlockStartEvent: + description: 'Event sent when a new content block starts' example: - data: - - created_at: '2026-04-20T10:00:00Z' - creator_user_id: 'user_2dHFtVWx2n56w6HkM0000000000' - description: null - designated_version_id: '550e8400-e29b-41d4-a716-446655440000' - id: '650e8400-e29b-41d4-a716-446655440001' - name: 'my-preset' - slug: 'my-preset' - status: 'active' - status_updated_at: null - updated_at: '2026-04-20T10:00:00Z' - workspace_id: '750e8400-e29b-41d4-a716-446655440002' - total_count: 1 + content_block: + citations: [] + text: '' + type: 'text' + index: 0 + type: 'content_block_start' properties: - data: - items: - $ref: '#/components/schemas/Preset' - type: 'array' - total_count: + content_block: + anyOf: + - $ref: '#/components/schemas/AnthropicTextBlock' + - $ref: '#/components/schemas/AnthropicToolUseBlock' + - $ref: '#/components/schemas/AnthropicThinkingBlock' + - $ref: '#/components/schemas/AnthropicRedactedThinkingBlock' + - $ref: '#/components/schemas/ORAnthropicServerToolUseBlock' + - $ref: '#/components/schemas/AnthropicWebSearchToolResult' + - $ref: '#/components/schemas/AnthropicWebFetchToolResult' + - $ref: '#/components/schemas/AnthropicCodeExecutionToolResult' + - $ref: '#/components/schemas/AnthropicBashCodeExecutionToolResult' + - $ref: '#/components/schemas/AnthropicTextEditorCodeExecutionToolResult' + - $ref: '#/components/schemas/AnthropicToolSearchToolResult' + - $ref: '#/components/schemas/AnthropicContainerUpload' + - $ref: '#/components/schemas/AnthropicCompactionBlock' + - $ref: '#/components/schemas/AnthropicAdvisorToolResult' + - $ref: '#/components/schemas/ORAnthropicShellToolResult' + - $ref: '#/components/schemas/ORAnthropicBashToolResult' + - $ref: '#/components/schemas/ORAnthropicToolSearchResult' + - properties: + content: + type: + - 'string' + - 'null' + encrypted_content: + type: + - 'string' + - 'null' + type: + enum: + - 'compaction' + type: 'string' + required: + - 'type' + - 'content' + type: 'object' + index: type: 'integer' + type: + enum: + - 'content_block_start' + type: 'string' required: - - 'data' - - 'total_count' + - 'type' + - 'index' + - 'content_block' type: 'object' - ListPresetVersionsResponse: - description: 'A paginated list of preset versions.' + MessagesContentBlockStopEvent: + description: 'Event sent when a content block is complete' example: - data: - - config: - model: 'openai/gpt-4o' - temperature: 0.7 - created_at: '2026-04-20T10:00:00Z' - creator_id: 'user_2dHFtVWx2n56w6HkM0000000000' - id: '550e8400-e29b-41d4-a716-446655440000' - preset_id: '650e8400-e29b-41d4-a716-446655440001' - system_prompt: 'You are a helpful assistant.' - updated_at: '2026-04-20T10:00:00Z' - version: 1 - total_count: 1 - properties: - data: - items: - $ref: '#/components/schemas/PresetDesignatedVersion' - type: 'array' - total_count: - type: 'integer' - required: - - 'data' - - 'total_count' - type: 'object' - ListPrivateEndpointsResponse: - properties: - data: - items: - $ref: '#/components/schemas/PrivateEndpointSummary' - type: 'array' - required: - - 'data' - type: 'object' - ListScimGroupMappingsResponse: - properties: - data: - items: - $ref: '#/components/schemas/ScimGroupMapping' - type: 'array' - total_count: - type: 'integer' - required: - - 'data' - - 'total_count' - type: 'object' - ListScimGroupsResponse: + index: 0 + type: 'content_block_stop' properties: - data: - items: - $ref: '#/components/schemas/ScimGroup' - type: 'array' - total_count: + index: type: 'integer' + type: + enum: + - 'content_block_stop' + type: 'string' required: - - 'data' - - 'total_count' + - 'type' + - 'index' type: 'object' - ListToolsResponse: + MessagesDeltaEvent: + description: 'Event sent when the message metadata changes (e.g., stop_reason)' + example: + delta: + container: null + stop_details: null + stop_reason: 'end_turn' + stop_sequence: null + type: 'message_delta' + usage: + cache_creation_input_tokens: null + cache_read_input_tokens: null + input_tokens: null + output_tokens: 15 + output_tokens_details: null + server_tool_use: null properties: - data: - items: - $ref: '#/components/schemas/ServerTool' - type: 'array' - links: + delta: properties: - next: - description: 'URL for the next page of results, or null if this is the last page' - example: null + container: + $ref: '#/components/schemas/AnthropicContainer' + safeguard_results: + items: + $ref: '#/components/schemas/AnthropicSafeguardResult' + type: + - 'array' + - 'null' + stop_details: + $ref: '#/components/schemas/AnthropicRefusalStopDetails' + stop_reason: + $ref: '#/components/schemas/ORAnthropicStopReason' + stop_sequence: type: - 'string' - 'null' required: - - 'next' + - 'container' + - 'stop_details' + - 'stop_reason' + - 'stop_sequence' type: 'object' - total_count: - description: 'Total number of tools' - example: 12 - type: 'integer' - required: - - 'data' - - 'total_count' - - 'links' - type: 'object' - ListWorkspaceBudgetsResponse: - example: - data: - - created_at: '2025-08-24T10:30:00Z' - id: '770e8400-e29b-41d4-a716-446655440000' - limit_usd: 100 - reset_interval: 'monthly' - updated_at: '2025-08-24T15:45:00Z' - workspace_id: '550e8400-e29b-41d4-a716-446655440000' - include_byok_in_budgets: false - properties: - data: - description: 'List of budgets configured for the workspace' - items: - $ref: '#/components/schemas/WorkspaceBudget' - type: 'array' - include_byok_in_budgets: - description: 'Whether BYOK (bring-your-own-key) spend is included when enforcing the workspace''s budgets. This is a workspace-wide setting that applies to all budget intervals (daily, weekly, monthly, and lifetime).' - example: false - type: 'boolean' - required: - - 'data' - type: 'object' - ListWorkspaceMembersResponse: - example: - data: - - created_at: '2025-08-24T10:30:00Z' - id: '660e8400-e29b-41d4-a716-446655440000' - role: 'member' - user_id: 'user_abc123' - workspace_id: '550e8400-e29b-41d4-a716-446655440000' - total_count: 1 - properties: - data: - description: 'List of workspace members' - items: - $ref: '#/components/schemas/WorkspaceMember' - type: 'array' - total_count: - description: 'Total number of members in the workspace' - example: 5 - type: 'integer' - required: - - 'data' - - 'total_count' - type: 'object' - ListWorkspacesResponse: - example: - data: - - created_at: '2025-08-24T10:30:00Z' - created_by: 'user_abc123' - default_guardrail_id: '595d5849-7e86-51fd-a7c0-705c34e4afff' - default_image_model: 'openai/dall-e-3' - default_provider_sort: 'price' - default_text_model: 'openai/gpt-4o' - description: 'Production environment workspace' - disabled_server_tools: null - id: '550e8400-e29b-41d4-a716-446655440000' - include_byok_in_budgets: false - io_logging_api_key_ids: null - io_logging_sampling_rate: 1 - is_data_discount_logging_enabled: true - is_observability_broadcast_enabled: false - is_observability_io_logging_enabled: false - name: 'Production' - slug: 'production' - updated_at: '2025-08-24T15:45:00Z' - total_count: 1 - properties: - data: - description: 'List of workspaces' - items: - $ref: '#/components/schemas/Workspace' - type: 'array' - total_count: - description: 'Total number of workspaces' - example: 5 - type: 'integer' - required: - - 'data' - - 'total_count' - type: 'object' - LocalShellCallItem: - description: 'A local shell command execution call' - example: - action: - command: - - 'ls' - - '-la' - env: - PATH: '/usr/bin' - timeout_ms: 5000 - type: 'exec' - call_id: 'call-abc123' - id: 'shell-abc123' - status: 'completed' - type: 'local_shell_call' - properties: - action: + type: + enum: + - 'message_delta' + type: 'string' + usage: properties: - command: - items: - type: 'string' - type: 'array' - env: - additionalProperties: - type: 'string' - type: 'object' - timeout_ms: + cache_creation: + $ref: '#/components/schemas/AnthropicCacheCreation' + cache_creation_input_tokens: type: - 'integer' - 'null' - type: - enum: - - 'exec' - type: 'string' - user: + cache_read_input_tokens: type: - - 'string' + - 'integer' - 'null' - working_directory: + input_tokens: type: - - 'string' + - 'integer' - 'null' + iterations: + items: + $ref: '#/components/schemas/AnthropicUsageIteration' + type: 'array' + output_tokens: + type: 'integer' + output_tokens_details: + $ref: '#/components/schemas/AnthropicOutputTokensDetails' + server_tool_use: + $ref: '#/components/schemas/ORAnthropicServerToolUsage' + required: + - 'input_tokens' + - 'output_tokens' + - 'output_tokens_details' + - 'cache_creation_input_tokens' + - 'cache_read_input_tokens' + - 'server_tool_use' + type: 'object' + required: + - 'type' + - 'delta' + - 'usage' + type: 'object' + MessagesErrorEvent: + description: 'Error event in the stream' + example: + error: + error_type: 'provider_overloaded' + message: 'Overloaded' + type: 'overloaded_error' + type: 'error' + properties: + error: + properties: + error_type: + $ref: '#/components/schemas/ApiErrorType' + message: + type: 'string' + type: + type: 'string' required: - 'type' - - 'command' - - 'env' + - 'message' type: 'object' - call_id: - type: 'string' - id: - type: 'string' - status: - $ref: '#/components/schemas/ToolCallStatus' + openrouter_metadata: + $ref: '#/components/schemas/OpenRouterMetadata' type: enum: - - 'local_shell_call' + - 'error' type: 'string' required: - 'type' - - 'id' - - 'call_id' - - 'action' - - 'status' + - 'error' type: 'object' - LocalShellCallOutputItem: - description: 'Output from a local shell command execution' + MessagesFallbackParam: + additionalProperties: {} + description: 'Fallback model to try when the primary model fails or refuses. Only the `model` field is supported; per-attempt overrides are rejected.' example: - id: 'output-abc123' - output: "total 24\ndrwxr-xr-x 5 user staff 160 Jan 1 12:00 ." - status: 'completed' - type: 'local_shell_call_output' + model: 'claude-opus-4-8' properties: - id: - type: 'string' - output: - type: 'string' - status: - anyOf: - - $ref: '#/components/schemas/ToolCallStatus' - - type: 'null' - type: - enum: - - 'local_shell_call_output' + model: type: 'string' required: - - 'type' - - 'id' - - 'output' + - 'model' type: 'object' - ManagedPrivateEndpoint: - allOf: - - $ref: '#/components/schemas/PrivateEndpointSummary' - - properties: - declared_region: - $ref: '#/components/schemas/PrivateEndpointDeclaredRegion' - declared_zdr: - description: 'Whether you attest this deployment retains no prompt or completion data. `null` means undeclared.' - example: true - type: - - 'boolean' - - 'null' - required: - - 'declared_zdr' - - 'declared_region' - type: 'object' - ManagedPrivateEndpointResponse: - properties: - data: - $ref: '#/components/schemas/ManagedPrivateEndpoint' - required: - - 'data' - type: 'object' - McpApprovalRequestItem: - description: 'Request for approval to execute an MCP tool' + MessagesMessageParam: + description: 'Anthropic message with OpenRouter extensions' example: - arguments: '{"id":"123"}' - id: 'approval-abc123' - name: 'delete_record' - server_label: 'database-server' - type: 'mcp_approval_request' + content: 'Hello, how are you?' + role: 'user' properties: - arguments: - type: 'string' - id: - type: 'string' - name: - type: 'string' - server_label: - type: 'string' - type: + clear_at: + $ref: '#/components/schemas/AnthropicSystemClearAt' + content: + anyOf: + - type: 'string' + - items: + oneOf: + - $ref: '#/components/schemas/AnthropicTextBlockParam' + - $ref: '#/components/schemas/AnthropicImageBlockParam' + - $ref: '#/components/schemas/AnthropicDocumentBlockParam' + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + id: + type: 'string' + input: {} + name: + type: 'string' + type: + enum: + - 'tool_use' + type: 'string' + required: + - 'type' + - 'id' + - 'name' + type: 'object' + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + content: + anyOf: + - type: 'string' + - items: + anyOf: + - $ref: '#/components/schemas/AnthropicTextBlockParam' + - $ref: '#/components/schemas/AnthropicImageBlockParam' + - properties: + tool_name: + type: 'string' + type: + enum: + - 'tool_reference' + type: 'string' + required: + - 'type' + - 'tool_name' + type: 'object' + - $ref: '#/components/schemas/AnthropicSearchResultBlockParam' + - $ref: '#/components/schemas/AnthropicDocumentBlockParam' + type: 'array' + is_error: + type: 'boolean' + tool_use_id: + type: 'string' + type: + enum: + - 'tool_result' + type: 'string' + required: + - 'type' + - 'tool_use_id' + type: 'object' + - properties: + signature: + type: 'string' + thinking: + type: 'string' + type: + enum: + - 'thinking' + type: 'string' + required: + - 'type' + - 'thinking' + - 'signature' + type: 'object' + - properties: + data: + type: 'string' + type: + enum: + - 'redacted_thinking' + type: 'string' + required: + - 'type' + - 'data' + type: 'object' + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + id: + type: 'string' + input: {} + name: + type: 'string' + type: + enum: + - 'server_tool_use' + type: 'string' + required: + - 'type' + - 'id' + - 'name' + type: 'object' + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + content: + anyOf: + - items: + $ref: '#/components/schemas/AnthropicWebSearchResultBlockParam' + type: 'array' + - properties: + error_code: + enum: + - 'invalid_tool_input' + - 'unavailable' + - 'max_uses_exceeded' + - 'too_many_requests' + - 'query_too_long' + - 'request_too_large' + type: 'string' + type: + enum: + - 'web_search_tool_result_error' + type: 'string' + required: + - 'type' + - 'error_code' + type: 'object' + tool_use_id: + type: 'string' + type: + enum: + - 'web_search_tool_result' + type: 'string' + required: + - 'type' + - 'tool_use_id' + - 'content' + type: 'object' + - $ref: '#/components/schemas/AnthropicSearchResultBlockParam' + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + content: + type: + - 'string' + - 'null' + encrypted_content: + type: + - 'string' + - 'null' + type: + enum: + - 'compaction' + type: 'string' + required: + - 'type' + - 'content' + type: 'object' + - $ref: '#/components/schemas/MessagesAdvisorToolResultBlock' + - $ref: '#/components/schemas/MessagesToolAdditionBlock' + - $ref: '#/components/schemas/MessagesToolRemovalBlock' + - $ref: '#/components/schemas/MessagesShellToolResultBlock' + - $ref: '#/components/schemas/MessagesBashToolResultBlock' + - $ref: '#/components/schemas/ORAnthropicToolSearchResultParam' + type: 'array' + output_config: + $ref: '#/components/schemas/AnthropicMessageOutputConfig' + role: enum: - - 'mcp_approval_request' + - 'user' + - 'assistant' + - 'system' type: 'string' required: - - 'type' - - 'id' - - 'name' - - 'arguments' - - 'server_label' + - 'role' + - 'content' type: 'object' - McpApprovalResponseItem: - description: 'User response to an MCP tool approval request' + MessagesOutputConfig: + description: 'Configuration for controlling output behavior. Supports the effort parameter and structured output format.' example: - approval_request_id: 'approval-abc123' - approve: true - reason: 'Approved for execution' - type: 'mcp_approval_response' + effort: 'medium' properties: - approval_request_id: - type: 'string' - approve: - type: 'boolean' - id: + effort: + description: 'How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer. Valid values are `low`, `medium`, `high`, `xhigh`, or `max`.' + enum: + - 'low' + - 'medium' + - 'high' + - 'xhigh' + - 'max' + - null + example: 'medium' type: - 'string' - 'null' - reason: + format: + description: 'A schema to specify Claude''s output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs).' + properties: + schema: + additionalProperties: {} + type: 'object' + type: + enum: + - 'json_schema' + type: 'string' + required: + - 'type' + - 'schema' type: - - 'string' + - 'object' - 'null' - type: - enum: - - 'mcp_approval_response' - type: 'string' - required: - - 'type' - - 'approval_request_id' - - 'approve' - type: 'object' - McpCallItem: - description: 'An MCP tool call with its output or error' - example: - arguments: '{"query":"SELECT * FROM users"}' - id: 'mcp-call-abc123' - name: 'query_database' - output: '[{"id":1,"name":"Alice"}]' - server_label: 'database-server' - type: 'mcp_call' - properties: - arguments: - type: 'string' - error: - $ref: '#/components/schemas/McpToolCallError' - id: - type: 'string' - name: - type: 'string' - output: + task_budget: + description: 'Task budget for an agentic turn. The model sees a countdown of remaining tokens and uses it to prioritize work and wind down gracefully. Advisory — does not enforce a hard cap.' + example: + total: 400000 + type: 'tokens' + properties: + remaining: + minimum: 0 + type: + - 'integer' + - 'null' + total: + minimum: 20000 + type: 'integer' + type: + enum: + - 'tokens' + type: 'string' + required: + - 'type' + - 'total' type: - - 'string' + - 'object' - 'null' - server_label: - type: 'string' - type: - enum: - - 'mcp_call' - type: 'string' - required: - - 'type' - - 'id' - - 'name' - - 'arguments' - - 'server_label' type: 'object' - McpHttpError: - description: 'The MCP server request failed at the HTTP layer' + MessagesPingEvent: + description: 'Keep-alive ping event' example: - code: 503 - message: 'Service Unavailable' - type: 'http_error' + type: 'ping' properties: - code: - type: 'integer' - message: - type: 'string' type: enum: - - 'http_error' + - 'ping' type: 'string' required: - 'type' - - 'code' - - 'message' type: 'object' - McpListToolsItem: - description: 'List of available MCP tools from a server' + MessagesRequest: + description: 'Request schema for Anthropic Messages API endpoint' example: - id: 'mcp-list-abc123' - server_label: 'database-server' - tools: - - description: 'Execute a database query' - input_schema: - properties: - query: - type: 'string' - type: 'object' - name: 'query_database' - type: 'mcp_list_tools' + max_tokens: 1024 + messages: + - content: 'Hello, how are you?' + role: 'user' + model: 'anthropic/claude-4.5-sonnet-20250929' + temperature: 0.7 properties: - error: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + context_management: + properties: + edits: + items: + oneOf: + - properties: + clear_at_least: + $ref: '#/components/schemas/AnthropicInputTokensClearAtLeast' + clear_tool_inputs: + anyOf: + - type: 'boolean' + - items: + type: 'string' + type: 'array' + - type: 'null' + exclude_tools: + items: + type: 'string' + type: + - 'array' + - 'null' + keep: + $ref: '#/components/schemas/AnthropicToolUsesKeep' + trigger: + discriminator: + mapping: + input_tokens: '#/components/schemas/AnthropicInputTokensTrigger' + tool_uses: '#/components/schemas/AnthropicToolUsesTrigger' + propertyName: 'type' + oneOf: + - $ref: '#/components/schemas/AnthropicInputTokensTrigger' + - $ref: '#/components/schemas/AnthropicToolUsesTrigger' + type: + enum: + - 'clear_tool_uses_20250919' + type: 'string' + required: + - 'type' + type: 'object' + - properties: + keep: + anyOf: + - $ref: '#/components/schemas/AnthropicThinkingTurns' + - properties: + type: + enum: + - 'all' + type: 'string' + required: + - 'type' + type: 'object' + - enum: + - 'all' + type: 'string' + type: + enum: + - 'clear_thinking_20251015' + type: 'string' + required: + - 'type' + type: 'object' + - properties: + instructions: + type: + - 'string' + - 'null' + pause_after_compaction: + type: 'boolean' + trigger: + anyOf: + - allOf: + - $ref: '#/components/schemas/AnthropicInputTokensTrigger' + - properties: {} + type: 'object' + - type: 'null' + example: + type: 'input_tokens' + value: 100000 + type: + enum: + - 'compact_20260112' + type: 'string' + required: + - 'type' + type: 'object' + type: 'array' type: - - 'string' + - 'object' - 'null' - id: - type: 'string' - server_label: + deferred_tools: + $ref: '#/components/schemas/DeferredToolsControl' + fallbacks: + description: '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.' + example: + - model: 'claude-opus-4-8' + items: + $ref: '#/components/schemas/MessagesFallbackParam' + type: + - 'array' + - 'null' + max_tokens: + type: 'integer' + messages: + items: + $ref: '#/components/schemas/MessagesMessageParam' + type: + - 'array' + - 'null' + metadata: + properties: + user_id: + type: + - 'string' + - 'null' + title: 'MessagesRequestMetadata' + type: 'object' + model: type: 'string' - tools: + models: items: - properties: - annotations: {} - description: - type: - - 'string' - - 'null' - input_schema: - additionalProperties: {} - type: 'object' - name: - type: 'string' - required: - - 'name' - - 'input_schema' - type: 'object' + type: 'string' type: 'array' - type: - enum: - - 'mcp_list_tools' - type: 'string' - required: - - 'type' - - 'id' - - 'server_label' - - 'tools' - type: 'object' - McpProtocolError: - description: 'The MCP server returned a protocol-level error' - example: - code: -32601 - message: 'Method not found' - type: 'mcp_protocol_error' - properties: - code: - type: 'integer' - message: - type: 'string' - type: - enum: - - 'mcp_protocol_error' - type: 'string' - required: - - 'type' - - 'code' - - 'message' - type: 'object' - McpServerTool: - description: 'MCP (Model Context Protocol) tool configuration' - example: - server_label: 'my-server' - server_url: 'https://example.com/mcp' - type: 'mcp' - properties: - allowed_tools: - anyOf: - - items: - type: 'string' - type: 'array' - - properties: - read_only: - type: 'boolean' - tool_names: - items: - type: 'string' - type: 'array' - type: 'object' - - type: 'null' - authorization: - type: 'string' - connector_id: - enum: - - 'connector_dropbox' - - 'connector_gmail' - - 'connector_googlecalendar' - - 'connector_googledrive' - - 'connector_microsoftteams' - - 'connector_outlookcalendar' - - 'connector_outlookemail' - - 'connector_sharepoint' - type: 'string' - headers: - additionalProperties: - type: 'string' - type: - - 'object' - - 'null' - require_approval: - anyOf: - - properties: - always: - properties: - tool_names: - items: - type: 'string' - type: 'array' - type: 'object' - never: - properties: - tool_names: - items: - type: 'string' - type: 'array' - type: 'object' - type: 'object' - - enum: - - 'always' - type: 'string' - - enum: - - 'never' - type: 'string' - - type: 'null' - server_description: - type: 'string' - server_label: - type: 'string' - server_url: - type: 'string' - type: - enum: - - 'mcp' - type: 'string' - required: - - 'type' - - 'server_label' - type: 'object' - McpToolCallError: - anyOf: - - type: 'string' - - $ref: '#/components/schemas/McpProtocolError' - - $ref: '#/components/schemas/McpToolExecutionError' - - $ref: '#/components/schemas/McpHttpError' - - type: 'null' - description: 'Error from an MCP tool call, either a plain message or a structured error' - example: - code: 503 - message: 'Service Unavailable' - type: 'http_error' - McpToolExecutionError: - description: 'The MCP tool ran but reported a failure' - example: - content: 'Connection refused' - type: 'mcp_tool_execution_error' - properties: - content: {} - type: - enum: - - 'mcp_tool_execution_error' - type: 'string' - required: - - 'type' - type: 'object' - MemberAssignment: - example: - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - organization_id: 'org_xyz789' - user_id: 'user_abc123' - properties: - assigned_by: - description: 'User ID of who made the assignment' - example: 'user_abc123' + output_config: + $ref: '#/components/schemas/MessagesOutputConfig' + plugins: + description: 'Plugins you want to enable for this request, including their settings.' + items: + discriminator: + mapping: + alignment: '#/components/schemas/AlignmentPlugin' + armor: '#/components/schemas/ArmorPlugin' + auto-beta-router: '#/components/schemas/AutoBetaRouterPlugin' + auto-router: '#/components/schemas/AutoRouterPlugin' + context-compression: '#/components/schemas/ContextCompressionPlugin' + file-parser: '#/components/schemas/FileParserPlugin' + fusion: '#/components/schemas/FusionPlugin' + jev-router: '#/components/schemas/JevRouterPlugin' + moderation: '#/components/schemas/ModerationPlugin' + pareto-router: '#/components/schemas/ParetoRouterPlugin' + response-healing: '#/components/schemas/ResponseHealingPlugin' + switchyard-router: '#/components/schemas/SwitchyardRouterPlugin' + web: '#/components/schemas/WebSearchPlugin' + web-fetch: '#/components/schemas/WebFetchPlugin' + propertyName: 'id' + oneOf: + - $ref: '#/components/schemas/AutoRouterPlugin' + - $ref: '#/components/schemas/AutoBetaRouterPlugin' + - $ref: '#/components/schemas/ModerationPlugin' + - $ref: '#/components/schemas/WebSearchPlugin' + - $ref: '#/components/schemas/WebFetchPlugin' + - $ref: '#/components/schemas/FileParserPlugin' + - $ref: '#/components/schemas/ResponseHealingPlugin' + - $ref: '#/components/schemas/ContextCompressionPlugin' + - $ref: '#/components/schemas/ParetoRouterPlugin' + - $ref: '#/components/schemas/FusionPlugin' + - $ref: '#/components/schemas/SwitchyardRouterPlugin' + - $ref: '#/components/schemas/JevRouterPlugin' + - $ref: '#/components/schemas/AlignmentPlugin' + - $ref: '#/components/schemas/ArmorPlugin' + type: 'array' + provider: + $ref: '#/components/schemas/ProviderPreferences' + route: + $ref: '#/components/schemas/DeprecatedRoute' + safeguards: + items: + $ref: '#/components/schemas/AnthropicSafeguard' type: - - 'string' + - 'array' - 'null' - created_at: - description: 'ISO 8601 timestamp of when the assignment was created' - example: '2025-08-24T10:30:00Z' - type: 'string' - guardrail_id: - description: 'ID of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440001' - format: 'uuid' - type: 'string' - id: - description: 'Unique identifier for the assignment' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' - organization_id: - description: 'Organization ID' - example: 'org_xyz789' - type: 'string' - user_id: - description: 'Clerk user ID of the assigned member' - example: 'user_abc123' - type: 'string' - required: - - 'id' - - 'user_id' - - 'organization_id' - - 'guardrail_id' - - 'assigned_by' - - 'created_at' - type: 'object' - MessagesAdvisorToolResultBlock: - description: 'Advisor tool result from a prior assistant turn, replayed back to the model on the next turn. Mirrors the block Anthropic returns in assistant content when the `advisor_20260301` tool runs.' - example: - content: - text: 'Advisor response text' - type: 'advisor_result' - tool_use_id: 'srvtoolu_01abc' - type: 'advisor_tool_result' - properties: - content: - additionalProperties: {} - type: 'object' - tool_use_id: - type: 'string' - type: - enum: - - 'advisor_tool_result' + service_tier: type: 'string' - required: - - 'type' - - 'tool_use_id' - - 'content' - type: 'object' - MessagesBashToolResultBlock: - description: 'Output of a sandbox-executed `openrouter:bash` call from a prior assistant turn. Accepted on replay and dropped before the provider request — Anthropic has no equivalent block.' - example: - content: - command: 'ls' - exitCode: 0 - stderr: '' - stdout: "README.md\n" - tool_use_id: 'srvtoolu_01abc' - type: 'openrouter_bash_tool_result' - properties: - container_id: - description: 'The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed.' + session_id: + description: '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.' + maxLength: 256 type: 'string' - content: - additionalProperties: {} - type: 'object' - files: - description: 'Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API.' + speed: + allOf: + - $ref: '#/components/schemas/AnthropicSpeed' + - description: 'Controls output generation speed. When set to `fast`, uses a higher-speed inference configuration at premium pricing. Defaults to `standard` when omitted.' + example: 'fast' + stop_sequences: items: - properties: - container_id: - type: 'string' - end_index: - type: 'integer' - file_id: - type: 'string' - filename: - type: 'string' - start_index: - type: 'integer' - type: - enum: - - 'container_file_citation' - type: 'string' - required: - - 'type' - - 'container_id' - - 'file_id' - - 'filename' - - 'start_index' - - 'end_index' - type: 'object' + type: 'string' type: 'array' - tool_use_id: - type: 'string' - type: - enum: - - 'openrouter_bash_tool_result' - type: 'string' - required: - - 'type' - - 'tool_use_id' - - 'content' - type: 'object' - MessagesContentBlockDeltaEvent: - description: 'Event sent when content is added to a content block' - example: - delta: - text: 'Hello' - type: 'text_delta' - index: 0 - type: 'content_block_delta' - properties: - delta: + stop_server_tools_when: + $ref: '#/components/schemas/StopServerToolsWhen' + stream: + type: 'boolean' + system: + anyOf: + - type: 'string' + - items: + $ref: '#/components/schemas/AnthropicTextBlockParam' + type: 'array' + temperature: + format: 'double' + type: 'number' + thinking: oneOf: - properties: - text: - type: 'string' + block_binding: + $ref: '#/components/schemas/AnthropicThinkingBlockBinding' + budget_tokens: + type: 'integer' + display: + $ref: '#/components/schemas/AnthropicThinkingDisplay' type: enum: - - 'text_delta' + - 'enabled' type: 'string' required: - 'type' - - 'text' + - 'budget_tokens' type: 'object' - properties: - partial_json: - type: 'string' type: enum: - - 'input_json_delta' + - 'disabled' type: 'string' required: - 'type' - - 'partial_json' type: 'object' - properties: - thinking: + block_binding: + $ref: '#/components/schemas/AnthropicThinkingBlockBinding' + display: + $ref: '#/components/schemas/AnthropicThinkingDisplay' + type: + enum: + - 'adaptive' type: 'string' + required: + - 'type' + type: 'object' + - additionalProperties: false + properties: type: enum: - - 'thinking_delta' + - 'between_tools' type: 'string' required: - 'type' - - 'thinking' type: 'object' + tool_choice: + oneOf: - properties: - signature: - type: 'string' + disable_parallel_tool_use: + type: 'boolean' type: enum: - - 'signature_delta' + - 'auto' type: 'string' required: - 'type' - - 'signature' type: 'object' - properties: - citation: - discriminator: - mapping: - char_location: '#/components/schemas/AnthropicCitationCharLocation' - content_block_location: '#/components/schemas/AnthropicCitationContentBlockLocation' - page_location: '#/components/schemas/AnthropicCitationPageLocation' - search_result_location: '#/components/schemas/AnthropicCitationSearchResultLocation' - web_search_result_location: '#/components/schemas/AnthropicCitationWebSearchResultLocation' - propertyName: 'type' - oneOf: - - $ref: '#/components/schemas/AnthropicCitationCharLocation' - - $ref: '#/components/schemas/AnthropicCitationPageLocation' - - $ref: '#/components/schemas/AnthropicCitationContentBlockLocation' - - $ref: '#/components/schemas/AnthropicCitationWebSearchResultLocation' - - $ref: '#/components/schemas/AnthropicCitationSearchResultLocation' + disable_parallel_tool_use: + type: 'boolean' type: enum: - - 'citations_delta' + - 'any' type: 'string' required: - 'type' - - 'citation' type: 'object' - properties: - content: - type: - - 'string' - - 'null' - encrypted_content: - type: - - 'string' - - 'null' type: enum: - - 'compaction_delta' + - 'none' type: 'string' required: - 'type' - - 'content' type: 'object' - index: - type: 'integer' - type: - enum: - - 'content_block_delta' - type: 'string' - required: - - 'type' - - 'index' - - 'delta' - type: 'object' - MessagesContentBlockStartEvent: - description: 'Event sent when a new content block starts' - example: - content_block: - citations: [] - text: '' - type: 'text' - index: 0 - type: 'content_block_start' - properties: - content_block: - anyOf: - - $ref: '#/components/schemas/AnthropicTextBlock' - - $ref: '#/components/schemas/AnthropicToolUseBlock' - - $ref: '#/components/schemas/AnthropicThinkingBlock' - - $ref: '#/components/schemas/AnthropicRedactedThinkingBlock' - - $ref: '#/components/schemas/ORAnthropicServerToolUseBlock' - - $ref: '#/components/schemas/AnthropicWebSearchToolResult' - - $ref: '#/components/schemas/AnthropicWebFetchToolResult' - - $ref: '#/components/schemas/AnthropicCodeExecutionToolResult' - - $ref: '#/components/schemas/AnthropicBashCodeExecutionToolResult' - - $ref: '#/components/schemas/AnthropicTextEditorCodeExecutionToolResult' - - $ref: '#/components/schemas/AnthropicToolSearchToolResult' - - $ref: '#/components/schemas/AnthropicContainerUpload' - - $ref: '#/components/schemas/AnthropicCompactionBlock' - - $ref: '#/components/schemas/AnthropicAdvisorToolResult' - - $ref: '#/components/schemas/ORAnthropicShellToolResult' - - $ref: '#/components/schemas/ORAnthropicBashToolResult' - - $ref: '#/components/schemas/ORAnthropicToolSearchResult' - properties: - content: - type: - - 'string' - - 'null' - encrypted_content: - type: - - 'string' - - 'null' + disable_parallel_tool_use: + type: 'boolean' + name: + type: 'string' type: enum: - - 'compaction' + - 'tool' type: 'string' required: - 'type' - - 'content' + - 'name' type: 'object' - index: - type: 'integer' - type: - enum: - - 'content_block_start' - type: 'string' - required: - - 'type' - - 'index' - - 'content_block' - type: 'object' - MessagesContentBlockStopEvent: - description: 'Event sent when a content block is complete' - example: - index: 0 - type: 'content_block_stop' - properties: - index: - type: 'integer' - type: - enum: - - 'content_block_stop' - type: 'string' - required: - - 'type' - - 'index' - type: 'object' - MessagesDeltaEvent: - description: 'Event sent when the message metadata changes (e.g., stop_reason)' - example: - delta: - container: null - stop_details: null - stop_reason: 'end_turn' - stop_sequence: null - type: 'message_delta' - usage: - cache_creation_input_tokens: null - cache_read_input_tokens: null - input_tokens: null - output_tokens: 15 - output_tokens_details: null - server_tool_use: null - properties: - delta: - properties: - container: - $ref: '#/components/schemas/AnthropicContainer' - safeguard_results: - items: - $ref: '#/components/schemas/AnthropicSafeguardResult' - type: - - 'array' - - 'null' - stop_details: - $ref: '#/components/schemas/AnthropicRefusalStopDetails' - stop_reason: - $ref: '#/components/schemas/ORAnthropicStopReason' - stop_sequence: - type: - - 'string' - - 'null' - required: - - 'container' - - 'stop_details' - - 'stop_reason' - - 'stop_sequence' - type: 'object' - type: - enum: - - 'message_delta' + tools: + items: + anyOf: + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + defer_loading: + type: 'boolean' + description: + type: 'string' + input_schema: + additionalProperties: {} + properties: + properties: {} + required: + items: + type: 'string' + type: + - 'array' + - 'null' + type: + default: 'object' + type: 'string' + type: 'object' + name: + type: 'string' + strict: + type: 'boolean' + type: + enum: + - 'custom' + type: 'string' + required: + - 'name' + - 'input_schema' + type: 'object' + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + name: + enum: + - 'bash' + type: 'string' + type: + enum: + - 'bash_20250124' + type: 'string' + required: + - 'type' + - 'name' + type: 'object' + - properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + name: + enum: + - 'str_replace_editor' + type: 'string' + type: + enum: + - 'text_editor_20250124' + type: 'string' + required: + - 'type' + - 'name' + type: 'object' + - properties: + allowed_domains: + items: + type: 'string' + type: + - 'array' + - 'null' + blocked_domains: + items: + type: 'string' + type: + - 'array' + - 'null' + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + max_uses: + type: + - 'integer' + - 'null' + name: + enum: + - 'web_search' + type: 'string' + type: + enum: + - 'web_search_20250305' + type: 'string' + user_location: + $ref: '#/components/schemas/AnthropicWebSearchToolUserLocation' + required: + - 'type' + - 'name' + type: 'object' + - properties: + allowed_callers: + $ref: '#/components/schemas/AnthropicAllowedCallers' + allowed_domains: + items: + type: 'string' + type: + - 'array' + - 'null' + blocked_domains: + items: + type: 'string' + type: + - 'array' + - 'null' + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + max_uses: + type: + - 'integer' + - 'null' + name: + enum: + - 'web_search' + type: 'string' + type: + enum: + - 'web_search_20260209' + type: 'string' + user_location: + $ref: '#/components/schemas/AnthropicWebSearchToolUserLocation' + required: + - 'type' + - 'name' + type: 'object' + - properties: + allowed_callers: + $ref: '#/components/schemas/AnthropicAllowedCallers' + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + caching: + anyOf: + - $ref: '#/components/schemas/AnthropicCacheControlDirective' + - type: 'null' + defer_loading: + type: 'boolean' + max_uses: + type: 'integer' + model: + type: 'string' + name: + enum: + - 'advisor' + type: 'string' + type: + enum: + - 'advisor_20260301' + type: 'string' + required: + - 'type' + - 'name' + - 'model' + type: 'object' + - $ref: '#/components/schemas/BashServerTool' + - $ref: '#/components/schemas/DatetimeServerTool' + - $ref: '#/components/schemas/ImageGenerationServerTool_OpenRouter' + - $ref: '#/components/schemas/MessagesSearchModelsServerTool' + - $ref: '#/components/schemas/WebFetchServerTool' + - $ref: '#/components/schemas/OpenRouterWebSearchServerTool' + - additionalProperties: {} + properties: + type: + type: 'string' + required: + - 'type' + type: 'object' + - $ref: '#/components/schemas/AnthropicToolSearchToolBm25' + - $ref: '#/components/schemas/AnthropicToolSearchToolRegex' + - $ref: '#/components/schemas/ShellServerTool_OpenRouter' + - $ref: '#/components/schemas/ToolSearchServerTool' + type: 'array' + top_k: + type: 'integer' + top_p: + format: 'double' + type: 'number' + trace: + $ref: '#/components/schemas/TraceConfig' + user: + description: '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.' + maxLength: 256 type: 'string' - usage: - properties: - cache_creation: - $ref: '#/components/schemas/AnthropicCacheCreation' - cache_creation_input_tokens: - type: - - 'integer' - - 'null' - cache_read_input_tokens: + required: + - 'model' + - 'messages' + type: 'object' + MessagesResult: + allOf: + - $ref: '#/components/schemas/BaseMessagesResult' + - properties: + context_management: + properties: + applied_edits: + items: + additionalProperties: {} + properties: + type: + type: 'string' + required: + - 'type' + type: 'object' + type: 'array' + required: + - 'applied_edits' type: - - 'integer' + - 'object' - 'null' - input_tokens: + openrouter_metadata: + $ref: '#/components/schemas/OpenRouterMetadata' + provider: + type: 'string' + safeguard_results: + items: + $ref: '#/components/schemas/AnthropicSafeguardResult' type: - - 'integer' + - 'array' - 'null' - iterations: - items: - $ref: '#/components/schemas/AnthropicUsageIteration' - type: 'array' - output_tokens: - type: 'integer' - output_tokens_details: - $ref: '#/components/schemas/AnthropicOutputTokensDetails' - server_tool_use: - $ref: '#/components/schemas/ORAnthropicServerToolUsage' - required: - - 'input_tokens' - - 'output_tokens' - - 'output_tokens_details' - - 'cache_creation_input_tokens' - - 'cache_read_input_tokens' - - 'server_tool_use' + usage: + allOf: + - $ref: '#/components/schemas/AnthropicUsage' + - properties: + cost: + format: 'double' + type: + - 'number' + - 'null' + cost_details: + $ref: '#/components/schemas/CostDetails' + is_byok: + type: 'boolean' + iterations: + items: + $ref: '#/components/schemas/AnthropicUsageIteration' + type: 'array' + server_tool_use: + $ref: '#/components/schemas/ORAnthropicServerToolUsage' + service_tier: + type: + - 'string' + - 'null' + speed: + $ref: '#/components/schemas/AnthropicSpeed' + type: 'object' + example: + cache_creation: null + cache_creation_input_tokens: null + cache_read_input_tokens: null + inference_geo: null + input_tokens: 100 + output_tokens: 50 + output_tokens_details: null + server_tool_use: null + service_tier: 'standard' type: 'object' - required: - - 'type' - - 'delta' - - 'usage' - type: 'object' - MessagesErrorEvent: - description: 'Error event in the stream' + description: 'Non-streaming response from the Anthropic Messages API with OpenRouter extensions' example: - error: - error_type: 'provider_overloaded' - message: 'Overloaded' - type: 'overloaded_error' - type: 'error' + container: null + content: + - citations: [] + text: 'Hello! I''m doing well, thank you for asking.' + type: 'text' + id: 'msg_01XFDUDYJgAACzvnptvVoYEL' + model: 'claude-sonnet-4-5-20250929' + role: 'assistant' + stop_details: null + stop_reason: 'end_turn' + stop_sequence: null + type: 'message' + usage: + cache_creation: null + cache_creation_input_tokens: null + cache_read_input_tokens: null + inference_geo: null + input_tokens: 12 + output_tokens: 15 + output_tokens_details: null + server_tool_use: null + service_tier: 'standard' + MessagesSearchModelsServerTool: + description: 'OpenRouter built-in server tool: searches and filters AI models available on OpenRouter' + example: + parameters: + max_results: 5 + type: 'openrouter:experimental__search_models' properties: - error: - properties: - error_type: - $ref: '#/components/schemas/ApiErrorType' - message: - type: 'string' - type: - type: 'string' - required: - - 'type' - - 'message' - type: 'object' - openrouter_metadata: - $ref: '#/components/schemas/OpenRouterMetadata' + parameters: + $ref: '#/components/schemas/SearchModelsServerToolConfig' type: enum: - - 'error' + - 'openrouter:experimental__search_models' type: 'string' required: - 'type' - - 'error' type: 'object' - MessagesFallbackParam: - additionalProperties: {} - description: 'Fallback model to try when the primary model fails or refuses. Only the `model` field is supported; per-attempt overrides are rejected.' + MessagesShellToolResultBlock: + description: 'Output of an `openrouter:shell` call from a prior assistant turn. Accepted on replay and dropped before the provider request — Anthropic has no equivalent block.' example: - model: 'claude-opus-4-8' + content: + output: + - outcome: + exit_code: 0 + type: 'exit' + stderr: '' + stdout: "README.md\n" + tool_use_id: 'srvtoolu_01abc' + type: 'openrouter_shell_tool_result' properties: - model: + container_id: + description: 'The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed.' + type: 'string' + content: + additionalProperties: {} + type: 'object' + files: + description: 'Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API.' + items: + properties: + container_id: + type: 'string' + end_index: + type: 'integer' + file_id: + type: 'string' + filename: + type: 'string' + start_index: + type: 'integer' + type: + enum: + - 'container_file_citation' + type: 'string' + required: + - 'type' + - 'container_id' + - 'file_id' + - 'filename' + - 'start_index' + - 'end_index' + type: 'object' + type: 'array' + tool_use_id: + type: 'string' + type: + enum: + - 'openrouter_shell_tool_result' type: 'string' required: - - 'model' + - 'type' + - 'tool_use_id' + - 'content' type: 'object' - MessagesMessageParam: - description: 'Anthropic message with OpenRouter extensions' + MessagesStartEvent: + description: 'Event sent at the start of a streaming message' example: - content: 'Hello, how are you?' - role: 'user' + message: + container: null + content: [] + id: 'msg_01XFDUDYJgAACzvnptvVoYEL' + model: 'claude-sonnet-4-5-20250929' + role: 'assistant' + stop_details: null + stop_reason: null + stop_sequence: null + type: 'message' + usage: + cache_creation: null + cache_creation_input_tokens: null + cache_read_input_tokens: null + inference_geo: null + input_tokens: 12 + output_tokens: 0 + output_tokens_details: null + server_tool_use: null + service_tier: 'standard' + type: 'message_start' properties: - clear_at: - $ref: '#/components/schemas/AnthropicSystemClearAt' - content: - anyOf: - - type: 'string' - - items: - oneOf: - - $ref: '#/components/schemas/AnthropicTextBlockParam' - - $ref: '#/components/schemas/AnthropicImageBlockParam' - - $ref: '#/components/schemas/AnthropicDocumentBlockParam' - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - id: - type: 'string' - input: {} - name: - type: 'string' - type: - enum: - - 'tool_use' - type: 'string' - required: - - 'type' - - 'id' - - 'name' - type: 'object' - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - content: - anyOf: - - type: 'string' - - items: - anyOf: - - $ref: '#/components/schemas/AnthropicTextBlockParam' - - $ref: '#/components/schemas/AnthropicImageBlockParam' - - properties: - tool_name: - type: 'string' - type: - enum: - - 'tool_reference' - type: 'string' - required: - - 'type' - - 'tool_name' - type: 'object' - - $ref: '#/components/schemas/AnthropicSearchResultBlockParam' - - $ref: '#/components/schemas/AnthropicDocumentBlockParam' - type: 'array' - is_error: - type: 'boolean' - tool_use_id: - type: 'string' - type: - enum: - - 'tool_result' - type: 'string' - required: - - 'type' - - 'tool_use_id' - type: 'object' - - properties: - signature: - type: 'string' - thinking: - type: 'string' - type: - enum: - - 'thinking' - type: 'string' - required: - - 'type' - - 'thinking' - - 'signature' - type: 'object' - - properties: - data: - type: 'string' - type: - enum: - - 'redacted_thinking' - type: 'string' - required: - - 'type' - - 'data' - type: 'object' - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - id: - type: 'string' - input: {} - name: - type: 'string' - type: - enum: - - 'server_tool_use' - type: 'string' - required: - - 'type' - - 'id' - - 'name' - type: 'object' - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - content: - anyOf: - - items: - $ref: '#/components/schemas/AnthropicWebSearchResultBlockParam' - type: 'array' - - properties: - error_code: - enum: - - 'invalid_tool_input' - - 'unavailable' - - 'max_uses_exceeded' - - 'too_many_requests' - - 'query_too_long' - - 'request_too_large' - type: 'string' - type: - enum: - - 'web_search_tool_result_error' - type: 'string' - required: - - 'type' - - 'error_code' - type: 'object' - tool_use_id: - type: 'string' - type: - enum: - - 'web_search_tool_result' - type: 'string' - required: - - 'type' - - 'tool_use_id' - - 'content' - type: 'object' - - $ref: '#/components/schemas/AnthropicSearchResultBlockParam' - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - content: - type: - - 'string' - - 'null' - encrypted_content: - type: - - 'string' - - 'null' - type: - enum: - - 'compaction' - type: 'string' - required: - - 'type' - - 'content' - type: 'object' - - $ref: '#/components/schemas/MessagesAdvisorToolResultBlock' - - $ref: '#/components/schemas/MessagesToolAdditionBlock' - - $ref: '#/components/schemas/MessagesToolRemovalBlock' - - $ref: '#/components/schemas/MessagesShellToolResultBlock' - - $ref: '#/components/schemas/MessagesBashToolResultBlock' - - $ref: '#/components/schemas/ORAnthropicToolSearchResultParam' - type: 'array' - output_config: - $ref: '#/components/schemas/AnthropicMessageOutputConfig' - role: - enum: - - 'user' - - 'assistant' - - 'system' - type: 'string' - required: - - 'role' - - 'content' - type: 'object' - MessagesOutputConfig: - description: 'Configuration for controlling output behavior. Supports the effort parameter and structured output format.' - example: - effort: 'medium' - properties: - effort: - description: 'How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer. Valid values are `low`, `medium`, `high`, `xhigh`, or `max`.' - enum: - - 'low' - - 'medium' - - 'high' - - 'xhigh' - - 'max' - - null - example: 'medium' - type: - - 'string' - - 'null' - format: - description: 'A schema to specify Claude''s output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs).' + message: properties: - schema: - additionalProperties: {} - type: 'object' - type: - enum: - - 'json_schema' + container: + $ref: '#/components/schemas/AnthropicContainer' + content: + items: + $ref: '#/components/schemas/ORAnthropicContentBlock' + type: 'array' + id: type: 'string' - required: - - 'type' - - 'schema' - type: - - 'object' - - 'null' - task_budget: - description: 'Task budget for an agentic turn. The model sees a countdown of remaining tokens and uses it to prioritize work and wind down gracefully. Advisory — does not enforce a hard cap.' - example: - total: 400000 - type: 'tokens' - properties: - remaining: - minimum: 0 + input_transformations: + items: + $ref: '#/components/schemas/AnthropicInputTransformation' type: - - 'integer' + - 'array' - 'null' - total: - minimum: 20000 - type: 'integer' + model: + type: 'string' + provider: + enum: + - 'AnyScale' + - 'Atoma' + - 'Cent-ML' + - 'CrofAI' + - 'Enfer' + - 'GoPomelo' + - 'HuggingFace' + - 'Hyperbolic' + - 'Hyperbolic 2' + - 'InoCloud' + - 'Kluster' + - 'Lambda' + - 'Lepton' + - 'Lynn 2' + - 'Lynn' + - 'Mancer' + - 'Modal' + - 'NCompass' + - 'Nineteen' + - 'OctoAI' + - 'Recursal' + - 'Reflection' + - 'Replicate' + - 'SambaNova 2' + - 'SF Compute' + - 'Targon' + - 'Together 2' + - 'Ubicloud' + - '01.AI' + - 'AkashML' + - 'AI21' + - 'AionLabs' + - 'Alibaba' + - 'Ambient' + - 'Baidu' + - 'Amazon Bedrock' + - 'Amazon Nova' + - 'Anthropic' + - 'Arcee AI' + - 'AssemblyAI' + - 'AtlasCloud' + - 'Avian' + - 'Azure' + - 'BaseTen' + - 'BytePlus' + - 'Black Forest Labs' + - 'Cerebras' + - 'Chutes' + - 'Cirrascale' + - 'Claude Platform on AWS' + - 'Clarifai' + - 'Cloudflare' + - 'Cohere' + - 'CoreWeave' + - 'Cosine' + - 'Crucible' + - 'Crusoe' + - 'Darkbloom' + - 'Databricks' + - 'Decart' + - 'Deepgram' + - 'DeepInfra' + - 'DeepSeek' + - 'DekaLLM' + - 'DigitalOcean' + - 'ElevenLabs' + - 'Featherless' + - 'Fireworks' + - 'Fish Audio' + - 'Friendli' + - 'GMICloud' + - 'Google' + - 'Google AI Studio' + - 'Groq' + - 'HeyGen' + - 'Inception' + - 'Inceptron' + - 'InferenceNet' + - 'Ionstream' + - 'Infermatic' + - 'Io Net' + - 'Inferact vLLM' + - 'Inflection' + - 'Liquid' + - 'Makora' + - 'Mara' + - 'Mancer 2' + - 'Meta' + - 'Minimax' + - 'ModelRun' + - 'Mistral' + - 'Modular' + - 'Moonshot AI' + - 'Morph' + - 'VoyageAI by MongoDB' + - 'TypeSafe' + - 'Near AI' + - 'Nebius' + - 'Nex AGI' + - 'NextBit' + - 'Novita' + - 'Nvidia' + - 'Ollama' + - 'OpenAI' + - 'OpenInference' + - 'Parasail' + - 'ParetoAlpha' + - 'Poolside' + - 'PrimeIntellect' + - 'Perceptron' + - 'Perplexity' + - 'Phala' + - 'Recraft' + - 'Recursive' + - 'Reka' + - 'Relace' + - 'Respan' + - 'Sail Research' + - 'Sakana AI' + - 'SambaNova' + - 'ScaleDown' + - 'Seed' + - 'SiliconFlow' + - 'Sourceful' + - 'StepFun' + - 'Stealth' + - 'StreamLake' + - 'Switchpoint' + - 'Tencent' + - 'Tenstorrent' + - 'Thinking Machines' + - 'Together' + - 'Unbiased' + - 'Upstage' + - 'Venice' + - 'Wafer' + - 'WandB' + - 'Quiver' + - 'Krea' + - 'Runway' + - 'Xiaomi' + - 'xAI' + - 'Z.AI' + - 'FakeProvider' + type: 'string' + x-speakeasy-unknown-values: 'allow' + role: + enum: + - 'assistant' + type: 'string' + stop_details: + $ref: '#/components/schemas/AnthropicRefusalStopDetails' + stop_reason: {} + stop_sequence: {} type: enum: - - 'tokens' + - 'message' type: 'string' + usage: + allOf: + - $ref: '#/components/schemas/AnthropicUsage' + - properties: + iterations: + items: + $ref: '#/components/schemas/AnthropicUsageIteration' + type: 'array' + speed: + $ref: '#/components/schemas/AnthropicSpeed' + type: 'object' + example: + cache_creation: + ephemeral_1h_input_tokens: 0 + ephemeral_5m_input_tokens: 7381 + cache_creation_input_tokens: 7381 + cache_read_input_tokens: 0 + inference_geo: null + input_tokens: 100 + output_tokens: 1 + output_tokens_details: null + server_tool_use: null + service_tier: 'standard' required: + - 'id' - 'type' - - 'total' - type: - - 'object' - - 'null' + - 'role' + - 'container' + - 'content' + - 'model' + - 'stop_reason' + - 'stop_details' + - 'stop_sequence' + - 'usage' + type: 'object' + type: + enum: + - 'message_start' + type: 'string' + required: + - 'type' + - 'message' type: 'object' - MessagesPingEvent: - description: 'Keep-alive ping event' + MessagesStopEvent: + description: 'Event sent when the message is complete' example: - type: 'ping' + type: 'message_stop' properties: + openrouter_metadata: + $ref: '#/components/schemas/OpenRouterMetadata' type: enum: - - 'ping' + - 'message_stop' type: 'string' required: - 'type' type: 'object' - MessagesRequest: - description: 'Request schema for Anthropic Messages API endpoint' + MessagesStreamEvents: + description: 'Union of all possible streaming events' + discriminator: + mapping: + content_block_delta: '#/components/schemas/MessagesContentBlockDeltaEvent' + content_block_start: '#/components/schemas/MessagesContentBlockStartEvent' + content_block_stop: '#/components/schemas/MessagesContentBlockStopEvent' + error: '#/components/schemas/MessagesErrorEvent' + message_delta: '#/components/schemas/MessagesDeltaEvent' + message_start: '#/components/schemas/MessagesStartEvent' + message_stop: '#/components/schemas/MessagesStopEvent' + ping: '#/components/schemas/MessagesPingEvent' + propertyName: 'type' example: - max_tokens: 1024 - messages: - - content: 'Hello, how are you?' - role: 'user' - model: 'anthropic/claude-4.5-sonnet-20250929' - temperature: 0.7 + delta: + text: 'Hello' + type: 'text_delta' + index: 0 + type: 'content_block_delta' + oneOf: + - $ref: '#/components/schemas/MessagesStartEvent' + - $ref: '#/components/schemas/MessagesDeltaEvent' + - $ref: '#/components/schemas/MessagesStopEvent' + - $ref: '#/components/schemas/MessagesContentBlockStartEvent' + - $ref: '#/components/schemas/MessagesContentBlockDeltaEvent' + - $ref: '#/components/schemas/MessagesContentBlockStopEvent' + - $ref: '#/components/schemas/MessagesPingEvent' + - $ref: '#/components/schemas/MessagesErrorEvent' + MessagesStreamingResponse: + example: + data: + delta: + text: 'Hello' + type: 'text_delta' + index: 0 + type: 'content_block_delta' + event: 'content_block_delta' + properties: + data: + $ref: '#/components/schemas/MessagesStreamEvents' + event: + type: 'string' + required: + - 'event' + - 'data' + type: 'object' + MessagesToolAdditionBlock: + description: 'Loads a previously deferred tool (declared in `tools` with `defer_loading: true`) mid-conversation without invalidating the prompt cache. Only valid in `role: "system"` messages. Not supported on Claude Sonnet 5 or models older than Claude Opus 4.8.' + example: + tool: + name: 'get_forecast' + type: 'tool_reference' + type: 'tool_addition' properties: cache_control: $ref: '#/components/schemas/AnthropicCacheControlDirective' - context_management: - properties: - edits: - items: - oneOf: - - properties: - clear_at_least: - $ref: '#/components/schemas/AnthropicInputTokensClearAtLeast' - clear_tool_inputs: - anyOf: - - type: 'boolean' - - items: - type: 'string' - type: 'array' - - type: 'null' - exclude_tools: - items: - type: 'string' - type: - - 'array' - - 'null' - keep: - $ref: '#/components/schemas/AnthropicToolUsesKeep' - trigger: - discriminator: - mapping: - input_tokens: '#/components/schemas/AnthropicInputTokensTrigger' - tool_uses: '#/components/schemas/AnthropicToolUsesTrigger' - propertyName: 'type' - oneOf: - - $ref: '#/components/schemas/AnthropicInputTokensTrigger' - - $ref: '#/components/schemas/AnthropicToolUsesTrigger' - type: - enum: - - 'clear_tool_uses_20250919' - type: 'string' - required: - - 'type' - type: 'object' - - properties: - keep: - anyOf: - - $ref: '#/components/schemas/AnthropicThinkingTurns' - - properties: - type: - enum: - - 'all' - type: 'string' - required: - - 'type' - type: 'object' - - enum: - - 'all' - type: 'string' - type: - enum: - - 'clear_thinking_20251015' - type: 'string' - required: - - 'type' - type: 'object' - - properties: - instructions: - type: - - 'string' - - 'null' - pause_after_compaction: - type: 'boolean' - trigger: - anyOf: - - allOf: - - $ref: '#/components/schemas/AnthropicInputTokensTrigger' - - properties: {} - type: 'object' - - type: 'null' - example: - type: 'input_tokens' - value: 100000 - type: - enum: - - 'compact_20260112' - type: 'string' - required: - - 'type' - type: 'object' - type: 'array' - type: - - 'object' - - 'null' - deferred_tools: - $ref: '#/components/schemas/DeferredToolsControl' - fallbacks: - description: '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.' - example: - - model: 'claude-opus-4-8' - items: - $ref: '#/components/schemas/MessagesFallbackParam' - type: - - 'array' - - 'null' - max_tokens: - type: 'integer' - messages: - items: - $ref: '#/components/schemas/MessagesMessageParam' - type: - - 'array' - - 'null' - metadata: - properties: - user_id: - type: - - 'string' - - 'null' - type: 'object' - model: - type: 'string' - models: - items: - type: 'string' - type: 'array' - output_config: - $ref: '#/components/schemas/MessagesOutputConfig' - plugins: - description: 'Plugins you want to enable for this request, including their settings.' - items: - discriminator: - mapping: - alignment: '#/components/schemas/AlignmentPlugin' - armor: '#/components/schemas/ArmorPlugin' - auto-beta-router: '#/components/schemas/AutoBetaRouterPlugin' - auto-router: '#/components/schemas/AutoRouterPlugin' - context-compression: '#/components/schemas/ContextCompressionPlugin' - file-parser: '#/components/schemas/FileParserPlugin' - fusion: '#/components/schemas/FusionPlugin' - jev-router: '#/components/schemas/JevRouterPlugin' - moderation: '#/components/schemas/ModerationPlugin' - pareto-router: '#/components/schemas/ParetoRouterPlugin' - response-healing: '#/components/schemas/ResponseHealingPlugin' - switchyard-router: '#/components/schemas/SwitchyardRouterPlugin' - web: '#/components/schemas/WebSearchPlugin' - web-fetch: '#/components/schemas/WebFetchPlugin' - propertyName: 'id' - oneOf: - - $ref: '#/components/schemas/AutoRouterPlugin' - - $ref: '#/components/schemas/AutoBetaRouterPlugin' - - $ref: '#/components/schemas/ModerationPlugin' - - $ref: '#/components/schemas/WebSearchPlugin' - - $ref: '#/components/schemas/WebFetchPlugin' - - $ref: '#/components/schemas/FileParserPlugin' - - $ref: '#/components/schemas/ResponseHealingPlugin' - - $ref: '#/components/schemas/ContextCompressionPlugin' - - $ref: '#/components/schemas/ParetoRouterPlugin' - - $ref: '#/components/schemas/FusionPlugin' - - $ref: '#/components/schemas/SwitchyardRouterPlugin' - - $ref: '#/components/schemas/JevRouterPlugin' - - $ref: '#/components/schemas/AlignmentPlugin' - - $ref: '#/components/schemas/ArmorPlugin' - type: 'array' - provider: - $ref: '#/components/schemas/ProviderPreferences' - route: - $ref: '#/components/schemas/DeprecatedRoute' - safeguards: - items: - $ref: '#/components/schemas/AnthropicSafeguard' - type: - - 'array' - - 'null' - service_tier: - type: 'string' - session_id: - description: '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.' - maxLength: 256 - type: 'string' - speed: - allOf: - - $ref: '#/components/schemas/AnthropicSpeed' - - description: 'Controls output generation speed. When set to `fast`, uses a higher-speed inference configuration at premium pricing. Defaults to `standard` when omitted.' - example: 'fast' - stop_sequences: - items: - type: 'string' - type: 'array' - stop_server_tools_when: - $ref: '#/components/schemas/StopServerToolsWhen' - stream: - type: 'boolean' - system: - anyOf: - - type: 'string' - - items: - $ref: '#/components/schemas/AnthropicTextBlockParam' - type: 'array' - temperature: - format: 'double' - type: 'number' - thinking: + tool: oneOf: - properties: - block_binding: - $ref: '#/components/schemas/AnthropicThinkingBlockBinding' - budget_tokens: - type: 'integer' - display: - $ref: '#/components/schemas/AnthropicThinkingDisplay' + name: + type: 'string' type: enum: - - 'enabled' + - 'tool_reference' type: 'string' required: - 'type' - - 'budget_tokens' + - 'name' type: 'object' - properties: + name: + type: 'string' + server_name: + type: 'string' type: enum: - - 'disabled' + - 'mcp_tool_reference' type: 'string' required: - 'type' + - 'name' + - 'server_name' type: 'object' - properties: - block_binding: - $ref: '#/components/schemas/AnthropicThinkingBlockBinding' - display: - $ref: '#/components/schemas/AnthropicThinkingDisplay' - type: - enum: - - 'adaptive' + server_name: type: 'string' - required: - - 'type' - type: 'object' - - additionalProperties: false - properties: type: enum: - - 'between_tools' + - 'mcp_toolset_reference' type: 'string' required: - 'type' + - 'server_name' type: 'object' - tool_choice: + type: + enum: + - 'tool_addition' + type: 'string' + required: + - 'type' + - 'tool' + type: 'object' + MessagesToolRemovalBlock: + description: 'Removes a tool from the conversation mid-conversation without invalidating the prompt cache. Only valid in `role: "system"` messages. Not supported on Claude Sonnet 5 or models older than Claude Opus 4.8.' + example: + tool: + name: 'get_weather' + type: 'tool_reference' + type: 'tool_removal' + properties: + cache_control: + $ref: '#/components/schemas/AnthropicCacheControlDirective' + tool: oneOf: - properties: - disable_parallel_tool_use: - type: 'boolean' - type: - enum: - - 'auto' + name: type: 'string' - required: - - 'type' - type: 'object' - - properties: - disable_parallel_tool_use: - type: 'boolean' type: enum: - - 'any' + - 'tool_reference' type: 'string' required: - 'type' + - 'name' type: 'object' - properties: + name: + type: 'string' + server_name: + type: 'string' type: enum: - - 'none' + - 'mcp_tool_reference' type: 'string' required: - 'type' + - 'name' + - 'server_name' type: 'object' - properties: - disable_parallel_tool_use: - type: 'boolean' - name: + server_name: type: 'string' type: enum: - - 'tool' + - 'mcp_toolset_reference' type: 'string' required: - 'type' - - 'name' + - 'server_name' type: 'object' - tools: - items: - anyOf: - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - defer_loading: - type: 'boolean' - description: - type: 'string' - input_schema: - additionalProperties: {} - properties: - properties: {} - required: - items: - type: 'string' - type: - - 'array' - - 'null' - type: - default: 'object' - type: 'string' - type: 'object' - name: - type: 'string' - strict: - type: 'boolean' - type: - enum: - - 'custom' - type: 'string' - required: - - 'name' - - 'input_schema' - type: 'object' - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - name: - enum: - - 'bash' - type: 'string' - type: - enum: - - 'bash_20250124' - type: 'string' - required: - - 'type' - - 'name' - type: 'object' - - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - name: - enum: - - 'str_replace_editor' - type: 'string' - type: - enum: - - 'text_editor_20250124' - type: 'string' - required: - - 'type' - - 'name' - type: 'object' - - properties: - allowed_domains: - items: - type: 'string' - type: - - 'array' - - 'null' - blocked_domains: - items: - type: 'string' - type: - - 'array' - - 'null' - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - max_uses: - type: - - 'integer' - - 'null' - name: - enum: - - 'web_search' - type: 'string' - type: - enum: - - 'web_search_20250305' - type: 'string' - user_location: - $ref: '#/components/schemas/AnthropicWebSearchToolUserLocation' - required: - - 'type' - - 'name' - type: 'object' - - properties: - allowed_callers: - $ref: '#/components/schemas/AnthropicAllowedCallers' - allowed_domains: - items: - type: 'string' - type: - - 'array' - - 'null' - blocked_domains: - items: - type: 'string' - type: - - 'array' - - 'null' - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - max_uses: - type: - - 'integer' - - 'null' - name: - enum: - - 'web_search' - type: 'string' - type: - enum: - - 'web_search_20260209' - type: 'string' - user_location: - $ref: '#/components/schemas/AnthropicWebSearchToolUserLocation' - required: - - 'type' - - 'name' - type: 'object' - - properties: - allowed_callers: - $ref: '#/components/schemas/AnthropicAllowedCallers' - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - caching: - anyOf: - - $ref: '#/components/schemas/AnthropicCacheControlDirective' - - type: 'null' - defer_loading: - type: 'boolean' - max_uses: - type: 'integer' - model: - type: 'string' - name: - enum: - - 'advisor' - type: 'string' - type: - enum: - - 'advisor_20260301' - type: 'string' - required: - - 'type' - - 'name' - - 'model' - type: 'object' - - $ref: '#/components/schemas/BashServerTool' - - $ref: '#/components/schemas/DatetimeServerTool' - - $ref: '#/components/schemas/ImageGenerationServerTool_OpenRouter' - - $ref: '#/components/schemas/MessagesSearchModelsServerTool' - - $ref: '#/components/schemas/WebFetchServerTool' - - $ref: '#/components/schemas/OpenRouterWebSearchServerTool' - - additionalProperties: {} - properties: - type: - type: 'string' - required: - - 'type' - type: 'object' - - $ref: '#/components/schemas/AnthropicToolSearchToolBm25' - - $ref: '#/components/schemas/AnthropicToolSearchToolRegex' - - $ref: '#/components/schemas/ShellServerTool_OpenRouter' - - $ref: '#/components/schemas/ToolSearchServerTool' - type: 'array' - top_k: - type: 'integer' - top_p: - format: 'double' - type: 'number' - trace: - $ref: '#/components/schemas/TraceConfig' - user: - description: '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.' - maxLength: 256 - type: 'string' - required: - - 'model' - - 'messages' - type: 'object' - MessagesResult: - allOf: - - $ref: '#/components/schemas/BaseMessagesResult' - - properties: - context_management: - properties: - applied_edits: - items: - additionalProperties: {} - properties: - type: - type: 'string' - required: - - 'type' - type: 'object' - type: 'array' - required: - - 'applied_edits' - type: - - 'object' - - 'null' - openrouter_metadata: - $ref: '#/components/schemas/OpenRouterMetadata' - provider: - type: 'string' - safeguard_results: - items: - $ref: '#/components/schemas/AnthropicSafeguardResult' - type: - - 'array' - - 'null' - usage: - allOf: - - $ref: '#/components/schemas/AnthropicUsage' - - properties: - cost: - format: 'double' - type: - - 'number' - - 'null' - cost_details: - $ref: '#/components/schemas/CostDetails' - is_byok: - type: 'boolean' - iterations: - items: - $ref: '#/components/schemas/AnthropicUsageIteration' - type: 'array' - server_tool_use: - $ref: '#/components/schemas/ORAnthropicServerToolUsage' - service_tier: - type: - - 'string' - - 'null' - speed: - $ref: '#/components/schemas/AnthropicSpeed' - type: 'object' - example: - cache_creation: null - cache_creation_input_tokens: null - cache_read_input_tokens: null - inference_geo: null - input_tokens: 100 - output_tokens: 50 - output_tokens_details: null - server_tool_use: null - service_tier: 'standard' - type: 'object' - description: 'Non-streaming response from the Anthropic Messages API with OpenRouter extensions' - example: - container: null - content: - - citations: [] - text: 'Hello! I''m doing well, thank you for asking.' - type: 'text' - id: 'msg_01XFDUDYJgAACzvnptvVoYEL' - model: 'claude-sonnet-4-5-20250929' - role: 'assistant' - stop_details: null - stop_reason: 'end_turn' - stop_sequence: null - type: 'message' - usage: - cache_creation: null - cache_creation_input_tokens: null - cache_read_input_tokens: null - inference_geo: null - input_tokens: 12 - output_tokens: 15 - output_tokens_details: null - server_tool_use: null - service_tier: 'standard' - MessagesSearchModelsServerTool: - description: 'OpenRouter built-in server tool: searches and filters AI models available on OpenRouter' - example: - parameters: - max_results: 5 - type: 'openrouter:experimental__search_models' - properties: - parameters: - $ref: '#/components/schemas/SearchModelsServerToolConfig' type: enum: - - 'openrouter:experimental__search_models' + - 'tool_removal' type: 'string' required: - 'type' - type: 'object' - MessagesShellToolResultBlock: - description: 'Output of an `openrouter:shell` call from a prior assistant turn. Accepted on replay and dropped before the provider request — Anthropic has no equivalent block.' - example: - content: - output: - - outcome: - exit_code: 0 - type: 'exit' - stderr: '' - stdout: "README.md\n" - tool_use_id: 'srvtoolu_01abc' - type: 'openrouter_shell_tool_result' - properties: - container_id: - description: 'The canonical container id the command ran under — the `{container_id}` for the Container Files API, reusable as a `container_reference` in later requests. Present on every sandbox-executed call, even when no files changed.' - type: 'string' - content: - additionalProperties: {} - type: 'object' - files: - description: 'Citations for the files the sandbox command created or modified, most-recently-touched first (at most 10). Retrieve them via the Container Files API.' - items: - properties: - container_id: - type: 'string' - end_index: - type: 'integer' - file_id: - type: 'string' - filename: - type: 'string' - start_index: - type: 'integer' - type: - enum: - - 'container_file_citation' - type: 'string' - required: - - 'type' - - 'container_id' - - 'file_id' - - 'filename' - - 'start_index' - - 'end_index' - type: 'object' - type: 'array' - tool_use_id: - type: 'string' - type: - enum: - - 'openrouter_shell_tool_result' - type: 'string' - required: - - 'type' - - 'tool_use_id' - - 'content' - type: 'object' - MessagesStartEvent: - description: 'Event sent at the start of a streaming message' - example: - message: - container: null - content: [] - id: 'msg_01XFDUDYJgAACzvnptvVoYEL' - model: 'claude-sonnet-4-5-20250929' - role: 'assistant' - stop_details: null - stop_reason: null - stop_sequence: null - type: 'message' - usage: - cache_creation: null - cache_creation_input_tokens: null - cache_read_input_tokens: null - inference_geo: null - input_tokens: 12 - output_tokens: 0 - output_tokens_details: null - server_tool_use: null - service_tier: 'standard' - type: 'message_start' - properties: - message: - properties: - container: - $ref: '#/components/schemas/AnthropicContainer' - content: - items: - $ref: '#/components/schemas/ORAnthropicContentBlock' - type: 'array' - id: - type: 'string' - input_transformations: - items: - $ref: '#/components/schemas/AnthropicInputTransformation' - type: - - 'array' - - 'null' - model: - type: 'string' - provider: - enum: - - 'AnyScale' - - 'Atoma' - - 'Cent-ML' - - 'CrofAI' - - 'Enfer' - - 'GoPomelo' - - 'HuggingFace' - - 'Hyperbolic' - - 'Hyperbolic 2' - - 'InoCloud' - - 'Kluster' - - 'Lambda' - - 'Lepton' - - 'Lynn 2' - - 'Lynn' - - 'Mancer' - - 'Modal' - - 'NCompass' - - 'Nineteen' - - 'OctoAI' - - 'Recursal' - - 'Reflection' - - 'Replicate' - - 'SambaNova 2' - - 'SF Compute' - - 'Targon' - - 'Together 2' - - 'Ubicloud' - - '01.AI' - - 'AkashML' - - 'AI21' - - 'AionLabs' - - 'Alibaba' - - 'Ambient' - - 'Baidu' - - 'Amazon Bedrock' - - 'Amazon Nova' - - 'Anthropic' - - 'Arcee AI' - - 'AssemblyAI' - - 'AtlasCloud' - - 'Avian' - - 'Azure' - - 'BaseTen' - - 'BytePlus' - - 'Black Forest Labs' - - 'Cerebras' - - 'Chutes' - - 'Cirrascale' - - 'Claude Platform on AWS' - - 'Clarifai' - - 'Cloudflare' - - 'Cohere' - - 'CoreWeave' - - 'Cosine' - - 'Crucible' - - 'Crusoe' - - 'Darkbloom' - - 'Databricks' - - 'Decart' - - 'Deepgram' - - 'DeepInfra' - - 'DeepSeek' - - 'DekaLLM' - - 'DigitalOcean' - - 'ElevenLabs' - - 'Featherless' - - 'Fireworks' - - 'Fish Audio' - - 'Friendli' - - 'GMICloud' - - 'Google' - - 'Google AI Studio' - - 'Groq' - - 'HeyGen' - - 'Inception' - - 'Inceptron' - - 'InferenceNet' - - 'Ionstream' - - 'Infermatic' - - 'Io Net' - - 'Inferact vLLM' - - 'Inflection' - - 'Liquid' - - 'Makora' - - 'Mara' - - 'Mancer 2' - - 'Meta' - - 'Minimax' - - 'ModelRun' - - 'Mistral' - - 'Modular' - - 'Moonshot AI' - - 'Morph' - - 'VoyageAI by MongoDB' - - 'TypeSafe' - - 'Near AI' - - 'Nebius' - - 'Nex AGI' - - 'NextBit' - - 'Novita' - - 'Nvidia' - - 'Ollama' - - 'OpenAI' - - 'OpenInference' - - 'Parasail' - - 'ParetoAlpha' - - 'Poolside' - - 'PrimeIntellect' - - 'Perceptron' - - 'Perplexity' - - 'Phala' - - 'Recraft' - - 'Recursive' - - 'Reka' - - 'Relace' - - 'Respan' - - 'Sail Research' - - 'Sakana AI' - - 'SambaNova' - - 'ScaleDown' - - 'Seed' - - 'SiliconFlow' - - 'Sourceful' - - 'StepFun' - - 'Stealth' - - 'StreamLake' - - 'Switchpoint' - - 'Tencent' - - 'Tenstorrent' - - 'Thinking Machines' - - 'Together' - - 'Unbiased' - - 'Upstage' - - 'Venice' - - 'Wafer' - - 'WandB' - - 'Quiver' - - 'Krea' - - 'Runway' - - 'Xiaomi' - - 'xAI' - - 'Z.AI' - - 'FakeProvider' - type: 'string' - x-speakeasy-unknown-values: 'allow' - role: - enum: - - 'assistant' - type: 'string' - stop_details: - $ref: '#/components/schemas/AnthropicRefusalStopDetails' - stop_reason: {} - stop_sequence: {} - type: - enum: - - 'message' - type: 'string' - usage: - allOf: - - $ref: '#/components/schemas/AnthropicUsage' - - properties: - iterations: - items: - $ref: '#/components/schemas/AnthropicUsageIteration' - type: 'array' - speed: - $ref: '#/components/schemas/AnthropicSpeed' - type: 'object' - example: - cache_creation: - ephemeral_1h_input_tokens: 0 - ephemeral_5m_input_tokens: 7381 - cache_creation_input_tokens: 7381 - cache_read_input_tokens: 0 - inference_geo: null - input_tokens: 100 - output_tokens: 1 - output_tokens_details: null - server_tool_use: null - service_tier: 'standard' - required: - - 'id' - - 'type' - - 'role' - - 'container' - - 'content' - - 'model' - - 'stop_reason' - - 'stop_details' - - 'stop_sequence' - - 'usage' - type: 'object' - type: - enum: - - 'message_start' - type: 'string' - required: - - 'type' - - 'message' - type: 'object' - MessagesStopEvent: - description: 'Event sent when the message is complete' - example: - type: 'message_stop' - properties: - openrouter_metadata: - $ref: '#/components/schemas/OpenRouterMetadata' - type: - enum: - - 'message_stop' - type: 'string' - required: - - 'type' - type: 'object' - MessagesStreamEvents: - description: 'Union of all possible streaming events' - discriminator: - mapping: - content_block_delta: '#/components/schemas/MessagesContentBlockDeltaEvent' - content_block_start: '#/components/schemas/MessagesContentBlockStartEvent' - content_block_stop: '#/components/schemas/MessagesContentBlockStopEvent' - error: '#/components/schemas/MessagesErrorEvent' - message_delta: '#/components/schemas/MessagesDeltaEvent' - message_start: '#/components/schemas/MessagesStartEvent' - message_stop: '#/components/schemas/MessagesStopEvent' - ping: '#/components/schemas/MessagesPingEvent' - propertyName: 'type' - example: - delta: - text: 'Hello' - type: 'text_delta' - index: 0 - type: 'content_block_delta' - oneOf: - - $ref: '#/components/schemas/MessagesStartEvent' - - $ref: '#/components/schemas/MessagesDeltaEvent' - - $ref: '#/components/schemas/MessagesStopEvent' - - $ref: '#/components/schemas/MessagesContentBlockStartEvent' - - $ref: '#/components/schemas/MessagesContentBlockDeltaEvent' - - $ref: '#/components/schemas/MessagesContentBlockStopEvent' - - $ref: '#/components/schemas/MessagesPingEvent' - - $ref: '#/components/schemas/MessagesErrorEvent' - MessagesStreamingResponse: - example: - data: - delta: - text: 'Hello' - type: 'text_delta' - index: 0 - type: 'content_block_delta' - event: 'content_block_delta' - properties: - data: - $ref: '#/components/schemas/MessagesStreamEvents' - event: - type: 'string' - required: - - 'event' - - 'data' - type: 'object' - MessagesToolAdditionBlock: - description: 'Loads a previously deferred tool (declared in `tools` with `defer_loading: true`) mid-conversation without invalidating the prompt cache. Only valid in `role: "system"` messages. Not supported on Claude Sonnet 5 or models older than Claude Opus 4.8.' - example: - tool: - name: 'get_forecast' - type: 'tool_reference' - type: 'tool_addition' - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - tool: - oneOf: - - properties: - name: - type: 'string' - type: - enum: - - 'tool_reference' - type: 'string' - required: - - 'type' - - 'name' - type: 'object' - - properties: - name: - type: 'string' - server_name: - type: 'string' - type: - enum: - - 'mcp_tool_reference' - type: 'string' - required: - - 'type' - - 'name' - - 'server_name' - type: 'object' - - properties: - server_name: - type: 'string' - type: - enum: - - 'mcp_toolset_reference' - type: 'string' - required: - - 'type' - - 'server_name' - type: 'object' - type: - enum: - - 'tool_addition' - type: 'string' - required: - - 'type' - - 'tool' - type: 'object' - MessagesToolRemovalBlock: - description: 'Removes a tool from the conversation mid-conversation without invalidating the prompt cache. Only valid in `role: "system"` messages. Not supported on Claude Sonnet 5 or models older than Claude Opus 4.8.' - example: - tool: - name: 'get_weather' - type: 'tool_reference' - type: 'tool_removal' - properties: - cache_control: - $ref: '#/components/schemas/AnthropicCacheControlDirective' - tool: - oneOf: - - properties: - name: - type: 'string' - type: - enum: - - 'tool_reference' - type: 'string' - required: - - 'type' - - 'name' - type: 'object' - - properties: - name: - type: 'string' - server_name: - type: 'string' - type: - enum: - - 'mcp_tool_reference' - type: 'string' - required: - - 'type' - - 'name' - - 'server_name' - type: 'object' - - properties: - server_name: - type: 'string' - type: - enum: - - 'mcp_toolset_reference' - type: 'string' - required: - - 'type' - - 'server_name' - type: 'object' - type: - enum: - - 'tool_removal' - type: 'string' - required: - - 'type' - - 'tool' + - 'tool' type: 'object' MetadataLevel: description: 'Opt-in level for surfacing routing metadata on the response under `openrouter_metadata`.' @@ -22109,6 +21120,7 @@ components: enum: - 'POST' - 'PUT' + title: 'ObservabilityWebhookDestinationMethod' type: 'string' url: type: 'string' @@ -23006,6 +22018,7 @@ components: - 'misalignment_policy_violation' - 'data_residency_mismatch' - 'permission_denied' + title: 'CodeEnum' type: 'string' message: type: 'string' @@ -27464,15 +26477,6 @@ components: - 'string' - 'null' type: 'object' - ProvisionInternResponse: - additionalProperties: false - properties: - provisioning: - const: true - type: 'boolean' - required: - - 'provisioning' - type: 'object' PublicEndpoint: description: 'Information about a specific model endpoint' example: @@ -29826,63 +28830,6 @@ components: oneOf: - $ref: '#/components/schemas/ContainerAutoEnvironment' - $ref: '#/components/schemas/ContainerReferenceEnvironment' - SignInternDaemonRequest: - additionalProperties: false - properties: - bodySha256: - description: 'Lower-case hex SHA-256 of the exact bytes the CLI will send as the daemon request body.' - example: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' - pattern: '^[0-9a-f]{64}$' - type: 'string' - route: - additionalProperties: false - description: 'The daemon request the proof is for. When present the response also carries the single-use, route-bound proof (`x-ori-invoke-signature-v2`, `x-ori-invoke-nonce`).' - properties: - method: - description: 'The HTTP method of the daemon request.' - enum: - - 'POST' - type: 'string' - path: - description: 'The daemon request path, percent-encoded as sent, without origin or query. The route-bound proof admits only this path.' - example: '/api/invoke' - pattern: '^\/[!"$->@-~]{0,2047}$' - type: 'string' - required: - - 'method' - - 'path' - type: 'object' - required: - - 'bodySha256' - type: 'object' - SignInternDaemonResponse: - additionalProperties: false - description: 'Headers the CLI copies onto the daemon request so the sidecar can verify who is asking.' - example: - x-ori-invoke-signature: 'MEUCIQ...' - x-ori-invoke-timestamp: '1789000000' - x-ori-invoke-user: 'user_2abc' - properties: - x-ori-invoke-nonce: - description: 'Present with `x-ori-invoke-signature-v2`: the single-use id that proof is bound to.' - type: 'string' - x-ori-invoke-signature: - description: 'Base64 Ed25519 signature over the intern id, timestamp, user and body digest.' - type: 'string' - x-ori-invoke-signature-v2: - description: 'Present when the request named a `route`: Base64 Ed25519 signature over the intern id, timestamp, nonce, user, method, path and body digest. The intern accepts it once.' - type: 'string' - x-ori-invoke-timestamp: - description: 'Unix seconds at signing; the daemon refuses proofs older than its window.' - type: 'string' - x-ori-invoke-user: - description: 'The verified OAuth subject the proof names. Never taken from the request.' - type: 'string' - required: - - 'x-ori-invoke-signature' - - 'x-ori-invoke-timestamp' - - 'x-ori-invoke-user' - type: 'object' SpeechInput: anyOf: - type: 'string' @@ -31091,15 +30038,6 @@ components: seed: type: 'boolean' type: 'object' - SuspendInternResponse: - additionalProperties: false - properties: - suspended: - const: true - type: 'boolean' - required: - - 'suspended' - type: 'object' SwitchyardRouterPlugin: example: algorithm: 'stage' @@ -32688,40 +31626,6 @@ components: required: - 'data' type: 'object' - UpdateInternRequest: - additionalProperties: false - description: 'Lifecycle settings to change. Omitted fields stay unchanged and null clears a field.' - example: - description: 'Researches customer questions' - model: 'openai/gpt-5.4' - properties: - description: - description: 'New free-form description. Null clears it.' - maxLength: 2000 - type: - - 'string' - - 'null' - instructions: - description: 'New standing instructions. Null clears them.' - maxLength: 100000 - type: - - 'string' - - 'null' - model: - description: 'New OpenRouter model slug in `author/slug` form (an optional `:variant` suffix is accepted). Other shapes are refused with 400. Null restores the workspace default. Takes effect on the next provision: until then `GET` shows this configured model while chat chunks show the model the running intern reports.' - maxLength: 200 - minLength: 1 - pattern: '^[A-Za-z0-9~._:@+-]+\/[A-Za-z0-9~._:@+-]+$' - type: - - 'string' - - 'null' - name: - description: 'New intern name, unique per creator within the workspace.' - maxLength: 17 - minLength: 2 - pattern: '^[a-z][a-z0-9]*(-[a-z0-9]+)*$' - type: 'string' - type: 'object' UpdateObservabilityDestinationRequest: example: enabled: false @@ -34611,2579 +33515,42 @@ paths: - description: '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.' in: 'query' name: 'group_by' - required: false - schema: - description: '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.' - enum: - - 'workspace' - example: 'workspace' - type: 'string' - - description: 'Filter by workspace ID (UUID). Returns only activity attributed to that workspace. The workspace must belong to the authenticated account.' - in: 'query' - name: 'workspace_id' - required: false - schema: - description: 'Filter by workspace ID (UUID). Returns only activity attributed to that workspace. The workspace must belong to the authenticated account.' - example: '550e8400-e29b-41d4-a716-446655440000' - type: 'string' - responses: - '200': - content: - application/json: - example: - data: - - byok_usage_inference: 0.012 - cached_tokens: 10 - completion_tokens: 125 - date: '2025-08-24' - endpoint_id: '550e8400-e29b-41d4-a716-446655440000' - model: 'openai/gpt-4.1' - model_permaslug: 'openai/gpt-4.1-2025-04-14' - prompt_tokens: 50 - provider_name: 'OpenAI' - reasoning_tokens: 25 - requests: 5 - usage: 0.015 - schema: - $ref: '#/components/schemas/ActivityResponse' - description: 'Returns user activity data grouped by endpoint' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Get user activity grouped by endpoint' - tags: - - 'Analytics' - x-speakeasy-max-method-params: 5 - /analytics/meta: - get: - description: 'Returns the available metrics, dimensions, filter operators, and granularities for the analytics query endpoint. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'getAnalyticsMeta' - responses: - '200': - content: - application/json: - example: - data: - dimensions: - - display_label: 'Model' - name: 'model' - granularities: - - display_label: 'Day' - name: 'day' - metrics: - - display_format: 'number' - display_label: 'Request Count' - is_rate: false - name: 'request_count' - operators: - - name: 'eq' - value_type: 'scalar' - schema: - properties: - data: - properties: - dimensions: - items: - properties: - display_label: - description: 'Human-readable label' - example: 'Model' - type: 'string' - name: - description: 'Dimension identifier used in query requests' - example: 'model' - type: 'string' - required: - - 'name' - - 'display_label' - type: 'object' - type: 'array' - granularities: - items: - properties: - display_label: - description: 'Human-readable label' - example: 'Day' - type: 'string' - name: - description: 'Granularity identifier' - enum: - - 'minute' - - 'hour' - - 'day' - - 'week' - - 'month' - example: 'day' - type: 'string' - required: - - 'name' - - 'display_label' - type: 'object' - type: 'array' - metrics: - items: - properties: - display_format: - description: 'How this metric value should be formatted for display (e.g. percent → multiply by 100 and append %, currency → prefix with $)' - enum: - - 'number' - - 'currency' - - 'percent' - - 'latency' - - 'throughput' - example: 'number' - type: 'string' - display_label: - description: 'Human-readable label' - example: 'Request Count' - type: 'string' - is_rate: - description: 'Whether this metric is a rate/ratio (averaged, not summed)' - type: 'boolean' - name: - description: 'Metric identifier used in query requests' - example: 'request_count' - type: 'string' - required: - - 'name' - - 'display_label' - - 'is_rate' - - 'display_format' - type: 'object' - type: 'array' - operators: - items: - properties: - name: - description: 'Operator identifier used in filter definitions' - enum: - - 'eq' - - 'neq' - - 'in' - - 'not_in' - - 'gt' - - 'gte' - - 'lt' - - 'lte' - example: 'eq' - type: 'string' - value_type: - description: 'Whether the operator expects a single value or an array' - enum: - - 'scalar' - - 'array' - type: 'string' - required: - - 'name' - - 'value_type' - type: 'object' - type: 'array' - required: - - 'metrics' - - 'dimensions' - - 'operators' - - 'granularities' - type: 'object' - required: - - 'data' - type: 'object' - description: 'Returns analytics query metadata' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Get available analytics metrics and dimensions' - tags: - - 'Analytics' - /analytics/query: - post: - description: 'Execute an analytics query with specified metrics, dimensions, filters, and time range. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'queryAnalytics' - requestBody: - content: - application/json: - example: - dimensions: - - 'model' - granularity: 'day' - limit: 100 - metrics: - - 'request_count' - time_range: - end: '2025-01-08T00:00:00Z' - start: '2025-01-01T00:00:00Z' - schema: - properties: - classifier_dimensions: - description: 'Group results by custom classifier tags, breaking down metrics by the specified dimension values. Requires an active classifier on the workspace.' - properties: - classifier_id: - description: 'UUID of the classifier whose tags to group by.' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' - dimension_names: - items: - description: 'Classifier dimension name (snake_case identifier). Each name becomes its own column key in the response; providing two names cross-groups results by both dimensions. With no names, the response uses `clf_dimension_name`/`clf_dimension_value` columns (one row per dimension/value pair).' - example: 'department' - type: 'string' - maxItems: 2 - type: 'array' - include_nulls: - description: 'When true, also include generations that have no tag from this classifier. Defaults to false, which returns only classified generations.' - type: 'boolean' - required: - - 'classifier_id' - type: 'object' - classifier_filters: - description: '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.' - properties: - classifier_id: - description: 'UUID of the classifier whose tags to filter by. Must match classifier_dimensions.classifier_id when both are specified.' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' - filters: - items: - properties: - field: - description: 'Classifier dimension name to filter on (snake_case identifier, e.g. "department", "work_type").' - example: 'department' - type: 'string' - operator: - description: 'Filter operator. Only equality/set operators are supported (eq, neq, in, not_in) — ordered comparisons are not available because classification values are strings.' - example: 'eq' - type: 'string' - value: - anyOf: - - type: 'string' - - format: 'double' - type: 'number' - - items: - anyOf: - - type: 'string' - - format: 'double' - type: 'number' - type: 'array' - description: 'Filter value. Use a scalar (string or number) for eq/neq, or an array for in/not_in.' - example: 'Engineering' - required: - - 'field' - - 'operator' - - 'value' - type: 'object' - maxItems: 10 - minItems: 1 - type: 'array' - required: - - 'classifier_id' - - 'filters' - type: 'object' - dimensions: - items: - description: 'Dimension to group by (up to 2). Use the /meta endpoint for available dimensions.' - example: 'model' - type: 'string' - maxItems: 2 - type: 'array' - filters: - items: - properties: - field: - description: 'Dimension to filter on. Use the /meta endpoint for available dimensions.' - example: 'model' - type: 'string' - include_unset: - description: 'Include rows where the dimension has no value. Applies only to the `in` and `not_in` operators and dimensions that have an unset bucket.' - type: 'boolean' - operator: - description: 'Filter operator' - example: 'eq' - type: 'string' - value: - anyOf: - - type: 'string' - - format: 'double' - type: 'number' - - items: - anyOf: - - type: 'string' - - format: 'double' - type: 'number' - type: 'array' - description: 'Filter value (scalar or array depending on operator). Several dimensions are enriched in responses (returned as human-readable labels), but filters must use the underlying ID: `api_key_id` — numeric ID (from generation metadata) or key hash (64-char hex from GET /api/v1/keys, resolved server-side); `user` — Clerk user ID (e.g. "user_abc123"), not the display name; `workspace` — workspace UUID, not the workspace name (filtering or grouping by the account default workspace also covers activity recorded before workspace resolution existed, which is attributed to that default workspace); `app` — numeric app ID, not the app title; `model` — permaslug (e.g. "openai/gpt-4o"), not the display name. Other dimensions (provider, origin, country, etc.) are not enriched and accept the value as returned.' - required: - - 'field' - - 'operator' - - 'value' - type: 'object' - maxItems: 20 - type: 'array' - granularity: - description: 'Time granularity' - example: 'day' - type: 'string' - group_limit: - description: '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.' - example: 100 - type: 'integer' - limit: - description: '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.' - type: 'integer' - metrics: - items: - description: 'Metric name' - example: 'request_count' - type: 'string' - minItems: 1 - type: 'array' - order_by: - properties: - direction: - enum: - - 'asc' - - 'desc' - type: 'string' - field: - description: 'Field to order by: a metric included in `metrics` (or "request_count", which may be ordered by without being requested), a requested dimension, or "date".' - example: 'request_count' - type: 'string' - required: - - 'field' - - 'direction' - type: 'object' - time_range: - properties: - end: - description: 'ISO 8601 UTC timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected.' - example: '2027-12-31T23:59:59Z' - format: 'date-time' - type: 'string' - start: - description: 'ISO 8601 UTC timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected.' - example: '2027-12-31T23:59:59Z' - format: 'date-time' - type: 'string' - required: - - 'start' - - 'end' - type: 'object' - required: - - 'metrics' - type: 'object' - required: true - responses: - '200': - content: - application/json: - example: - data: - data: - - date__day: '2025-01-01T00:00:00.000Z' - request_count: 1500 - metadata: - query_time_ms: 42 - row_count: 1 - truncated: false - schema: - properties: - data: - properties: - cachedAt: - format: 'double' - type: 'number' - data: - items: - description: 'A row of analytics data with metric/dimension values' - type: 'object' - type: 'array' - metadata: - properties: - query_time_ms: - format: 'double' - type: 'number' - row_count: - type: 'integer' - truncated: - type: 'boolean' - required: - - 'query_time_ms' - - 'row_count' - - 'truncated' - type: 'object' - warnings: - description: 'Warnings about filter resolution issues (e.g. unresolvable api_key_id hashes). The query still runs normally; these inform the caller that some filter values could not be resolved.' - items: - type: 'string' - type: 'array' - required: - - 'data' - - 'metadata' - type: 'object' - required: - - 'data' - type: 'object' - description: 'Analytics query results' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out. Please try again later.' - schema: - $ref: '#/components/schemas/RequestTimeoutResponse' - description: 'Request Timeout - Operation exceeded time limit' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Query analytics data' - tags: - - 'Analytics' - /api/alpha/decisions: - post: - description: 'Submits a Decisions request to the Decisions router' - operationId: 'createApiAlphaDecisions' - requestBody: - content: - application/json: - example: - 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.' - schema: - $ref: '#/components/schemas/DecisionsRequest' - required: true - responses: - '200': - content: - application/json: - example: - answers: - is_bug: - noul: 0.96 - type: 'noul' - team: - choice: 'payments' - confidence: 0.75 - probabilities: - account: 0 - frontend: 0.16 - payments: 0.84 - type: 'choice' - urgency: - confidence: 0.99 - legend: - '0': 'Can wait for the next release' - '1': 'Should be fixed this week' - '2': 'Blocking revenue right now' - probabilities: - '0': 0 - '1': 0.01 - '2': 0.99 - score: 1.99 - type: 'score' - id: 'gen-dec-1789738314-X5e5eKGQdvR9rblyX250' - model: 'typesafe/jev-1.13-20260917' - provider: 'TypeSafe' - usage: - cost: 0.000019992 - input_tokens: 476 - output_tokens: 70 - schema: - $ref: '#/components/schemas/DecisionsResponse' - description: 'Decisions response' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '402': - content: - application/json: - example: - error: - code: 402 - message: 'Insufficient credits. Add more using https://openrouter.ai/credits' - schema: - $ref: '#/components/schemas/PaymentRequiredResponse' - description: 'Payment Required - Insufficient credits or quota to complete request' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Request payload too large' - schema: - $ref: '#/components/schemas/PayloadTooLargeResponse' - description: 'Payload Too Large - Request payload exceeds size limits' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded' - schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '503': - content: - application/json: - example: - error: - code: 503 - message: 'Service temporarily unavailable' - schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - '524': - content: - application/json: - example: - error: - code: 524 - message: 'Request timed out. Please try again later.' - schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': - content: - application/json: - example: - error: - code: 529 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - servers: - - url: 'https://openrouter.ai' - summary: 'Submit a Decisions request' - tags: - - 'alpha.decisions' - x-speakeasy-name-override: 'create' - /audio/speech: - post: - description: 'Synthesizes audio from the input text. Returns a raw audio bytestream in the requested format (e.g. mp3, pcm, wav).' - operationId: 'createAudioSpeech' - requestBody: - content: - application/json: - example: - input: 'Hello world' - model: 'mistralai/voxtral-mini-tts-2603' - response_format: 'pcm' - speed: 1 - voice: 'en_paul_neutral' - schema: - $ref: '#/components/schemas/SpeechRequest' - required: true - responses: - '200': - content: - audio/*: - schema: - description: 'Raw audio bytestream. Content-Type varies by requested format (audio/mpeg for mp3, audio/pcm for pcm — 16-bit little-endian).' - example: '' - format: 'binary' - type: 'string' - description: 'Audio bytes stream' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '402': - content: - application/json: - example: - error: - code: 402 - message: 'Insufficient credits. Add more using https://openrouter.ai/credits' - schema: - $ref: '#/components/schemas/PaymentRequiredResponse' - description: 'Payment Required - Insufficient credits or quota to complete request' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Request payload too large' - schema: - $ref: '#/components/schemas/PayloadTooLargeResponse' - description: 'Payload Too Large - Request payload exceeds size limits' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded' - schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '503': - content: - application/json: - example: - error: - code: 503 - message: 'Service temporarily unavailable' - schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - '524': - content: - application/json: - example: - error: - code: 524 - message: 'Request timed out. Please try again later.' - schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': - content: - application/json: - example: - error: - code: 529 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - summary: 'Create speech' - tags: - - 'TTS' - x-speakeasy-max-method-params: 1 - x-speakeasy-name-override: 'createSpeech' - /audio/transcriptions: - post: - description: 'Transcribes audio into text. Accepts base64-encoded audio input as JSON, an OpenAI-style multipart/form-data file upload, or a URL the provider downloads directly, and returns the transcribed text.' - operationId: 'createAudioTranscriptions' - requestBody: - content: - application/json: - example: - input_audio: - data: 'UklGRiQA...' - format: 'wav' - language: 'en' - model: 'openai/whisper-large-v3' - schema: - $ref: '#/components/schemas/STTRequest' - multipart/form-data: - example: - file: 'audio.wav' - language: 'en' - model: 'openai/whisper-large-v3' - schema: - properties: - diarize: - description: 'Label each word with the speaker who said it (words[].speaker, words[].speaker_label). Requires response_format "verbose_json" (400 otherwise); word timestamps are included even when timestamp_granularities[] omits "word". Only supported by some providers; 400 when the selected model cannot diarize.' - type: 'boolean' - file: - description: 'The audio file to transcribe. The format is derived from the filename extension or the file part content type. Max 25 MB; send larger files as base64 JSON via input_audio, or by URL via source_url. Exactly one of file or source_url is required.' - format: 'binary' - type: 'string' - keyterms[]: - description: 'Domain terms, names, or phrases to bias recognition toward; repeat the part once per term (keyterms=... is also accepted). Only supported by some providers; 400 when the selected model cannot use keyterms.' - items: - type: 'string' - type: 'array' - language: - description: 'The language of the input audio (ISO-639-1).' - type: 'string' - model: - description: 'The model to use for transcription.' - type: 'string' - provider: - description: 'JSON-encoded provider preferences object, the same shape as the JSON body field: { "zdr": true, "data_collection": "deny", "options": { "": { ... } } }. Only options for the matched provider are forwarded. Must decode to a JSON object.' - type: 'string' - response_format: - description: 'The response format. "json" (default) returns { text, usage }; "verbose_json" additionally returns task, language, duration, and segment-level timestamps (OpenAI-compatible providers only).' - enum: - - 'json' - - 'verbose_json' - type: 'string' - session_id: - description: '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.' - maxLength: 256 - type: 'string' - source_url: - description: 'Publicly reachable http(s) URL of the audio file, downloaded by the provider directly (no size limit on our side). The format is derived from the URL path extension. Only supported by some providers; exactly one of file or source_url is required.' - format: 'uri' - type: 'string' - temperature: - description: 'The sampling temperature.' - type: 'number' - timestamp_granularities[]: - description: 'Timestamp detail levels to include when response_format is "verbose_json". "word" additionally returns word-level timestamps in the words array.' - items: - enum: - - 'word' - - 'segment' - type: 'string' - type: 'array' - trace: - description: 'JSON-encoded trace metadata object (trace_id, trace_name, span_name, generation_name, parent_span_id and custom keys) attached to the Broadcast trace. Must decode to a JSON object.' - type: 'string' - user: - description: 'A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.' - maxLength: 256 - type: 'string' - required: - - 'model' - type: 'object' - required: true - responses: - '200': - content: - application/json: - example: - text: 'Hello, this is a test of OpenAI speech-to-text transcription.' - usage: - cost: 0.000508 - input_tokens: 83 - output_tokens: 30 - seconds: 9.2 - total_tokens: 113 - schema: - $ref: '#/components/schemas/STTResponse' - description: 'Transcription result' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '402': - content: - application/json: - example: - error: - code: 402 - message: 'Insufficient credits. Add more using https://openrouter.ai/credits' - schema: - $ref: '#/components/schemas/PaymentRequiredResponse' - description: 'Payment Required - Insufficient credits or quota to complete request' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Request payload too large' - schema: - $ref: '#/components/schemas/PayloadTooLargeResponse' - description: 'Payload Too Large - Request payload exceeds size limits' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded' - schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '503': - content: - application/json: - example: - error: - code: 503 - message: 'Service temporarily unavailable' - schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - '504': - content: - application/json: - example: - error: - code: 504 - message: 'The operation was aborted due to timeout' - schema: - $ref: '#/components/schemas/GatewayTimeoutResponse' - description: 'Gateway Timeout - Provider did not respond before the upstream deadline' - '524': - content: - application/json: - example: - error: - code: 524 - message: 'Request timed out. Please try again later.' - schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': - content: - application/json: - example: - error: - code: 529 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - summary: 'Create transcription' - tags: - - 'STT' - x-speakeasy-max-method-params: 1 - x-speakeasy-name-override: 'createTranscription' - /auth/keys: - post: - description: 'Exchange an authorization code from the PKCE flow for a user-controlled API key' - operationId: 'exchangeAuthCodeForAPIKey' - requestBody: - content: - application/json: - example: - code: 'auth_code_abc123def456' - code_challenge_method: 'S256' - code_verifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' - schema: - example: - code: 'auth_code_abc123def456' - code_challenge_method: 'S256' - code_verifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' - properties: - code: - description: 'The authorization code received from the OAuth redirect' - example: 'auth_code_abc123def456' - type: 'string' - code_challenge_method: - description: 'The method used to generate the code challenge' - enum: - - 'S256' - - 'plain' - - null - example: 'S256' - type: - - 'string' - - 'null' - code_verifier: - description: 'The code verifier if code_challenge was used in the authorization request' - example: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' - type: 'string' - required: - - 'code' - type: 'object' - required: true - responses: - '200': - content: - application/json: - example: - key: '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' - user_id: 'user_2yOPcMpKoQhcd4bVgSMlELRaIah' - schema: - example: - key: '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' - user_id: 'user_2yOPcMpKoQhcd4bVgSMlELRaIah' - properties: - key: - description: 'The API key to use for OpenRouter requests' - example: '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' - type: 'string' - user_id: - description: 'User ID associated with the API key' - example: 'user_2yOPcMpKoQhcd4bVgSMlELRaIah' - type: - - 'string' - - 'null' - required: - - 'key' - - 'user_id' - type: 'object' - description: 'Successfully exchanged code for an API key' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Exchange authorization code for API key' - tags: - - 'OAuth' - /auth/keys/code: - post: - description: 'Create an authorization code for the PKCE flow to generate a user-controlled API key' - operationId: 'createAuthKeysCode' - requestBody: - content: - application/json: - example: - callback_url: 'https://myapp.com/auth/callback' - code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' - code_challenge_method: 'S256' - limit: 100 - schema: - example: - callback_url: 'https://myapp.com/auth/callback' - code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' - code_challenge_method: 'S256' - limit: 100 - properties: - callback_url: - description: '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.' - example: 'https://myapp.com/auth/callback' - format: 'uri' - type: 'string' - code_challenge: - description: 'PKCE code challenge for enhanced security' - example: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' - type: 'string' - code_challenge_method: - description: 'The method used to generate the code challenge' - enum: - - 'S256' - - 'plain' - example: 'S256' - type: 'string' - expires_at: - description: 'Optional ISO 8601 UTC expiration timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected.' - example: '2027-12-31T23:59:59Z' - format: 'date-time' - type: - - 'string' - - 'null' - key_label: - description: 'Optional custom label for the API key. Defaults to the app name if not provided.' - example: 'My Custom Key' - maxLength: 100 - type: 'string' - limit: - description: 'Credit limit for the API key to be created' - example: 100 - format: 'double' - type: 'number' - spawn_agent: - description: 'Agent identifier for spawn telemetry' - example: 'my-agent' - type: 'string' - x-fern-ignore: true - x-speakeasy-ignore: true - spawn_cloud: - description: 'Cloud identifier for spawn telemetry' - example: 'aws-us-east-1' - type: 'string' - x-fern-ignore: true - x-speakeasy-ignore: true - usage_limit_type: - description: 'Optional credit limit reset interval. When set, the credit limit resets on this interval.' - enum: - - 'daily' - - 'weekly' - - 'monthly' - example: 'monthly' - type: 'string' - workspace_id: - description: 'Optional workspace ID to associate the API key with' - format: 'uuid' - type: 'string' - required: - - 'callback_url' - type: 'object' - required: true - responses: - '200': - content: - application/json: - example: - data: - app_id: 12345 - created_at: '2025-08-24T10:30:00Z' - id: 'auth_code_xyz789' - schema: - example: - data: - app_id: 12345 - created_at: '2025-08-24T10:30:00Z' - id: 'auth_code_xyz789' - properties: - data: - description: 'Auth code data' - example: - app_id: 12345 - created_at: '2025-08-24T10:30:00Z' - id: 'auth_code_xyz789' - properties: - app_id: - description: 'The application ID associated with this auth code' - example: 12345 - type: 'integer' - created_at: - description: 'ISO 8601 timestamp of when the auth code was created' - example: '2025-08-24T10:30:00Z' - type: 'string' - id: - description: 'The authorization code ID to use in the exchange request' - example: 'auth_code_xyz789' - type: 'string' - required: - - 'id' - - 'app_id' - - 'created_at' - type: 'object' - required: - - 'data' - type: 'object' - description: 'Successfully created authorization code' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '409': - content: - application/json: - example: - error: - code: 409 - message: 'Resource conflict. Please try again later.' - schema: - $ref: '#/components/schemas/ConflictResponse' - description: 'Conflict - Resource conflict or concurrent modification' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Create authorization code' - tags: - - 'OAuth' - x-speakeasy-name-override: 'createAuthCode' - /batches: - get: - description: 'Lists batches in the workspace of the authenticating API key, newest first. To fetch the next page, pass the previous page''s `last_id` as `after`. List items omit `results`. Use `GET /batches/{id}` to get them. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' - operationId: 'listBatches' - parameters: - - description: 'Maximum number of batches to return, from 1 through 100.' - in: 'query' - name: 'limit' - required: false - schema: - description: 'Maximum number of batches to return, from 1 through 100.' - example: 20 - type: 'integer' - - description: 'Batch id from the previous page''s `last_id`.' - in: 'query' - name: 'after' - required: false - schema: - description: 'Batch id from the previous page''s `last_id`.' - example: 'batch_7a4b02' - minLength: 1 - type: 'string' - - description: 'Repeat this parameter to include more than one status.' - explode: true - in: 'query' - name: 'status' - required: false - schema: - description: 'Repeat this parameter to include more than one status.' - example: - - 'completed' - - 'failed' - items: - $ref: '#/components/schemas/BatchListStatus' - type: 'array' - style: 'form' - - description: 'Only include batches created strictly after this timestamp.' - in: 'query' - name: 'created_after' - required: false - schema: - $ref: '#/components/schemas/BatchListTimestamp' - - description: 'Only include batches created strictly before this timestamp.' - in: 'query' - name: 'created_before' - required: false - schema: - allOf: - - $ref: '#/components/schemas/BatchListTimestamp' - - description: 'Only include batches created strictly before this timestamp.' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/BatchListResponse' - description: 'A newest-first page of batches.' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid batch list query.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Malformed or unsupported batch list query parameters.' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'No auth credentials found.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Missing or invalid API key.' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Batch API rate limit exceeded for the billable entity.' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal server error.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Unexpected error in the ingress or upstream batch-api.' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Upstream batch-api is unavailable.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' - summary: 'List batches' - tags: - - 'Batch' - x-speakeasy-name-override: 'list' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'after' - type: 'cursor' - outputs: - nextCursor: '$.last_id' - results: '$.data' - type: 'cursor' - post: - description: 'Creates a batch of requests that run asynchronously against a single endpoint (`/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/embeddings`). Returns `202` with `status: "validating"`. Poll `GET /batches/{id}` for progress and results. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' - operationId: 'createBatches' - requestBody: - content: - application/json: - examples: - chatCompletions: - summary: 'Chat completions batch' - value: - endpoint: '/v1/chat/completions' - model: 'openai/gpt-4o' - requests: - - body: - messages: - - content: 'Summarize ...' - role: 'user' - model: 'openai/gpt-4o' - custom_id: 'req-0001' - messages: - summary: 'Messages batch' - value: - endpoint: '/v1/messages' - model: 'openai/gpt-5-nano' - requests: - - body: - max_tokens: 1024 - messages: - - content: 'Summarize ...' - role: 'user' - model: 'openai/gpt-5-nano' - custom_id: 'req-0001' - providerPinned: - summary: 'Batch pinned to Vertex' - value: - endpoint: '/v1/chat/completions' - model: 'google/gemini-3.6-flash' - provider: - only: - - 'google-vertex' - requests: - - body: - messages: - - content: 'Summarize ...' - role: 'user' - model: 'google/gemini-3.6-flash' - custom_id: 'req-0001' - responses: - summary: 'Responses batch' - value: - endpoint: '/v1/responses' - model: 'openai/gpt-4o' - requests: - - body: - input: - - content: - - text: 'Summarize ...' - type: 'input_text' - role: 'user' - model: 'openai/gpt-4o' - custom_id: 'req-0001' - schema: - $ref: '#/components/schemas/BatchSubmitBody' - description: 'The batch to create. Each item in `requests` has a unique `custom_id` and a `body` in the request format of the chosen `endpoint`.' - required: true - responses: - '202': - content: - application/json: - schema: - $ref: '#/components/schemas/BatchObject' - description: 'Batch payload durably persisted and queued for asynchronous validation and provider submission (`status: "validating"`).' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'custom_id is required on requests[0].' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Malformed batch input or an unknown/incompatible batch model.' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'No auth credentials found.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Missing or invalid API key.' - '402': - content: - application/json: - example: - error: - code: 402 - message: 'Insufficient balance for this batch.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The estimated batch cost exceeds the available balance.' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'The selected provider or model is not allowed.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The resolved batch endpoint is blocked by account policy.' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Batch not found.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'No batch exists for the given id.' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Batch input exceeds the 200 MB payload limit.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Batch input exceeds the maximum payload size.' - '422': - content: - application/json: - example: - error: - code: 422 - message: 'The batch request could not be processed.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The requested model variant or custom IDs violate Batch API constraints.' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Batch API rate limit exceeded for the billable entity.' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal server error.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Unexpected error in the ingress or upstream batch-api.' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Upstream batch-api is unavailable.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' - summary: 'Create a batch' - tags: - - 'Batch' - x-speakeasy-retries: - retryConnectionErrors: false - statusCodes: - - '429' - strategy: 'backoff' - /batches/{id}: - delete: - description: 'Deletes a batch in a terminal status (`completed`, `failed`, `expired`, or `cancelled`) and its stored requests and results. Batches still in progress return `409`. Billing and usage records are kept. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' - operationId: 'deleteBatch' - parameters: - - description: 'The batch job id returned from submit.' - in: 'path' - name: 'id' - required: true - schema: - description: 'The batch job id returned from submit.' - example: 'batch_abc123' - minLength: 1 - type: 'string' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/BatchDeletedObject' - description: 'The batch was deleted; per-target outcomes are reported under `deletion`.' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'No auth credentials found.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Missing or invalid API key.' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Batch not found.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'No batch exists for the given id.' - '409': - content: - application/json: - example: - error: - code: 409 - message: 'Only completed, failed, expired, or cancelled batches can be deleted. Wait for the batch to finish and try again.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The batch is still processing, its required provider key is unavailable, or its state changed during deletion.' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Batch API rate limit exceeded for the billable entity.' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal server error.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Unexpected error in the ingress or upstream batch-api.' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Upstream batch-api is unavailable.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' - summary: 'Delete a batch' - tags: - - 'Batch' - x-speakeasy-name-override: 'delete' - get: - description: 'Returns a batch with its status and request counts. Batches in a terminal status include `results`. Failed batches report the reason in `error.message`. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' - operationId: 'getBatches' - parameters: - - description: 'The batch job id returned from submit.' - in: 'path' - name: 'id' - required: true - schema: - description: 'The batch job id returned from submit.' - example: 'batch_abc123' - minLength: 1 - type: 'string' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/BatchObject' - description: 'The current batch job status.' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'No auth credentials found.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Missing or invalid API key.' - '402': - content: - application/json: - schema: - $ref: '#/components/schemas/BatchPaymentRequiredResponse' - description: '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': - content: - application/json: - example: - error: - code: 404 - message: 'Batch not found.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'No batch exists for the given id.' - '410': - content: - application/json: - example: - error: - code: 410 - message: 'Batch results have expired. OpenRouter deletes batch results 30 days after the batch is created.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The batch results were deleted after the 30-day retention window.' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Batch API rate limit exceeded for the billable entity.' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal server error.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'Unexpected error in the ingress or upstream batch-api.' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Upstream batch-api is unavailable.' - schema: - $ref: '#/components/schemas/BatchErrorResponse' - description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' - summary: 'Get a batch' - tags: - - 'Batch' - /benchmarks: - get: - description: 'Unified benchmark endpoint that aggregates scores from multiple benchmark sources (Artificial Analysis, Design Arena, and OpenRouter''s own tau-bench, GPQA, and web-search evals). Filter by source to reproduce the exact shapes from the legacy per-source endpoints, or use task_type to find models suited for specific workloads. Use task_type=search (or a search_* benchmark_type) for OpenRouter''s search benchmarks, which publish each model''s highest-scoring eligible evaluation configuration with same-configuration runs combined by task-weighted mean. Authenticate with any valid OpenRouter API key. Rate-limited to 30 requests/minute per key and 500 requests/day per account.' - operationId: 'getBenchmarks' - parameters: - - description: 'Benchmark source to query. Determines the shape of the returned items. When omitted, returns results from all sources.' - in: 'query' - name: 'source' - required: false - schema: - description: 'Benchmark source to query. Determines the shape of the returned items. When omitted, returns results from all sources.' - enum: - - 'artificial-analysis' - - 'design-arena' - - 'openrouter' - example: 'artificial-analysis' - type: 'string' - - description: 'Filter results by task type. For Artificial Analysis, maps to the corresponding index. For Design Arena, maps to the matching category. `search` returns OpenRouter search benchmark results only.' - in: 'query' - name: 'task_type' - required: false - schema: - description: 'Filter results by task type. For Artificial Analysis, maps to the corresponding index. For Design Arena, maps to the matching category. `search` returns OpenRouter search benchmark results only.' - enum: - - 'coding' - - 'intelligence' - - 'agentic' - - 'search' - example: 'coding' - type: 'string' - - description: '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.' - in: 'query' - name: 'benchmark_type' - required: false - schema: - description: '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.' - enum: - - 'gpqa_diamond' - - 'tau_bench_verified_airline' - - 'search_browsecomp' - - 'search_hle' - - 'search_dsqa' - - 'search_widesearch' - example: 'search_widesearch' - type: 'string' - - description: '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.' - in: 'query' - name: 'include_run_config' - required: false - schema: - default: false - description: '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.' - example: true - type: 'boolean' - - description: 'OpenRouter search benchmarks only: filter by the search engine used.' - in: 'query' - name: 'search_engine' - required: false - schema: - description: 'OpenRouter search benchmarks only: filter by the search engine used.' - example: 'exa' - type: 'string' - - description: 'OpenRouter search benchmarks only: filter by the request surface the lane ran on.' - in: 'query' - name: 'search_surface' - required: false - schema: - description: 'OpenRouter search benchmarks only: filter by the request surface the lane ran on.' - enum: - - 'server-tool' - - 'plugin' - example: 'server-tool' - type: 'string' - - description: 'Design Arena only: arena to query. Defaults to `models` when source is `design-arena`.' - in: 'query' - name: 'arena' - required: false - schema: - description: 'Design Arena only: arena to query. Defaults to `models` when source is `design-arena`.' - enum: - - 'models' - - 'builders' - - 'agents' - example: 'models' - type: 'string' - - description: 'Design Arena only: category within the arena (e.g. `codecategories`, `uicomponent`, `gamedev`, `3d`, `dataviz`, `image`, `video`, `svg`). When omitted, returns all categories.' - in: 'query' - name: 'category' - required: false - schema: - description: 'Design Arena only: category within the arena (e.g. `codecategories`, `uicomponent`, `gamedev`, `3d`, `dataviz`, `image`, `video`, `svg`). When omitted, returns all categories.' - example: 'codecategories' - type: 'string' - - description: 'Maximum number of items to return. When omitted, all matching results are returned.' - in: 'query' - name: 'max_results' - required: false - schema: - description: 'Maximum number of items to return. When omitted, all matching results are returned.' - example: 50 - minimum: 1 - type: 'integer' - responses: - '200': - content: - application/json: - example: - data: - - agentic_index: 58.3 - coding_index: 65.8 - display_name: 'GPT-4o' - intelligence_index: 71.2 - model_permaslug: 'openai/gpt-4o' - pricing: - completion: '0.00001' - prompt: '0.0000025' - source: 'artificial-analysis' - - accuracy: 0.72 - accuracy_stddev: 0.03 - avg_cost_per_task: 0.002 - benchmark_type: 'gpqa_diamond' - display_name: 'GPT-4o' - last_run_timestamp: '2026-06-03T12:00:00Z' - model_permaslug: 'openai/gpt-4o' - source: 'openrouter' - total_tasks: 300 - meta: - as_of: '2026-06-03T12:00:00Z' - citation: null - model_count: 1 - source: null - source_url: null - task_type: null - version: 'v1' - schema: - $ref: '#/components/schemas/UnifiedBenchmarksResponse' - description: 'Benchmark results filtered by the specified source and optional task type.' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded' - schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'List Benchmarks' - tags: - - 'Benchmarks' - /byok: - get: - description: 'List the bring-your-own-key (BYOK) provider credentials for the authenticated entity''s default workspace. Use the `workspace_id` query parameter to scope the result to a different workspace, or the `provider` query parameter to filter by upstream provider. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'listBYOKKeys' - parameters: - - description: 'Number of records to skip for pagination' - in: 'query' - name: 'offset' - required: false - schema: - default: 0 - description: 'Number of records to skip for pagination' - example: 0 - minimum: 0 - type: - - 'integer' - - 'null' - - description: 'Maximum number of records to return (max 100)' - in: 'query' - name: 'limit' - required: false - schema: - default: 50 - description: 'Maximum number of records to return (max 100)' - example: 50 - maximum: 100 - minimum: 1 - type: 'integer' - - description: 'Optional workspace ID to filter by. When omitted, resolves to the account’s default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly.' - in: 'query' - name: 'workspace_id' - required: false - schema: - description: 'Optional workspace ID to filter by. When omitted, resolves to the account’s default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly.' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' - - description: 'Optional provider slug to filter by (e.g. `openai`, `anthropic`, `amazon-bedrock`).' - in: 'query' - name: 'provider' - required: false - schema: - description: 'Optional provider slug to filter by (e.g. `openai`, `anthropic`, `amazon-bedrock`).' - enum: - - 'ai21' - - 'aion-labs' - - 'akashml' - - 'alibaba' - - 'amazon-bedrock' - - 'amazon-bedrock/claude-on-aws' - - 'amazon-nova' - - 'ambient' - - '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' - - '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' - - 'liquid' - - 'makora' - - 'mancer' - - 'mara' - - 'meta' - - 'minimax' - - 'mistral' - - 'modal' - - 'modelrun' - - 'modular' - - 'moonshotai' - - 'morph' - - 'near-ai' - - 'nebius' - - 'nex-agi' - - 'nextbit' - - 'novita' - - 'nvidia' - - 'ollama' - - 'open-inference' - - 'openai' - - 'parasail' - - 'pareto-alpha' - - 'perceptron' - - 'perplexity' - - 'phala' - - 'poolside' - - 'primeintellect' - - 'quiver' - - 'recraft' - - 'recursive' - - 'reka' - - 'relace' - - 'respan' - - 'runway' - - 'sail-research' - - 'sakana' - - 'sakana-ai' - - 'sambanova' - - 'scaledown' - - 'seed' - - 'siliconflow' - - 'sourceful' - - 'stepfun' - - 'streamlake' - - 'switchpoint' - - 'tencent' - - 'tenstorrent' - - 'thinkingmachines' - - 'together' - - 'typesafe' - - 'unbiased' - - 'upstage' - - 'venice' - - 'voyageai' - - 'wafer' - - 'wandb' - - 'wandb-legacy' - - 'xai' - - 'xiaomi' - - 'z-ai' - example: 'openai' - type: 'string' - responses: - '200': - content: - application/json: - example: - data: - - allowed_api_key_hashes: null - allowed_models: null - allowed_user_ids: null - created_at: '2025-08-24T10:30:00Z' - declared_region: null - declared_zdr: null - disabled: false - id: '11111111-2222-3333-4444-555555555555' - is_byok_only: false - is_fallback: false - is_required: false - label: 'sk-...AbCd' - name: 'Production OpenAI Key' - provider: 'openai' - sort_order: 0 - workspace_id: '550e8400-e29b-41d4-a716-446655440000' - total_count: 1 - schema: - $ref: '#/components/schemas/ListBYOKKeysResponse' - description: 'List of BYOK credentials' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'List BYOK provider credentials' - tags: - - 'BYOK' - x-speakeasy-name-override: 'list' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'offset' - type: 'offset' - - in: 'parameters' - name: 'limit' - type: 'limit' - outputs: - results: '$.data' - type: 'offsetLimit' - post: - description: 'Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. When `workspace_id` is omitted, the credential is created in the default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly. Treat the raw key as write-only; it is never returned after creation. Use `allowed_api_key_hashes` to restrict the credential to specific OpenRouter API keys. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'createBYOKKey' - requestBody: - content: - application/json: - example: - key: 'sk-proj-abc123...' - name: 'Production OpenAI Key' - provider: 'openai' - schema: - $ref: '#/components/schemas/CreateBYOKKeyRequest' - required: true - responses: - '201': - content: - application/json: - example: - data: - allowed_api_key_hashes: null - allowed_models: null - allowed_user_ids: null - created_at: '2025-08-24T10:30:00Z' - declared_region: null - declared_zdr: null - disabled: false - id: '11111111-2222-3333-4444-555555555555' - is_byok_only: false - is_fallback: false - is_required: false - label: 'sk-...AbCd' - name: 'Production OpenAI Key' - provider: 'openai' - sort_order: 0 - workspace_id: '550e8400-e29b-41d4-a716-446655440000' - schema: - $ref: '#/components/schemas/CreateBYOKKeyResponse' - description: 'BYOK credential created successfully' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Create a BYOK provider credential' - tags: - - 'BYOK' - x-speakeasy-name-override: 'create' - /byok/{id}: - delete: - description: 'Delete (soft-delete) a bring-your-own-key (BYOK) provider credential by its `id`. The encrypted key material is wiped and the record is marked as deleted. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'deleteBYOKKey' - parameters: - - description: 'The BYOK credential ID (UUID).' - in: 'path' - name: 'id' - required: true - schema: - description: 'The BYOK credential ID (UUID).' - example: '11111111-2222-3333-4444-555555555555' - format: 'uuid' - type: 'string' - responses: - '200': - content: - application/json: - example: - deleted: true - schema: - $ref: '#/components/schemas/DeleteBYOKKeyResponse' - description: 'BYOK credential deleted successfully' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Delete a BYOK provider credential' - tags: - - 'BYOK' - x-speakeasy-name-override: 'delete' - get: - description: 'Get a single bring-your-own-key (BYOK) provider credential by its `id`. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'getBYOKKey' - parameters: - - description: 'The BYOK credential ID (UUID).' - in: 'path' - name: 'id' - required: true + required: false schema: - description: 'The BYOK credential ID (UUID).' - example: '11111111-2222-3333-4444-555555555555' - format: 'uuid' + description: '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.' + enum: + - 'workspace' + example: 'workspace' type: 'string' - responses: - '200': - content: - application/json: - example: - data: - allowed_api_key_hashes: null - allowed_models: null - allowed_user_ids: null - created_at: '2025-08-24T10:30:00Z' - declared_region: null - declared_zdr: null - disabled: false - id: '11111111-2222-3333-4444-555555555555' - is_byok_only: false - is_fallback: false - is_required: false - label: 'sk-...AbCd' - name: 'Production OpenAI Key' - provider: 'openai' - sort_order: 0 - workspace_id: '550e8400-e29b-41d4-a716-446655440000' - schema: - $ref: '#/components/schemas/GetBYOKKeyResponse' - description: 'BYOK credential details' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Get a BYOK provider credential' - tags: - - 'BYOK' - x-speakeasy-name-override: 'get' - patch: - description: 'Update an existing bring-your-own-key (BYOK) provider credential by its `id`. Include the `key` field to rotate the raw provider API key in-place (the previous key material is overwritten). Use `allowed_api_key_hashes` to restrict the credential to specific OpenRouter API keys (`null` clears the restriction). [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'updateBYOKKey' - parameters: - - description: 'The BYOK credential ID (UUID).' - in: 'path' - name: 'id' - required: true + - description: 'Filter by workspace ID (UUID). Returns only activity attributed to that workspace. The workspace must belong to the authenticated account.' + in: 'query' + name: 'workspace_id' + required: false schema: - description: 'The BYOK credential ID (UUID).' - example: '11111111-2222-3333-4444-555555555555' - format: 'uuid' + description: 'Filter by workspace ID (UUID). Returns only activity attributed to that workspace. The workspace must belong to the authenticated account.' + example: '550e8400-e29b-41d4-a716-446655440000' type: 'string' - requestBody: - content: - application/json: - example: - disabled: false - name: 'Updated OpenAI Key' - schema: - $ref: '#/components/schemas/UpdateBYOKKeyRequest' - required: true responses: '200': content: application/json: example: data: - allowed_api_key_hashes: null - allowed_models: null - allowed_user_ids: null - created_at: '2025-08-24T10:30:00Z' - declared_region: null - declared_zdr: null - disabled: false - id: '11111111-2222-3333-4444-555555555555' - is_byok_only: false - is_fallback: false - is_required: false - label: 'sk-...AbCd' - name: 'Updated OpenAI Key' - provider: 'openai' - sort_order: 0 - workspace_id: '550e8400-e29b-41d4-a716-446655440000' + - byok_usage_inference: 0.012 + cached_tokens: 10 + completion_tokens: 125 + date: '2025-08-24' + endpoint_id: '550e8400-e29b-41d4-a716-446655440000' + model: 'openai/gpt-4.1' + model_permaslug: 'openai/gpt-4.1-2025-04-14' + prompt_tokens: 50 + provider_name: 'OpenAI' + reasoning_tokens: 25 + requests: 5 + usage: 0.015 schema: - $ref: '#/components/schemas/UpdateBYOKKeyResponse' - description: 'BYOK credential updated successfully' + $ref: '#/components/schemas/ActivityResponse' + description: 'Returns user activity data grouped by endpoint' '400': content: application/json: @@ -37224,224 +33591,6 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' - '409': - content: - application/json: - example: - error: - code: 409 - message: 'Resource conflict. Please try again later.' - schema: - $ref: '#/components/schemas/ConflictResponse' - description: 'Conflict - Resource conflict or concurrent modification' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Update a BYOK provider credential' - tags: - - 'BYOK' - x-speakeasy-name-override: 'update' - /chat/completions: - post: - description: 'Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes.' - operationId: 'sendChatCompletionRequest' - parameters: - - description: '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.' - example: 'enabled' - in: 'header' - name: 'X-OpenRouter-Metadata' - required: false - schema: - $ref: '#/components/schemas/MetadataLevel' - requestBody: - content: - application/json: - example: - 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 - schema: - $ref: '#/components/schemas/ChatRequest' - required: true - responses: - '200': - content: - application/json: - example: - choices: - - finish_reason: 'stop' - index: 0 - message: - content: 'The capital of France is Paris.' - role: 'assistant' - created: 1677652288 - id: 'chatcmpl-123' - model: 'openai/gpt-4' - object: 'chat.completion' - system_fingerprint: 'fp_44709d6fcb' - usage: - completion_tokens: 10 - prompt_tokens: 25 - total_tokens: 35 - schema: - $ref: '#/components/schemas/ChatResult' - text/event-stream: - example: - data: - choices: - - delta: - content: 'Hello' - role: 'assistant' - finish_reason: null - index: 0 - created: 1677652288 - id: 'chatcmpl-123' - model: 'openai/gpt-4' - object: 'chat.completion.chunk' - schema: - $ref: '#/components/schemas/ChatStreamingResponse' - x-speakeasy-sse-sentinel: '[DONE]' - description: 'Successful chat completion response' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' - schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '402': - content: - application/json: - example: - error: - code: 402 - message: 'Insufficient credits. Add more using https://openrouter.ai/credits' - schema: - $ref: '#/components/schemas/PaymentRequiredResponse' - description: 'Payment Required - Insufficient credits or quota to complete request' - '403': - content: - application/json: - examples: - guardrail-blocked: - summary: 'Guardrail blocked the request' - value: - error: - code: 403 - message: 'Request blocked: prompt injection patterns detected' - metadata: - patterns: - - 'ignore all previous instructions' - openrouter_metadata: - attempt: 1 - endpoints: - available: - - model: 'openai/gpt-4o' - provider: 'OpenAI' - selected: false - total: 1 - is_byok: false - pipeline: - - data: - action: 'blocked' - detected: true - engines: - - 'regex' - patterns: - - 'ignore all previous instructions' - guardrail_id: 'grd_abc123' - guardrail_scope: 'api-key' - name: 'regex_pi_detection' - summary: 'Blocked: prompt injection detected (1 pattern matched)' - type: 'guardrail' - region: 'iad' - requested: 'openai/gpt-4o' - strategy: 'direct' - summary: 'available=1' - insufficient-permissions: - summary: 'Insufficient permissions' - value: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: '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': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out. Please try again later.' - schema: - $ref: '#/components/schemas/RequestTimeoutResponse' - description: 'Request Timeout - Operation exceeded time limit' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Request payload too large' - schema: - $ref: '#/components/schemas/PayloadTooLargeResponse' - description: 'Payload Too Large - Request payload exceeds size limits' - '422': - content: - application/json: - example: - error: - code: 422 - message: 'Invalid argument' - schema: - $ref: '#/components/schemas/UnprocessableEntityResponse' - description: 'Unprocessable Entity - Semantic validation failure' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded' - schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: @@ -37452,106 +33601,144 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '503': - content: - application/json: - example: - error: - code: 503 - message: 'Service temporarily unavailable' - schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - '524': - content: - application/json: - example: - error: - code: 524 - message: 'Request timed out. Please try again later.' - schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': - content: - application/json: - example: - error: - code: 529 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - summary: 'Create a chat completion' + summary: 'Get user activity grouped by endpoint' tags: - - 'Chat' - x-speakeasy-group: 'chat' - x-speakeasy-name-override: 'send' - x-speakeasy-stream-request-field: 'stream' - /classifications/task: + - 'Analytics' + x-speakeasy-max-method-params: 5 + /analytics/meta: get: - description: "Returns the market-share breakdown of OpenRouter traffic by task classification\n(e.g. code generation, web search, summarization) over a trailing time window.\n\nEach classification reports its share of classified sampled requests (`usage_share`)\nand classified sampled token volume (`token_share`) as fractions between 0 and 1.\nThe unclassified `other` bucket is excluded. Absolute volumes are not exposed\nbecause the underlying data is sampled.\n\nEach classification also includes a `models` array listing the top models by\nrequest volume within that classification, with their within-tag usage and token shares.\n\nClassifications are grouped into macro-categories (Code, Data, Agent, General)\nwith aggregate shares provided for each.\n\nAuthenticate with any valid OpenRouter API key (same key used for inference).\nRate-limited to 30 requests/minute per key and 500 requests/day per account.\n\nWhen republishing or quoting this data, cite as:\n\"Source: OpenRouter (openrouter.ai/rankings), as of {as_of}.\"" - operationId: 'getTaskClassifications' - parameters: - - description: 'Trailing time window for the classification data. Currently only `7d` (trailing 7 days) is supported.' - in: 'query' - name: 'window' - required: false - schema: - default: '7d' - description: 'Trailing time window for the classification data. Currently only `7d` (trailing 7 days) is supported.' - enum: - - '7d' - example: '7d' - type: 'string' + description: 'Returns the available metrics, dimensions, filter operators, and granularities for the analytics query endpoint. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'getAnalyticsMeta' responses: '200': content: application/json: example: data: - as_of: '2026-06-17' - classifications: - - category_token_share: 0.48 - category_usage_share: 0.51 - display_name: 'Code Generation' - macro_category: 'code' - models: - - id: 'openai/gpt-4.1-mini' - tag_token_share: 0.75 - tag_usage_share: 0.55 - tag: 'code:general_impl' - token_share: 0.31 - usage_share: 0.23 - macro_categories: - - key: 'code' - label: 'Code' - token_share: 0.52 - usage_share: 0.45 - window_days: 7 - schema: - $ref: '#/components/schemas/TaskClassificationResponse' - description: 'Task classification market-share data for the requested trailing window.' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' + dimensions: + - display_label: 'Model' + name: 'model' + granularities: + - display_label: 'Day' + name: 'day' + metrics: + - display_format: 'number' + display_label: 'Request Count' + is_rate: false + name: 'request_count' + operators: + - name: 'eq' + value_type: 'scalar' schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' + properties: + data: + properties: + dimensions: + items: + properties: + display_label: + description: 'Human-readable label' + example: 'Model' + type: 'string' + name: + description: 'Dimension identifier used in query requests' + example: 'model' + type: 'string' + required: + - 'name' + - 'display_label' + type: 'object' + type: 'array' + granularities: + items: + properties: + display_label: + description: 'Human-readable label' + example: 'Day' + type: 'string' + name: + description: 'Granularity identifier' + enum: + - 'minute' + - 'hour' + - 'day' + - 'week' + - 'month' + example: 'day' + type: 'string' + required: + - 'name' + - 'display_label' + type: 'object' + type: 'array' + metrics: + items: + properties: + display_format: + description: 'How this metric value should be formatted for display (e.g. percent → multiply by 100 and append %, currency → prefix with $)' + enum: + - 'number' + - 'currency' + - 'percent' + - 'latency' + - 'throughput' + example: 'number' + type: 'string' + display_label: + description: 'Human-readable label' + example: 'Request Count' + type: 'string' + is_rate: + description: 'Whether this metric is a rate/ratio (averaged, not summed)' + type: 'boolean' + name: + description: 'Metric identifier used in query requests' + example: 'request_count' + type: 'string' + required: + - 'name' + - 'display_label' + - 'is_rate' + - 'display_format' + type: 'object' + type: 'array' + operators: + items: + properties: + name: + description: 'Operator identifier used in filter definitions' + enum: + - 'eq' + - 'neq' + - 'in' + - 'not_in' + - 'gt' + - 'gte' + - 'lt' + - 'lte' + example: 'eq' + type: 'string' + value_type: + description: 'Whether the operator expects a single value or an array' + enum: + - 'scalar' + - 'array' + type: 'string' + required: + - 'name' + - 'value_type' + type: 'object' + type: 'array' + required: + - 'metrics' + - 'dimensions' + - 'operators' + - 'granularities' + type: 'object' + required: + - 'data' + type: 'object' + description: 'Returns analytics query metadata' '401': content: application/json: @@ -37562,16 +33749,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '429': + '403': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '500': content: application/json: @@ -37582,61 +33769,239 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Task classification market share' + summary: 'Get available analytics metrics and dimensions' tags: - - 'Classifications' - /containers/{container_id}/files: - get: - description: 'Lists the files in a container, in lexicographic path order. The container id is the canonical id returned in bash/shell tool results; a restarted session is a separate container with its own id. Paginate with `limit` and `after` (pass the previous page’s `last_id`); `has_more: true` always means the next page is fetchable that way. `last_id` is the resume cursor: it is the last listed file’s id, except when a page ends at the per-request scan bound on hidden bookkeeping objects, where it names the scan position instead and may not appear in `data` (which can then be empty).' - operationId: 'listContainerFiles' - parameters: - - description: '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.' - in: 'path' - name: 'container_id' - required: true - schema: - description: '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.' - example: 'sess_abc123' - type: 'string' - - description: 'Maximum number of files to return (1-1000). Defaults to 100 when absent.' - in: 'query' - name: 'limit' - required: false - schema: - default: 100 - description: 'Maximum number of files to return (1-1000). Defaults to 100 when absent.' - example: 100 - maximum: 1000 - minimum: 1 - type: 'integer' - - description: '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.' - in: 'query' - name: 'after' - required: false - schema: - description: '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.' - example: 'cfile_b3V0L3JlcG9ydC5jc3Y' - type: 'string' + - 'Analytics' + /analytics/query: + post: + description: 'Execute an analytics query with specified metrics, dimensions, filters, and time range. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'queryAnalytics' + requestBody: + content: + application/json: + example: + dimensions: + - 'model' + granularity: 'day' + limit: 100 + metrics: + - 'request_count' + time_range: + end: '2025-01-08T00:00:00Z' + start: '2025-01-01T00:00:00Z' + schema: + properties: + classifier_dimensions: + description: 'Group results by custom classifier tags, breaking down metrics by the specified dimension values. Requires an active classifier on the workspace.' + properties: + classifier_id: + description: 'UUID of the classifier whose tags to group by.' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' + type: 'string' + dimension_names: + items: + description: 'Classifier dimension name (snake_case identifier). Each name becomes its own column key in the response; providing two names cross-groups results by both dimensions. With no names, the response uses `clf_dimension_name`/`clf_dimension_value` columns (one row per dimension/value pair).' + example: 'department' + type: 'string' + maxItems: 2 + type: 'array' + include_nulls: + description: 'When true, also include generations that have no tag from this classifier. Defaults to false, which returns only classified generations.' + type: 'boolean' + required: + - 'classifier_id' + type: 'object' + classifier_filters: + description: '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.' + properties: + classifier_id: + description: 'UUID of the classifier whose tags to filter by. Must match classifier_dimensions.classifier_id when both are specified.' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' + type: 'string' + filters: + items: + properties: + field: + description: 'Classifier dimension name to filter on (snake_case identifier, e.g. "department", "work_type").' + example: 'department' + type: 'string' + operator: + description: 'Filter operator. Only equality/set operators are supported (eq, neq, in, not_in) — ordered comparisons are not available because classification values are strings.' + example: 'eq' + type: 'string' + value: + anyOf: + - type: 'string' + - format: 'double' + type: 'number' + - items: + anyOf: + - type: 'string' + - format: 'double' + type: 'number' + type: 'array' + description: 'Filter value. Use a scalar (string or number) for eq/neq, or an array for in/not_in.' + example: 'Engineering' + required: + - 'field' + - 'operator' + - 'value' + type: 'object' + maxItems: 10 + minItems: 1 + type: 'array' + required: + - 'classifier_id' + - 'filters' + type: 'object' + dimensions: + items: + description: 'Dimension to group by (up to 2). Use the /meta endpoint for available dimensions.' + example: 'model' + type: 'string' + maxItems: 2 + type: 'array' + filters: + items: + properties: + field: + description: 'Dimension to filter on. Use the /meta endpoint for available dimensions.' + example: 'model' + type: 'string' + include_unset: + description: 'Include rows where the dimension has no value. Applies only to the `in` and `not_in` operators and dimensions that have an unset bucket.' + type: 'boolean' + operator: + description: 'Filter operator' + example: 'eq' + type: 'string' + value: + anyOf: + - type: 'string' + - format: 'double' + type: 'number' + - items: + anyOf: + - type: 'string' + - format: 'double' + type: 'number' + type: 'array' + description: 'Filter value (scalar or array depending on operator). Several dimensions are enriched in responses (returned as human-readable labels), but filters must use the underlying ID: `api_key_id` — numeric ID (from generation metadata) or key hash (64-char hex from GET /api/v1/keys, resolved server-side); `user` — Clerk user ID (e.g. "user_abc123"), not the display name; `workspace` — workspace UUID, not the workspace name (filtering or grouping by the account default workspace also covers activity recorded before workspace resolution existed, which is attributed to that default workspace); `app` — numeric app ID, not the app title; `model` — permaslug (e.g. "openai/gpt-4o"), not the display name. Other dimensions (provider, origin, country, etc.) are not enriched and accept the value as returned.' + required: + - 'field' + - 'operator' + - 'value' + type: 'object' + maxItems: 20 + type: 'array' + granularity: + description: 'Time granularity' + example: 'day' + type: 'string' + group_limit: + description: '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.' + example: 100 + type: 'integer' + limit: + description: '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.' + type: 'integer' + metrics: + items: + description: 'Metric name' + example: 'request_count' + type: 'string' + minItems: 1 + type: 'array' + order_by: + properties: + direction: + enum: + - 'asc' + - 'desc' + type: 'string' + field: + description: 'Field to order by: a metric included in `metrics` (or "request_count", which may be ordered by without being requested), a requested dimension, or "date".' + example: 'request_count' + type: 'string' + required: + - 'field' + - 'direction' + type: 'object' + time_range: + properties: + end: + description: 'ISO 8601 UTC timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected.' + example: '2027-12-31T23:59:59Z' + format: 'date-time' + type: 'string' + start: + description: 'ISO 8601 UTC timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected.' + example: '2027-12-31T23:59:59Z' + format: 'date-time' + type: 'string' + required: + - 'start' + - 'end' + type: 'object' + required: + - 'metrics' + type: 'object' + required: true responses: '200': content: application/json: example: data: - - bytes: 123 - container_id: 'sess_abc123' - created_at: 1755640000 - id: 'cfile_b3V0L3JlcG9ydC5jc3Y' - object: 'container.file' - path: 'out/report.csv' - source: 'assistant' - first_id: 'cfile_b3V0L3JlcG9ydC5jc3Y' - has_more: false - last_id: 'cfile_b3V0L3JlcG9ydC5jc3Y' - object: 'list' + data: + - date__day: '2025-01-01T00:00:00.000Z' + request_count: 1500 + metadata: + query_time_ms: 42 + row_count: 1 + truncated: false schema: - $ref: '#/components/schemas/ContainerFileListResponse' - description: 'The files in the container.' + properties: + data: + properties: + cachedAt: + format: 'double' + type: 'number' + data: + items: + description: 'A row of analytics data with metric/dimension values' + type: 'object' + type: 'array' + metadata: + properties: + query_time_ms: + format: 'double' + type: 'number' + row_count: + type: 'integer' + truncated: + type: 'boolean' + required: + - 'query_time_ms' + - 'row_count' + - 'truncated' + title: 'Metadata' + type: 'object' + warnings: + description: 'Warnings about filter resolution issues (e.g. unresolvable api_key_id hashes). The query still runs normally; these inform the caller that some filter values could not be resolved.' + items: + type: 'string' + type: 'array' + required: + - 'data' + - 'metadata' + type: 'object' + required: + - 'data' + type: 'object' + description: 'Analytics query results' '400': content: application/json: @@ -37667,16 +34032,16 @@ paths: schema: $ref: '#/components/schemas/ForbiddenResponse' description: 'Forbidden - Authentication successful but insufficient permissions' - '429': + '408': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 408 + message: 'Operation timed out. Please try again later.' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' + $ref: '#/components/schemas/RequestTimeoutResponse' + description: 'Request Timeout - Operation exceeded time limit' '500': content: application/json: @@ -37687,55 +34052,84 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - '503': - content: - application/json: - example: - error: - code: 503 - message: 'Service temporarily unavailable' - schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - summary: 'List container files' + summary: 'Query analytics data' tags: - - 'Containers' - /containers/{container_id}/files/{file_id}: - get: - description: 'Returns the metadata of a single file in a container.' - operationId: 'getContainerFile' - parameters: - - description: '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.' - in: 'path' - name: 'container_id' - required: true - schema: - description: '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.' - example: 'sess_abc123' - type: 'string' - - description: 'Container file id (`cfile_` + base64url of the file path).' - in: 'path' - name: 'file_id' - required: true - schema: - description: 'Container file id (`cfile_` + base64url of the file path).' - example: 'cfile_b3V0L3JlcG9ydC5jc3Y' - type: 'string' + - 'Analytics' + /api/alpha/decisions: + post: + description: 'Submits a Decisions request to the Decisions router' + operationId: 'createApiAlphaDecisions' + requestBody: + content: + application/json: + example: + 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.' + schema: + $ref: '#/components/schemas/DecisionsRequest' + required: true responses: '200': content: application/json: example: - bytes: 123 - container_id: 'sess_abc123' - created_at: 1755640000 - id: 'cfile_b3V0L3JlcG9ydC5jc3Y' - object: 'container.file' - path: 'out/report.csv' - source: 'assistant' + answers: + is_bug: + noul: 0.96 + type: 'noul' + team: + choice: 'payments' + confidence: 0.75 + probabilities: + account: 0 + frontend: 0.16 + payments: 0.84 + type: 'choice' + urgency: + confidence: 0.99 + legend: + '0': 'Can wait for the next release' + '1': 'Should be fixed this week' + '2': 'Blocking revenue right now' + probabilities: + '0': 0 + '1': 0.01 + '2': 0.99 + score: 1.99 + type: 'score' + id: 'gen-dec-1789738314-X5e5eKGQdvR9rblyX250' + model: 'typesafe/jev-1.13-20260917' + provider: 'TypeSafe' + usage: + cost: 0.000019992 + input_tokens: 476 + output_tokens: 70 schema: - $ref: '#/components/schemas/ContainerFile' - description: 'The container file.' + $ref: '#/components/schemas/DecisionsResponse' + description: 'Decisions response' '400': content: application/json: @@ -37756,6 +34150,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' + '402': + content: + application/json: + example: + error: + code: 402 + message: 'Insufficient credits. Add more using https://openrouter.ai/credits' + schema: + $ref: '#/components/schemas/PaymentRequiredResponse' + description: 'Payment Required - Insufficient credits or quota to complete request' '403': content: application/json: @@ -37776,6 +34180,16 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' + '413': + content: + application/json: + example: + error: + code: 413 + message: 'Request payload too large' + schema: + $ref: '#/components/schemas/PayloadTooLargeResponse' + description: 'Payload Too Large - Request payload exceeds size limits' '429': content: application/json: @@ -37796,6 +34210,16 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' + '502': + content: + application/json: + example: + error: + code: 502 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' '503': content: application/json: @@ -37806,39 +34230,58 @@ paths: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' description: 'Service Unavailable - Service temporarily unavailable' - summary: 'Retrieve a container file' + '524': + content: + application/json: + example: + error: + code: 524 + message: 'Request timed out. Please try again later.' + schema: + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': + content: + application/json: + example: + error: + code: 529 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + servers: + - url: 'https://openrouter.ai' + summary: 'Submit a Decisions request' tags: - - 'Containers' - /containers/{container_id}/files/{file_id}/content: - get: - description: 'Streams the raw bytes of a file in a container.' - operationId: 'downloadContainerFileContent' - parameters: - - description: '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.' - in: 'path' - name: 'container_id' - required: true - schema: - description: '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.' - example: 'sess_abc123' - type: 'string' - - description: 'Container file id (`cfile_` + base64url of the file path).' - in: 'path' - name: 'file_id' - required: true - schema: - description: 'Container file id (`cfile_` + base64url of the file path).' - example: 'cfile_b3V0L3JlcG9ydC5jc3Y' - type: 'string' + - 'alpha.decisions' + x-speakeasy-name-override: 'create' + /audio/speech: + post: + description: 'Synthesizes audio from the input text. Returns a raw audio bytestream in the requested format (e.g. mp3, pcm, wav).' + operationId: 'createAudioSpeech' + requestBody: + content: + application/json: + example: + input: 'Hello world' + model: 'mistralai/voxtral-mini-tts-2603' + response_format: 'pcm' + speed: 1 + voice: 'en_paul_neutral' + schema: + $ref: '#/components/schemas/SpeechRequest' + required: true responses: '200': content: - application/octet-stream: - example: 'binary file contents' + audio/*: schema: + description: 'Raw audio bytestream. Content-Type varies by requested format (audio/mpeg for mp3, audio/pcm for pcm — 16-bit little-endian).' + example: '' format: 'binary' type: 'string' - description: 'The raw file content.' + description: 'Audio bytes stream' '400': content: application/json: @@ -37859,6 +34302,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' + '402': + content: + application/json: + example: + error: + code: 402 + message: 'Insufficient credits. Add more using https://openrouter.ai/credits' + schema: + $ref: '#/components/schemas/PaymentRequiredResponse' + description: 'Payment Required - Insufficient credits or quota to complete request' '403': content: application/json: @@ -37879,6 +34332,16 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' + '413': + content: + application/json: + example: + error: + code: 413 + message: 'Request payload too large' + schema: + $ref: '#/components/schemas/PayloadTooLargeResponse' + description: 'Payload Too Large - Request payload exceeds size limits' '429': content: application/json: @@ -37899,6 +34362,16 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' + '502': + content: + application/json: + example: + error: + code: 502 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' '503': content: application/json: @@ -37909,46 +34382,125 @@ paths: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' description: 'Service Unavailable - Service temporarily unavailable' - summary: 'Download container file content' + '524': + content: + application/json: + example: + error: + code: 524 + message: 'Request timed out. Please try again later.' + schema: + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': + content: + application/json: + example: + error: + code: 529 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + summary: 'Create speech' tags: - - 'Containers' - /containers/{container_id}/files/{file_id}/promote: + - 'TTS' + x-speakeasy-max-method-params: 1 + x-speakeasy-name-override: 'createSpeech' + /audio/transcriptions: post: - description: 'Copies a file from the container''s sandbox prefix into the workspace''s durable document storage, so it outlives the container. Returns the new document in the Files API shape, with a durable file id in the documents namespace. The copy counts against the workspace''s storage quota. Unlike a direct upload, promoted files are downloadable.' - operationId: 'promoteContainerFile' - parameters: - - description: '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.' - in: 'path' - name: 'container_id' - required: true - schema: - description: '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.' - example: 'sess_abc123' - type: 'string' - - description: 'Container file id (`cfile_` + base64url of the file path).' - in: 'path' - name: 'file_id' - required: true - schema: - description: 'Container file id (`cfile_` + base64url of the file path).' - example: 'cfile_b3V0L3JlcG9ydC5jc3Y' - type: 'string' + description: 'Transcribes audio into text. Accepts base64-encoded audio input as JSON, an OpenAI-style multipart/form-data file upload, or a URL the provider downloads directly, and returns the transcribed text.' + operationId: 'createAudioTranscriptions' + requestBody: + content: + application/json: + example: + input_audio: + data: 'UklGRiQA...' + format: 'wav' + language: 'en' + model: 'openai/whisper-large-v3' + schema: + $ref: '#/components/schemas/STTRequest' + multipart/form-data: + example: + file: 'audio.wav' + language: 'en' + model: 'openai/whisper-large-v3' + schema: + properties: + diarize: + description: 'Label each word with the speaker who said it (words[].speaker, words[].speaker_label). Requires response_format "verbose_json" (400 otherwise); word timestamps are included even when timestamp_granularities[] omits "word". Only supported by some providers; 400 when the selected model cannot diarize.' + type: 'boolean' + file: + description: 'The audio file to transcribe. The format is derived from the filename extension or the file part content type. Max 25 MB; send larger files as base64 JSON via input_audio, or by URL via source_url. Exactly one of file or source_url is required.' + format: 'binary' + type: 'string' + keyterms[]: + description: 'Domain terms, names, or phrases to bias recognition toward; repeat the part once per term (keyterms=... is also accepted). Only supported by some providers; 400 when the selected model cannot use keyterms.' + items: + type: 'string' + type: 'array' + language: + description: 'The language of the input audio (ISO-639-1).' + type: 'string' + model: + description: 'The model to use for transcription.' + type: 'string' + provider: + description: 'JSON-encoded provider preferences object, the same shape as the JSON body field: { "zdr": true, "data_collection": "deny", "options": { "": { ... } } }. Only options for the matched provider are forwarded. Must decode to a JSON object.' + type: 'string' + response_format: + description: 'The response format. "json" (default) returns { text, usage }; "verbose_json" additionally returns task, language, duration, and segment-level timestamps (OpenAI-compatible providers only).' + enum: + - 'json' + - 'verbose_json' + type: 'string' + session_id: + description: '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.' + maxLength: 256 + type: 'string' + source_url: + description: 'Publicly reachable http(s) URL of the audio file, downloaded by the provider directly (no size limit on our side). The format is derived from the URL path extension. Only supported by some providers; exactly one of file or source_url is required.' + format: 'uri' + type: 'string' + temperature: + description: 'The sampling temperature.' + type: 'number' + timestamp_granularities[]: + description: 'Timestamp detail levels to include when response_format is "verbose_json". "word" additionally returns word-level timestamps in the words array.' + items: + enum: + - 'word' + - 'segment' + type: 'string' + type: 'array' + trace: + description: 'JSON-encoded trace metadata object (trace_id, trace_name, span_name, generation_name, parent_span_id and custom keys) attached to the Broadcast trace. Must decode to a JSON object.' + type: 'string' + user: + description: 'A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.' + maxLength: 256 + type: 'string' + required: + - 'model' + type: 'object' + required: true responses: '200': content: application/json: example: - _shape: 'openrouter' - created_at: '2026-08-23T00:00:00Z' - downloadable: true - filename: 'out/report.csv' - id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - mime_type: 'text/csv' - size_bytes: 123 - type: 'file' + text: 'Hello, this is a test of OpenAI speech-to-text transcription.' + usage: + cost: 0.000508 + input_tokens: 83 + output_tokens: 30 + seconds: 9.2 + total_tokens: 113 schema: - $ref: '#/components/schemas/FileResponse' - description: 'The promoted file, as a workspace document.' + $ref: '#/components/schemas/STTResponse' + description: 'Transcription result' '400': content: application/json: @@ -37969,6 +34521,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' + '402': + content: + application/json: + example: + error: + code: 402 + message: 'Insufficient credits. Add more using https://openrouter.ai/credits' + schema: + $ref: '#/components/schemas/PaymentRequiredResponse' + description: 'Payment Required - Insufficient credits or quota to complete request' '403': content: application/json: @@ -38009,16 +34571,6 @@ paths: schema: $ref: '#/components/schemas/TooManyRequestsResponse' description: 'Too Many Requests - Rate limit exceeded' - '499': - content: - application/json: - example: - error: - code: 499 - message: 'The request was cancelled.' - schema: - $ref: '#/components/schemas/ClientClosedRequestResponse' - description: 'Client Closed Request - The caller cancelled the request' '500': content: application/json: @@ -38029,6 +34581,16 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' + '502': + content: + application/json: + example: + error: + code: 502 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' '503': content: application/json: @@ -38039,230 +34601,264 @@ paths: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' description: 'Service Unavailable - Service temporarily unavailable' - summary: 'Promote a container file into workspace documents' - tags: - - 'Containers' - /credits: - get: - description: 'Get total credits purchased and used for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'getCredits' - responses: - '200': - content: - application/json: - example: - data: - total_credits: 100.5 - total_usage: 25.75 - schema: - description: 'Total credits purchased and used' - example: - data: - total_credits: 100.5 - total_usage: 25.75 - properties: - data: - example: - total_credits: 100.5 - total_usage: 25.75 - properties: - total_credits: - description: 'Total credits purchased' - example: 100.5 - format: 'double' - type: 'number' - total_usage: - description: 'Total credits used' - example: 25.75 - format: 'double' - type: 'number' - required: - - 'total_credits' - - 'total_usage' - type: 'object' - required: - - 'data' - type: 'object' - description: 'Returns the total credits purchased and used' - '401': + '504': content: application/json: example: error: - code: 401 - message: 'Missing Authentication header' + code: 504 + message: 'The operation was aborted due to timeout' schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': + $ref: '#/components/schemas/GatewayTimeoutResponse' + description: 'Gateway Timeout - Provider did not respond before the upstream deadline' + '524': content: application/json: example: error: - code: 403 - message: 'Only management keys can perform this operation' + code: 524 + message: 'Request timed out. Please try again later.' schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '500': + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': content: application/json: example: error: - code: 500 - message: 'Internal Server Error' + code: 529 + message: 'Provider returned error' schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Get remaining credits' + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + summary: 'Create transcription' tags: - - 'Credits' - x-speakeasy-name-override: 'getCredits' - /credits/coinbase: + - 'STT' + x-speakeasy-max-method-params: 1 + x-speakeasy-name-override: 'createTranscription' + /auth/keys: post: - deprecated: true - description: 'Deprecated. The Coinbase APIs used by this endpoint have been deprecated, so Coinbase Commerce charges have been removed. Use the web credits purchase flow instead.' - operationId: 'createCoinbaseCharge' + description: 'Exchange an authorization code from the PKCE flow for a user-controlled API key' + operationId: 'exchangeAuthCodeForAPIKey' + requestBody: + content: + application/json: + example: + code: 'auth_code_abc123def456' + code_challenge_method: 'S256' + code_verifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' + schema: + example: + code: 'auth_code_abc123def456' + code_challenge_method: 'S256' + code_verifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' + properties: + code: + description: 'The authorization code received from the OAuth redirect' + example: 'auth_code_abc123def456' + type: 'string' + code_challenge_method: + description: 'The method used to generate the code challenge' + enum: + - 'S256' + - 'plain' + - null + example: 'S256' + type: + - 'string' + - 'null' + code_verifier: + description: 'The code verifier if code_challenge was used in the authorization request' + example: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' + type: 'string' + required: + - 'code' + type: 'object' + required: true responses: '200': - description: 'This endpoint is deprecated and will never return a 200 response.' - '410': content: application/json: example: - error: - code: 410 - message: 'The Coinbase APIs used by this endpoint have been deprecated, so the Coinbase Commerce credits API has been removed. Use the web credits purchase flow instead.' + key: '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' + user_id: 'user_2yOPcMpKoQhcd4bVgSMlELRaIah' schema: - $ref: '#/components/schemas/GoneResponse' - description: 'Gone - Endpoint has been permanently removed or deprecated' - security: [] - summary: 'Deprecated Coinbase Commerce charge endpoint' - tags: - - 'Credits' - x-fern-ignore: true - x-speakeasy-ignore: true - x-speakeasy-name-override: 'createCoinbaseCharge' - /datasets/app-rankings: - get: - description: "Returns the top public apps on OpenRouter ranked by token usage inside the requested\ndate window, matching the public apps marketplace on openrouter.ai/apps. Token totals\nare `prompt_tokens + completion_tokens`; hidden and private apps are excluded and\ntraffic from related app aliases is merged into the canonical visible app.\n\n`sort=popular` (default) ranks by total token volume inside the window.\n`sort=trending` ranks by absolute excess token growth: window volume minus the average\nvolume of the three equal-length periods immediately preceding the window. Apps with\nno excess growth are omitted, so `trending` may return fewer than `limit` rows.\n\nFilter with `category` (marketplace category group, e.g. `coding`) or `subcategory`\n(e.g. `cli-agent`). Ranks are re-numbered 1..N after filtering. Page with `offset` —\n`rank` stays absolute, so the first row of `offset=50` is `rank: 51`.\n\nAuthenticate with any valid OpenRouter API key (same key used for inference).\nRate-limited to 30 requests/minute per key and 500 requests/day per account.\n\nWhen republishing or quoting this dataset, OpenRouter must be cited as:\n\"Source: OpenRouter (openrouter.ai/apps), as of {as_of}.\"\n\nToken counts come from each upstream provider's own tokenizer, so a token attributed\nto one app is not directly comparable to a token attributed to another app whose\ntraffic flows through a different provider.\n\nLicensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse and republish with attribution to OpenRouter." - operationId: 'getAppRankings' - parameters: - - description: '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.' - in: 'query' - name: 'category' - required: false - schema: - description: '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.' - enum: - - 'coding' - - 'creative' - - 'productivity' - - 'entertainment' - example: 'coding' - type: 'string' - - description: '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.' - in: 'query' - name: 'subcategory' - required: false - schema: - description: '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.' - enum: - - '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' - example: 'cli-agent' - type: 'string' - - description: '`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.' - in: 'query' - name: 'sort' - required: false - schema: - default: 'popular' - description: '`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.' - enum: - - 'popular' - - 'trending' - example: 'popular' - type: 'string' - - description: '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`.' - in: 'query' - name: 'start_date' - required: false - schema: - description: '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`.' - example: '2026-04-12' - pattern: '^\d{4}-\d{2}-\d{2}$' - type: 'string' - - description: '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.' - in: 'query' - name: 'end_date' - required: false - schema: - description: '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.' - example: '2026-05-11' - pattern: '^\d{4}-\d{2}-\d{2}$' - type: 'string' - - description: 'Maximum number of apps to return (1-100). Defaults to 50.' - in: 'query' - name: 'limit' - required: false - schema: - default: 50 - description: 'Maximum number of apps to return (1-100). Defaults to 50.' - example: 50 - maximum: 100 - minimum: 1 - type: 'integer' - - description: '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`.' - in: 'query' - name: 'offset' - required: false - schema: - default: 0 - description: '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`.' - example: 0 - maximum: 100 - minimum: 0 - type: - - 'integer' - - 'null' + example: + key: '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' + user_id: 'user_2yOPcMpKoQhcd4bVgSMlELRaIah' + properties: + key: + description: 'The API key to use for OpenRouter requests' + example: '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' + type: 'string' + user_id: + description: 'User ID associated with the API key' + example: 'user_2yOPcMpKoQhcd4bVgSMlELRaIah' + type: + - 'string' + - 'null' + required: + - 'key' + - 'user_id' + type: 'object' + description: 'Successfully exchanged code for an API key' + '400': + content: + application/json: + example: + error: + code: 400 + message: 'Invalid request parameters' + schema: + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' + '403': + content: + application/json: + example: + error: + code: 403 + message: 'Only management keys can perform this operation' + schema: + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '500': + content: + application/json: + example: + error: + code: 500 + message: 'Internal Server Error' + schema: + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Exchange authorization code for API key' + tags: + - 'OAuth' + /auth/keys/code: + post: + description: 'Create an authorization code for the PKCE flow to generate a user-controlled API key' + operationId: 'createAuthKeysCode' + requestBody: + content: + application/json: + example: + callback_url: 'https://myapp.com/auth/callback' + code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' + code_challenge_method: 'S256' + limit: 100 + schema: + example: + callback_url: 'https://myapp.com/auth/callback' + code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' + code_challenge_method: 'S256' + limit: 100 + properties: + callback_url: + description: '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.' + example: 'https://myapp.com/auth/callback' + format: 'uri' + type: 'string' + code_challenge: + description: 'PKCE code challenge for enhanced security' + example: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' + type: 'string' + code_challenge_method: + description: 'The method used to generate the code challenge' + enum: + - 'S256' + - 'plain' + example: 'S256' + type: 'string' + expires_at: + description: 'Optional ISO 8601 UTC expiration timestamp. Must include seconds (YYYY-MM-DDTHH:MM:SSZ; fractional seconds allowed); minute-precision timestamps are rejected.' + example: '2027-12-31T23:59:59Z' + format: 'date-time' + type: + - 'string' + - 'null' + key_label: + description: 'Optional custom label for the API key. Defaults to the app name if not provided.' + example: 'My Custom Key' + maxLength: 100 + type: 'string' + limit: + description: 'Credit limit for the API key to be created' + example: 100 + format: 'double' + type: 'number' + spawn_agent: + description: 'Agent identifier for spawn telemetry' + example: 'my-agent' + type: 'string' + x-fern-ignore: true + x-speakeasy-ignore: true + spawn_cloud: + description: 'Cloud identifier for spawn telemetry' + example: 'aws-us-east-1' + type: 'string' + x-fern-ignore: true + x-speakeasy-ignore: true + usage_limit_type: + description: 'Optional credit limit reset interval. When set, the credit limit resets on this interval.' + enum: + - 'daily' + - 'weekly' + - 'monthly' + example: 'monthly' + type: 'string' + workspace_id: + description: 'Optional workspace ID to associate the API key with' + format: 'uuid' + type: 'string' + required: + - 'callback_url' + type: 'object' + required: true responses: '200': content: application/json: example: data: - - app_id: 12345 - app_name: 'Cline' - rank: 1 - total_requests: 4321 - total_tokens: '12345678' - - app_id: 67890 - app_name: 'Roo Code' - rank: 2 - total_requests: 2109 - total_tokens: '9876543' - meta: - as_of: '2026-05-12T02:00:00Z' - end_date: '2026-05-11' - start_date: '2026-04-12' - version: 'v1' + app_id: 12345 + created_at: '2025-08-24T10:30:00Z' + id: 'auth_code_xyz789' schema: - $ref: '#/components/schemas/AppRankingsResponse' - description: '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.' + example: + data: + app_id: 12345 + created_at: '2025-08-24T10:30:00Z' + id: 'auth_code_xyz789' + properties: + data: + description: 'Auth code data' + example: + app_id: 12345 + created_at: '2025-08-24T10:30:00Z' + id: 'auth_code_xyz789' + properties: + app_id: + description: 'The application ID associated with this auth code' + example: 12345 + type: 'integer' + created_at: + description: 'ISO 8601 timestamp of when the auth code was created' + example: '2025-08-24T10:30:00Z' + type: 'string' + id: + description: 'The authorization code ID to use in the exchange request' + example: 'auth_code_xyz789' + type: 'string' + required: + - 'id' + - 'app_id' + - 'created_at' + type: 'object' + required: + - 'data' + type: 'object' + description: 'Successfully created authorization code' '400': content: application/json: @@ -38283,16 +34879,26 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '429': + '403': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '409': + content: + application/json: + example: + error: + code: 409 + message: 'Resource conflict. Please try again later.' + schema: + $ref: '#/components/schemas/ConflictResponse' + description: 'Conflict - Resource conflict or concurrent modification' '500': content: application/json: @@ -38303,742 +34909,584 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Top apps by token usage' + summary: 'Create authorization code' tags: - - 'Datasets' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'offset' - type: 'offset' - - in: 'parameters' - name: 'limit' - type: 'limit' - outputs: - results: '$.data' - type: 'offsetLimit' - /datasets/rankings-daily: + - 'OAuth' + x-speakeasy-name-override: 'createAuthCode' + /batches: get: - description: "Returns the top 50 public models per day by total token usage on OpenRouter, plus a\nsingle aggregated `other` row per day that sums every model outside that top 50.\nToken totals are `prompt_tokens + completion_tokens`, matching the public rankings\nchart on openrouter.ai/rankings.\n\nEach row is a distinct `(date, model_permaslug)` pair. The `other` row uses the\nreserved permaslug `other` and is always returned last within its date, so callers\ncan compute `top-50 traffic / total daily traffic` without a second request.\n\nOptional filters slice the dataset. `period` (`day`/`week`/`month`) sets the time\ngrain. `modality` and `context_bucket` narrow the exact dataset by output/input\nmodality (or tool-calling activity) and request context length. `category` and\n`language_type` instead read a sampled, upsampled dataset whose `total_tokens` are\nweekly-grain estimates — they cannot be combined with each other or with the exact\nfilters, and reject `period=day` with a 400.\n\nAuthenticate with any valid OpenRouter API key (same key used for inference).\nRate-limited to 30 requests/minute per key and 500 requests/day per account.\n\nWhen republishing or quoting this dataset, OpenRouter must be cited as:\n\"Source: OpenRouter (openrouter.ai/rankings), as of {as_of}.\"\n\nToken counts come from each upstream provider's own tokenizer (Anthropic counts\nare as reported by Anthropic, OpenAI counts are as reported by OpenAI, etc.), so\na token in one row is not directly comparable to a token in another row from a\ndifferent provider.\n\nLicensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse and republish with attribution to OpenRouter." - operationId: 'getRankingsDaily' + description: 'Lists batches in the workspace of the authenticating API key, newest first. To fetch the next page, pass the previous page''s `last_id` as `after`. List items omit `results`. Use `GET /batches/{id}` to get them. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' + operationId: 'listBatches' parameters: - - description: '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`.' - in: 'query' - name: 'start_date' - required: false - schema: - description: '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`.' - example: '2026-04-12' - pattern: '^\d{4}-\d{2}-\d{2}$' - type: 'string' - - description: '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.' - in: 'query' - name: 'end_date' - required: false - schema: - description: '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.' - example: '2026-05-11' - pattern: '^\d{4}-\d{2}-\d{2}$' - type: 'string' - - description: '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.' + - description: 'Maximum number of batches to return, from 1 through 100.' in: 'query' - name: 'period' + name: 'limit' required: false schema: - description: '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.' - enum: - - 'day' - - 'week' - - 'month' - example: 'day' - type: 'string' - - description: '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`.' + description: 'Maximum number of batches to return, from 1 through 100.' + example: 20 + type: 'integer' + - description: 'Batch id from the previous page''s `last_id`.' in: 'query' - name: 'modality' + name: 'after' required: false schema: - description: '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`.' - enum: - - 'text' - - 'image' - - 'image_output' - - 'audio' - - 'tool_calling' - example: 'text' + description: 'Batch id from the previous page''s `last_id`.' + example: 'batch_7a4b02' + minLength: 1 type: 'string' - - description: '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`.' + - description: 'Repeat this parameter to include more than one status.' + explode: true in: 'query' - name: 'context_bucket' + name: 'status' required: false schema: - description: '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`.' - enum: - - '1K' - - '10K' - - '100K' - - '1M' - - '10M' - example: '100K' - type: 'string' - - description: '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`.' + description: 'Repeat this parameter to include more than one status.' + example: + - 'completed' + - 'failed' + items: + $ref: '#/components/schemas/BatchListStatus' + type: 'array' + style: 'form' + - description: 'Only include batches created strictly after this timestamp.' in: 'query' - name: 'category' + name: 'created_after' required: false schema: - description: '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`.' - enum: - - 'programming' - - 'roleplay' - - 'marketing' - - 'marketing/seo' - - 'technology' - - 'science' - - 'translation' - - 'legal' - - 'finance' - - 'health' - - 'trivia' - - 'academia' - example: 'programming' - type: 'string' - - description: '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`.' + $ref: '#/components/schemas/BatchListTimestamp' + - description: 'Only include batches created strictly before this timestamp.' in: 'query' - name: 'language_type' + name: 'created_before' required: false schema: - description: '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`.' - enum: - - 'natural' - - 'programming' - example: 'natural' - type: 'string' + allOf: + - $ref: '#/components/schemas/BatchListTimestamp' + - description: 'Only include batches created strictly before this timestamp.' responses: '200': content: application/json: - example: - data: - - date: '2026-05-11' - model_permaslug: 'openai/gpt-4o-2024-05-13' - total_tokens: '12345678' - - date: '2026-05-11' - model_permaslug: 'anthropic/claude-3.5-sonnet-20241022' - total_tokens: '9876543' - - date: '2026-05-11' - model_permaslug: 'other' - total_tokens: '4321098' - meta: - as_of: '2026-05-12T02:00:00Z' - end_date: '2026-05-11' - start_date: '2026-04-12' - version: 'v1' schema: - $ref: '#/components/schemas/RankingsDailyResponse' - description: '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.' + $ref: '#/components/schemas/BatchListResponse' + description: 'A newest-first page of batches.' '400': content: application/json: example: error: code: 400 - message: 'Invalid request parameters' + message: 'Invalid batch list query.' schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Malformed or unsupported batch list query parameters.' '401': content: application/json: example: error: code: 401 - message: 'Missing Authentication header' + message: 'No auth credentials found.' schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Missing or invalid API key.' '429': content: application/json: example: error: code: 429 - message: 'Rate limit exceeded' + message: 'Rate limit exceeded.' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Batch API rate limit exceeded for the billable entity.' '500': content: application/json: example: error: code: 500 - message: 'Internal Server Error' + message: 'Internal server error.' schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Daily token totals for top 50 models' - tags: - - 'Datasets' - /datasets/session-cost: - get: - description: "Returns weekly refreshed, aggregated cost-per-session cells for the published harnesses.\nSessions are never pooled across apps. Medians are of per-session USD spend, and\nprivacy-preserving aggregation never exposes clerk_user_id values or per-session rows.\n\nFilter by `app_slug`, `model`, or `turn_range`. Filtering by `model` alone works across apps\nfor harness-vs-harness comparison at a fixed model. Results refresh weekly and include the source snapshot\nwindow in `meta`.\n\nLicensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse and republish with attribution to OpenRouter." - operationId: 'getSessionCost' - parameters: - - description: 'Filter to one published harness slug.' - in: 'query' - name: 'app_slug' - required: false - schema: - description: 'Filter to one published harness slug.' - example: 'hermes-agent' - type: 'string' - - description: 'Exact model permaslug filter. Works across all harness apps.' - in: 'query' - name: 'model' - required: false - schema: - description: 'Exact model permaslug filter. Works across all harness apps.' - example: 'anthropic/claude-4.8-opus' - type: 'string' - - description: 'Filter by the inclusive number of turns in a session.' - in: 'query' - name: 'turn_range' - required: false - schema: - description: 'Filter by the inclusive number of turns in a session.' - enum: - - '1-turn' - - '2-9-turns' - - '10-49-turns' - - '50-plus-turns' - example: '10-49-turns' - type: 'string' - - description: 'Maximum number of cells to return (1-500). Defaults to 100.' - in: 'query' - name: 'limit' - required: false - schema: - default: 100 - description: 'Maximum number of cells to return (1-500). Defaults to 100.' - example: 100 - maximum: 500 - minimum: 1 - type: 'integer' - - description: 'Number of sorted cells to skip (0-5000). Defaults to 0.' - in: 'query' - name: 'offset' - required: false - schema: - default: 0 - description: 'Number of sorted cells to skip (0-5000). Defaults to 0.' - example: 0 - maximum: 5000 - minimum: 0 - type: - - 'integer' - - 'null' - responses: - '200': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Unexpected error in the ingress or upstream batch-api.' + '502': content: application/json: example: - data: - - app_name: 'Hermes Agent' - app_slug: 'hermes-agent' - median_session_cost_usd: 1.74 - model_permaslug: 'anthropic/claude-4.8-opus' - turn_range: '10-49-turns' - meta: - as_of: '2026-05-12T02:00:00.000Z' - version: 'v1' - window_days: 30 - window_end_date: '2026-05-11' + error: + code: 502 + message: 'Upstream batch-api is unavailable.' + schema: + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' + summary: 'List batches' + tags: + - 'Batch' + x-speakeasy-name-override: 'list' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'after' + type: 'cursor' + outputs: + nextCursor: '$.last_id' + results: '$.data' + type: 'cursor' + post: + description: 'Creates a batch of requests that run asynchronously against a single endpoint (`/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/embeddings`). Returns `202` with `status: "validating"`. Poll `GET /batches/{id}` for progress and results. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' + operationId: 'createBatches' + requestBody: + content: + application/json: + examples: + chatCompletions: + summary: 'Chat completions batch' + value: + endpoint: '/v1/chat/completions' + model: 'openai/gpt-4o' + requests: + - body: + messages: + - content: 'Summarize ...' + role: 'user' + model: 'openai/gpt-4o' + custom_id: 'req-0001' + messages: + summary: 'Messages batch' + value: + endpoint: '/v1/messages' + model: 'openai/gpt-5-nano' + requests: + - body: + max_tokens: 1024 + messages: + - content: 'Summarize ...' + role: 'user' + model: 'openai/gpt-5-nano' + custom_id: 'req-0001' + providerPinned: + summary: 'Batch pinned to Vertex' + value: + endpoint: '/v1/chat/completions' + model: 'google/gemini-3.6-flash' + provider: + only: + - 'google-vertex' + requests: + - body: + messages: + - content: 'Summarize ...' + role: 'user' + model: 'google/gemini-3.6-flash' + custom_id: 'req-0001' + responses: + summary: 'Responses batch' + value: + endpoint: '/v1/responses' + model: 'openai/gpt-4o' + requests: + - body: + input: + - content: + - text: 'Summarize ...' + type: 'input_text' + role: 'user' + model: 'openai/gpt-4o' + custom_id: 'req-0001' + schema: + $ref: '#/components/schemas/BatchSubmitBody' + description: 'The batch to create. Each item in `requests` has a unique `custom_id` and a `body` in the request format of the chosen `endpoint`.' + required: true + responses: + '202': + content: + application/json: schema: - $ref: '#/components/schemas/SessionCostResponse' - description: 'Aggregated cost-per-session cells for the requested filters.' + $ref: '#/components/schemas/BatchObject' + description: 'Batch payload durably persisted and queued for asynchronous validation and provider submission (`status: "validating"`).' '400': content: application/json: example: error: code: 400 - message: 'Invalid request parameters' + message: 'custom_id is required on requests[0].' schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Malformed batch input or an unknown/incompatible batch model.' '401': content: application/json: example: error: code: 401 - message: 'Missing Authentication header' + message: 'No auth credentials found.' schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '429': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Missing or invalid API key.' + '402': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 402 + message: 'Insufficient balance for this batch.' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '500': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The estimated batch cost exceeds the available balance.' + '403': content: application/json: example: error: - code: 500 - message: 'Internal Server Error' + code: 403 + message: 'The selected provider or model is not allowed.' schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Cost per session by harness and model' - tags: - - 'Datasets' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'offset' - type: 'offset' - - in: 'parameters' - name: 'limit' - type: 'limit' - outputs: - results: '$.data' - type: 'offsetLimit' - /embeddings: - post: - description: 'Submits an embedding request to the embeddings router' - operationId: 'createEmbeddings' - requestBody: - content: - application/json: - schema: - description: 'Embeddings request input' - example: - dimensions: 1536 - input: 'The quick brown fox jumps over the lazy dog' - model: 'openai/text-embedding-3-small' - properties: - dimensions: - description: 'The number of dimensions for the output embeddings' - example: 1536 - minimum: 1 - type: 'integer' - encoding_format: - description: 'The format of the output embeddings' - enum: - - 'float' - - 'base64' - example: 'float' - type: 'string' - input: - anyOf: - - minLength: 1 - type: 'string' - - items: - minLength: 1 - type: 'string' - type: 'array' - - items: - type: 'number' - type: 'array' - - items: - items: - type: 'number' - type: 'array' - type: 'array' - - items: - properties: - content: - items: - oneOf: - - properties: - text: - minLength: 1 - type: 'string' - type: - enum: - - 'text' - type: 'string' - required: - - 'type' - - 'text' - type: 'object' - - properties: - image_url: - properties: - url: - type: 'string' - required: - - 'url' - type: 'object' - type: - enum: - - 'image_url' - type: 'string' - required: - - 'type' - - 'image_url' - type: 'object' - - $ref: '#/components/schemas/ContentPartInputAudio' - - $ref: '#/components/schemas/ContentPartInputVideo' - - $ref: '#/components/schemas/ContentPartInputFile' - minItems: 1 - type: 'array' - required: - - 'content' - type: 'object' - type: 'array' - description: 'Text, token, or multimodal input(s) to embed' - example: 'The quick brown fox jumps over the lazy dog' - input_type: - description: 'The type of input (e.g. search_query, search_document)' - example: 'search_query' - type: 'string' - model: - description: 'The model to use for embeddings' - example: 'openai/text-embedding-3-small' - type: 'string' - provider: - allOf: - - $ref: '#/components/schemas/ProviderPreferences' - - description: 'Provider routing preferences for the request.' - session_id: - description: '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.' - example: 'session-1234' - maxLength: 256 - type: 'string' - trace: - $ref: '#/components/schemas/TraceConfig' - user: - description: 'A unique identifier for the end-user' - example: 'user-1234' - type: 'string' - required: - - 'input' - - 'model' - type: 'object' - required: true - responses: - '200': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The resolved batch endpoint is blocked by account policy.' + '404': content: application/json: + example: + error: + code: 404 + message: 'Batch not found.' schema: - description: 'Embeddings response containing embedding vectors' - example: - data: - - embedding: - - 0.0023064255 - - -0.009327292 - - 0.015797347 - index: 0 - object: 'embedding' - model: 'openai/text-embedding-3-small' - object: 'list' - usage: - prompt_tokens: 8 - total_tokens: 8 - properties: - data: - description: 'List of embedding objects' - example: - - embedding: - - 0.0023064255 - - -0.009327292 - - 0.015797347 - index: 0 - object: 'embedding' - items: - description: 'A single embedding object' - example: - embedding: - - 0.0023064255 - - -0.009327292 - - 0.015797347 - index: 0 - object: 'embedding' - properties: - embedding: - anyOf: - - items: - type: 'number' - type: 'array' - - type: 'string' - description: 'Embedding vector as an array of floats or a base64 string' - example: - - 0.0023064255 - - -0.009327292 - - 0.015797347 - index: - description: 'Index of the embedding in the input list' - example: 0 - type: 'integer' - object: - enum: - - 'embedding' - type: 'string' - required: - - 'object' - - 'embedding' - type: 'object' - type: 'array' - id: - description: 'Unique identifier for the embeddings response' - example: 'embd-1234567890' - type: 'string' - model: - description: 'The model used for embeddings' - example: 'openai/text-embedding-3-small' - type: 'string' - object: - enum: - - 'list' - type: 'string' - usage: - description: 'Token usage statistics' - example: - prompt_tokens: 8 - total_tokens: 8 - properties: - cost: - description: 'Cost of the request in credits' - example: 0.0001 - format: 'double' - type: 'number' - cost_details: - $ref: '#/components/schemas/CostDetails' - is_byok: - description: 'Whether a request was made using a Bring Your Own Key configuration' - type: 'boolean' - prompt_tokens: - description: 'Number of tokens in the input' - example: 8 - type: 'integer' - prompt_tokens_details: - description: 'Per-modality token breakdown. Only present when the input contains 2+ modalities (e.g. text + image) and the upstream provider returns modality-level usage data. Only non-zero modality counts are included.' - properties: - audio_tokens: - description: 'Number of audio tokens in the input' - type: 'integer' - file_tokens: - description: 'Number of file/document tokens in the input' - type: 'integer' - image_tokens: - description: 'Number of image tokens in the input' - example: 258 - type: 'integer' - text_tokens: - description: 'Number of text tokens in the input' - example: 8 - type: 'integer' - video_tokens: - description: 'Number of video tokens in the input' - type: 'integer' - type: 'object' - total_tokens: - description: 'Total number of tokens used' - example: 8 - type: 'integer' - required: - - 'prompt_tokens' - - 'total_tokens' - type: 'object' - required: - - 'object' - - 'data' - - 'model' - type: 'object' - text/event-stream: - example: 'data: [DONE]' - schema: - description: 'Not used for embeddings - embeddings do not support streaming' - type: 'string' - x-speakeasy-sse-sentinel: '[DONE]' - description: 'Embedding response' - '400': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'No batch exists for the given id.' + '413': content: application/json: example: error: - code: 400 - message: 'Invalid request parameters' + code: 413 + message: 'Batch input exceeds the 200 MB payload limit.' schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Batch input exceeds the maximum payload size.' + '422': content: application/json: example: error: - code: 401 - message: 'Missing Authentication header' + code: 422 + message: 'The batch request could not be processed.' schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '402': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The requested model variant or custom IDs violate Batch API constraints.' + '429': content: application/json: example: error: - code: 402 - message: 'Insufficient credits. Add more using https://openrouter.ai/credits' + code: 429 + message: 'Rate limit exceeded.' schema: - $ref: '#/components/schemas/PaymentRequiredResponse' - description: 'Payment Required - Insufficient credits or quota to complete request' - '403': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Batch API rate limit exceeded for the billable entity.' + '500': content: application/json: example: error: - code: 403 - message: 'Only management keys can perform this operation' + code: 500 + message: 'Internal server error.' schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Unexpected error in the ingress or upstream batch-api.' + '502': content: application/json: example: error: - code: 404 - message: 'Resource not found' + code: 502 + message: 'Upstream batch-api is unavailable.' schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '408': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' + summary: 'Create a batch' + tags: + - 'Batch' + x-speakeasy-retries: + retryConnectionErrors: false + statusCodes: + - '429' + strategy: 'backoff' + /batches/{id}: + delete: + description: 'Deletes a batch in a terminal status (`completed`, `failed`, `expired`, or `cancelled`) and its stored requests and results. Batches still in progress return `409`. Billing and usage records are kept. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' + operationId: 'deleteBatch' + parameters: + - description: 'The batch job id returned from submit.' + in: 'path' + name: 'id' + required: true + schema: + description: 'The batch job id returned from submit.' + example: 'batch_abc123' + minLength: 1 + type: 'string' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/BatchDeletedObject' + description: 'The batch was deleted; per-target outcomes are reported under `deletion`.' + '401': content: application/json: example: error: - code: 408 - message: 'Operation timed out. Please try again later.' + code: 401 + message: 'No auth credentials found.' schema: - $ref: '#/components/schemas/RequestTimeoutResponse' - description: 'Request Timeout - Operation exceeded time limit' - '413': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Missing or invalid API key.' + '404': content: application/json: example: error: - code: 413 - message: 'Request payload too large' + code: 404 + message: 'Batch not found.' schema: - $ref: '#/components/schemas/PayloadTooLargeResponse' - description: 'Payload Too Large - Request payload exceeds size limits' - '429': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'No batch exists for the given id.' + '409': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 409 + message: 'Only completed, failed, expired, or cancelled batches can be deleted. Wait for the batch to finish and try again.' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '499': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The batch is still processing, its required provider key is unavailable, or its state changed during deletion.' + '429': content: application/json: example: error: - code: 499 - message: 'The request was cancelled.' + code: 429 + message: 'Rate limit exceeded.' schema: - $ref: '#/components/schemas/ClientClosedRequestResponse' - description: 'Client Closed Request - The caller cancelled the request' + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Batch API rate limit exceeded for the billable entity.' '500': content: application/json: example: error: code: 500 - message: 'Internal Server Error' + message: 'Internal server error.' schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Unexpected error in the ingress or upstream batch-api.' '502': content: application/json: example: error: code: 502 - message: 'Provider returned error' + message: 'Upstream batch-api is unavailable.' schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '503': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' + summary: 'Delete a batch' + tags: + - 'Batch' + x-speakeasy-name-override: 'delete' + get: + description: 'Returns a batch with its status and request counts. Batches in a terminal status include `results`. Failed batches report the reason in `error.message`. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart).' + operationId: 'getBatches' + parameters: + - description: 'The batch job id returned from submit.' + in: 'path' + name: 'id' + required: true + schema: + description: 'The batch job id returned from submit.' + example: 'batch_abc123' + minLength: 1 + type: 'string' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/BatchObject' + description: 'The current batch job status.' + '401': content: application/json: example: error: - code: 503 - message: 'Service temporarily unavailable' + code: 401 + message: 'No auth credentials found.' schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - '504': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Missing or invalid API key.' + '402': + content: + application/json: + schema: + $ref: '#/components/schemas/BatchPaymentRequiredResponse' + description: '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': content: application/json: example: error: - code: 504 - message: 'The operation was aborted due to timeout' + code: 404 + message: 'Batch not found.' schema: - $ref: '#/components/schemas/GatewayTimeoutResponse' - description: 'Gateway Timeout - Provider did not respond before the upstream deadline' - '524': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'No batch exists for the given id.' + '410': + content: + application/json: + example: + error: + code: 410 + message: 'Batch results have expired. OpenRouter deletes batch results 30 days after the batch is created.' + schema: + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The batch results were deleted after the 30-day retention window.' + '429': + content: + application/json: + example: + error: + code: 429 + message: 'Rate limit exceeded.' + schema: + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Batch API rate limit exceeded for the billable entity.' + '500': content: application/json: example: error: - code: 524 - message: 'Request timed out. Please try again later.' + code: 500 + message: 'Internal server error.' schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': + $ref: '#/components/schemas/BatchErrorResponse' + description: 'Unexpected error in the ingress or upstream batch-api.' + '502': content: application/json: example: error: - code: 529 - message: 'Provider returned error' + code: 502 + message: 'Upstream batch-api is unavailable.' schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - summary: 'Submit an embedding request' + $ref: '#/components/schemas/BatchErrorResponse' + description: 'The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.' + summary: 'Get a batch' tags: - - 'Embeddings' - x-speakeasy-name-override: 'generate' - /embeddings/models: + - 'Batch' + /benchmarks: get: - description: 'Returns a list of all available embeddings models and their properties' - operationId: 'listEmbeddingsModels' + description: 'Unified benchmark endpoint that aggregates scores from multiple benchmark sources (Artificial Analysis, Design Arena, and OpenRouter''s own tau-bench, GPQA, and web-search evals). Filter by source to reproduce the exact shapes from the legacy per-source endpoints, or use task_type to find models suited for specific workloads. Use task_type=search (or a search_* benchmark_type) for OpenRouter''s search benchmarks, which publish each model''s highest-scoring eligible evaluation configuration with same-configuration runs combined by task-weighted mean. Authenticate with any valid OpenRouter API key. Rate-limited to 30 requests/minute per key and 500 requests/day per account.' + operationId: 'getBenchmarks' parameters: - - description: 'Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned' + - description: 'Benchmark source to query. Determines the shape of the returned items. When omitted, returns results from all sources.' in: 'query' - name: 'offset' + name: 'source' required: false schema: - default: 0 - description: 'Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned' - example: 0 - minimum: 0 - type: - - 'integer' - - 'null' - - description: 'Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned' + description: 'Benchmark source to query. Determines the shape of the returned items. When omitted, returns results from all sources.' + enum: + - 'artificial-analysis' + - 'design-arena' + - 'openrouter' + example: 'artificial-analysis' + type: 'string' + - description: 'Filter results by task type. For Artificial Analysis, maps to the corresponding index. For Design Arena, maps to the matching category. `search` returns OpenRouter search benchmark results only.' in: 'query' - name: 'limit' + name: 'task_type' required: false schema: - default: 500 - description: 'Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned' - example: 500 - maximum: 1000 + description: 'Filter results by task type. For Artificial Analysis, maps to the corresponding index. For Design Arena, maps to the matching category. `search` returns OpenRouter search benchmark results only.' + enum: + - 'coding' + - 'intelligence' + - 'agentic' + - 'search' + example: 'coding' + type: 'string' + - description: '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.' + in: 'query' + name: 'benchmark_type' + required: false + schema: + description: '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.' + enum: + - 'gpqa_diamond' + - 'tau_bench_verified_airline' + - 'search_browsecomp' + - 'search_hle' + - 'search_dsqa' + - 'search_widesearch' + example: 'search_widesearch' + type: 'string' + - description: '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.' + in: 'query' + name: 'include_run_config' + required: false + schema: + default: false + description: '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.' + example: true + type: 'boolean' + - description: 'OpenRouter search benchmarks only: filter by the search engine used.' + in: 'query' + name: 'search_engine' + required: false + schema: + description: 'OpenRouter search benchmarks only: filter by the search engine used.' + example: 'exa' + type: 'string' + - description: 'OpenRouter search benchmarks only: filter by the request surface the lane ran on.' + in: 'query' + name: 'search_surface' + required: false + schema: + description: 'OpenRouter search benchmarks only: filter by the request surface the lane ran on.' + enum: + - 'server-tool' + - 'plugin' + example: 'server-tool' + type: 'string' + - description: 'Design Arena only: arena to query. Defaults to `models` when source is `design-arena`.' + in: 'query' + name: 'arena' + required: false + schema: + description: 'Design Arena only: arena to query. Defaults to `models` when source is `design-arena`.' + enum: + - 'models' + - 'builders' + - 'agents' + example: 'models' + type: 'string' + - description: 'Design Arena only: category within the arena (e.g. `codecategories`, `uicomponent`, `gamedev`, `3d`, `dataviz`, `image`, `video`, `svg`). When omitted, returns all categories.' + in: 'query' + name: 'category' + required: false + schema: + description: 'Design Arena only: category within the arena (e.g. `codecategories`, `uicomponent`, `gamedev`, `3d`, `dataviz`, `image`, `video`, `svg`). When omitted, returns all categories.' + example: 'codecategories' + type: 'string' + - description: 'Maximum number of items to return. When omitted, all matching results are returned.' + in: 'query' + name: 'max_results' + required: false + schema: + description: 'Maximum number of items to return. When omitted, all matching results are returned.' + example: 50 minimum: 1 type: 'integer' responses: @@ -39047,40 +35495,35 @@ paths: application/json: example: data: - - architecture: - input_modalities: - - 'text' - instruct_type: null - modality: 'text->embeddings' - output_modalities: - - 'embeddings' - tokenizer: 'GPT' - canonical_slug: 'openai/text-embedding-3-small' - context_length: 8192 - created: 1692901234 - default_parameters: null - description: 'OpenAI text embedding model optimized for performance.' - expiration_date: null - id: 'openai/text-embedding-3-small' - knowledge_cutoff: null - links: - details: '/api/v1/models/openai/text-embedding-3-small/endpoints' - name: 'Text Embedding 3 Small' - per_request_limits: null + - agentic_index: 58.3 + coding_index: 65.8 + display_name: 'GPT-4o' + intelligence_index: 71.2 + model_permaslug: 'openai/gpt-4o' pricing: - completion: '0' - image: '0' - prompt: '0.00000002' - request: '0' - supported_parameters: [] - supported_voices: null - top_provider: - context_length: 8192 - is_moderated: false - max_completion_tokens: null + completion: '0.00001' + prompt: '0.0000025' + source: 'artificial-analysis' + - accuracy: 0.72 + accuracy_stddev: 0.03 + avg_cost_per_task: 0.002 + benchmark_type: 'gpqa_diamond' + display_name: 'GPT-4o' + last_run_timestamp: '2026-06-03T12:00:00Z' + model_permaslug: 'openai/gpt-4o' + source: 'openrouter' + total_tasks: 300 + meta: + as_of: '2026-06-03T12:00:00Z' + citation: null + model_count: 1 + source: null + source_url: null + task_type: null + version: 'v1' schema: - $ref: '#/components/schemas/ModelsListResponse' - description: 'Returns a list of embeddings models' + $ref: '#/components/schemas/UnifiedBenchmarksResponse' + description: 'Benchmark results filtered by the specified source and optional task type.' '400': content: application/json: @@ -39091,138 +35534,26 @@ paths: schema: $ref: '#/components/schemas/BadRequestResponse' description: 'Bad Request - Invalid request parameters or malformed input' - '500': + '401': content: application/json: example: error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'List all embeddings models' - tags: - - 'Embeddings' - x-speakeasy-name-override: 'listModels' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'offset' - type: 'offset' - - in: 'parameters' - name: 'limit' - type: 'limit' - outputs: - results: '$.data' - type: 'offsetLimit' - /endpoints/zdr: - get: - operationId: 'listEndpointsZdr' - responses: - '200': - content: - application/json: - example: - data: - - context_length: 8192 - latency_last_30m: - p50: 0.25 - p75: 0.35 - p90: 0.48 - p99: 0.85 - max_completion_tokens: 4096 - max_prompt_tokens: 8192 - model_id: 'openai/gpt-4' - model_name: 'GPT-4' - name: 'OpenAI: GPT-4' - native_tools: {} - pricing: - completion: '0.00006' - image: '0' - prompt: '0.00003' - request: '0' - provider_name: 'OpenAI' - quantization: 'fp16' - status: 0 - supported_parameters: - - 'temperature' - - 'top_p' - - 'max_tokens' - supports_diarization: false - supports_image_reference: false - supports_implicit_caching: true - supports_multiple_audio_references: false - supports_voice_cloning: false - tag: 'openai' - throughput_last_30m: - p50: 45.2 - p75: 38.5 - p90: 28.3 - p99: 15.1 - uptime_last_1d: 99.8 - uptime_last_30m: 99.5 - uptime_last_5m: 100 + code: 401 + message: 'Missing Authentication header' schema: - example: - data: - - context_length: 8192 - latency_last_30m: - p50: 0.25 - p75: 0.35 - p90: 0.48 - p99: 0.85 - max_completion_tokens: 4096 - max_prompt_tokens: 8192 - model_id: 'openai/gpt-4' - model_name: 'GPT-4' - name: 'OpenAI: GPT-4' - native_tools: {} - pricing: - completion: '0.00006' - image: '0' - prompt: '0.00003' - request: '0' - provider_name: 'OpenAI' - quantization: 'fp16' - status: 0 - supported_parameters: - - 'temperature' - - 'top_p' - - 'max_tokens' - supports_diarization: false - supports_image_reference: false - supports_implicit_caching: true - supports_multiple_audio_references: false - supports_voice_cloning: false - tag: 'openai' - throughput_last_30m: - p50: 45.2 - p75: 38.5 - p90: 28.3 - p99: 15.1 - uptime_last_1d: 99.8 - uptime_last_30m: 99.5 - uptime_last_5m: 100 - properties: - data: - items: - $ref: '#/components/schemas/PublicEndpoint' - type: 'array' - required: - - 'data' - type: 'object' - description: 'Returns a list of endpoints' - '403': + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '429': content: application/json: example: error: - code: 403 - message: 'Only management keys can perform this operation' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: @@ -39233,14 +35564,13 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Preview the impact of ZDR on the available endpoints' + summary: 'List Benchmarks' tags: - - 'Endpoints' - x-speakeasy-name-override: 'listZdrEndpoints' - /external-users: + - 'Benchmarks' + /byok: get: - description: 'List registrations belonging to the authenticated organization. Inactive registrations are excluded by default. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'listExternalUsers' + description: 'List the bring-your-own-key (BYOK) provider credentials for the authenticated entity''s default workspace. Use the `workspace_id` query parameter to scope the result to a different workspace, or the `provider` query parameter to filter by upstream provider. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'listBYOKKeys' parameters: - description: 'Number of records to skip for pagination' in: 'query' @@ -39265,40 +35595,167 @@ paths: maximum: 100 minimum: 1 type: 'integer' - - description: '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.' + - description: 'Optional workspace ID to filter by. When omitted, resolves to the account’s default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly.' in: 'query' - name: 'user' + name: 'workspace_id' required: false schema: - description: '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.' - example: 'employee_123' - maxLength: 512 - minLength: 1 - pattern: '^[^\u0000]+$' + description: 'Optional workspace ID to filter by. When omitted, resolves to the account’s default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly.' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' - - description: 'Include deactivated registrations.' + - description: 'Optional provider slug to filter by (e.g. `openai`, `anthropic`, `amazon-bedrock`).' in: 'query' - name: 'include_inactive' + name: 'provider' required: false schema: - default: false - description: 'Include deactivated registrations.' - example: false - type: 'boolean' + description: 'Optional provider slug to filter by (e.g. `openai`, `anthropic`, `amazon-bedrock`).' + enum: + - 'ai21' + - 'aion-labs' + - 'akashml' + - 'alibaba' + - 'amazon-bedrock' + - 'amazon-bedrock/claude-on-aws' + - 'amazon-nova' + - 'ambient' + - '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' + - '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' + - 'liquid' + - 'makora' + - 'mancer' + - 'mara' + - 'meta' + - 'minimax' + - 'mistral' + - 'modal' + - 'modelrun' + - 'modular' + - 'moonshotai' + - 'morph' + - 'near-ai' + - 'nebius' + - 'nex-agi' + - 'nextbit' + - 'novita' + - 'nvidia' + - 'ollama' + - 'open-inference' + - 'openai' + - 'parasail' + - 'pareto-alpha' + - 'perceptron' + - 'perplexity' + - 'phala' + - 'poolside' + - 'primeintellect' + - 'quiver' + - 'recraft' + - 'recursive' + - 'reka' + - 'relace' + - 'respan' + - 'runway' + - 'sail-research' + - 'sakana' + - 'sakana-ai' + - 'sambanova' + - 'scaledown' + - 'seed' + - 'siliconflow' + - 'sourceful' + - 'stepfun' + - 'streamlake' + - 'switchpoint' + - 'tencent' + - 'tenstorrent' + - 'thinkingmachines' + - 'together' + - 'typesafe' + - 'unbiased' + - 'upstage' + - 'venice' + - 'voyageai' + - 'wafer' + - 'wandb' + - 'wandb-legacy' + - 'xai' + - 'xiaomi' + - 'z-ai' + example: 'openai' + type: 'string' responses: '200': content: application/json: example: data: - - created_at: '2026-09-16T12:00:00Z' - is_active: true - updated_at: '2026-09-16T12:00:00Z' - user: 'employee_123' + - allowed_api_key_hashes: null + allowed_models: null + allowed_user_ids: null + created_at: '2025-08-24T10:30:00Z' + declared_region: null + declared_zdr: null + disabled: false + id: '11111111-2222-3333-4444-555555555555' + is_byok_only: false + is_fallback: false + is_required: false + label: 'sk-...AbCd' + name: 'Production OpenAI Key' + provider: 'openai' + sort_order: 0 + workspace_id: '550e8400-e29b-41d4-a716-446655440000' total_count: 1 schema: - $ref: '#/components/schemas/ListExternalUsersResponse' - description: 'Matching registrations and their total count.' + $ref: '#/components/schemas/ListBYOKKeysResponse' + description: 'List of BYOK credentials' '400': content: application/json: @@ -39329,16 +35786,6 @@ paths: schema: $ref: '#/components/schemas/ForbiddenResponse' description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' '500': content: application/json: @@ -39349,10 +35796,9 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'List registered external users' + summary: 'List BYOK provider credentials' tags: - - 'External Users' - x-speakeasy-group: 'externalUsers' + - 'BYOK' x-speakeasy-name-override: 'list' x-speakeasy-pagination: inputs: @@ -39366,15 +35812,17 @@ paths: results: '$.data' type: 'offsetLimit' post: - description: 'Register a caller-supplied tracking ID under the authenticated organization. No login account, policy, or credentials are created. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'createExternalUser' + description: 'Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. When `workspace_id` is omitted, the credential is created in the default workspace; if that default has been deleted, the request returns a 400 and you must pass `workspace_id` explicitly. Treat the raw key as write-only; it is never returned after creation. Use `allowed_api_key_hashes` to restrict the credential to specific OpenRouter API keys. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'createBYOKKey' requestBody: content: application/json: example: - user: 'employee_123' + key: 'sk-proj-abc123...' + name: 'Production OpenAI Key' + provider: 'openai' schema: - $ref: '#/components/schemas/CreateExternalUserRequest' + $ref: '#/components/schemas/CreateBYOKKeyRequest' required: true responses: '201': @@ -39382,13 +35830,25 @@ paths: application/json: example: data: - created_at: '2026-09-16T12:00:00Z' - is_active: true - updated_at: '2026-09-16T12:00:00Z' - user: 'employee_123' + allowed_api_key_hashes: null + allowed_models: null + allowed_user_ids: null + created_at: '2025-08-24T10:30:00Z' + declared_region: null + declared_zdr: null + disabled: false + id: '11111111-2222-3333-4444-555555555555' + is_byok_only: false + is_fallback: false + is_required: false + label: 'sk-...AbCd' + name: 'Production OpenAI Key' + provider: 'openai' + sort_order: 0 + workspace_id: '550e8400-e29b-41d4-a716-446655440000' schema: - $ref: '#/components/schemas/ExternalUserResponse' - description: 'The registered external user. No generated public identifier is returned.' + $ref: '#/components/schemas/CreateBYOKKeyResponse' + description: 'BYOK credential created successfully' '400': content: application/json: @@ -39409,26 +35869,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '409': + '403': content: application/json: example: error: - code: 409 - message: 'This tracking ID is already registered' + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/ConflictResponse' - description: 'The tracking ID is already registered in this organization, active or not.' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '500': content: application/json: @@ -39439,40 +35889,33 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Register an external user' + summary: 'Create a BYOK provider credential' tags: - - 'External Users' - x-speakeasy-group: 'externalUsers' + - 'BYOK' x-speakeasy-name-override: 'create' - /external-users/{user}: + /byok/{id}: delete: - description: 'Soft-deactivate a registration while retaining its tracking ID. Repeat deactivation succeeds. This does not block inference; reactivate through PATCH. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'deleteExternalUser' + description: 'Delete (soft-delete) a bring-your-own-key (BYOK) provider credential by its `id`. The encrypted key material is wiped and the record is marked as deleted. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'deleteBYOKKey' parameters: - - description: '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.' + - description: 'The BYOK credential ID (UUID).' in: 'path' - name: 'user' + name: 'id' required: true schema: - description: '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.' - example: 'employee_123' - maxLength: 512 - minLength: 1 - pattern: '^[^\u0000]+$' + description: 'The BYOK credential ID (UUID).' + example: '11111111-2222-3333-4444-555555555555' + format: 'uuid' type: 'string' responses: - '204': - description: 'Registration is inactive.' - '400': + '200': content: application/json: example: - error: - code: 400 - message: 'Invalid request parameters' + deleted: true schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' + $ref: '#/components/schemas/DeleteBYOKKeyResponse' + description: 'BYOK credential deleted successfully' '401': content: application/json: @@ -39483,6 +35926,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' + '403': + content: + application/json: + example: + error: + code: 403 + message: 'Only management keys can perform this operation' + schema: + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -39503,25 +35956,22 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Deactivate a registered external user' + summary: 'Delete a BYOK provider credential' tags: - - 'External Users' - x-speakeasy-group: 'externalUsers' + - 'BYOK' x-speakeasy-name-override: 'delete' get: - description: 'Retrieve an active or inactive registration by its URL-encoded, caller-supplied tracking ID. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'getExternalUser' + description: 'Get a single bring-your-own-key (BYOK) provider credential by its `id`. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'getBYOKKey' parameters: - - description: '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.' + - description: 'The BYOK credential ID (UUID).' in: 'path' - name: 'user' + name: 'id' required: true schema: - description: '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.' - example: 'employee_123' - maxLength: 512 - minLength: 1 - pattern: '^[^\u0000]+$' + description: 'The BYOK credential ID (UUID).' + example: '11111111-2222-3333-4444-555555555555' + format: 'uuid' type: 'string' responses: '200': @@ -39529,23 +35979,25 @@ paths: application/json: example: data: - created_at: '2026-09-16T12:00:00Z' - is_active: true - updated_at: '2026-09-16T12:00:00Z' - user: 'employee_123' - schema: - $ref: '#/components/schemas/ExternalUserResponse' - description: 'The registered external user. No generated public identifier is returned.' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' + allowed_api_key_hashes: null + allowed_models: null + allowed_user_ids: null + created_at: '2025-08-24T10:30:00Z' + declared_region: null + declared_zdr: null + disabled: false + id: '11111111-2222-3333-4444-555555555555' + is_byok_only: false + is_fallback: false + is_required: false + label: 'sk-...AbCd' + name: 'Production OpenAI Key' + provider: 'openai' + sort_order: 0 + workspace_id: '550e8400-e29b-41d4-a716-446655440000' schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' + $ref: '#/components/schemas/GetBYOKKeyResponse' + description: 'BYOK credential details' '401': content: application/json: @@ -39586,33 +36038,31 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Get a registered external user' + summary: 'Get a BYOK provider credential' tags: - - 'External Users' - x-speakeasy-group: 'externalUsers' + - 'BYOK' x-speakeasy-name-override: 'get' patch: - description: 'Update registration state without changing identity. State changes do not enforce inference access. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'updateExternalUser' + description: 'Update an existing bring-your-own-key (BYOK) provider credential by its `id`. Include the `key` field to rotate the raw provider API key in-place (the previous key material is overwritten). Use `allowed_api_key_hashes` to restrict the credential to specific OpenRouter API keys (`null` clears the restriction). [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'updateBYOKKey' parameters: - - description: '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.' + - description: 'The BYOK credential ID (UUID).' in: 'path' - name: 'user' + name: 'id' required: true schema: - description: '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.' - example: 'employee_123' - maxLength: 512 - minLength: 1 - pattern: '^[^\u0000]+$' + description: 'The BYOK credential ID (UUID).' + example: '11111111-2222-3333-4444-555555555555' + format: 'uuid' type: 'string' requestBody: content: application/json: example: - is_active: true + disabled: false + name: 'Updated OpenAI Key' schema: - $ref: '#/components/schemas/UpdateExternalUserRequest' + $ref: '#/components/schemas/UpdateBYOKKeyRequest' required: true responses: '200': @@ -39620,13 +36070,25 @@ paths: application/json: example: data: - created_at: '2026-09-16T12:00:00Z' - is_active: true - updated_at: '2026-09-16T12:00:00Z' - user: 'employee_123' + allowed_api_key_hashes: null + allowed_models: null + allowed_user_ids: null + created_at: '2025-08-24T10:30:00Z' + declared_region: null + declared_zdr: null + disabled: false + id: '11111111-2222-3333-4444-555555555555' + is_byok_only: false + is_fallback: false + is_required: false + label: 'sk-...AbCd' + name: 'Updated OpenAI Key' + provider: 'openai' + sort_order: 0 + workspace_id: '550e8400-e29b-41d4-a716-446655440000' schema: - $ref: '#/components/schemas/ExternalUserResponse' - description: 'The registered external user. No generated public identifier is returned.' + $ref: '#/components/schemas/UpdateBYOKKeyResponse' + description: 'BYOK credential updated successfully' '400': content: application/json: @@ -39647,6 +36109,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' + '403': + content: + application/json: + example: + error: + code: 403 + message: 'Only management keys can perform this operation' + schema: + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -39657,6 +36129,16 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' + '409': + content: + application/json: + example: + error: + code: 409 + message: 'Resource conflict. Please try again later.' + schema: + $ref: '#/components/schemas/ConflictResponse' + description: 'Conflict - Resource conflict or concurrent modification' '500': content: application/json: @@ -39667,105 +36149,76 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Update a registered external user' + summary: 'Update a BYOK provider credential' tags: - - 'External Users' - x-speakeasy-group: 'externalUsers' + - 'BYOK' x-speakeasy-name-override: 'update' - /files: - get: - description: 'Lists files belonging to the workspace of the authenticating API key.' - operationId: 'listFiles' + /chat/completions: + post: + description: 'Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes.' + operationId: 'sendChatCompletionRequest' parameters: - - description: 'Maximum number of files to return (1–1000).' - in: 'query' - name: 'limit' - required: false - schema: - description: 'Maximum number of files to return (1–1000).' - example: 100 - maximum: 1000 - minimum: 1 - type: 'integer' - - description: 'Opaque pagination cursor from a previous response.' - in: 'query' - name: 'cursor' - required: false - schema: - description: 'Opaque pagination cursor from a previous response.' - example: 'eyJjdXJzb3IiOiJvcl9maWxlXzAxMUNOaGE4aUNKY1Uxd1hOUjZxNFY4dyJ9' - type: 'string' - - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - in: 'query' - name: 'workspace_id' - required: false - schema: - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' - format: 'uuid' - type: 'string' - - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' - example: 'openai' - in: 'query' - name: 'provider' - required: false - schema: - $ref: '#/components/schemas/FileProvider' - - description: 'OpenAI-style forward cursor: the id to list after.' - in: 'query' - name: 'after' - required: false - schema: - description: 'OpenAI-style forward cursor: the id to list after.' - example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - type: 'string' - - description: 'Anthropic-style forward cursor: the id to list after.' - in: 'query' - name: 'after_id' - required: false - schema: - description: 'Anthropic-style forward cursor: the id to list after.' - example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - type: 'string' - - description: 'Anthropic-style reverse cursor. Not supported by OpenRouter storage.' - in: 'query' - name: 'before_id' - required: false - schema: - description: 'Anthropic-style reverse cursor. Not supported by OpenRouter storage.' - example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - type: 'string' - - description: 'Sort direction. Only `asc` is supported by OpenRouter storage.' - in: 'query' - name: 'order' + - description: '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.' + example: 'enabled' + in: 'header' + name: 'X-OpenRouter-Metadata' required: false schema: - description: 'Sort direction. Only `asc` is supported by OpenRouter storage.' - enum: - - 'asc' - - 'desc' - example: 'asc' - type: 'string' + $ref: '#/components/schemas/MetadataLevel' + requestBody: + content: + application/json: + example: + 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 + schema: + $ref: '#/components/schemas/ChatRequest' + required: true responses: '200': content: application/json: example: - cursor: null + choices: + - finish_reason: 'stop' + index: 0 + message: + content: 'The capital of France is Paris.' + role: 'assistant' + created: 1677652288 + id: 'chatcmpl-123' + model: 'openai/gpt-4' + object: 'chat.completion' + system_fingerprint: 'fp_44709d6fcb' + usage: + completion_tokens: 10 + prompt_tokens: 25 + total_tokens: 35 + schema: + $ref: '#/components/schemas/ChatResult' + text/event-stream: + example: data: - - created_at: '2025-01-01T00:00:00Z' - downloadable: false - filename: 'document.pdf' - id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - mime_type: 'application/pdf' - size_bytes: 1024000 - type: 'file' - first_id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - has_more: false - last_id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + choices: + - delta: + content: 'Hello' + role: 'assistant' + finish_reason: null + index: 0 + created: 1677652288 + id: 'chatcmpl-123' + model: 'openai/gpt-4' + object: 'chat.completion.chunk' schema: - $ref: '#/components/schemas/FileListResponse' - description: 'A page of files.' + $ref: '#/components/schemas/ChatStreamingResponse' + x-speakeasy-sse-sentinel: '[DONE]' + description: 'Successful chat completion response' '400': content: application/json: @@ -39786,148 +36239,84 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Rate limit exceeded' - schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '503': + '402': content: application/json: example: error: - code: 503 - message: 'Service temporarily unavailable' - schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - summary: 'List files' - tags: - - 'Files' - x-speakeasy-name-override: 'list' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'cursor' - type: 'cursor' - outputs: - nextCursor: '$.cursor' - results: '$.data' - type: 'cursor' - post: - description: 'Uploads a file to be referenced in future API calls. The file is stored under the workspace of the authenticating API key. Maximum file size: 100 MB; empty files are rejected. The file type is determined from the file contents — not the filename or the declared content type — and must be a PDF, a PNG/JPEG/GIF/WebP image, a DOCX/XLSX/PPTX document, an MP3/WAV/FLAC/OGG audio file, or UTF-8 text. Text is reported by its structure as `application/json`, `application/x-ndjson`, `text/csv`, `text/markdown`, or `text/plain`.' - operationId: 'uploadFile' - parameters: - - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - in: 'query' - name: 'workspace_id' - required: false - schema: - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' - format: 'uuid' - type: 'string' - - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' - example: 'openai' - in: 'query' - name: 'provider' - required: false - schema: - $ref: '#/components/schemas/FileProvider' - requestBody: - content: - multipart/form-data: - example: - file: 'document.pdf' - schema: - properties: - file: - format: 'binary' - type: 'string' - required: - - 'file' - type: 'object' - required: true - responses: - '200': - content: - application/json: - example: - created_at: '2025-01-01T00:00:00Z' - downloadable: false - filename: 'document.pdf' - id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - mime_type: 'application/pdf' - size_bytes: 1024000 - type: 'file' + code: 402 + message: 'Insufficient credits. Add more using https://openrouter.ai/credits' schema: - $ref: '#/components/schemas/FileResponse' - description: 'The uploaded file metadata.' - '400': + $ref: '#/components/schemas/PaymentRequiredResponse' + description: 'Payment Required - Insufficient credits or quota to complete request' + '403': content: application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' + examples: + guardrail-blocked: + summary: 'Guardrail blocked the request' + value: + error: + code: 403 + message: 'Request blocked: prompt injection patterns detected' + metadata: + patterns: + - 'ignore all previous instructions' + openrouter_metadata: + attempt: 1 + endpoints: + available: + - model: 'openai/gpt-4o' + provider: 'OpenAI' + selected: false + total: 1 + is_byok: false + pipeline: + - data: + action: 'blocked' + detected: true + engines: + - 'regex' + patterns: + - 'ignore all previous instructions' + guardrail_id: 'grd_abc123' + guardrail_scope: 'api-key' + name: 'regex_pi_detection' + summary: 'Blocked: prompt injection detected (1 pattern matched)' + type: 'guardrail' + region: 'iad' + requested: 'openai/gpt-4o' + strategy: 'direct' + summary: 'available=1' + insufficient-permissions: + summary: 'Insufficient permissions' + value: + error: + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' - '401': + $ref: '#/components/schemas/ForbiddenResponse' + description: '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': content: application/json: example: error: - code: 401 - message: 'Missing Authentication header' + code: 404 + message: 'Resource not found' schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '408': content: application/json: example: error: - code: 403 - message: 'Only management keys can perform this operation' + code: 408 + message: 'Operation timed out. Please try again later.' schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' + $ref: '#/components/schemas/RequestTimeoutResponse' + description: 'Request Timeout - Operation exceeded time limit' '413': content: application/json: @@ -39938,26 +36327,26 @@ paths: schema: $ref: '#/components/schemas/PayloadTooLargeResponse' description: 'Payload Too Large - Request payload exceeds size limits' - '429': + '422': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 422 + message: 'Invalid argument' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '499': + $ref: '#/components/schemas/UnprocessableEntityResponse' + description: 'Unprocessable Entity - Semantic validation failure' + '429': content: application/json: example: error: - code: 499 - message: 'The request was cancelled.' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/ClientClosedRequestResponse' - description: 'Client Closed Request - The caller cancelled the request' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: @@ -39988,80 +36377,96 @@ paths: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' description: 'Service Unavailable - Service temporarily unavailable' - summary: 'Upload a file' + '524': + content: + application/json: + example: + error: + code: 524 + message: 'Request timed out. Please try again later.' + schema: + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': + content: + application/json: + example: + error: + code: 529 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + summary: 'Create a chat completion' tags: - - 'Files' - x-speakeasy-name-override: 'upload' - /files/{file_id}: - delete: - description: 'Deletes a file owned by the requesting workspace. Deletion is irreversible.' - operationId: 'deleteFile' + - 'Chat' + x-speakeasy-group: 'chat' + x-speakeasy-name-override: 'send' + x-speakeasy-stream-request-field: 'stream' + /classifications/task: + get: + description: "Returns the market-share breakdown of OpenRouter traffic by task classification\n(e.g. code generation, web search, summarization) over a trailing time window.\n\nEach classification reports its share of classified sampled requests (`usage_share`)\nand classified sampled token volume (`token_share`) as fractions between 0 and 1.\nThe unclassified `other` bucket is excluded. Absolute volumes are not exposed\nbecause the underlying data is sampled.\n\nEach classification also includes a `models` array listing the top models by\nrequest volume within that classification, with their within-tag usage and token shares.\n\nClassifications are grouped into macro-categories (Code, Data, Agent, General)\nwith aggregate shares provided for each.\n\nAuthenticate with any valid OpenRouter API key (same key used for inference).\nRate-limited to 30 requests/minute per key and 500 requests/day per account.\n\nWhen republishing or quoting this data, cite as:\n\"Source: OpenRouter (openrouter.ai/rankings), as of {as_of}.\"" + operationId: 'getTaskClassifications' parameters: - - in: 'path' - name: 'file_id' - required: true - schema: - example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - maxLength: 256 - minLength: 1 - pattern: '^[\w-]+$' - type: 'string' - - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + - description: 'Trailing time window for the classification data. Currently only `7d` (trailing 7 days) is supported.' in: 'query' - name: 'workspace_id' + name: 'window' required: false schema: - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' - format: 'uuid' + default: '7d' + description: 'Trailing time window for the classification data. Currently only `7d` (trailing 7 days) is supported.' + enum: + - '7d' + example: '7d' type: 'string' - - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' - example: 'openai' - in: 'query' - name: 'provider' - required: false - schema: - $ref: '#/components/schemas/FileProvider' responses: '200': content: application/json: example: - id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - type: 'file_deleted' - schema: - $ref: '#/components/schemas/FileDeleteResponse' - description: 'The file was deleted.' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' + data: + as_of: '2026-06-17' + classifications: + - category_token_share: 0.48 + category_usage_share: 0.51 + display_name: 'Code Generation' + macro_category: 'code' + models: + - id: 'openai/gpt-4.1-mini' + tag_token_share: 0.75 + tag_usage_share: 0.55 + tag: 'code:general_impl' + token_share: 0.31 + usage_share: 0.23 + macro_categories: + - key: 'code' + label: 'Code' + token_share: 0.52 + usage_share: 0.45 + window_days: 7 schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': + $ref: '#/components/schemas/TaskClassificationResponse' + description: 'Task classification market-share data for the requested trailing window.' + '400': content: application/json: example: error: - code: 403 - message: 'Only management keys can perform this operation' + code: 400 + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' + '401': content: application/json: example: error: - code: 404 - message: 'Resource not found' + code: 401 + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '429': content: application/json: @@ -40082,74 +36487,71 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '503': - content: - application/json: - example: - error: - code: 503 - message: 'Service temporarily unavailable' - schema: - $ref: '#/components/schemas/ServiceUnavailableResponse' - description: 'Service Unavailable - Service temporarily unavailable' - summary: 'Delete a file' + summary: 'Task classification market share' tags: - - 'Files' - x-speakeasy-name-override: 'delete' + - 'Classifications' + /containers/{container_id}/files: get: - description: 'Retrieves metadata for a single file owned by the requesting workspace.' - operationId: 'getFileMetadata' + description: 'Lists the files in a container, in lexicographic path order. The container id is the canonical id returned in bash/shell tool results; a restarted session is a separate container with its own id. Paginate with `limit` and `after` (pass the previous page’s `last_id`); `has_more: true` always means the next page is fetchable that way. `last_id` is the resume cursor: it is the last listed file’s id, except when a page ends at the per-request scan bound on hidden bookkeeping objects, where it names the scan position instead and may not appear in `data` (which can then be empty).' + operationId: 'listContainerFiles' parameters: - - in: 'path' - name: 'file_id' + - description: '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.' + in: 'path' + name: 'container_id' required: true schema: - example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - maxLength: 256 - minLength: 1 - pattern: '^[\w-]+$' + description: '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.' + example: 'sess_abc123' type: 'string' - - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + - description: 'Maximum number of files to return (1-1000). Defaults to 100 when absent.' in: 'query' - name: 'workspace_id' + name: 'limit' required: false schema: - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' - format: 'uuid' - type: 'string' - - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' - example: 'openai' + default: 100 + description: 'Maximum number of files to return (1-1000). Defaults to 100 when absent.' + example: 100 + maximum: 1000 + minimum: 1 + type: 'integer' + - description: '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.' in: 'query' - name: 'provider' + name: 'after' required: false schema: - $ref: '#/components/schemas/FileProvider' + description: '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.' + example: 'cfile_b3V0L3JlcG9ydC5jc3Y' + type: 'string' responses: '200': content: application/json: example: - created_at: '2025-01-01T00:00:00Z' - downloadable: false - filename: 'document.pdf' - id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - mime_type: 'application/pdf' - size_bytes: 1024000 - type: 'file' + data: + - bytes: 123 + container_id: 'sess_abc123' + created_at: 1755640000 + id: 'cfile_b3V0L3JlcG9ydC5jc3Y' + object: 'container.file' + path: 'out/report.csv' + source: 'assistant' + first_id: 'cfile_b3V0L3JlcG9ydC5jc3Y' + has_more: false + last_id: 'cfile_b3V0L3JlcG9ydC5jc3Y' + object: 'list' schema: - $ref: '#/components/schemas/FileResponse' - description: 'The file metadata.' + $ref: '#/components/schemas/ContainerFileListResponse' + description: 'The files in the container.' + '400': + content: + application/json: + example: + error: + code: 400 + message: 'Invalid request parameters' + schema: + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: @@ -40170,16 +36572,6 @@ paths: schema: $ref: '#/components/schemas/ForbiddenResponse' description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' '429': content: application/json: @@ -40200,16 +36592,6 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' '503': content: application/json: @@ -40220,49 +36602,45 @@ paths: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' description: 'Service Unavailable - Service temporarily unavailable' - summary: 'Get file metadata' + summary: 'List container files' tags: - - 'Files' - x-speakeasy-name-override: 'retrieve' - /files/{file_id}/content: + - 'Containers' + /containers/{container_id}/files/{file_id}: get: - description: 'Downloads the raw bytes of a file. Only files created server-side are downloadable; uploaded files return 400.' - operationId: 'downloadFileContent' + description: 'Returns the metadata of a single file in a container.' + operationId: 'getContainerFile' parameters: - - in: 'path' - name: 'file_id' + - description: '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.' + in: 'path' + name: 'container_id' required: true schema: - example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' - maxLength: 256 - minLength: 1 - pattern: '^[\w-]+$' + description: '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.' + example: 'sess_abc123' type: 'string' - - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - in: 'query' - name: 'workspace_id' - required: false + - description: 'Container file id (`cfile_` + base64url of the file path).' + in: 'path' + name: 'file_id' + required: true schema: - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' - example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' - format: 'uuid' + description: 'Container file id (`cfile_` + base64url of the file path).' + example: 'cfile_b3V0L3JlcG9ydC5jc3Y' type: 'string' - - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' - example: 'openai' - in: 'query' - name: 'provider' - required: false - schema: - $ref: '#/components/schemas/FileProvider' responses: '200': content: - application/octet-stream: - example: 'binary file contents' + application/json: + example: + bytes: 123 + container_id: 'sess_abc123' + created_at: 1755640000 + id: 'cfile_b3V0L3JlcG9ydC5jc3Y' + object: 'container.file' + path: 'out/report.csv' + source: 'assistant' schema: - format: 'binary' - type: 'string' - description: 'The raw file content.' + $ref: '#/components/schemas/ContainerFile' + description: 'The container file.' '400': content: application/json: @@ -40323,16 +36701,6 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' '503': content: application/json: @@ -40343,76 +36711,39 @@ paths: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' description: 'Service Unavailable - Service temporarily unavailable' - summary: 'Download file content' + summary: 'Retrieve a container file' tags: - - 'Files' - x-speakeasy-name-override: 'download' - /generation: + - 'Containers' + /containers/{container_id}/files/{file_id}/content: get: - operationId: 'getGeneration' + description: 'Streams the raw bytes of a file in a container.' + operationId: 'downloadContainerFileContent' parameters: - - description: 'The generation ID' - in: 'query' - name: 'id' + - description: '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.' + in: 'path' + name: 'container_id' required: true schema: - description: 'The generation ID' - example: 'gen-1234567890' - maxLength: 128 - pattern: '^gen-[0-9A-Za-z-]+$' + description: '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.' + example: 'sess_abc123' + type: 'string' + - description: 'Container file id (`cfile_` + base64url of the file path).' + in: 'path' + name: 'file_id' + required: true + schema: + description: 'Container file id (`cfile_` + base64url of the file path).' + example: 'cfile_b3V0L3JlcG9ydC5jc3Y' type: 'string' responses: '200': content: - application/json: - example: - data: - api_type: 'completions' - app_id: 12345 - cache_discount: null - cancelled: false - created_at: '2024-07-15T23:33:19.433273+00:00' - data_region: 'global' - external_user: 'user-123' - finish_reason: 'stop' - generation_time: 1200 - http_referer: 'https://openrouter.ai/' - id: 'gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG' - is_byok: false - latency: 1250 - model: 'sao10k/l3-stheno-8b' - moderation_latency: 50 - native_finish_reason: 'stop' - native_tokens_cached: 3 - native_tokens_completion: 25 - native_tokens_completion_images: 0 - native_tokens_prompt: 10 - native_tokens_reasoning: 5 - num_fetches: 0 - num_input_audio_prompt: 0 - num_media_completion: 0 - num_media_prompt: 1 - num_search_results: 5 - origin: 'https://openrouter.ai/' - preset_id: 'a9e8d400-592a-494f-908c-375efa66cafd' - provider_name: 'Infermatic' - provider_responses: null - request_id: 'req-1727282430-aBcDeFgHiJkLmNoPqRsT' - router: 'openrouter/auto' - service_tier: 'priority' - session_id: null - streamed: true - tokens_completion: 25 - tokens_prompt: 10 - total_cost: 0.0015 - upstream_id: 'chatcmpl-791bcf62-080e-4568-87d0-94c72e3b4946' - upstream_inference_cost: 0.0012 - usage: 0.0015 - user_agent: 'Mozilla/5.0' - web_search_engine: 'exa' + application/octet-stream: + example: 'binary file contents' schema: - $ref: '#/components/schemas/GenerationResponse' - description: 'Returns the request metadata for this generation' + format: 'binary' + type: 'string' + description: 'The raw file content.' '400': content: application/json: @@ -40433,26 +36764,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '402': - content: - application/json: - example: - error: - code: 402 - message: 'Insufficient credits. Add more using https://openrouter.ai/credits' - schema: - $ref: '#/components/schemas/PaymentRequiredResponse' - description: 'Payment Required - Insufficient credits or quota to complete request' '403': content: application/json: example: error: code: 403 - message: 'Management key does not have permission for this request' + message: 'Only management keys can perform this operation' schema: $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - The management key does not have permission for this request' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -40483,70 +36804,56 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - '502': - content: - application/json: - example: - error: - code: 502 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '524': - content: - application/json: - example: - error: - code: 524 - message: 'Request timed out. Please try again later.' - schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': + '503': content: application/json: example: error: - code: 529 - message: 'Provider returned error' + code: 503 + message: 'Service temporarily unavailable' schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - summary: 'Get request & usage metadata for a generation' + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + summary: 'Download container file content' tags: - - 'Generations' - /generation/content: - get: - operationId: 'listGenerationContent' + - 'Containers' + /containers/{container_id}/files/{file_id}/promote: + post: + description: 'Copies a file from the container''s sandbox prefix into the workspace''s durable document storage, so it outlives the container. Returns the new document in the Files API shape, with a durable file id in the documents namespace. The copy counts against the workspace''s storage quota. Unlike a direct upload, promoted files are downloadable.' + operationId: 'promoteContainerFile' parameters: - - description: 'The generation ID' - in: 'query' - name: 'id' + - description: '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.' + in: 'path' + name: 'container_id' required: true schema: - description: 'The generation ID' - example: 'gen-1234567890' - maxLength: 128 - pattern: '^gen-[0-9A-Za-z-]+$' + description: '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.' + example: 'sess_abc123' + type: 'string' + - description: 'Container file id (`cfile_` + base64url of the file path).' + in: 'path' + name: 'file_id' + required: true + schema: + description: 'Container file id (`cfile_` + base64url of the file path).' + example: 'cfile_b3V0L3JlcG9ydC5jc3Y' type: 'string' responses: '200': content: application/json: example: - data: - error: null - input: - messages: - - content: 'What is the meaning of life?' - role: 'user' - output: - completion: 'The meaning of life is a philosophical question...' - reasoning: null + _shape: 'openrouter' + created_at: '2026-08-23T00:00:00Z' + downloadable: true + filename: 'out/report.csv' + id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + mime_type: 'text/csv' + size_bytes: 123 + type: 'file' schema: - $ref: '#/components/schemas/GenerationContentResponse' - description: 'Returns the stored prompt and completion content, plus the failure error when the generation failed' + $ref: '#/components/schemas/FileResponse' + description: 'The promoted file, as a workspace document.' '400': content: application/json: @@ -40587,93 +36894,101 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' - '429': + '413': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 413 + message: 'Request payload too large' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' - '500': + $ref: '#/components/schemas/PayloadTooLargeResponse' + description: 'Payload Too Large - Request payload exceeds size limits' + '429': content: application/json: example: error: - code: 500 - message: 'Internal Server Error' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - '502': + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' + '499': content: application/json: example: error: - code: 502 - message: 'Provider returned error' + code: 499 + message: 'The request was cancelled.' schema: - $ref: '#/components/schemas/BadGatewayResponse' - description: 'Bad Gateway - Provider/upstream API failure' - '524': + $ref: '#/components/schemas/ClientClosedRequestResponse' + description: 'Client Closed Request - The caller cancelled the request' + '500': content: application/json: example: error: - code: 524 - message: 'Request timed out. Please try again later.' + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + '503': content: application/json: example: error: - code: 529 - message: 'Provider returned error' + code: 503 + message: 'Service temporarily unavailable' schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - summary: 'Get stored prompt, completion, and error content for a generation' + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + summary: 'Promote a container file into workspace documents' tags: - - 'Generations' - /generation/feedback: - post: - description: 'Submit structured feedback on a generation the authenticated user made. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'submitGenerationFeedback' - requestBody: - content: - application/json: - example: - category: 'incorrect_response' - comment: 'The model repeated the same paragraph three times.' - generation_id: 'gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG' - schema: - $ref: '#/components/schemas/SubmitGenerationFeedbackRequest' - required: true + - 'Containers' + /credits: + get: + description: 'Get total credits purchased and used for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'getCredits' responses: '200': content: application/json: example: data: - success: true - schema: - $ref: '#/components/schemas/SubmitGenerationFeedbackResponse' - description: 'Feedback recorded successfully' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid request parameters' + total_credits: 100.5 + total_usage: 25.75 schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' + description: 'Total credits purchased and used' + example: + data: + total_credits: 100.5 + total_usage: 25.75 + properties: + data: + example: + total_credits: 100.5 + total_usage: 25.75 + properties: + total_credits: + description: 'Total credits purchased' + example: 100.5 + format: 'double' + type: 'number' + total_usage: + description: 'Total credits used' + example: 25.75 + format: 'double' + type: 'number' + required: + - 'total_credits' + - 'total_usage' + type: 'object' + required: + - 'data' + type: 'object' + description: 'Returns the total credits purchased and used' '401': content: application/json: @@ -40684,36 +36999,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '409': - content: - application/json: - example: - error: - code: 409 - message: 'Feedback was already submitted for this generation' - schema: - $ref: '#/components/schemas/ConflictResponse' - description: 'Conflict - Feedback was already submitted for this generation by this account. The first submission is kept.' - '429': + '403': content: application/json: example: error: - code: 429 - message: 'Rate limit exceeded' + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/TooManyRequestsResponse' - description: 'Too Many Requests - Rate limit exceeded' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '500': content: application/json: @@ -40724,74 +37019,155 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Submit feedback for a generation' + summary: 'Get remaining credits' tags: - - 'Generations' - x-speakeasy-name-override: 'submitFeedback' - /guardrails: + - 'Credits' + x-speakeasy-name-override: 'getCredits' + /credits/coinbase: + post: + deprecated: true + description: 'Deprecated. The Coinbase APIs used by this endpoint have been deprecated, so Coinbase Commerce charges have been removed. Use the web credits purchase flow instead.' + operationId: 'createCoinbaseCharge' + responses: + '200': + description: 'This endpoint is deprecated and will never return a 200 response.' + '410': + content: + application/json: + example: + error: + code: 410 + message: 'The Coinbase APIs used by this endpoint have been deprecated, so the Coinbase Commerce credits API has been removed. Use the web credits purchase flow instead.' + schema: + $ref: '#/components/schemas/GoneResponse' + description: 'Gone - Endpoint has been permanently removed or deprecated' + security: [] + summary: 'Deprecated Coinbase Commerce charge endpoint' + tags: + - 'Credits' + x-fern-ignore: true + x-speakeasy-ignore: true + x-speakeasy-name-override: 'createCoinbaseCharge' + /datasets/app-rankings: get: - description: 'List all guardrails for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'listGuardrails' + description: "Returns the top public apps on OpenRouter ranked by token usage inside the requested\ndate window, matching the public apps marketplace on openrouter.ai/apps. Token totals\nare `prompt_tokens + completion_tokens`; hidden and private apps are excluded and\ntraffic from related app aliases is merged into the canonical visible app.\n\n`sort=popular` (default) ranks by total token volume inside the window.\n`sort=trending` ranks by absolute excess token growth: window volume minus the average\nvolume of the three equal-length periods immediately preceding the window. Apps with\nno excess growth are omitted, so `trending` may return fewer than `limit` rows.\n\nFilter with `category` (marketplace category group, e.g. `coding`) or `subcategory`\n(e.g. `cli-agent`). Ranks are re-numbered 1..N after filtering. Page with `offset` —\n`rank` stays absolute, so the first row of `offset=50` is `rank: 51`.\n\nAuthenticate with any valid OpenRouter API key (same key used for inference).\nRate-limited to 30 requests/minute per key and 500 requests/day per account.\n\nWhen republishing or quoting this dataset, OpenRouter must be cited as:\n\"Source: OpenRouter (openrouter.ai/apps), as of {as_of}.\"\n\nToken counts come from each upstream provider's own tokenizer, so a token attributed\nto one app is not directly comparable to a token attributed to another app whose\ntraffic flows through a different provider.\n\nLicensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse and republish with attribution to OpenRouter." + operationId: 'getAppRankings' parameters: - - description: 'Number of records to skip for pagination' + - description: '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.' in: 'query' - name: 'offset' + name: 'category' required: false schema: - default: 0 - description: 'Number of records to skip for pagination' - example: 0 - minimum: 0 - type: - - 'integer' - - 'null' - - description: 'Maximum number of records to return (max 100)' + description: '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.' + enum: + - 'coding' + - 'creative' + - 'productivity' + - 'entertainment' + example: 'coding' + type: 'string' + - description: '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.' + in: 'query' + name: 'subcategory' + required: false + schema: + description: '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.' + enum: + - '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' + example: 'cli-agent' + type: 'string' + - description: '`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.' + in: 'query' + name: 'sort' + required: false + schema: + default: 'popular' + description: '`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.' + enum: + - 'popular' + - 'trending' + example: 'popular' + type: 'string' + - description: '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`.' + in: 'query' + name: 'start_date' + required: false + schema: + description: '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`.' + example: '2026-04-12' + pattern: '^\d{4}-\d{2}-\d{2}$' + type: 'string' + - description: '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.' + in: 'query' + name: 'end_date' + required: false + schema: + description: '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.' + example: '2026-05-11' + pattern: '^\d{4}-\d{2}-\d{2}$' + type: 'string' + - description: 'Maximum number of apps to return (1-100). Defaults to 50.' in: 'query' name: 'limit' required: false schema: default: 50 - description: 'Maximum number of records to return (max 100)' + description: 'Maximum number of apps to return (1-100). Defaults to 50.' example: 50 maximum: 100 minimum: 1 type: 'integer' - - description: 'Filter guardrails by workspace ID. By default, guardrails in the default workspace are returned.' + - description: '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`.' in: 'query' - name: 'workspace_id' + name: 'offset' required: false schema: - description: 'Filter guardrails by workspace ID. By default, guardrails in the default workspace are returned.' - example: '0df9e665-d932-5740-b2c7-b52af166bc11' - format: 'uuid' - type: 'string' + default: 0 + description: '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`.' + example: 0 + maximum: 100 + minimum: 0 + type: + - 'integer' + - 'null' responses: '200': content: application/json: example: data: - - allowed_models: null - allowed_providers: - - 'openai' - - 'anthropic' - - 'google' - created_at: '2025-08-24T10:30:00Z' - description: 'Guardrail for production environment' - enforce_zdr: false - id: '550e8400-e29b-41d4-a716-446655440000' - ignored_models: null - ignored_providers: null - include_byok_in_budgets: false - limit_usd: 100 - name: 'Production Guardrail' - reset_interval: 'monthly' - updated_at: '2025-08-24T15:45:00Z' - workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' - total_count: 1 + - app_id: 12345 + app_name: 'Cline' + rank: 1 + total_requests: 4321 + total_tokens: '12345678' + - app_id: 67890 + app_name: 'Roo Code' + rank: 2 + total_requests: 2109 + total_tokens: '9876543' + meta: + as_of: '2026-05-12T02:00:00Z' + end_date: '2026-05-11' + start_date: '2026-04-12' + version: 'v1' schema: - $ref: '#/components/schemas/ListGuardrailsResponse' - description: 'List of guardrails' + $ref: '#/components/schemas/AppRankingsResponse' + description: '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.' '400': content: application/json: @@ -40812,16 +37188,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '403': + '429': content: application/json: example: error: - code: 403 - message: 'Only management keys can perform this operation' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: @@ -40832,10 +37208,9 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'List guardrails' + summary: 'Top apps by token usage' tags: - - 'Guardrails' - x-speakeasy-name-override: 'list' + - 'Datasets' x-speakeasy-pagination: inputs: - in: 'parameters' @@ -40847,65 +37222,124 @@ paths: outputs: results: '$.data' type: 'offsetLimit' - post: - description: 'Create a new guardrail for the authenticated user. A newly created guardrail enforces nothing until it is assigned to API keys or organization members; `workspace_id` places the guardrail in a workspace but does not apply it to that workspace''s traffic. To restrict all traffic in a workspace, update the workspace''s default guardrail instead. Set `allowed_data_regions` to enforce [In-Region Routing](/docs/guides/features/in-region-routing#enforcing-in-region-routing-with-guardrails): governed requests must arrive through one of the listed OpenRouter domains and are rejected with a 403 otherwise. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'createGuardrail' - requestBody: - content: - application/json: - example: - 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' - schema: - $ref: '#/components/schemas/CreateGuardrailRequest' - required: true - responses: - '201': - content: - application/json: - example: - data: - allowed_models: null - allowed_providers: - - 'openai' - - 'anthropic' - - 'google' - created_at: '2025-08-24T10:30:00Z' - description: 'A guardrail for limiting API usage' - enforce_zdr: null - enforce_zdr_anthropic: true - enforce_zdr_google: false - enforce_zdr_openai: true - enforce_zdr_other: false - enforce_zdr_xai: false - id: '550e8400-e29b-41d4-a716-446655440000' - ignored_models: null - ignored_providers: null - include_byok_in_budgets: false - limit_usd: 50 - name: 'My New Guardrail' - reset_interval: 'monthly' - updated_at: null - workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' + /datasets/rankings-daily: + get: + description: "Returns the top 50 public models per day by total token usage on OpenRouter, plus a\nsingle aggregated `other` row per day that sums every model outside that top 50.\nToken totals are `prompt_tokens + completion_tokens`, matching the public rankings\nchart on openrouter.ai/rankings.\n\nEach row is a distinct `(date, model_permaslug)` pair. The `other` row uses the\nreserved permaslug `other` and is always returned last within its date, so callers\ncan compute `top-50 traffic / total daily traffic` without a second request.\n\nOptional filters slice the dataset. `period` (`day`/`week`/`month`) sets the time\ngrain. `modality` and `context_bucket` narrow the exact dataset by output/input\nmodality (or tool-calling activity) and request context length. `category` and\n`language_type` instead read a sampled, upsampled dataset whose `total_tokens` are\nweekly-grain estimates — they cannot be combined with each other or with the exact\nfilters, and reject `period=day` with a 400.\n\nAuthenticate with any valid OpenRouter API key (same key used for inference).\nRate-limited to 30 requests/minute per key and 500 requests/day per account.\n\nWhen republishing or quoting this dataset, OpenRouter must be cited as:\n\"Source: OpenRouter (openrouter.ai/rankings), as of {as_of}.\"\n\nToken counts come from each upstream provider's own tokenizer (Anthropic counts\nare as reported by Anthropic, OpenAI counts are as reported by OpenAI, etc.), so\na token in one row is not directly comparable to a token in another row from a\ndifferent provider.\n\nLicensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse and republish with attribution to OpenRouter." + operationId: 'getRankingsDaily' + parameters: + - description: '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`.' + in: 'query' + name: 'start_date' + required: false + schema: + description: '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`.' + example: '2026-04-12' + pattern: '^\d{4}-\d{2}-\d{2}$' + type: 'string' + - description: '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.' + in: 'query' + name: 'end_date' + required: false + schema: + description: '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.' + example: '2026-05-11' + pattern: '^\d{4}-\d{2}-\d{2}$' + type: 'string' + - description: '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.' + in: 'query' + name: 'period' + required: false + schema: + description: '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.' + enum: + - 'day' + - 'week' + - 'month' + example: 'day' + type: 'string' + - description: '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`.' + in: 'query' + name: 'modality' + required: false + schema: + description: '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`.' + enum: + - 'text' + - 'image' + - 'image_output' + - 'audio' + - 'tool_calling' + example: 'text' + type: 'string' + - description: '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`.' + in: 'query' + name: 'context_bucket' + required: false + schema: + description: '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`.' + enum: + - '1K' + - '10K' + - '100K' + - '1M' + - '10M' + example: '100K' + type: 'string' + - description: '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`.' + in: 'query' + name: 'category' + required: false + schema: + description: '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`.' + enum: + - 'programming' + - 'roleplay' + - 'marketing' + - 'marketing/seo' + - 'technology' + - 'science' + - 'translation' + - 'legal' + - 'finance' + - 'health' + - 'trivia' + - 'academia' + example: 'programming' + type: 'string' + - description: '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`.' + in: 'query' + name: 'language_type' + required: false + schema: + description: '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`.' + enum: + - 'natural' + - 'programming' + example: 'natural' + type: 'string' + responses: + '200': + content: + application/json: + example: + data: + - date: '2026-05-11' + model_permaslug: 'openai/gpt-4o-2024-05-13' + total_tokens: '12345678' + - date: '2026-05-11' + model_permaslug: 'anthropic/claude-3.5-sonnet-20241022' + total_tokens: '9876543' + - date: '2026-05-11' + model_permaslug: 'other' + total_tokens: '4321098' + meta: + as_of: '2026-05-12T02:00:00Z' + end_date: '2026-05-11' + start_date: '2026-04-12' + version: 'v1' schema: - $ref: '#/components/schemas/CreateGuardrailResponse' - description: 'Guardrail created successfully' + $ref: '#/components/schemas/RankingsDailyResponse' + description: '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.' '400': content: application/json: @@ -40926,16 +37360,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '403': + '429': content: application/json: example: error: - code: 403 - message: 'Only management keys can perform this operation' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: '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.' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: @@ -40946,116 +37380,96 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Create a guardrail' + summary: 'Daily token totals for top 50 models' tags: - - 'Guardrails' - x-speakeasy-name-override: 'create' - /guardrails/{id}: - delete: - description: 'Delete an existing guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'deleteGuardrail' + - 'Datasets' + /datasets/session-cost: + get: + description: "Returns weekly refreshed, aggregated cost-per-session cells for the published harnesses.\nSessions are never pooled across apps. Medians are of per-session USD spend, and\nprivacy-preserving aggregation never exposes clerk_user_id values or per-session rows.\n\nFilter by `app_slug`, `model`, or `turn_range`. Filtering by `model` alone works across apps\nfor harness-vs-harness comparison at a fixed model. Results refresh weekly and include the source snapshot\nwindow in `meta`.\n\nLicensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse and republish with attribution to OpenRouter." + operationId: 'getSessionCost' parameters: - - description: 'The unique identifier of the guardrail to delete' - in: 'path' - name: 'id' - required: true + - description: 'Filter to one published harness slug.' + in: 'query' + name: 'app_slug' + required: false schema: - description: 'The unique identifier of the guardrail to delete' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' + description: 'Filter to one published harness slug.' + example: 'hermes-agent' + type: 'string' + - description: 'Exact model permaslug filter. Works across all harness apps.' + in: 'query' + name: 'model' + required: false + schema: + description: 'Exact model permaslug filter. Works across all harness apps.' + example: 'anthropic/claude-4.8-opus' + type: 'string' + - description: 'Filter by the inclusive number of turns in a session.' + in: 'query' + name: 'turn_range' + required: false + schema: + description: 'Filter by the inclusive number of turns in a session.' + enum: + - '1-turn' + - '2-9-turns' + - '10-49-turns' + - '50-plus-turns' + example: '10-49-turns' type: 'string' + - description: 'Maximum number of cells to return (1-500). Defaults to 100.' + in: 'query' + name: 'limit' + required: false + schema: + default: 100 + description: 'Maximum number of cells to return (1-500). Defaults to 100.' + example: 100 + maximum: 500 + minimum: 1 + type: 'integer' + - description: 'Number of sorted cells to skip (0-5000). Defaults to 0.' + in: 'query' + name: 'offset' + required: false + schema: + default: 0 + description: 'Number of sorted cells to skip (0-5000). Defaults to 0.' + example: 0 + maximum: 5000 + minimum: 0 + type: + - 'integer' + - 'null' responses: '200': content: application/json: example: - deleted: true - schema: - $ref: '#/components/schemas/DeleteGuardrailResponse' - description: 'Guardrail deleted successfully' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' + data: + - app_name: 'Hermes Agent' + app_slug: 'hermes-agent' + median_session_cost_usd: 1.74 + model_permaslug: 'anthropic/claude-4.8-opus' + turn_range: '10-49-turns' + meta: + as_of: '2026-05-12T02:00:00.000Z' + version: 'v1' + window_days: 30 + window_end_date: '2026-05-11' schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '500': + $ref: '#/components/schemas/SessionCostResponse' + description: 'Aggregated cost-per-session cells for the requested filters.' + '400': content: application/json: example: error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'Delete a guardrail' - tags: - - 'Guardrails' - x-speakeasy-name-override: 'delete' - get: - description: 'Get a single guardrail by ID. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'getGuardrail' - parameters: - - description: 'The unique identifier of the guardrail to retrieve' - in: 'path' - name: 'id' - required: true - schema: - description: 'The unique identifier of the guardrail to retrieve' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' - responses: - '200': - content: - application/json: - example: - data: - allowed_models: null - allowed_providers: - - 'openai' - - 'anthropic' - - 'google' - created_at: '2025-08-24T10:30:00Z' - description: 'Guardrail for production environment' - enforce_zdr: false - id: '550e8400-e29b-41d4-a716-446655440000' - ignored_models: null - ignored_providers: null - include_byok_in_budgets: false - limit_usd: 100 - name: 'Production Guardrail' - reset_interval: 'monthly' - updated_at: '2025-08-24T15:45:00Z' - workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' + code: 400 + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/GetGuardrailResponse' - description: 'Guardrail details' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: @@ -41066,26 +37480,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': + '429': content: application/json: example: error: - code: 404 - message: 'Resource not found' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Guardrail not found, or the workspace default guardrail has not been configured yet.' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: @@ -41096,63 +37500,270 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Get a guardrail' + summary: 'Cost per session by harness and model' tags: - - 'Guardrails' - x-speakeasy-name-override: 'get' - patch: - description: 'Update an existing guardrail, or materialize an unconfigured workspace default guardrail. Collection fields use replace semantics: send the full desired set on every update. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'updateGuardrail' - parameters: - - description: 'The unique identifier of the guardrail to update' - in: 'path' - name: 'id' - required: true - schema: - description: 'The unique identifier of the guardrail to update' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' + - 'Datasets' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'offset' + type: 'offset' + - in: 'parameters' + name: 'limit' + type: 'limit' + outputs: + results: '$.data' + type: 'offsetLimit' + /embeddings: + post: + description: 'Submits an embedding request to the embeddings router' + operationId: 'createEmbeddings' requestBody: content: application/json: - example: - description: 'Updated description' - limit_usd: 75 - name: 'Updated Guardrail Name' - reset_interval: 'weekly' schema: - $ref: '#/components/schemas/UpdateGuardrailRequest' + description: 'Embeddings request input' + example: + dimensions: 1536 + input: 'The quick brown fox jumps over the lazy dog' + model: 'openai/text-embedding-3-small' + properties: + dimensions: + description: 'The number of dimensions for the output embeddings' + example: 1536 + minimum: 1 + type: 'integer' + encoding_format: + description: 'The format of the output embeddings' + enum: + - 'float' + - 'base64' + example: 'float' + type: 'string' + input: + anyOf: + - minLength: 1 + type: 'string' + - items: + minLength: 1 + type: 'string' + type: 'array' + - items: + type: 'number' + type: 'array' + - items: + items: + type: 'number' + type: 'array' + type: 'array' + - items: + properties: + content: + items: + oneOf: + - properties: + text: + minLength: 1 + type: 'string' + type: + enum: + - 'text' + type: 'string' + required: + - 'type' + - 'text' + type: 'object' + - properties: + image_url: + properties: + url: + type: 'string' + required: + - 'url' + type: 'object' + type: + enum: + - 'image_url' + type: 'string' + required: + - 'type' + - 'image_url' + type: 'object' + - $ref: '#/components/schemas/ContentPartInputAudio' + - $ref: '#/components/schemas/ContentPartInputVideo' + - $ref: '#/components/schemas/ContentPartInputFile' + minItems: 1 + type: 'array' + required: + - 'content' + type: 'object' + type: 'array' + description: 'Text, token, or multimodal input(s) to embed' + example: 'The quick brown fox jumps over the lazy dog' + input_type: + description: 'The type of input (e.g. search_query, search_document)' + example: 'search_query' + type: 'string' + model: + description: 'The model to use for embeddings' + example: 'openai/text-embedding-3-small' + type: 'string' + provider: + allOf: + - $ref: '#/components/schemas/ProviderPreferences' + - description: 'Provider routing preferences for the request.' + session_id: + description: '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.' + example: 'session-1234' + maxLength: 256 + type: 'string' + trace: + $ref: '#/components/schemas/TraceConfig' + user: + description: 'A unique identifier for the end-user' + example: 'user-1234' + type: 'string' + required: + - 'input' + - 'model' + type: 'object' required: true responses: '200': content: application/json: - example: - data: - allowed_models: null - allowed_providers: - - 'openai' - created_at: '2025-08-24T10:30:00Z' - description: 'Updated description' - enforce_zdr: null - enforce_zdr_anthropic: true - enforce_zdr_google: true - enforce_zdr_openai: true - enforce_zdr_other: true - enforce_zdr_xai: true - id: '550e8400-e29b-41d4-a716-446655440000' - ignored_models: null - ignored_providers: null - include_byok_in_budgets: true - limit_usd: 75 - name: 'Updated Guardrail Name' - reset_interval: 'weekly' - updated_at: '2025-08-24T16:00:00Z' - workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' schema: - $ref: '#/components/schemas/UpdateGuardrailResponse' - description: 'Guardrail updated successfully' + description: 'Embeddings response containing embedding vectors' + example: + data: + - embedding: + - 0.0023064255 + - -0.009327292 + - 0.015797347 + index: 0 + object: 'embedding' + model: 'openai/text-embedding-3-small' + object: 'list' + usage: + prompt_tokens: 8 + total_tokens: 8 + properties: + data: + description: 'List of embedding objects' + example: + - embedding: + - 0.0023064255 + - -0.009327292 + - 0.015797347 + index: 0 + object: 'embedding' + items: + description: 'A single embedding object' + example: + embedding: + - 0.0023064255 + - -0.009327292 + - 0.015797347 + index: 0 + object: 'embedding' + properties: + embedding: + anyOf: + - items: + type: 'number' + type: 'array' + - type: 'string' + description: 'Embedding vector as an array of floats or a base64 string' + example: + - 0.0023064255 + - -0.009327292 + - 0.015797347 + index: + description: 'Index of the embedding in the input list' + example: 0 + type: 'integer' + object: + enum: + - 'embedding' + type: 'string' + required: + - 'object' + - 'embedding' + type: 'object' + type: 'array' + id: + description: 'Unique identifier for the embeddings response' + example: 'embd-1234567890' + type: 'string' + model: + description: 'The model used for embeddings' + example: 'openai/text-embedding-3-small' + type: 'string' + object: + enum: + - 'list' + type: 'string' + usage: + description: 'Token usage statistics' + example: + prompt_tokens: 8 + total_tokens: 8 + properties: + cost: + description: 'Cost of the request in credits' + example: 0.0001 + format: 'double' + type: 'number' + cost_details: + $ref: '#/components/schemas/CostDetails' + is_byok: + description: 'Whether a request was made using a Bring Your Own Key configuration' + type: 'boolean' + prompt_tokens: + description: 'Number of tokens in the input' + example: 8 + type: 'integer' + prompt_tokens_details: + description: 'Per-modality token breakdown. Only present when the input contains 2+ modalities (e.g. text + image) and the upstream provider returns modality-level usage data. Only non-zero modality counts are included.' + properties: + audio_tokens: + description: 'Number of audio tokens in the input' + type: 'integer' + file_tokens: + description: 'Number of file/document tokens in the input' + type: 'integer' + image_tokens: + description: 'Number of image tokens in the input' + example: 258 + type: 'integer' + text_tokens: + description: 'Number of text tokens in the input' + example: 8 + type: 'integer' + video_tokens: + description: 'Number of video tokens in the input' + type: 'integer' + type: 'object' + total_tokens: + description: 'Total number of tokens used' + example: 8 + type: 'integer' + required: + - 'prompt_tokens' + - 'total_tokens' + type: 'object' + required: + - 'object' + - 'data' + - 'model' + type: 'object' + text/event-stream: + example: 'data: [DONE]' + schema: + description: 'Not used for embeddings - embeddings do not support streaming' + type: 'string' + x-speakeasy-sse-sentinel: '[DONE]' + description: 'Embedding response' '400': content: application/json: @@ -41162,7 +37773,7 @@ paths: message: 'Invalid request parameters' schema: $ref: '#/components/schemas/BadRequestResponse' - description: '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).' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: @@ -41173,6 +37784,16 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' + '402': + content: + application/json: + example: + error: + code: 402 + message: 'Insufficient credits. Add more using https://openrouter.ai/credits' + schema: + $ref: '#/components/schemas/PaymentRequiredResponse' + description: 'Payment Required - Insufficient credits or quota to complete request' '403': content: application/json: @@ -41182,7 +37803,7 @@ paths: message: 'Only management keys can perform this operation' schema: $ref: '#/components/schemas/ForbiddenResponse' - description: '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.' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -41193,16 +37814,46 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' - '409': + '408': content: application/json: example: error: - code: 409 - message: 'Resource conflict. Please try again later.' + code: 408 + message: 'Operation timed out. Please try again later.' schema: - $ref: '#/components/schemas/ConflictResponse' - description: 'Guardrail name conflict — another guardrail in this workspace already uses the requested name.' + $ref: '#/components/schemas/RequestTimeoutResponse' + description: 'Request Timeout - Operation exceeded time limit' + '413': + content: + application/json: + example: + error: + code: 413 + message: 'Request payload too large' + schema: + $ref: '#/components/schemas/PayloadTooLargeResponse' + description: 'Payload Too Large - Request payload exceeds size limits' + '429': + content: + application/json: + example: + error: + code: 429 + message: 'Rate limit exceeded' + schema: + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' + '499': + content: + application/json: + example: + error: + code: 499 + message: 'The request was cancelled.' + schema: + $ref: '#/components/schemas/ClientClosedRequestResponse' + description: 'Client Closed Request - The caller cancelled the request' '500': content: application/json: @@ -41213,45 +37864,86 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Update a guardrail' + '502': + content: + application/json: + example: + error: + code: 502 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '503': + content: + application/json: + example: + error: + code: 503 + message: 'Service temporarily unavailable' + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + '504': + content: + application/json: + example: + error: + code: 504 + message: 'The operation was aborted due to timeout' + schema: + $ref: '#/components/schemas/GatewayTimeoutResponse' + description: 'Gateway Timeout - Provider did not respond before the upstream deadline' + '524': + content: + application/json: + example: + error: + code: 524 + message: 'Request timed out. Please try again later.' + schema: + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': + content: + application/json: + example: + error: + code: 529 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + summary: 'Submit an embedding request' tags: - - 'Guardrails' - x-speakeasy-name-override: 'update' - /guardrails/{id}/assignments/keys: + - 'Embeddings' + x-speakeasy-name-override: 'generate' + /embeddings/models: get: - description: 'List all API key assignments for a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'listGuardrailKeyAssignments' + description: 'Returns a list of all available embeddings models and their properties' + operationId: 'listEmbeddingsModels' parameters: - - description: 'The unique identifier of the guardrail' - in: 'path' - name: 'id' - required: true - schema: - description: 'The unique identifier of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' - - description: 'Number of records to skip for pagination' + - description: 'Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned' in: 'query' name: 'offset' required: false schema: default: 0 - description: 'Number of records to skip for pagination' + description: 'Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned' example: 0 minimum: 0 type: - 'integer' - 'null' - - description: 'Maximum number of records to return (max 100)' + - description: 'Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned' in: 'query' name: 'limit' required: false schema: - default: 50 - description: 'Maximum number of records to return (max 100)' - example: 50 - maximum: 100 + default: 500 + description: 'Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned' + example: 500 + maximum: 1000 minimum: 1 type: 'integer' responses: @@ -41260,47 +37952,50 @@ paths: application/json: example: data: - - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' - key_label: 'prod-key' - key_name: 'Production Key' - total_count: 1 - schema: - $ref: '#/components/schemas/ListKeyAssignmentsResponse' - description: 'List of key assignments' - '401': - content: - application/json: - example: - error: - code: 401 - message: 'Missing Authentication header' - schema: - $ref: '#/components/schemas/UnauthorizedResponse' - description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' + - architecture: + input_modalities: + - 'text' + instruct_type: null + modality: 'text->embeddings' + output_modalities: + - 'embeddings' + tokenizer: 'GPT' + canonical_slug: 'openai/text-embedding-3-small' + context_length: 8192 + created: 1692901234 + default_parameters: null + description: 'OpenAI text embedding model optimized for performance.' + expiration_date: null + id: 'openai/text-embedding-3-small' + knowledge_cutoff: null + links: + details: '/api/v1/models/openai/text-embedding-3-small/endpoints' + name: 'Text Embedding 3 Small' + per_request_limits: null + pricing: + completion: '0' + image: '0' + prompt: '0.00000002' + request: '0' + supported_parameters: [] + supported_voices: null + top_provider: + context_length: 8192 + is_moderated: false + max_completion_tokens: null schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' - '404': + $ref: '#/components/schemas/ModelsListResponse' + description: 'Returns a list of embeddings models' + '400': content: application/json: example: error: - code: 404 - message: 'Resource not found' + code: 400 + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '500': content: application/json: @@ -41311,10 +38006,10 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'List key assignments for a guardrail' + summary: 'List all embeddings models' tags: - - 'Guardrails' - x-speakeasy-name-override: 'listGuardrailKeyAssignments' + - 'Embeddings' + x-speakeasy-name-override: 'listModels' x-speakeasy-pagination: inputs: - in: 'parameters' @@ -41326,37 +38021,189 @@ paths: outputs: results: '$.data' type: 'offsetLimit' - post: - description: 'Assign multiple API keys to a specific guardrail. A key may hold at most one guardrail; assigning replaces any existing assignment. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'bulkAssignKeysToGuardrail' + /endpoints/zdr: + get: + operationId: 'listEndpointsZdr' + responses: + '200': + content: + application/json: + example: + data: + - context_length: 8192 + latency_last_30m: + p50: 0.25 + p75: 0.35 + p90: 0.48 + p99: 0.85 + max_completion_tokens: 4096 + max_prompt_tokens: 8192 + model_id: 'openai/gpt-4' + model_name: 'GPT-4' + name: 'OpenAI: GPT-4' + native_tools: {} + pricing: + completion: '0.00006' + image: '0' + prompt: '0.00003' + request: '0' + provider_name: 'OpenAI' + quantization: 'fp16' + status: 0 + supported_parameters: + - 'temperature' + - 'top_p' + - 'max_tokens' + supports_diarization: false + supports_image_reference: false + supports_implicit_caching: true + supports_multiple_audio_references: false + supports_voice_cloning: false + tag: 'openai' + throughput_last_30m: + p50: 45.2 + p75: 38.5 + p90: 28.3 + p99: 15.1 + uptime_last_1d: 99.8 + uptime_last_30m: 99.5 + uptime_last_5m: 100 + schema: + example: + data: + - context_length: 8192 + latency_last_30m: + p50: 0.25 + p75: 0.35 + p90: 0.48 + p99: 0.85 + max_completion_tokens: 4096 + max_prompt_tokens: 8192 + model_id: 'openai/gpt-4' + model_name: 'GPT-4' + name: 'OpenAI: GPT-4' + native_tools: {} + pricing: + completion: '0.00006' + image: '0' + prompt: '0.00003' + request: '0' + provider_name: 'OpenAI' + quantization: 'fp16' + status: 0 + supported_parameters: + - 'temperature' + - 'top_p' + - 'max_tokens' + supports_diarization: false + supports_image_reference: false + supports_implicit_caching: true + supports_multiple_audio_references: false + supports_voice_cloning: false + tag: 'openai' + throughput_last_30m: + p50: 45.2 + p75: 38.5 + p90: 28.3 + p99: 15.1 + uptime_last_1d: 99.8 + uptime_last_30m: 99.5 + uptime_last_5m: 100 + properties: + data: + items: + $ref: '#/components/schemas/PublicEndpoint' + type: 'array' + required: + - 'data' + type: 'object' + description: 'Returns a list of endpoints' + '403': + content: + application/json: + example: + error: + code: 403 + message: 'Only management keys can perform this operation' + schema: + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '500': + content: + application/json: + example: + error: + code: 500 + message: 'Internal Server Error' + schema: + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Preview the impact of ZDR on the available endpoints' + tags: + - 'Endpoints' + x-speakeasy-name-override: 'listZdrEndpoints' + /external-users: + get: + description: 'List registrations belonging to the authenticated organization. Inactive registrations are excluded by default. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'listExternalUsers' parameters: - - description: 'The unique identifier of the guardrail' - in: 'path' - name: 'id' - required: true + - description: 'Number of records to skip for pagination' + in: 'query' + name: 'offset' + required: false schema: - description: 'The unique identifier of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' + default: 0 + description: 'Number of records to skip for pagination' + example: 0 + minimum: 0 + type: + - 'integer' + - 'null' + - description: 'Maximum number of records to return (max 100)' + in: 'query' + name: 'limit' + required: false + schema: + default: 50 + description: 'Maximum number of records to return (max 100)' + example: 50 + maximum: 100 + minimum: 1 + type: 'integer' + - description: '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.' + in: 'query' + name: 'user' + required: false + schema: + description: '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.' + example: 'employee_123' + maxLength: 512 + minLength: 1 + pattern: '^[^\u0000]+$' type: 'string' - requestBody: - content: - application/json: - example: - key_hashes: - - 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' - schema: - $ref: '#/components/schemas/BulkAssignKeysRequest' - required: true + - description: 'Include deactivated registrations.' + in: 'query' + name: 'include_inactive' + required: false + schema: + default: false + description: 'Include deactivated registrations.' + example: false + type: 'boolean' responses: '200': content: application/json: example: - assigned_count: 3 + data: + - created_at: '2026-09-16T12:00:00Z' + is_active: true + updated_at: '2026-09-16T12:00:00Z' + user: 'employee_123' + total_count: 1 schema: - $ref: '#/components/schemas/BulkAssignKeysResponse' - description: 'Assignment result' + $ref: '#/components/schemas/ListExternalUsersResponse' + description: 'Matching registrations and their total count.' '400': content: application/json: @@ -41386,7 +38233,7 @@ paths: message: 'Only management keys can perform this operation' schema: $ref: '#/components/schemas/ForbiddenResponse' - description: '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.' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -41407,42 +38254,46 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Bulk assign keys to a guardrail' + summary: 'List registered external users' tags: - - 'Guardrails' - x-speakeasy-name-override: 'bulkAssignKeys' - /guardrails/{id}/assignments/keys/remove: + - 'External Users' + x-speakeasy-group: 'externalUsers' + x-speakeasy-name-override: 'list' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'offset' + type: 'offset' + - in: 'parameters' + name: 'limit' + type: 'limit' + outputs: + results: '$.data' + type: 'offsetLimit' post: - description: 'Unassign multiple API keys from a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'bulkUnassignKeysFromGuardrail' - parameters: - - description: 'The unique identifier of the guardrail' - in: 'path' - name: 'id' - required: true - schema: - description: 'The unique identifier of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' - type: 'string' + description: 'Register a caller-supplied tracking ID under the authenticated organization. No login account, policy, or credentials are created. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'createExternalUser' requestBody: content: application/json: example: - key_hashes: - - 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' + user: 'employee_123' schema: - $ref: '#/components/schemas/BulkUnassignKeysRequest' + $ref: '#/components/schemas/CreateExternalUserRequest' required: true responses: - '200': + '201': content: application/json: example: - unassigned_count: 3 + data: + created_at: '2026-09-16T12:00:00Z' + is_active: true + updated_at: '2026-09-16T12:00:00Z' + user: 'employee_123' schema: - $ref: '#/components/schemas/BulkUnassignKeysResponse' - description: 'Unassignment result' + $ref: '#/components/schemas/ExternalUserResponse' + description: 'The registered external user. No generated public identifier is returned.' '400': content: application/json: @@ -41463,16 +38314,6 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -41483,6 +38324,16 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' + '409': + content: + application/json: + example: + error: + code: 409 + message: 'This tracking ID is already registered' + schema: + $ref: '#/components/schemas/ConflictResponse' + description: 'The tracking ID is already registered in this organization, active or not.' '500': content: application/json: @@ -41493,63 +38344,40 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Bulk unassign keys from a guardrail' + summary: 'Register an external user' tags: - - 'Guardrails' - x-speakeasy-name-override: 'bulkUnassignKeys' - /guardrails/{id}/assignments/members: - get: - description: 'List all organization member assignments for a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'listGuardrailMemberAssignments' + - 'External Users' + x-speakeasy-group: 'externalUsers' + x-speakeasy-name-override: 'create' + /external-users/{user}: + delete: + description: 'Soft-deactivate a registration while retaining its tracking ID. Repeat deactivation succeeds. This does not block inference; reactivate through PATCH. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'deleteExternalUser' parameters: - - description: 'The unique identifier of the guardrail' + - description: '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.' in: 'path' - name: 'id' + name: 'user' required: true schema: - description: 'The unique identifier of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' + description: '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.' + example: 'employee_123' + maxLength: 512 + minLength: 1 + pattern: '^[^\u0000]+$' type: 'string' - - description: 'Number of records to skip for pagination' - in: 'query' - name: 'offset' - required: false - schema: - default: 0 - description: 'Number of records to skip for pagination' - example: 0 - minimum: 0 - type: - - 'integer' - - 'null' - - description: 'Maximum number of records to return (max 100)' - in: 'query' - name: 'limit' - required: false - schema: - default: 50 - description: 'Maximum number of records to return (max 100)' - example: 50 - maximum: 100 - minimum: 1 - type: 'integer' responses: - '200': + '204': + description: 'Registration is inactive.' + '400': content: application/json: example: - data: - - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - organization_id: 'org_xyz789' - user_id: 'user_abc123' - total_count: 1 + error: + code: 400 + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/ListMemberAssignmentsResponse' - description: 'List of member assignments' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: @@ -41560,16 +38388,6 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -41590,53 +38408,39 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'List member assignments for a guardrail' + summary: 'Deactivate a registered external user' tags: - - 'Guardrails' - x-speakeasy-name-override: 'listGuardrailMemberAssignments' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'offset' - type: 'offset' - - in: 'parameters' - name: 'limit' - type: 'limit' - outputs: - results: '$.data' - type: 'offsetLimit' - post: - description: 'Assign multiple organization members to a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'bulkAssignMembersToGuardrail' + - 'External Users' + x-speakeasy-group: 'externalUsers' + x-speakeasy-name-override: 'delete' + get: + description: 'Retrieve an active or inactive registration by its URL-encoded, caller-supplied tracking ID. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'getExternalUser' parameters: - - description: 'The unique identifier of the guardrail' + - description: '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.' in: 'path' - name: 'id' + name: 'user' required: true schema: - description: 'The unique identifier of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' + description: '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.' + example: 'employee_123' + maxLength: 512 + minLength: 1 + pattern: '^[^\u0000]+$' type: 'string' - requestBody: - content: - application/json: - example: - member_user_ids: - - 'user_abc123' - - 'user_def456' - schema: - $ref: '#/components/schemas/BulkAssignMembersRequest' - required: true responses: '200': content: application/json: example: - assigned_count: 2 + data: + created_at: '2026-09-16T12:00:00Z' + is_active: true + updated_at: '2026-09-16T12:00:00Z' + user: 'employee_123' schema: - $ref: '#/components/schemas/BulkAssignMembersResponse' - description: 'Assignment result' + $ref: '#/components/schemas/ExternalUserResponse' + description: 'The registered external user. No generated public identifier is returned.' '400': content: application/json: @@ -41687,43 +38491,47 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Bulk assign members to a guardrail' + summary: 'Get a registered external user' tags: - - 'Guardrails' - x-speakeasy-name-override: 'bulkAssignMembers' - /guardrails/{id}/assignments/members/remove: - post: - description: 'Unassign multiple organization members from a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'bulkUnassignMembersFromGuardrail' + - 'External Users' + x-speakeasy-group: 'externalUsers' + x-speakeasy-name-override: 'get' + patch: + description: 'Update registration state without changing identity. State changes do not enforce inference access. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'updateExternalUser' parameters: - - description: 'The unique identifier of the guardrail' + - description: '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.' in: 'path' - name: 'id' + name: 'user' required: true schema: - description: 'The unique identifier of the guardrail' - example: '550e8400-e29b-41d4-a716-446655440000' - format: 'uuid' + description: '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.' + example: 'employee_123' + maxLength: 512 + minLength: 1 + pattern: '^[^\u0000]+$' type: 'string' requestBody: content: application/json: example: - member_user_ids: - - 'user_abc123' - - 'user_def456' + is_active: true schema: - $ref: '#/components/schemas/BulkUnassignMembersRequest' + $ref: '#/components/schemas/UpdateExternalUserRequest' required: true responses: '200': content: application/json: example: - unassigned_count: 2 + data: + created_at: '2026-09-16T12:00:00Z' + is_active: true + updated_at: '2026-09-16T12:00:00Z' + user: 'employee_123' schema: - $ref: '#/components/schemas/BulkUnassignMembersResponse' - description: 'Unassignment result' + $ref: '#/components/schemas/ExternalUserResponse' + description: 'The registered external user. No generated public identifier is returned.' '400': content: application/json: @@ -41744,16 +38552,6 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Only management keys can perform this operation' - schema: - $ref: '#/components/schemas/ForbiddenResponse' - description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: @@ -41774,55 +38572,105 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'Bulk unassign members from a guardrail' + summary: 'Update a registered external user' tags: - - 'Guardrails' - x-speakeasy-name-override: 'bulkUnassignMembers' - /guardrails/assignments/keys: + - 'External Users' + x-speakeasy-group: 'externalUsers' + x-speakeasy-name-override: 'update' + /files: get: - description: 'List all API key guardrail assignments for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'listKeyAssignments' + description: 'Lists files belonging to the workspace of the authenticating API key.' + operationId: 'listFiles' parameters: - - description: 'Number of records to skip for pagination' - in: 'query' - name: 'offset' - required: false - schema: - default: 0 - description: 'Number of records to skip for pagination' - example: 0 - minimum: 0 - type: - - 'integer' - - 'null' - - description: 'Maximum number of records to return (max 100)' + - description: 'Maximum number of files to return (1–1000).' in: 'query' name: 'limit' required: false schema: - default: 50 - description: 'Maximum number of records to return (max 100)' - example: 50 - maximum: 100 + description: 'Maximum number of files to return (1–1000).' + example: 100 + maximum: 1000 minimum: 1 type: 'integer' + - description: 'Opaque pagination cursor from a previous response.' + in: 'query' + name: 'cursor' + required: false + schema: + description: 'Opaque pagination cursor from a previous response.' + example: 'eyJjdXJzb3IiOiJvcl9maWxlXzAxMUNOaGE4aUNKY1Uxd1hOUjZxNFY4dyJ9' + type: 'string' + - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + in: 'query' + name: 'workspace_id' + required: false + schema: + description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' + format: 'uuid' + type: 'string' + - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' + example: 'openai' + in: 'query' + name: 'provider' + required: false + schema: + $ref: '#/components/schemas/FileProvider' + - description: 'OpenAI-style forward cursor: the id to list after.' + in: 'query' + name: 'after' + required: false + schema: + description: 'OpenAI-style forward cursor: the id to list after.' + example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + type: 'string' + - description: 'Anthropic-style forward cursor: the id to list after.' + in: 'query' + name: 'after_id' + required: false + schema: + description: 'Anthropic-style forward cursor: the id to list after.' + example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + type: 'string' + - description: 'Anthropic-style reverse cursor. Not supported by OpenRouter storage.' + in: 'query' + name: 'before_id' + required: false + schema: + description: 'Anthropic-style reverse cursor. Not supported by OpenRouter storage.' + example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + type: 'string' + - description: 'Sort direction. Only `asc` is supported by OpenRouter storage.' + in: 'query' + name: 'order' + required: false + schema: + description: 'Sort direction. Only `asc` is supported by OpenRouter storage.' + enum: + - 'asc' + - 'desc' + example: 'asc' + type: 'string' responses: '200': content: application/json: example: + cursor: null data: - - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' - key_label: 'prod-key' - key_name: 'Production Key' - total_count: 1 + - created_at: '2025-01-01T00:00:00Z' + downloadable: false + filename: 'document.pdf' + id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + mime_type: 'application/pdf' + size_bytes: 1024000 + type: 'file' + first_id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + has_more: false + last_id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' schema: - $ref: '#/components/schemas/ListKeyAssignmentsResponse' - description: 'List of key assignments' + $ref: '#/components/schemas/FileListResponse' + description: 'A page of files.' '400': content: application/json: @@ -41853,16 +38701,16 @@ paths: schema: $ref: '#/components/schemas/ForbiddenResponse' description: 'Forbidden - Authentication successful but insufficient permissions' - '404': + '429': content: application/json: example: error: - code: 404 - message: 'Resource not found' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: @@ -41873,65 +38721,88 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'List all key assignments' + '502': + content: + application/json: + example: + error: + code: 502 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '503': + content: + application/json: + example: + error: + code: 503 + message: 'Service temporarily unavailable' + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + summary: 'List files' tags: - - 'Guardrails' - x-speakeasy-name-override: 'listKeyAssignments' + - 'Files' + x-speakeasy-name-override: 'list' x-speakeasy-pagination: inputs: - in: 'parameters' - name: 'offset' - type: 'offset' - - in: 'parameters' - name: 'limit' - type: 'limit' + name: 'cursor' + type: 'cursor' outputs: + nextCursor: '$.cursor' results: '$.data' - type: 'offsetLimit' - /guardrails/assignments/members: - get: - description: 'List all organization member guardrail assignments for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' - operationId: 'listMemberAssignments' + type: 'cursor' + post: + description: 'Uploads a file to be referenced in future API calls. The file is stored under the workspace of the authenticating API key. Maximum file size: 100 MB; empty files are rejected. The file type is determined from the file contents — not the filename or the declared content type — and must be a PDF, a PNG/JPEG/GIF/WebP image, a DOCX/XLSX/PPTX document, an MP3/WAV/FLAC/OGG audio file, or UTF-8 text. Text is reported by its structure as `application/json`, `application/x-ndjson`, `text/csv`, `text/markdown`, or `text/plain`.' + operationId: 'uploadFile' parameters: - - description: 'Number of records to skip for pagination' + - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' in: 'query' - name: 'offset' + name: 'workspace_id' required: false schema: - default: 0 - description: 'Number of records to skip for pagination' - example: 0 - minimum: 0 - type: - - 'integer' - - 'null' - - description: 'Maximum number of records to return (max 100)' + description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' + format: 'uuid' + type: 'string' + - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' + example: 'openai' in: 'query' - name: 'limit' + name: 'provider' required: false schema: - default: 50 - description: 'Maximum number of records to return (max 100)' - example: 50 - maximum: 100 - minimum: 1 - type: 'integer' + $ref: '#/components/schemas/FileProvider' + requestBody: + content: + multipart/form-data: + example: + file: 'document.pdf' + schema: + properties: + file: + format: 'binary' + type: 'string' + required: + - 'file' + type: 'object' + required: true responses: '200': content: application/json: example: - data: - - assigned_by: 'user_abc123' - created_at: '2025-08-24T10:30:00Z' - guardrail_id: '550e8400-e29b-41d4-a716-446655440001' - id: '550e8400-e29b-41d4-a716-446655440000' - organization_id: 'org_xyz789' - user_id: 'user_abc123' - total_count: 1 + created_at: '2025-01-01T00:00:00Z' + downloadable: false + filename: 'document.pdf' + id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + mime_type: 'application/pdf' + size_bytes: 1024000 + type: 'file' schema: - $ref: '#/components/schemas/ListMemberAssignmentsResponse' - description: 'List of member assignments' + $ref: '#/components/schemas/FileResponse' + description: 'The uploaded file metadata.' '400': content: application/json: @@ -41962,16 +38833,36 @@ paths: schema: $ref: '#/components/schemas/ForbiddenResponse' description: 'Forbidden - Authentication successful but insufficient permissions' - '404': + '413': content: application/json: example: error: - code: 404 - message: 'Resource not found' + code: 413 + message: 'Request payload too large' schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' + $ref: '#/components/schemas/PayloadTooLargeResponse' + description: 'Payload Too Large - Request payload exceeds size limits' + '429': + content: + application/json: + example: + error: + code: 429 + message: 'Rate limit exceeded' + schema: + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' + '499': + content: + application/json: + example: + error: + code: 499 + message: 'The request was cancelled.' + schema: + $ref: '#/components/schemas/ClientClosedRequestResponse' + description: 'Client Closed Request - The caller cancelled the request' '500': content: application/json: @@ -41982,69 +38873,70 @@ paths: schema: $ref: '#/components/schemas/InternalServerResponse' description: 'Internal Server Error - Unexpected server error' - summary: 'List all member assignments' - tags: - - 'Guardrails' - x-speakeasy-name-override: 'listMemberAssignments' - x-speakeasy-pagination: - inputs: - - in: 'parameters' - name: 'offset' - type: 'offset' - - in: 'parameters' - name: 'limit' - type: 'limit' - outputs: - results: '$.data' - type: 'offsetLimit' - /images: - post: - description: 'Generates an image from a text prompt via the image generation router' - operationId: 'createImages' - requestBody: - content: - application/json: - example: - model: 'bytedance-seed/seedream-4.5' - prompt: 'a red panda astronaut floating in space, studio lighting' - schema: - $ref: '#/components/schemas/ImageGenerationRequest' - required: true - responses: - '200': + '502': content: application/json: example: - created: 1748372400 - data: - - b64_json: '' - usage: - completion_tokens: 4175 - cost: 0.04 - prompt_tokens: 0 - total_tokens: 4175 + error: + code: 502 + message: 'Provider returned error' schema: - $ref: '#/components/schemas/ImageGenerationResponse' - text/event-stream: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '503': + content: + application/json: example: - data: - b64_json: '' - partial_image_index: 0 - type: 'image_generation.partial_image' + error: + code: 503 + message: 'Service temporarily unavailable' schema: - $ref: '#/components/schemas/ImageStreamingResponse' - x-speakeasy-sse-sentinel: '[DONE]' - description: 'Image generation response' - '400': + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + summary: 'Upload a file' + tags: + - 'Files' + x-speakeasy-name-override: 'upload' + /files/{file_id}: + delete: + description: 'Deletes a file owned by the requesting workspace. Deletion is irreversible.' + operationId: 'deleteFile' + parameters: + - in: 'path' + name: 'file_id' + required: true + schema: + example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + maxLength: 256 + minLength: 1 + pattern: '^[\w-]+$' + type: 'string' + - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + in: 'query' + name: 'workspace_id' + required: false + schema: + description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' + format: 'uuid' + type: 'string' + - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' + example: 'openai' + in: 'query' + name: 'provider' + required: false + schema: + $ref: '#/components/schemas/FileProvider' + responses: + '200': content: application/json: example: - error: - code: 400 - message: 'Invalid request parameters' + id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + type: 'file_deleted' schema: - $ref: '#/components/schemas/BadRequestResponse' - description: 'Bad Request - Invalid request parameters or malformed input' + $ref: '#/components/schemas/FileDeleteResponse' + description: 'The file was deleted.' '401': content: application/json: @@ -42055,16 +38947,6 @@ paths: schema: $ref: '#/components/schemas/UnauthorizedResponse' description: 'Unauthorized - Authentication required or invalid credentials' - '402': - content: - application/json: - example: - error: - code: 402 - message: 'Insufficient credits. Add more using https://openrouter.ai/credits' - schema: - $ref: '#/components/schemas/PaymentRequiredResponse' - description: 'Payment Required - Insufficient credits or quota to complete request' '403': content: application/json: @@ -42085,16 +38967,6 @@ paths: schema: $ref: '#/components/schemas/NotFoundResponse' description: 'Not Found - Resource does not exist' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Request payload too large' - schema: - $ref: '#/components/schemas/PayloadTooLargeResponse' - description: 'Payload Too Large - Request payload exceeds size limits' '429': content: application/json: @@ -42125,1220 +38997,943 @@ paths: schema: $ref: '#/components/schemas/BadGatewayResponse' description: 'Bad Gateway - Provider/upstream API failure' - '524': - content: - application/json: - example: - error: - code: 524 - message: 'Request timed out. Please try again later.' - schema: - $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' - description: 'Infrastructure Timeout - Provider request timed out at edge network' - '529': - content: - application/json: - example: - error: - code: 529 - message: 'Provider returned error' - schema: - $ref: '#/components/schemas/ProviderOverloadedResponse' - description: 'Provider Overloaded - Provider is temporarily overloaded' - summary: 'Generate an image' - tags: - - 'Images' - x-speakeasy-name-override: 'generate' - /images/models: - get: - description: 'Lists every image generation model with its top-level supported-parameter superset and a URL to its full per-endpoint records.' - operationId: 'listImageModels' - responses: - '200': - content: - application/json: - example: - data: - - architecture: - input_modalities: - - 'text' - output_modalities: - - 'image' - created: 1692901234 - description: 'A text-to-image model.' - endpoints: '/api/v1/images/models/bytedance-seed/seedream-4.5/endpoints' - id: 'bytedance-seed/seedream-4.5' - name: 'Seedream 4.5' - supported_parameters: - resolution: - type: 'enum' - values: - - '1K' - - '2K' - - '4K' - supports_streaming: false - schema: - $ref: '#/components/schemas/ImageModelsListResponse' - description: 'List of image generation models' - '500': + '503': content: application/json: example: error: - code: 500 - message: 'Internal Server Error' + code: 503 + message: 'Service temporarily unavailable' schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'List image generation models' + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + summary: 'Delete a file' tags: - - 'Images' - x-speakeasy-name-override: 'listModels' - /images/models/{author}/{slug}/endpoints: + - 'Files' + x-speakeasy-name-override: 'delete' get: - description: 'Returns the full per-endpoint records for an image model: each endpoint''s definitive supported parameters, pricing, and passthrough allowlist.' - operationId: 'listImageModelEndpoints' + description: 'Retrieves metadata for a single file owned by the requesting workspace.' + operationId: 'getFileMetadata' parameters: - - description: 'Model author/organization' - in: 'path' - name: 'author' - required: true - schema: - description: 'Model author/organization' - example: 'bytedance-seed' - type: 'string' - - description: 'Model slug' - in: 'path' - name: 'slug' + - in: 'path' + name: 'file_id' required: true schema: - description: 'Model slug' - example: 'seedream-4.5' + example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + maxLength: 256 + minLength: 1 + pattern: '^[\w-]+$' type: 'string' - responses: - '200': - content: - application/json: - example: - endpoints: - - allowed_passthrough_parameters: [] - pricing: - - billable: 'output_image' - cost_usd: 0.05 - unit: 'image' - provider_name: 'Bytedance' - provider_slug: 'bytedance' - provider_tag: 'bytedance' - supported_parameters: - resolution: - type: 'enum' - values: - - '1K' - - '2K' - - '4K' - supports_streaming: false - id: 'bytedance-seed/seedream-4.5' - schema: - $ref: '#/components/schemas/ImageModelEndpointsResponse' - description: 'The full per-endpoint records for an image model' - '404': - content: - application/json: - example: - error: - code: 404 - message: 'Resource not found' - schema: - $ref: '#/components/schemas/NotFoundResponse' - description: 'Not Found - Resource does not exist' - '500': - content: - application/json: - example: - error: - code: 500 - message: 'Internal Server Error' - schema: - $ref: '#/components/schemas/InternalServerResponse' - description: 'Internal Server Error - Unexpected server error' - summary: 'List endpoints for an image model' - tags: - - 'Images' - x-speakeasy-name-override: 'listModelEndpoints' - /interns: - get: - description: 'Lists interns visible to the authenticated key, newest first. Filter by workspace and one or more lifecycle statuses. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'listInterns' - parameters: - - description: 'Maximum number of interns to return, from 1 through 500.' - in: 'query' - name: 'limit' - required: false - schema: - description: 'Maximum number of interns to return, from 1 through 500.' - example: 50 - maximum: 500 - minimum: 1 - type: 'integer' - - description: 'Comma-separated lifecycle statuses to include, at most 8. Repeats are collapsed.' - explode: false - in: 'query' - name: 'status' - required: false - schema: - description: 'Comma-separated lifecycle statuses to include, at most 8. Repeats are collapsed.' - example: - - 'queued' - - 'running' - items: - enum: - - 'awaiting_slack_install' - - 'queued' - - 'provisioning' - - 'running' - - 'failed' - - 'stopped' - - 'destroying' - - 'destroy_failed' - type: 'string' - maxItems: 8 - type: 'array' - style: 'form' - - description: 'The opaque `next_cursor` of the previous page. Returns the interns that come after it in the newest-first order. A malformed cursor is a 400.' + - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' in: 'query' - name: 'starting_after' + name: 'workspace_id' required: false schema: - description: 'The opaque `next_cursor` of the previous page. Returns the interns that come after it in the newest-first order. A malformed cursor is a 400.' - example: 'MjAyNi0wOS0xNlQwODozMDowMC4wMDAwMDBafDdjOWU2Njc5LTc0MjUtNDBkZS05NDRiLWUwN2ZjMWY5MGFlNw' + description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' + format: 'uuid' type: 'string' - - description: 'Only return interns in this workspace. It must match the API key workspace.' + - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' + example: 'openai' in: 'query' - name: 'workspace_id' + name: 'provider' required: false schema: - description: 'Only return interns in this workspace. It must match the API key workspace.' - example: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - format: 'uuid' - type: 'string' + $ref: '#/components/schemas/FileProvider' responses: '200': content: application/json: example: - data: - - attached_vault_id: null - can_edit: true - created_at: '2026-09-16T08:30:00.000Z' - created_by_you: true - description: 'Researches customer questions' - hostname: 'research-assistant.openrouter.ai' - icon_sha256: null - id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - instructions: null - last_failure_message: null - model: 'openai/gpt-5.4' - name: 'research-assistant' - progress: null - status: 'running' - updated_at: '2026-09-16T08:45:00.000Z' - vault_id: 'b431c59d-6eed-41ac-bc89-9a89be79a121' - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - has_more: false - schema: - $ref: '#/components/schemas/InternListResponse' - description: 'Interns matching the filters.' - '400': - content: - application/json: - example: - error: - code: 400 - message: 'Invalid list query' - metadata: - reason: 'invalid_body' - retryable: false + created_at: '2025-01-01T00:00:00Z' + downloadable: false + filename: 'document.pdf' + id: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + mime_type: 'application/pdf' + size_bytes: 1024000 + type: 'file' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The list filters are invalid.' + $ref: '#/components/schemas/FileResponse' + description: 'The file metadata.' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Forbidden' + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, or the request used a regional hostname.' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '429': content: application/json: example: error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'List interns' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + '502': + content: + application/json: + example: + error: + code: 502 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '503': + content: + application/json: + example: + error: + code: 503 + message: 'Service temporarily unavailable' + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + summary: 'Get file metadata' tags: - - 'Interns' - post: - description: 'Creates an intern in an explicit workspace. The operation also creates its private vault. It can start provisioning immediately or wait for a later provision call. A retry with the same idempotency key and body resumes unfinished work. The request body is capped at 1048576 bytes and a larger body is refused with 413. A non-empty body must declare `Content-Type: application/json` or it is refused with 415. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'createIntern' + - 'Files' + x-speakeasy-name-override: 'retrieve' + /files/{file_id}/content: + get: + description: 'Downloads the raw bytes of a file. Only files created server-side are downloadable; uploaded files return 400.' + operationId: 'downloadFileContent' parameters: - - description: 'Key that makes retries resume the same create operation, from 1 through 255 characters. An empty or longer key is refused with 400. Without the header, the server derives a stable key from the request body.' - in: 'header' - name: 'Idempotency-Key' - required: false + - in: 'path' + name: 'file_id' + required: true schema: - description: 'Key that makes retries resume the same create operation, from 1 through 255 characters. An empty or longer key is refused with 400. Without the header, the server derives a stable key from the request body.' - example: 'create-research-assistant-2026-09-16' - maxLength: 255 + example: 'or_file_011CNha8iCJcU1wXNR6q4V8w' + maxLength: 256 minLength: 1 + pattern: '^[\w-]+$' type: 'string' - requestBody: - content: - application/json: - example: - name: 'research-assistant' - provision: true - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - schema: - $ref: '#/components/schemas/CreateInternRequest' - required: true + - description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + in: 'query' + name: 'workspace_id' + required: false + schema: + description: 'Workspace to scope the request to. Defaults to the caller’s default workspace.' + example: 'a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7' + format: 'uuid' + type: 'string' + - description: 'Store or read this file on the named provider using your own API key for it. Omit to use OpenRouter storage.' + example: 'openai' + in: 'query' + name: 'provider' + required: false + schema: + $ref: '#/components/schemas/FileProvider' responses: '200': content: - application/json: - example: - attached_vault_id: null - can_edit: true - created_at: '2026-09-16T08:30:00.000Z' - created_by_you: true - description: 'Researches customer questions' - hostname: 'research-assistant.openrouter.ai' - icon_sha256: null - id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - instructions: null - last_failure_message: null - model: 'openai/gpt-5.4' - name: 'research-assistant' - progress: null - status: 'running' - updated_at: '2026-09-16T08:45:00.000Z' - vault_id: 'b431c59d-6eed-41ac-bc89-9a89be79a121' - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - schema: - $ref: '#/components/schemas/Intern' - description: 'A completed create operation was replayed.' - '201': - content: - application/json: - example: - attached_vault_id: null - can_edit: true - created_at: '2026-09-16T08:30:00.000Z' - created_by_you: true - description: 'Researches customer questions' - hostname: 'research-assistant.openrouter.ai' - icon_sha256: null - id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - instructions: null - last_failure_message: null - model: 'openai/gpt-5.4' - name: 'research-assistant' - progress: null - status: 'running' - updated_at: '2026-09-16T08:45:00.000Z' - vault_id: 'b431c59d-6eed-41ac-bc89-9a89be79a121' - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - schema: - $ref: '#/components/schemas/Intern' - description: 'Intern created.' + application/octet-stream: + example: 'binary file contents' + schema: + format: 'binary' + type: 'string' + description: 'The raw file content.' '400': content: application/json: example: error: code: 400 - message: 'Invalid request body' - metadata: - reason: 'invalid_body' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is invalid.' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': - content: - application/json: - examples: - lifecycle_writes_disabled: - value: - error: - code: 403 - message: 'Intern lifecycle writes are not enabled for this account' - metadata: - reason: 'lifecycle_writes_disabled' - retryable: false - no_acting_user: - value: - error: - code: 403 - message: 'This key acts as the organization and has no member to own a new intern' - metadata: - reason: 'no_acting_user' - retryable: false - workspace_capability_unavailable: - value: - error: - code: 403 - message: 'This feature is not available in this workspace.' - metadata: - reason: 'workspace_capability_unavailable' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key acts as an organization and has no member who can own the intern, the workspace does not allow interns, lifecycle writes are not enabled for the caller, or regional access is refused.' - '404': content: application/json: example: error: - code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '404': content: application/json: example: error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' - '409': - content: - application/json: - examples: - idempotency_key_reused: - value: - error: - code: 409 - message: 'This Idempotency-Key was already used with a different request' - metadata: - reason: 'idempotency_key_reused' - retryable: false - name_taken: - value: - error: - code: 409 - message: 'An intern named "research-assistant" already exists in this workspace' - metadata: - reason: 'name_taken' - retryable: false + code: 404 + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The idempotency key was reused, the intern name is already taken in the workspace, the member reached the intern limit, or the requested vault cannot be attached.' - '413': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '429': content: application/json: example: error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is larger than 1048576 bytes.' - '415': + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' + '500': content: application/json: example: error: - code: 415 - message: 'Request body must be sent as application/json' - metadata: - reason: 'unsupported_media_type' - retryable: false + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is non-empty and its Content-Type is not application/json.' - '500': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + '502': content: application/json: example: error: - code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + code: 502 + message: 'Provider returned error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - '502': + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '503': content: application/json: example: error: - code: 502 - message: 'The intern was created but setup is not ready yet, retry the request' - metadata: - reason: 'upstream_unavailable' - retryable: true + code: 503 + message: 'Service temporarily unavailable' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The vault or provisioner did not complete a recoverable create step. Retry the same request.' - security: - - apiKey: [] - summary: 'Create an intern' + $ref: '#/components/schemas/ServiceUnavailableResponse' + description: 'Service Unavailable - Service temporarily unavailable' + summary: 'Download file content' tags: - - 'Interns' - /interns/{internId}: - delete: - description: 'Starts safe teardown of the intern, its runtime and its private vault. The body is optional. Send `{"acknowledge_workspace_loss": true}` to delete a `destroy_failed` intern whose `last_failure_message` names `workspace_archive_failed`, accepting that its workspace is not backed up. The request body is capped at 1048576 bytes and a larger body is refused with 413. A non-empty body must declare `Content-Type: application/json` or it is refused with 415. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'deleteIntern' + - 'Files' + x-speakeasy-name-override: 'download' + /generation: + get: + operationId: 'getGeneration' parameters: - - description: 'ID of an intern visible to the authenticated API key.' - in: 'path' - name: 'internId' + - description: 'The generation ID' + in: 'query' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 + description: 'The generation ID' + example: 'gen-1234567890' + maxLength: 128 + pattern: '^gen-[0-9A-Za-z-]+$' type: 'string' - requestBody: - content: - application/json: - example: - acknowledge_workspace_loss: true - schema: - $ref: '#/components/schemas/DeleteInternRequest' - required: true responses: - '202': + '200': content: application/json: example: - deleting: true + data: + api_type: 'completions' + app_id: 12345 + cache_discount: null + cancelled: false + created_at: '2024-07-15T23:33:19.433273+00:00' + data_region: 'global' + external_user: 'user-123' + finish_reason: 'stop' + generation_time: 1200 + http_referer: 'https://openrouter.ai/' + id: 'gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG' + is_byok: false + latency: 1250 + model: 'sao10k/l3-stheno-8b' + moderation_latency: 50 + native_finish_reason: 'stop' + native_tokens_cached: 3 + native_tokens_completion: 25 + native_tokens_completion_images: 0 + native_tokens_prompt: 10 + native_tokens_reasoning: 5 + num_fetches: 0 + num_input_audio_prompt: 0 + num_media_completion: 0 + num_media_prompt: 1 + num_search_results: 5 + origin: 'https://openrouter.ai/' + preset_id: 'a9e8d400-592a-494f-908c-375efa66cafd' + provider_name: 'Infermatic' + provider_responses: null + request_id: 'req-1727282430-aBcDeFgHiJkLmNoPqRsT' + router: 'openrouter/auto' + service_tier: 'priority' + session_id: null + streamed: true + tokens_completion: 25 + tokens_prompt: 10 + total_cost: 0.0015 + upstream_id: 'chatcmpl-791bcf62-080e-4568-87d0-94c72e3b4946' + upstream_inference_cost: 0.0012 + usage: 0.0015 + user_agent: 'Mozilla/5.0' + web_search_engine: 'exa' schema: - $ref: '#/components/schemas/DeleteInternResponse' - description: 'The operation was accepted.' + $ref: '#/components/schemas/GenerationResponse' + description: 'Returns the request metadata for this generation' '400': content: application/json: example: error: code: 400 - message: 'Invalid request body' - metadata: - reason: 'invalid_body' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is invalid.' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' + schema: + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '402': + content: + application/json: + example: + error: + code: 402 + message: 'Insufficient credits. Add more using https://openrouter.ai/credits' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/PaymentRequiredResponse' + description: 'Payment Required - Insufficient credits or quota to complete request' '403': content: application/json: example: error: code: 403 - message: 'Intern lifecycle writes are not enabled for this account' - metadata: - reason: 'lifecycle_writes_disabled' - retryable: false + message: 'Management key does not have permission for this request' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, the request used a regional hostname, or lifecycle writes are not enabled for the caller (`metadata.reason` is `lifecycle_writes_disabled`).' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - The management key does not have permission for this request' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' - '409': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '429': content: application/json: example: error: - code: 409 - message: 'Another operation holds the intern, retry once it settles' - metadata: - reason: 'intern_busy' - retryable: true + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern is not in a state that allows this operation. `metadata.reason` says whether to try again: `intern_busy` means another operation still holds the intern and carries `metadata.retryable: true`, so the same request may be sent again once it settles. A duplicate delete of an intern already being deleted is not a conflict and is accepted with 202.' - '413': + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' + '500': content: application/json: example: error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is larger than 1048576 bytes.' - '415': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + '502': content: application/json: example: error: - code: 415 - message: 'Request body must be sent as application/json' - metadata: - reason: 'unsupported_media_type' - retryable: false + code: 502 + message: 'Provider returned error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is non-empty and its Content-Type is not application/json.' - '500': + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '524': content: application/json: example: error: - code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + code: 524 + message: 'Request timed out. Please try again later.' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - '502': + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': content: application/json: example: error: - code: 502 - message: 'The intern service could not be reached, retry the request' - metadata: - reason: 'upstream_unavailable' - retryable: true + code: 529 + message: 'Provider returned error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern service could not accept the operation.' - security: - - apiKey: [] - summary: 'Delete an intern' + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + summary: 'Get request & usage metadata for a generation' tags: - - 'Interns' + - 'Generations' + /generation/content: get: - description: 'Returns the public lifecycle state and settings for one visible intern. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'getIntern' + operationId: 'listGenerationContent' parameters: - - description: 'ID of an intern visible to the authenticated API key.' - in: 'path' - name: 'internId' + - description: 'The generation ID' + in: 'query' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 + description: 'The generation ID' + example: 'gen-1234567890' + maxLength: 128 + pattern: '^gen-[0-9A-Za-z-]+$' type: 'string' responses: '200': content: application/json: example: - attached_vault_id: null - can_edit: true - created_at: '2026-09-16T08:30:00.000Z' - created_by_you: true - description: 'Researches customer questions' - hostname: 'research-assistant.openrouter.ai' - icon_sha256: null - id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - instructions: null - last_failure_message: null - model: 'openai/gpt-5.4' - name: 'research-assistant' - progress: null - status: 'running' - updated_at: '2026-09-16T08:45:00.000Z' - vault_id: 'b431c59d-6eed-41ac-bc89-9a89be79a121' - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - schema: - $ref: '#/components/schemas/Intern' - description: 'Intern lifecycle state and settings.' + data: + error: null + input: + messages: + - content: 'What is the meaning of life?' + role: 'user' + output: + completion: 'The meaning of life is a philosophical question...' + reasoning: null + schema: + $ref: '#/components/schemas/GenerationContentResponse' + description: 'Returns the stored prompt and completion content, plus the failure error when the generation failed' + '400': + content: + application/json: + example: + error: + code: 400 + message: 'Invalid request parameters' + schema: + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Forbidden' + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, or the request used a regional hostname.' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '429': content: application/json: example: error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'Get an intern' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + '502': + content: + application/json: + example: + error: + code: 502 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '524': + content: + application/json: + example: + error: + code: 524 + message: 'Request timed out. Please try again later.' + schema: + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': + content: + application/json: + example: + error: + code: 529 + message: 'Provider returned error' + schema: + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + summary: 'Get stored prompt, completion, and error content for a generation' tags: - - 'Interns' - patch: - description: 'Changes the intern name, description, instructions or model. Omitted fields stay unchanged. The request body is capped at 1048576 bytes and a larger body is refused with 413. A non-empty body must declare `Content-Type: application/json` or it is refused with 415. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'updateIntern' - parameters: - - description: 'ID of an intern visible to the authenticated API key.' - in: 'path' - name: 'internId' - required: true - schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 - type: 'string' + - 'Generations' + /generation/feedback: + post: + description: 'Submit structured feedback on a generation the authenticated user made. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'submitGenerationFeedback' requestBody: content: application/json: example: - description: 'Researches customer questions' - model: 'openai/gpt-5.4' + category: 'incorrect_response' + comment: 'The model repeated the same paragraph three times.' + generation_id: 'gen-3bhGkxlo4XFrqiabUM7NDtwDzWwG' schema: - $ref: '#/components/schemas/UpdateInternRequest' + $ref: '#/components/schemas/SubmitGenerationFeedbackRequest' required: true responses: '200': content: application/json: example: - attached_vault_id: null - can_edit: true - created_at: '2026-09-16T08:30:00.000Z' - created_by_you: true - description: 'Researches customer questions' - hostname: 'research-assistant.openrouter.ai' - icon_sha256: null - id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - instructions: null - last_failure_message: null - model: 'openai/gpt-5.4' - name: 'research-assistant' - progress: null - status: 'running' - updated_at: '2026-09-16T08:45:00.000Z' - vault_id: 'b431c59d-6eed-41ac-bc89-9a89be79a121' - workspace_id: '89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb' - schema: - $ref: '#/components/schemas/Intern' - description: 'Updated intern.' + data: + success: true + schema: + $ref: '#/components/schemas/SubmitGenerationFeedbackResponse' + description: 'Feedback recorded successfully' '400': content: application/json: example: error: code: 400 - message: 'Invalid request body' - metadata: - reason: 'invalid_body' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is invalid.' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' - '403': - content: - application/json: - example: - error: - code: 403 - message: 'Intern lifecycle writes are not enabled for this account' - metadata: - reason: 'lifecycle_writes_disabled' - retryable: false + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, the request used a regional hostname, or lifecycle writes are not enabled for the caller (`metadata.reason` is `lifecycle_writes_disabled`).' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' '409': content: application/json: example: error: code: 409 - message: 'An intern named "research-assistant" already exists in this workspace' - metadata: - reason: 'name_taken' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The new name is already taken by an intern in this workspace.' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + message: 'Feedback was already submitted for this generation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is larger than 1048576 bytes.' - '415': + $ref: '#/components/schemas/ConflictResponse' + description: 'Conflict - Feedback was already submitted for this generation by this account. The first submission is kept.' + '429': content: application/json: example: error: - code: 415 - message: 'Request body must be sent as application/json' - metadata: - reason: 'unsupported_media_type' - retryable: false + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is non-empty and its Content-Type is not application/json.' + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'Update an intern' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Submit feedback for a generation' tags: - - 'Interns' - /interns/{internId}/chat/completions: - post: - description: "Sends a prompt to one of your interns and streams the reply as OpenAI-compatible server-sent events ending with `[DONE]`. The run executes on the intern, which may pause to ask you something. It then streams one `openrouter.provide_input` tool call and finishes with `finish_reason: \"tool_calls\"`, and the run stays open on the intern.\n\nEvery response, whether it ends with `stop`, `tool_calls` or `error`, is followed by a final chunk with empty `choices` that carries `session_id`, then `data: [DONE]`. That chunk carries the `usage` the intern reported for the run, after `stop` or `error`, and `null` when the intern reported none. After `tool_calls` its `usage` is `null` because the turn is not over. Read through `[DONE]`: the `session_id` you need to reply arrives after the `tool_calls` finish chunk.\n\nTo answer, send a second request with the same `session_id`, the assistant message echoing that tool call, and a `tool` message whose `tool_call_id` is the tool call id and whose `content` is the answer. The answer is delivered to the run that asked and the stream continues from where it paused. A question stays open for its interaction deadline (5 minutes by default) and the run is cancelled when that passes. Rejected replies do not extend the deadline.\n\nClosing the connection after the `[DONE]` that follows `finish_reason: \"tool_calls\"` keeps the run alive. Disconnecting while a response is still streaming cancels the run. The stream writes a `: keepalive` comment whenever nothing else has been written for 30 seconds, so a disconnect is noticed within that interval even while the intern is silent.\n\nA run the intern ends while you are still connected, by cancellation or by a deadline, ends the stream with a `finish_reason: \"error\"` chunk carrying `410` and reason `run_ended`, then the final empty-`choices` chunk and `[DONE]`. That error reports only an ending the intern confirmed. A connection that breaks without that confirmation ends with reason `stream_severed`, and a client that has already disconnected is promised no final event.\n\nSet `approval_mode` to `manual` to have the intern ask before approval-bearing tools such as the shell. Omitted, the run self-drives and consents on your behalf. The mode belongs to the run started by that prompt and must be repeated on later prompts.\n\nAvailable to interns programme members. Callers outside the programme receive `404` for every path under `/api/v1/interns`." - operationId: 'createInternChatCompletion' + - 'Generations' + x-speakeasy-name-override: 'submitFeedback' + /guardrails: + get: + description: 'List all guardrails for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'listGuardrails' parameters: - - description: 'The intern to talk to.' - in: 'path' - name: 'internId' - required: true + - description: 'Number of records to skip for pagination' + in: 'query' + name: 'offset' + required: false + schema: + default: 0 + description: 'Number of records to skip for pagination' + example: 0 + minimum: 0 + type: + - 'integer' + - 'null' + - description: 'Maximum number of records to return (max 100)' + in: 'query' + name: 'limit' + required: false schema: - description: 'The intern to talk to.' - example: 'a11e0000-0000-4000-8000-000000000005' + default: 50 + description: 'Maximum number of records to return (max 100)' + example: 50 + maximum: 100 + minimum: 1 + type: 'integer' + - description: 'Filter guardrails by workspace ID. By default, guardrails in the default workspace are returned.' + in: 'query' + name: 'workspace_id' + required: false + schema: + description: 'Filter guardrails by workspace ID. By default, guardrails in the default workspace are returned.' + example: '0df9e665-d932-5740-b2c7-b52af166bc11' + format: 'uuid' type: 'string' - requestBody: - content: - application/json: - example: - approval_mode: 'manual' - messages: - - content: 'Summarize the open pull requests.' - role: 'user' - stream: true - schema: - $ref: '#/components/schemas/InternChatCompletionRequest' - required: true responses: '200': content: - text/event-stream: + application/json: example: data: - choices: - - delta: - tool_calls: - - function: - arguments: '{"kind":"permission","operation":"shell","options":["allow_once","allow_always","reject_once","reject_always"]}' - name: 'openrouter.provide_input' - id: '15e90ad6-5320-4a59-af4f-b371428154fa' - index: 0 - type: 'function' - finish_reason: null - index: 0 - created: 1789537541 - id: 'chatcmpl-f727571a-3bad-4e0d-8a9e-f18f8cda9750' - model: 'openrouter/intern' - object: 'chat.completion.chunk' - schema: - $ref: '#/components/schemas/InternChatStreamingResponse' - x-speakeasy-sse-sentinel: '[DONE]' - description: 'The streamed completion. Chunks carry text, then a finish chunk: `finish_reason: "stop"` when the turn is complete, `finish_reason: "tool_calls"` when the intern is waiting for an answer, or `finish_reason: "error"` for a failure after this status. A final chunk with empty `choices` follows in every case, carrying `session_id` and `usage` (`null` unless the intern reported usage, and always `null` after `tool_calls`), and the stream ends with `data: [DONE]`.' - '202': - content: - application/json: + - allowed_models: null + allowed_providers: + - 'openai' + - 'anthropic' + - 'google' + created_at: '2025-08-24T10:30:00Z' + description: 'Guardrail for production environment' + enforce_zdr: false + id: '550e8400-e29b-41d4-a716-446655440000' + ignored_models: null + ignored_providers: null + include_byok_in_budgets: false + limit_usd: 100 + name: 'Production Guardrail' + reset_interval: 'monthly' + updated_at: '2025-08-24T15:45:00Z' + workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' + total_count: 1 schema: - $ref: '#/components/schemas/InternChatSteeredResponse' - description: 'A turn is already running in this `session_id`, and the message was delivered into it instead of starting a new turn. Nothing streams here: the intern takes the message up on the running turn, whose stream continues on the request that started it. Sent only for a `user` message with a `session_id`; a `tool` reply into a running session gets `409 busy`, as does a message the intern could not take. Other sessions on the same intern are not affected and run in parallel.' + $ref: '#/components/schemas/ListGuardrailsResponse' + description: 'List of guardrails' '400': content: application/json: example: error: code: 400 - message: 'The intern did not accept that answer for this tool_call_id.' - metadata: - reason: 'bad_request' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The body is not a valid request (`bad_request`), or the intern did not accept the answer for the pending question, such as a permission option it did not offer.' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'No valid API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'This API key''s creator is no longer a member of the organization. Ask an organization admin to reassign the key to an active member.' + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The key belongs to a member who has left the organization and holds no grant.' - '404': + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '500': content: application/json: example: error: - code: 404 - message: 'No pending question has this tool_call_id.' - metadata: - reason: 'interaction_unknown' - retryable: false + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The caller is outside the interns programme, the intern does not exist for this key (`not_found`), or no pending question has this `tool_call_id` in this session (`interaction_unknown`).' - '408': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'List guardrails' + tags: + - 'Guardrails' + x-speakeasy-name-override: 'list' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'offset' + type: 'offset' + - in: 'parameters' + name: 'limit' + type: 'limit' + outputs: + results: '$.data' + type: 'offsetLimit' + post: + description: 'Create a new guardrail for the authenticated user. A newly created guardrail enforces nothing until it is assigned to API keys or organization members; `workspace_id` places the guardrail in a workspace but does not apply it to that workspace''s traffic. To restrict all traffic in a workspace, update the workspace''s default guardrail instead. Set `allowed_data_regions` to enforce [In-Region Routing](/docs/guides/features/in-region-routing#enforcing-in-region-routing-with-guardrails): governed requests must arrive through one of the listed OpenRouter domains and are rejected with a 403 otherwise. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'createGuardrail' + requestBody: + content: + application/json: + example: + 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' + schema: + $ref: '#/components/schemas/CreateGuardrailRequest' + required: true + responses: + '201': content: application/json: example: - error: - code: 408 - message: 'Operation timed out after 300s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + data: + allowed_models: null + allowed_providers: + - 'openai' + - 'anthropic' + - 'google' + created_at: '2025-08-24T10:30:00Z' + description: 'A guardrail for limiting API usage' + enforce_zdr: null + enforce_zdr_anthropic: true + enforce_zdr_google: false + enforce_zdr_openai: true + enforce_zdr_other: false + enforce_zdr_xai: false + id: '550e8400-e29b-41d4-a716-446655440000' + ignored_models: null + ignored_providers: null + include_byok_in_budgets: false + limit_usd: 50 + name: 'My New Guardrail' + reset_interval: 'monthly' + updated_at: null + workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The request exceeded the route''s own deadline before the handler answered (`timeout`). Distinct from the 504, which is the intern failing to answer within the turn budget.' - '409': + $ref: '#/components/schemas/CreateGuardrailResponse' + description: 'Guardrail created successfully' + '400': content: application/json: example: error: - code: 409 - message: 'The run that asked this question has already ended.' - metadata: - reason: 'interaction_not_pending' - retryable: false - schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern is not running (`intern_not_ready`), a turn is already running in this session and did not take the message within 15 seconds (`busy`, also sent when the turn is waiting on a question of its own), the question is no longer waiting (`interaction_not_pending`), or another request is already attached to the run (`attachment_failed`). Turns in different sessions on the same intern run in parallel. `intern_not_ready` and `busy` report `retryable: true`, and a `busy` refusal carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request. Present only on a `busy` refusal.' - required: false + code: 400 + message: 'Invalid request parameters' schema: - description: 'Seconds to wait before retrying this request. Present only on a `busy` refusal.' - example: '5' - type: 'string' - '410': + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' + '401': content: application/json: example: error: - code: 410 - message: 'The run produced more output than the intern retains for replay.' - metadata: - reason: 'attachment_failed' - retryable: false + code: 401 + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The run produced more output than the intern retains, so the paused stream cannot be resumed (`attachment_failed`).' - '413': + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '403': content: application/json: example: error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The body exceeds 1 MiB (`payload_too_large`).' - '429': + $ref: '#/components/schemas/ForbiddenResponse' + description: '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': content: application/json: example: error: - code: 429 - message: 'Too many intern turns. Please wait a moment.' - metadata: - reason: 'rate_limited' - retryable: true + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'Too many turns for the user or organization this key acts as (`rate_limited`). It reports `retryable: true` and carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request.' - required: true + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Create a guardrail' + tags: + - 'Guardrails' + x-speakeasy-name-override: 'create' + /guardrails/{id}: + delete: + description: 'Delete an existing guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'deleteGuardrail' + parameters: + - description: 'The unique identifier of the guardrail to delete' + in: 'path' + name: 'id' + required: true + schema: + description: 'The unique identifier of the guardrail to delete' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' + type: 'string' + responses: + '200': + content: + application/json: + example: + deleted: true schema: - description: 'Seconds to wait before retrying this request.' - example: '60' - type: 'string' - '502': + $ref: '#/components/schemas/DeleteGuardrailResponse' + description: 'Guardrail deleted successfully' + '401': content: application/json: example: error: - code: 502 - message: 'The intern could not be reached.' - metadata: - reason: 'intern_unreachable' - retryable: true + code: 401 + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern could not be reached or rejected the request (`intern_unreachable`, `intern_rejected`), the intern refused the turn before any output (`turn_failed`), or its stream ended before the turn started (`stream_severed`). `intern_unreachable` and `stream_severed` are transient and report `retryable: true`; `intern_rejected` reports `false`. A `turn_failed` varies by failure and carries the intern''s own classification of what went wrong, so read `metadata.retryable` rather than assuming from the reason.' - '503': + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '403': content: application/json: example: error: - code: 503 - message: 'The intern cannot hold another run open across a question right now. Retry later.' - metadata: - reason: 'busy' - retryable: true + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern cannot hold another run open across a question right now (`busy`). It reports `retryable: true` and carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request.' - required: true + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '404': + content: + application/json: + example: + error: + code: 404 + message: 'Resource not found' schema: - description: 'Seconds to wait before retrying this request.' - example: '5' - type: 'string' - '504': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '500': content: application/json: example: error: - code: 504 - message: 'The intern did not answer in time.' - metadata: - reason: 'timeout' - retryable: true + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern did not answer within the request budget (`timeout`).' - security: - - apiKey: [] - summary: 'Stream a chat completion with an intern' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Delete a guardrail' tags: - - 'Interns' - x-speakeasy-group: 'interns' - x-speakeasy-name-override: 'chat' - /interns/{internId}/connections: + - 'Guardrails' + x-speakeasy-name-override: 'delete' get: - description: 'Returns the Slack, GitHub, Google Workspace and MCP connections one visible intern can reach, and the shared ones switched off for it or disabled for the workspace. An OAuth grant needs `vault:read`, because the list names members'' personal accounts; without it the route answers 403 `insufficient_scope`. The response is sent with `Cache-Control: no-store`. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'getInternConnections' + description: 'Get a single guardrail by ID. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'getGuardrail' parameters: - - description: 'ID of an intern visible to the authenticated API key.' + - description: 'The unique identifier of the guardrail to retrieve' in: 'path' - name: 'internId' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 + description: 'The unique identifier of the guardrail to retrieve' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' responses: '200': @@ -43346,1206 +39941,1235 @@ paths: application/json: example: data: - - account: - acts_as: null - is_your_account_linked: null - note: null - scope: 'workspace' - id: 'github' - is_enabled: true - is_intern_only: false - kind: 'github' - mcp_server_name: null - name: 'GitHub' - off_reason: null - server: null - status: - reason: null - state: 'connected' - tool_count: null - schema: - $ref: '#/components/schemas/InternConnectionList' - description: 'The intern connections.' + allowed_models: null + allowed_providers: + - 'openai' + - 'anthropic' + - 'google' + created_at: '2025-08-24T10:30:00Z' + description: 'Guardrail for production environment' + enforce_zdr: false + id: '550e8400-e29b-41d4-a716-446655440000' + ignored_models: null + ignored_providers: null + include_byok_in_budgets: false + limit_usd: 100 + name: 'Production Guardrail' + reset_interval: 'monthly' + updated_at: '2025-08-24T15:45:00Z' + workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' + schema: + $ref: '#/components/schemas/GetGuardrailResponse' + description: 'Guardrail details' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Forbidden' + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, or the request used a regional hostname.' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' + $ref: '#/components/schemas/NotFoundResponse' + description: 'Guardrail not found, or the workspace default guardrail has not been configured yet.' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'List an intern''s connections' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Get a guardrail' tags: - - 'Interns' - /interns/{internId}/daemon: - get: - description: 'Returns the origin and daemon token that attach `ori tui --host` to one visible, running intern. The token is a credential: only an OAuth-token caller (`ori login --oidc`) may read it, the response is sent with `Cache-Control: no-store`, and each reveal is logged by caller and intern. API keys get 403 `personal_identity_required`. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'getInternDaemon' + - 'Guardrails' + x-speakeasy-name-override: 'get' + patch: + description: 'Update an existing guardrail, or materialize an unconfigured workspace default guardrail. Collection fields use replace semantics: send the full desired set on every update. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'updateGuardrail' parameters: - - description: 'ID of an intern visible to the authenticated API key.' + - description: 'The unique identifier of the guardrail to update' in: 'path' - name: 'internId' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 + description: 'The unique identifier of the guardrail to update' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' + requestBody: + content: + application/json: + example: + description: 'Updated description' + limit_usd: 75 + name: 'Updated Guardrail Name' + reset_interval: 'weekly' + schema: + $ref: '#/components/schemas/UpdateGuardrailRequest' + required: true responses: '200': content: application/json: + example: + data: + allowed_models: null + allowed_providers: + - 'openai' + created_at: '2025-08-24T10:30:00Z' + description: 'Updated description' + enforce_zdr: null + enforce_zdr_anthropic: true + enforce_zdr_google: true + enforce_zdr_openai: true + enforce_zdr_other: true + enforce_zdr_xai: true + id: '550e8400-e29b-41d4-a716-446655440000' + ignored_models: null + ignored_providers: null + include_byok_in_budgets: true + limit_usd: 75 + name: 'Updated Guardrail Name' + reset_interval: 'weekly' + updated_at: '2025-08-24T16:00:00Z' + workspace_id: '0df9e665-d932-5740-b2c7-b52af166bc11' + schema: + $ref: '#/components/schemas/UpdateGuardrailResponse' + description: 'Guardrail updated successfully' + '400': + content: + application/json: + example: + error: + code: 400 + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternDaemonAccess' - description: 'Daemon origin and token.' + $ref: '#/components/schemas/BadRequestResponse' + description: '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': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Forbidden' + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, or the request used a regional hostname.' + $ref: '#/components/schemas/ForbiddenResponse' + description: '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': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' '409': content: application/json: example: error: code: 409 - message: 'This intern is not running.' - metadata: - reason: 'intern_not_running' - retryable: false + message: 'Resource conflict. Please try again later.' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern cannot be attached to. `metadata.reason` is `intern_not_running`, `intern_unreachable` when it has no usable address yet, or `intern_needs_restart` when it was provisioned before daemon access was available.' + $ref: '#/components/schemas/ConflictResponse' + description: 'Guardrail name conflict — another guardrail in this workspace already uses the requested name.' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'Get an intern''s daemon access' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Update a guardrail' tags: - - 'Interns' - /interns/{internId}/daemon-access: + - 'Guardrails' + x-speakeasy-name-override: 'update' + /guardrails/{id}/assignments/keys: get: - deprecated: true - description: 'Deprecated alias of `GET /interns/{internId}/daemon` with the same request, response, and errors. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'getInternDaemonAccess' + description: 'List all API key assignments for a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'listGuardrailKeyAssignments' parameters: - - description: 'ID of an intern visible to the authenticated API key.' + - description: 'The unique identifier of the guardrail' in: 'path' - name: 'internId' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 + description: 'The unique identifier of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' + - description: 'Number of records to skip for pagination' + in: 'query' + name: 'offset' + required: false + schema: + default: 0 + description: 'Number of records to skip for pagination' + example: 0 + minimum: 0 + type: + - 'integer' + - 'null' + - description: 'Maximum number of records to return (max 100)' + in: 'query' + name: 'limit' + required: false + schema: + default: 50 + description: 'Maximum number of records to return (max 100)' + example: 50 + maximum: 100 + minimum: 1 + type: 'integer' responses: '200': content: application/json: + example: + data: + - assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' + key_label: 'prod-key' + key_name: 'Production Key' + total_count: 1 schema: - $ref: '#/components/schemas/InternDaemonAccess' - description: 'Daemon origin and token.' + $ref: '#/components/schemas/ListKeyAssignmentsResponse' + description: 'List of key assignments' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Forbidden' + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, or the request used a regional hostname.' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' - '409': - content: - application/json: - example: - error: - code: 409 - message: 'This intern is not running.' - metadata: - reason: 'intern_not_running' - retryable: false + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern cannot be attached to. `metadata.reason` is `intern_not_running`, `intern_unreachable` when it has no usable address yet, or `intern_needs_restart` when it was provisioned before daemon access was available.' + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'Get an intern''s daemon access (deprecated alias)' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'List key assignments for a guardrail' tags: - - 'Interns' - /interns/{internId}/daemon-access/sign: + - 'Guardrails' + x-speakeasy-name-override: 'listGuardrailKeyAssignments' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'offset' + type: 'offset' + - in: 'parameters' + name: 'limit' + type: 'limit' + outputs: + results: '$.data' + type: 'offsetLimit' post: - deprecated: true - description: 'Deprecated alias of `POST /interns/{internId}/daemon/sign` with the same request, response, and errors. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'signInternDaemonAccessRequest' + description: 'Assign multiple API keys to a specific guardrail. A key may hold at most one guardrail; assigning replaces any existing assignment. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'bulkAssignKeysToGuardrail' parameters: - - description: 'ID of an intern visible to the authenticated API key.' + - description: 'The unique identifier of the guardrail' in: 'path' - name: 'internId' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 + description: 'The unique identifier of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' requestBody: content: application/json: + example: + key_hashes: + - 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' schema: - $ref: '#/components/schemas/SignInternDaemonRequest' + $ref: '#/components/schemas/BulkAssignKeysRequest' required: true responses: '200': content: application/json: + example: + assigned_count: 3 schema: - $ref: '#/components/schemas/SignInternDaemonResponse' - description: 'Signature headers for the digest.' + $ref: '#/components/schemas/BulkAssignKeysResponse' + description: 'Assignment result' '400': content: application/json: example: error: code: 400 - message: 'Invalid request body' - metadata: - reason: 'invalid_body' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is invalid.' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Personal connections require ori login --oidc.' - metadata: - reason: 'personal_identity_required' - retryable: false + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is an API key, which names no person (`personal_identity_required`), or an OAuth grant without `vault:read` (`insufficient_scope`). Also returned when the key owner no longer has access or the request used a regional hostname.' + $ref: '#/components/schemas/ForbiddenResponse' + description: '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': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' - '413': - content: - application/json: - example: - error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is larger than 1048576 bytes.' - '415': - content: - application/json: - example: - error: - code: 415 - message: 'Request body must be sent as application/json' - metadata: - reason: 'unsupported_media_type' - retryable: false - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is non-empty and its Content-Type is not application/json.' - '429': - content: - application/json: - example: - error: - code: 429 - message: 'Too many intern turns. Please wait a moment.' - metadata: - reason: 'rate_limited' - retryable: true - schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Too many turns for the user or organization this credential acts as (`rate_limited`). Shares the chat turn limiter, reports `retryable: true` and carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request.' - required: true + message: 'Resource not found' schema: - description: 'Seconds to wait before retrying this request.' - example: '60' - type: 'string' + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'Sign a daemon request with the caller''s identity (deprecated alias)' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Bulk assign keys to a guardrail' tags: - - 'Interns' - /interns/{internId}/daemon/sign: + - 'Guardrails' + x-speakeasy-name-override: 'bulkAssignKeys' + /guardrails/{id}/assignments/keys/remove: post: - description: 'Signs the SHA-256 digest of one request the CLI is about to send to the intern daemon, binding it to the intern and to the signed-in member so personal connections resolve. Only an OAuth session from `ori login --oidc` whose grant carries `vault:read` can sign: an API key is refused with 403 because it names no person, and an `interns`-only grant is refused with 403 because a proof releases that user''s personal connections. The route is behind the same gate as chat and counts against the chat turn limiter. The response is sent with `Cache-Control: no-store`. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'signInternDaemonRequest' + description: 'Unassign multiple API keys from a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'bulkUnassignKeysFromGuardrail' parameters: - - description: 'ID of an intern visible to the authenticated API key.' + - description: 'The unique identifier of the guardrail' in: 'path' - name: 'internId' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 + description: 'The unique identifier of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' requestBody: content: application/json: + example: + key_hashes: + - 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' schema: - $ref: '#/components/schemas/SignInternDaemonRequest' + $ref: '#/components/schemas/BulkUnassignKeysRequest' required: true responses: '200': content: application/json: + example: + unassigned_count: 3 schema: - $ref: '#/components/schemas/SignInternDaemonResponse' - description: 'Signature headers for the digest.' + $ref: '#/components/schemas/BulkUnassignKeysResponse' + description: 'Unassignment result' '400': content: application/json: example: error: code: 400 - message: 'Invalid request body' - metadata: - reason: 'invalid_body' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is invalid.' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Personal connections require ori login --oidc.' - metadata: - reason: 'personal_identity_required' - retryable: false + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is an API key, which names no person (`personal_identity_required`), or an OAuth grant without `vault:read` (`insufficient_scope`). Also returned when the key owner no longer has access or the request used a regional hostname.' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '500': content: application/json: example: error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' - '413': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Bulk unassign keys from a guardrail' + tags: + - 'Guardrails' + x-speakeasy-name-override: 'bulkUnassignKeys' + /guardrails/{id}/assignments/members: + get: + description: 'List all organization member assignments for a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'listGuardrailMemberAssignments' + parameters: + - description: 'The unique identifier of the guardrail' + in: 'path' + name: 'id' + required: true + schema: + description: 'The unique identifier of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' + type: 'string' + - description: 'Number of records to skip for pagination' + in: 'query' + name: 'offset' + required: false + schema: + default: 0 + description: 'Number of records to skip for pagination' + example: 0 + minimum: 0 + type: + - 'integer' + - 'null' + - description: 'Maximum number of records to return (max 100)' + in: 'query' + name: 'limit' + required: false + schema: + default: 50 + description: 'Maximum number of records to return (max 100)' + example: 50 + maximum: 100 + minimum: 1 + type: 'integer' + responses: + '200': content: application/json: example: - error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + data: + - assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + organization_id: 'org_xyz789' + user_id: 'user_abc123' + total_count: 1 schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is larger than 1048576 bytes.' - '415': + $ref: '#/components/schemas/ListMemberAssignmentsResponse' + description: 'List of member assignments' + '401': content: application/json: example: error: - code: 415 - message: 'Request body must be sent as application/json' - metadata: - reason: 'unsupported_media_type' - retryable: false + code: 401 + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is non-empty and its Content-Type is not application/json.' - '429': + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '403': content: application/json: example: error: - code: 429 - message: 'Too many intern turns. Please wait a moment.' - metadata: - reason: 'rate_limited' - retryable: true + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Too many turns for the user or organization this credential acts as (`rate_limited`). Shares the chat turn limiter, reports `retryable: true` and carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request.' - required: true + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '404': + content: + application/json: + example: + error: + code: 404 + message: 'Resource not found' schema: - description: 'Seconds to wait before retrying this request.' - example: '60' - type: 'string' + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'Sign a daemon request with the caller''s identity' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'List member assignments for a guardrail' tags: - - 'Interns' - /interns/{internId}/icon: - get: - description: 'Returns the icon image of one visible intern. Pass the intern''s `icon_sha256` as `v` to receive a response that can be cached indefinitely. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'getInternIcon' + - 'Guardrails' + x-speakeasy-name-override: 'listGuardrailMemberAssignments' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'offset' + type: 'offset' + - in: 'parameters' + name: 'limit' + type: 'limit' + outputs: + results: '$.data' + type: 'offsetLimit' + post: + description: 'Assign multiple organization members to a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'bulkAssignMembersToGuardrail' parameters: - - description: 'ID of an intern visible to the authenticated API key.' + - description: 'The unique identifier of the guardrail' in: 'path' - name: 'internId' + name: 'id' required: true schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 - type: 'string' - - description: 'The `icon_sha256` the caller expects.' - in: 'query' - name: 'v' - required: false - schema: - description: 'The `icon_sha256` the caller expects.' + description: 'The unique identifier of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' + requestBody: + content: + application/json: + example: + member_user_ids: + - 'user_abc123' + - 'user_def456' + schema: + $ref: '#/components/schemas/BulkAssignMembersRequest' + required: true responses: '200': content: - image/*: + application/json: + example: + assigned_count: 2 schema: - format: 'binary' - type: 'string' - description: 'Icon image bytes.' - '401': + $ref: '#/components/schemas/BulkAssignMembersResponse' + description: 'Assignment result' + '400': content: application/json: example: error: - code: 401 - message: 'Invalid or missing API key' + code: 400 + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' - '403': + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' + '401': content: application/json: example: error: - code: 403 - message: 'Forbidden' + code: 401 + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, or the request used a regional hostname.' - '404': + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '403': content: application/json: example: error: - code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '404': content: application/json: example: error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + code: 404 + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' '500': content: application/json: example: error: code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - security: - - apiKey: [] - summary: 'Get an intern''s icon' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Bulk assign members to a guardrail' tags: - - 'Interns' - /interns/{internId}/invoke: + - 'Guardrails' + x-speakeasy-name-override: 'bulkAssignMembers' + /guardrails/{id}/assignments/members/remove: post: - description: "Starts a run on one of your interns and answers `202` with the `session_id` as soon as the intern accepts it. The run keeps going on the intern after the response. Nothing about its progress comes back on this request; the intern reports through its own tools, such as Slack.\n\nSend the same `session_id` later to continue the conversation, for example to hand the intern a decision on work it started. If that session already has a run going, the prompt is delivered into it and the status is `steered`. A `session_id` is accepted only from the caller it was issued to, on the same intern; any other, including sessions started from Slack or the chat endpoint, is refused with `404`.\n\nRuns started here self-drive: the intern consents to its own tool approvals, and a question it asks is answered by its own fallback. A run ends when the intern finishes it or after its execution deadline (1 hour by default).\n\nAvailable to interns programme members. Callers outside the programme receive `404` for every path under `/api/v1/interns`." - operationId: 'invokeIntern' + description: 'Unassign multiple organization members from a specific guardrail. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'bulkUnassignMembersFromGuardrail' parameters: - - description: 'The intern to run.' + - description: 'The unique identifier of the guardrail' in: 'path' - name: 'internId' + name: 'id' required: true schema: - description: 'The intern to run.' - example: 'a11e0000-0000-4000-8000-000000000005' + description: 'The unique identifier of the guardrail' + example: '550e8400-e29b-41d4-a716-446655440000' + format: 'uuid' type: 'string' requestBody: content: application/json: + example: + member_user_ids: + - 'user_abc123' + - 'user_def456' schema: - $ref: '#/components/schemas/InternInvokeRequest' + $ref: '#/components/schemas/BulkUnassignMembersRequest' required: true responses: - '202': + '200': content: application/json: + example: + unassigned_count: 2 schema: - $ref: '#/components/schemas/InternInvokeAcceptedResponse' - description: 'The intern accepted the prompt. The run continues on the intern.' + $ref: '#/components/schemas/BulkUnassignMembersResponse' + description: 'Unassignment result' '400': content: application/json: example: error: code: 400 - message: 'Invalid invoke request (input: Too small: expected string to have >=1 characters).' - metadata: - reason: 'bad_request' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The body is not a valid request (`bad_request`).' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'No valid API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'This API key''s creator is no longer a member of the organization. Ask an organization admin to reassign the key to an active member.' + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The key belongs to a member who has left the organization and holds no grant.' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false - schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The caller is outside the interns programme, the intern does not exist for this key, or the `session_id` was not issued to this caller on this intern (`not_found`).' - '408': - content: - application/json: - example: - error: - code: 408 - message: 'Operation timed out after 60s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The request exceeded the route''s own deadline before the handler answered (`timeout`).' - '409': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '500': content: application/json: example: error: - code: 409 - message: 'This intern is not running.' - metadata: - reason: 'intern_not_ready' - retryable: true - schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern is not running or its runtime is too old to keep a run going without a connection (`intern_not_ready`), or the session already has a run that did not take the prompt (`busy`). A `busy` refusal carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request. Present only on a `busy` refusal.' - required: false + code: 500 + message: 'Internal Server Error' schema: - description: 'Seconds to wait before retrying this request. Present only on a `busy` refusal.' - example: '5' - type: 'string' - '413': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'Bulk unassign members from a guardrail' + tags: + - 'Guardrails' + x-speakeasy-name-override: 'bulkUnassignMembers' + /guardrails/assignments/keys: + get: + description: 'List all API key guardrail assignments for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'listKeyAssignments' + parameters: + - description: 'Number of records to skip for pagination' + in: 'query' + name: 'offset' + required: false + schema: + default: 0 + description: 'Number of records to skip for pagination' + example: 0 + minimum: 0 + type: + - 'integer' + - 'null' + - description: 'Maximum number of records to return (max 100)' + in: 'query' + name: 'limit' + required: false + schema: + default: 50 + description: 'Maximum number of records to return (max 100)' + example: 50 + maximum: 100 + minimum: 1 + type: 'integer' + responses: + '200': content: application/json: example: - error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + data: + - assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + key_hash: 'c56454edb818d6b14bc0d61c46025f1450b0f4012d12304ab40aacb519fcbc93' + key_label: 'prod-key' + key_name: 'Production Key' + total_count: 1 schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The body exceeds 1 MiB (`payload_too_large`).' - '429': + $ref: '#/components/schemas/ListKeyAssignmentsResponse' + description: 'List of key assignments' + '400': content: application/json: example: error: - code: 429 - message: 'Too many intern turns. Please wait a moment.' - metadata: - reason: 'rate_limited' - retryable: true - schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'Too many turns for the user or organization this key acts as (`rate_limited`). It carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request.' - required: true + code: 400 + message: 'Invalid request parameters' schema: - description: 'Seconds to wait before retrying this request.' - example: '60' - type: 'string' - '500': + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' + '401': content: application/json: example: error: - code: 500 - message: 'Could not look up the intern' - metadata: - reason: 'intern_unreachable' - retryable: true + code: 401 + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern could not be looked up, or authenticating the key failed.' - '502': + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '403': content: application/json: example: error: - code: 502 - message: 'The intern could not be reached.' - metadata: - reason: 'intern_unreachable' - retryable: true + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern could not be reached, rejected the request, or refused the turn before it started.' - '503': + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '404': content: application/json: example: error: - code: 503 - message: 'The intern cannot hold another run open across a question right now. Retry later.' - metadata: - reason: 'busy' - retryable: true - schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern cannot take another run right now (`busy`). It reports `retryable: true` and carries `Retry-After`.' - headers: - Retry-After: - description: 'Seconds to wait before retrying this request.' - required: true + code: 404 + message: 'Resource not found' schema: - description: 'Seconds to wait before retrying this request.' - example: '5' - type: 'string' - '504': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '500': content: application/json: example: error: - code: 504 - message: 'The intern did not answer in time.' - metadata: - reason: 'timeout' - retryable: true + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternChatErrorResponse' - description: 'The intern did not accept the turn in time (`timeout`).' - security: - - apiKey: [] - summary: 'Start an intern run without waiting for it' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'List all key assignments' tags: - - 'Interns' - x-speakeasy-group: 'interns' - x-speakeasy-name-override: 'invoke' - /interns/{internId}/provision: - post: - description: 'Starts the first boot, or resumes an intern after suspension. This operation takes no request body. A body carrying any field is refused with 400 rather than ignored. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'provisionIntern' + - 'Guardrails' + x-speakeasy-name-override: 'listKeyAssignments' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'offset' + type: 'offset' + - in: 'parameters' + name: 'limit' + type: 'limit' + outputs: + results: '$.data' + type: 'offsetLimit' + /guardrails/assignments/members: + get: + description: 'List all organization member guardrail assignments for the authenticated user. [Management key](/docs/guides/overview/auth/management-api-keys) required.' + operationId: 'listMemberAssignments' parameters: - - description: 'ID of an intern visible to the authenticated API key.' - in: 'path' - name: 'internId' - required: true + - description: 'Number of records to skip for pagination' + in: 'query' + name: 'offset' + required: false schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 - type: 'string' + default: 0 + description: 'Number of records to skip for pagination' + example: 0 + minimum: 0 + type: + - 'integer' + - 'null' + - description: 'Maximum number of records to return (max 100)' + in: 'query' + name: 'limit' + required: false + schema: + default: 50 + description: 'Maximum number of records to return (max 100)' + example: 50 + maximum: 100 + minimum: 1 + type: 'integer' responses: - '202': + '200': content: application/json: example: - provisioning: true + data: + - assigned_by: 'user_abc123' + created_at: '2025-08-24T10:30:00Z' + guardrail_id: '550e8400-e29b-41d4-a716-446655440001' + id: '550e8400-e29b-41d4-a716-446655440000' + organization_id: 'org_xyz789' + user_id: 'user_abc123' + total_count: 1 schema: - $ref: '#/components/schemas/ProvisionInternResponse' - description: 'The operation was accepted.' + $ref: '#/components/schemas/ListMemberAssignmentsResponse' + description: 'List of member assignments' '400': content: application/json: example: error: code: 400 - message: 'Invalid request body' - metadata: - reason: 'invalid_body' - retryable: false + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is invalid.' + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' '401': content: application/json: example: error: code: 401 - message: 'Invalid or missing API key' + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' '403': content: application/json: example: error: code: 403 - message: 'Intern lifecycle writes are not enabled for this account' - metadata: - reason: 'lifecycle_writes_disabled' - retryable: false + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, the request used a regional hostname, or lifecycle writes are not enabled for the caller (`metadata.reason` is `lifecycle_writes_disabled`).' + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' '404': content: application/json: example: error: code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '500': content: application/json: example: error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' - '409': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'List all member assignments' + tags: + - 'Guardrails' + x-speakeasy-name-override: 'listMemberAssignments' + x-speakeasy-pagination: + inputs: + - in: 'parameters' + name: 'offset' + type: 'offset' + - in: 'parameters' + name: 'limit' + type: 'limit' + outputs: + results: '$.data' + type: 'offsetLimit' + /images: + post: + description: 'Generates an image from a text prompt via the image generation router' + operationId: 'createImages' + requestBody: + content: + application/json: + example: + model: 'bytedance-seed/seedream-4.5' + prompt: 'a red panda astronaut floating in space, studio lighting' + schema: + $ref: '#/components/schemas/ImageGenerationRequest' + required: true + responses: + '200': content: application/json: example: - error: - code: 409 - message: 'Another operation holds the intern, retry once it settles' - metadata: - reason: 'intern_busy' - retryable: true + created: 1748372400 + data: + - b64_json: '' + usage: + completion_tokens: 4175 + cost: 0.04 + prompt_tokens: 0 + total_tokens: 4175 schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern is not in a state that allows this operation. `metadata.reason` says whether to try again: `intern_busy` means another operation still holds the intern and carries `metadata.retryable: true`, so the same request may be sent again once it settles. A duplicate delete of an intern already being deleted is not a conflict and is accepted with 202.' - '413': + $ref: '#/components/schemas/ImageGenerationResponse' + text/event-stream: + example: + data: + b64_json: '' + partial_image_index: 0 + type: 'image_generation.partial_image' + schema: + $ref: '#/components/schemas/ImageStreamingResponse' + x-speakeasy-sse-sentinel: '[DONE]' + description: 'Image generation response' + '400': content: application/json: example: error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + code: 400 + message: 'Invalid request parameters' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is larger than 1048576 bytes.' - '415': + $ref: '#/components/schemas/BadRequestResponse' + description: 'Bad Request - Invalid request parameters or malformed input' + '401': content: application/json: example: error: - code: 415 - message: 'Request body must be sent as application/json' - metadata: - reason: 'unsupported_media_type' - retryable: false + code: 401 + message: 'Missing Authentication header' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is non-empty and its Content-Type is not application/json.' - '500': + $ref: '#/components/schemas/UnauthorizedResponse' + description: 'Unauthorized - Authentication required or invalid credentials' + '402': content: application/json: example: error: - code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + code: 402 + message: 'Insufficient credits. Add more using https://openrouter.ai/credits' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - '502': + $ref: '#/components/schemas/PaymentRequiredResponse' + description: 'Payment Required - Insufficient credits or quota to complete request' + '403': content: application/json: example: error: - code: 502 - message: 'The intern service could not be reached, retry the request' - metadata: - reason: 'upstream_unavailable' - retryable: true + code: 403 + message: 'Only management keys can perform this operation' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern service could not accept the operation.' - security: - - apiKey: [] - summary: 'Provision an intern' - tags: - - 'Interns' - /interns/{internId}/suspend: - post: - description: 'Stops the intern runtime while keeping its disk and configuration for a later provision call. This operation takes no request body. A body carrying any field is refused with 400 rather than ignored. The API key selects the caller, workspace and visible interns. An intern''s own API key sees only that intern: the collection and every other intern answer 404 to it. There is no default workspace fallback. Requests on regional hostnames such as `eu.openrouter.ai` are refused. [API key](/docs/api-reference/authentication) required.' - operationId: 'suspendIntern' - parameters: - - description: 'ID of an intern visible to the authenticated API key.' - in: 'path' - name: 'internId' - required: true - schema: - description: 'ID of an intern visible to the authenticated API key.' - example: '7c9e6679-7425-40de-944b-e07fc1f90ae7' - minLength: 1 - type: 'string' - responses: - '200': + $ref: '#/components/schemas/ForbiddenResponse' + description: 'Forbidden - Authentication successful but insufficient permissions' + '404': content: application/json: example: - suspended: true + error: + code: 404 + message: 'Resource not found' schema: - $ref: '#/components/schemas/SuspendInternResponse' - description: 'Intern suspended.' - '400': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '413': content: application/json: example: error: - code: 400 - message: 'Invalid request body' - metadata: - reason: 'invalid_body' - retryable: false + code: 413 + message: 'Request payload too large' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is invalid.' - '401': + $ref: '#/components/schemas/PayloadTooLargeResponse' + description: 'Payload Too Large - Request payload exceeds size limits' + '429': content: application/json: example: error: - code: 401 - message: 'Invalid or missing API key' + code: 429 + message: 'Rate limit exceeded' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'Missing, unknown or provisioning API key.' - '403': + $ref: '#/components/schemas/TooManyRequestsResponse' + description: 'Too Many Requests - Rate limit exceeded' + '500': content: application/json: example: error: - code: 403 - message: 'Intern lifecycle writes are not enabled for this account' - metadata: - reason: 'lifecycle_writes_disabled' - retryable: false + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The key owner no longer has access, the request used a regional hostname, or lifecycle writes are not enabled for the caller (`metadata.reason` is `lifecycle_writes_disabled`).' - '404': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + '502': content: application/json: example: error: - code: 404 - message: 'Intern not found' - metadata: - reason: 'not_found' - retryable: false + code: 502 + message: 'Provider returned error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The caller is outside the Intern API programme, or the intern is hidden.' - '408': + $ref: '#/components/schemas/BadGatewayResponse' + description: 'Bad Gateway - Provider/upstream API failure' + '524': content: application/json: example: error: - code: 408 - message: 'Operation timed out after 10s. Please try again later.' - metadata: - reason: 'timeout' - retryable: true + code: 524 + message: 'Request timed out. Please try again later.' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request exceeded its route deadline. The deadline quoted in the message is the route''s own, so it differs between operations.' - '409': + $ref: '#/components/schemas/EdgeNetworkTimeoutResponse' + description: 'Infrastructure Timeout - Provider request timed out at edge network' + '529': content: application/json: example: error: - code: 409 - message: 'Another operation holds the intern, retry once it settles' - metadata: - reason: 'intern_busy' - retryable: true + code: 529 + message: 'Provider returned error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern is not in a state that allows this operation. `metadata.reason` says whether to try again: `intern_busy` means another operation still holds the intern and carries `metadata.retryable: true`, so the same request may be sent again once it settles. A duplicate delete of an intern already being deleted is not a conflict and is accepted with 202.' - '413': + $ref: '#/components/schemas/ProviderOverloadedResponse' + description: 'Provider Overloaded - Provider is temporarily overloaded' + summary: 'Generate an image' + tags: + - 'Images' + x-speakeasy-name-override: 'generate' + /images/models: + get: + description: 'Lists every image generation model with its top-level supported-parameter superset and a URL to its full per-endpoint records.' + operationId: 'listImageModels' + responses: + '200': content: application/json: example: - error: - code: 413 - message: 'Request body exceeds 1048576 bytes' - metadata: - reason: 'payload_too_large' - retryable: false + data: + - architecture: + input_modalities: + - 'text' + output_modalities: + - 'image' + created: 1692901234 + description: 'A text-to-image model.' + endpoints: '/api/v1/images/models/bytedance-seed/seedream-4.5/endpoints' + id: 'bytedance-seed/seedream-4.5' + name: 'Seedream 4.5' + supported_parameters: + resolution: + type: 'enum' + values: + - '1K' + - '2K' + - '4K' + supports_streaming: false schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is larger than 1048576 bytes.' - '415': + $ref: '#/components/schemas/ImageModelsListResponse' + description: 'List of image generation models' + '500': content: application/json: example: error: - code: 415 - message: 'Request body must be sent as application/json' - metadata: - reason: 'unsupported_media_type' - retryable: false + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request body is non-empty and its Content-Type is not application/json.' - '500': + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'List image generation models' + tags: + - 'Images' + x-speakeasy-name-override: 'listModels' + /images/models/{author}/{slug}/endpoints: + get: + description: 'Returns the full per-endpoint records for an image model: each endpoint''s definitive supported parameters, pricing, and passthrough allowlist.' + operationId: 'listImageModelEndpoints' + parameters: + - description: 'Model author/organization' + in: 'path' + name: 'author' + required: true + schema: + description: 'Model author/organization' + example: 'bytedance-seed' + type: 'string' + - description: 'Model slug' + in: 'path' + name: 'slug' + required: true + schema: + description: 'Model slug' + example: 'seedream-4.5' + type: 'string' + responses: + '200': + content: + application/json: + example: + endpoints: + - allowed_passthrough_parameters: [] + pricing: + - billable: 'output_image' + cost_usd: 0.05 + unit: 'image' + provider_name: 'Bytedance' + provider_slug: 'bytedance' + provider_tag: 'bytedance' + supported_parameters: + resolution: + type: 'enum' + values: + - '1K' + - '2K' + - '4K' + supports_streaming: false + id: 'bytedance-seed/seedream-4.5' + schema: + $ref: '#/components/schemas/ImageModelEndpointsResponse' + description: 'The full per-endpoint records for an image model' + '404': content: application/json: example: error: - code: 500 - message: 'The request could not be completed' - metadata: - reason: 'internal_error' - retryable: true + code: 404 + message: 'Resource not found' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The request could not be completed. `metadata.reason` says whether to try again: `internal_error` is a transient failure and carries `metadata.retryable: true`, so the same request may be sent again, while `configuration_error` carries `retryable: false` because the next attempt reads the same missing binding or unusable stored credential.' - '502': + $ref: '#/components/schemas/NotFoundResponse' + description: 'Not Found - Resource does not exist' + '500': content: application/json: example: error: - code: 502 - message: 'The intern service could not be reached, retry the request' - metadata: - reason: 'upstream_unavailable' - retryable: true + code: 500 + message: 'Internal Server Error' schema: - $ref: '#/components/schemas/InternLifecycleError' - description: 'The intern service could not accept the operation.' - security: - - apiKey: [] - summary: 'Suspend an intern' + $ref: '#/components/schemas/InternalServerResponse' + description: 'Internal Server Error - Unexpected server error' + summary: 'List endpoints for an image model' tags: - - 'Interns' + - 'Images' + x-speakeasy-name-override: 'listModelEndpoints' /key: get: description: 'Get information on the API key associated with the current authentication session' @@ -55738,8 +52362,6 @@ tags: name: 'Guardrails' - description: 'Images endpoints' name: 'Images' - - description: 'Create, inspect, update, provision, suspend and delete OpenRouter interns through an API key, and talk to them: the chat route streams OpenAI-compatible completions from one intern, pausing as an `openrouter.provide_input` tool call when the intern needs your permission or an answer. Available to interns programme members; other callers receive 404. See https://openrouter.ai/docs/guides/ori/intern-chat.' - name: 'Interns' - description: 'Model information endpoints' name: 'Models' - description: 'OAuth authentication endpoints'