@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api OpenRouter API
@base https://openrouter.ai/api/v1
@version 1.0.0
@auth Bearer bearer | Bearer bearer
@endpoints 39
@hint download_for_search
@toc responses(1), messages(1), activity(1), chat(1), credits(2), generation(1), models(4), endpoints(1), providers(1), keys(5), organization(1), guardrails(13), key(1), auth(2), embeddings(2), rerank(2)

@group responses
@endpoint POST /responses
@desc Create a response
@optional {input: any # Input for a response request - can be a string or array of items, instructions: str, metadata: map # Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed., tools: [any], tool_choice: any, parallel_tool_calls: bool, model: str, models: [str], text: any # Text output configuration including format and verbosity, reasoning: any # Configuration for reasoning mode in the response, max_output_tokens: int, temperature: num(double), top_p: num(double), top_logprobs: int, max_tool_calls: int, presence_penalty: num(double), frequency_penalty: num(double), top_k: int, image_config: map # Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/features/multimodal/image-generation for more details., modalities: [str] # Output modalities for the response. Supported values are "text" and "image"., prompt_cache_key: str, previous_response_id: str, prompt: map{id!: str, variables: map}, include: [str], background: bool, safety_identifier: str, store: bool=false, service_tier: str(auto/default/flex/priority/scale)=auto, truncation: str(auto/disabled), stream: bool=false, provider: map{allow_fallbacks: bool, require_parameters: bool, data_collection: str, zdr: bool, enforce_distillable_text: bool, order: [any], only: [any], ignore: [any], quantizations: [str], sort: any, max_price: map, preferred_min_throughput: any, preferred_max_latency: any} # When multiple model providers are available, optionally indicate your routing preference., plugins: [any] # Plugins you want to enable for this request, including their settings., route: str(fallback/sort) # **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none")., user: str # A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 256 characters., session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow) for observability. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., trace: map{trace_id: str, trace_name: str, span_name: str, generation_name: str, parent_span_id: str} # Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.}
@returns(200) Successful response
@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 413: Payload Too Large - Request payload exceeds size limits, 422: Unprocessable Entity - Semantic validation failure, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 503: Service Unavailable - Service temporarily unavailable, 524: Infrastructure Timeout - Request timed out at our edge network, 529: Provider Overloaded - Provider is temporarily overloaded}
@example_request {"model":"openai/gpt-4o","input":"Tell me a joke"}

@endgroup

@group messages
@endpoint POST /messages
@desc Create a message
@required {model: str, messages: [map{role!: str, content!: any}]}
@optional {max_tokens: int, system: any, metadata: map{user_id: str}, stop_sequences: [str], temperature: num(double), top_p: num(double), top_k: int, tools: [any], tool_choice: any, thinking: any, service_tier: str(auto/standard_only), output_config: map{effort: str, format: map} # Configuration for controlling output behavior. Supports the effort parameter and structured output format., cache_control: map{type!: str, ttl: str}, stream: bool, context_management: map{edits: [any]}, provider: map{allow_fallbacks: bool, require_parameters: bool, data_collection: any, zdr: bool, enforce_distillable_text: bool, order: [any], only: [any], ignore: [any], quantizations: [str], sort: any, max_price: map, preferred_min_throughput: any, preferred_max_latency: any} # When multiple model providers are available, optionally indicate your routing preference., plugins: [any] # Plugins you want to enable for this request, including their settings., route: str(fallback/sort) # **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none")., user: str # A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 256 characters., session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow) for observability. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., trace: map{trace_id: str, trace_name: str, span_name: str, generation_name: str, parent_span_id: str} # Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations., models: [str], speed: str(fast/standard) # Controls output generation speed. When set to `fast`, uses a higher-speed inference configuration at premium pricing. Defaults to `standard` when omitted.}
@returns(200) Successful response
@errors {400: Invalid request error, 401: Authentication error, 403: Permission denied error, 404: Not found error, 429: Rate limit error, 500: API error, 503: Overloaded error, 529: Overloaded error}
@example_request {"model":"anthropic/claude-sonnet-4","max_tokens":1024,"messages":[{"role":"user","content":"Hello, how are you?"}]}

@endgroup

@group activity
@endpoint GET /activity
@desc Get user activity grouped by endpoint
@optional {date: str # Filter by a single UTC date in the last 30 days (YYYY-MM-DD format)., api_key_hash: str # Filter by API key hash (SHA-256 hex string, as returned by the keys API)., user_id: str # Filter by org member user ID. Only applicable for organization accounts.}
@returns(200) {data: [map]} # Returns user activity data grouped by endpoint
@errors {400: Bad Request - Invalid date format or date range, 401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Only management keys can fetch activity, 404: Not Found - User is not a member of the organization, 500: Internal Server Error - Unexpected server error}

@endgroup

@group chat
@endpoint POST /chat/completions
@desc Create a chat completion
@required {messages: [any] # List of messages for the conversation}
@optional {provider: map{allow_fallbacks: bool, require_parameters: bool, data_collection: any, zdr: bool, enforce_distillable_text: bool, order: [any], only: [any], ignore: [any], quantizations: [str], sort: any, max_price: map, preferred_min_throughput: any, preferred_max_latency: any} # When multiple model providers are available, optionally indicate your routing preference., plugins: [any] # Plugins you want to enable for this request, including their settings., route: str(fallback/sort) # **DEPRECATED** Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none")., user: str # Unique user identifier, session_id: str # A unique identifier for grouping related requests (e.g., a conversation or agent workflow) for observability. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters., trace: map{trace_id: str, trace_name: str, span_name: str, generation_name: str, parent_span_id: str} # Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations., model: str # Model to use for completion, models: [any] # Models to use for completion, frequency_penalty: num(double) # Frequency penalty (-2.0 to 2.0), logit_bias: map # Token logit bias adjustments, logprobs: bool # Return log probabilities, top_logprobs: int # Number of top log probabilities to return (0-20), max_completion_tokens: int # Maximum tokens in completion, max_tokens: int # Maximum tokens (deprecated, use max_completion_tokens). Note: some providers enforce a minimum of 16., metadata: map # Key-value pairs for additional object information (max 16 pairs, 64 char keys, 512 char values), presence_penalty: num(double) # Presence penalty (-2.0 to 2.0), reasoning: map{effort: str, summary: str} # Configuration options for reasoning models, response_format: any # Response format configuration, seed: int # Random seed for deterministic outputs, stop: any # Stop sequences (up to 4), stream: bool=false # Enable streaming response, stream_options: map{include_usage: bool} # Streaming configuration options, temperature: num(double) # Sampling temperature (0-2), parallel_tool_calls: bool # Whether to enable parallel function calling during tool use. When true, the model may generate multiple tool calls in a single response., tool_choice: any # Tool choice configuration, tools: [any] # Available tools for function calling, top_p: num(double) # Nucleus sampling parameter (0-1), debug: map{echo_upstream_body: bool} # Debug options for inspecting request transformations (streaming only), image_config: map # Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details., modalities: [str] # Output modalities for the response. Supported values are "text", "image", and "audio"., cache_control: any, service_tier: str(auto/default/flex/priority/scale) # The service tier to use for processing this request.}
@returns(200) {id: str, choices: [map], created: int, model: str, object: str, system_fingerprint: str?, service_tier: str?, usage: map{completion_tokens: int, prompt_tokens: int, total_tokens: int, completion_tokens_details: map?{reasoning_tokens: int, audio_tokens: int, accepted_prediction_tokens: int, rejected_prediction_tokens: int}, prompt_tokens_details: map?{cached_tokens: int, cache_write_tokens: int, audio_tokens: int, video_tokens: int}}} # Successful chat completion response
@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 404: Not Found - Resource does not exist, 408: Request Timeout - Operation exceeded time limit, 413: Payload Too Large - Request payload exceeds size limits, 422: Unprocessable Entity - Semantic validation failure, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 503: Service Unavailable - Service temporarily unavailable, 524: Infrastructure Timeout - Request timed out at our edge network, 529: Provider Overloaded - Provider is temporarily overloaded}
@example_request {"model":"openai/gpt-4","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is the capital of France?"}],"temperature":0.7,"max_tokens":150}

@endgroup

@group credits
@endpoint GET /credits
@desc Get remaining credits
@returns(200) {data: map{total_credits: num(double), total_usage: num(double)}} # Returns the total credits purchased and used
@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Only management keys can fetch credits, 500: Internal Server Error - Unexpected server error}

@endpoint POST /credits/coinbase
@desc Deprecated Coinbase Commerce charge endpoint
@errors {410: Gone - Coinbase Commerce charge creation has been removed}

@endgroup

@group generation
@endpoint GET /generation
@desc Get request & usage metadata for a generation
@required {id: str}
@returns(200) {data: map{id: str, upstream_id: str?, total_cost: num(double), cache_discount: num(double), upstream_inference_cost: num(double), created_at: str, model: str, app_id: int, streamed: bool?, cancelled: bool?, provider_name: str?, latency: num(double), moderation_latency: num(double), generation_time: num(double), finish_reason: str?, tokens_prompt: int, tokens_completion: int, native_tokens_prompt: int, native_tokens_completion: int, native_tokens_completion_images: int, native_tokens_reasoning: int, native_tokens_cached: int, num_media_prompt: int, num_input_audio_prompt: int, num_media_completion: int, num_search_results: int, origin: str, usage: num(double), is_byok: bool, native_finish_reason: str?, external_user: str?, api_type: str?, router: str?, provider_responses: [map]?, user_agent: str?, http_referer: str?, request_id: str?}} # Returns the request metadata for this generation
@errors {401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 404: Not Found - Generation not found, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 524: Infrastructure Timeout - Request timed out at our edge network, 529: Provider Overloaded - Provider is temporarily overloaded}

@endgroup

@group models
@endpoint GET /models/count
@desc Get total count of available models
@optional {output_modalities: str # Filter models by output modality. Accepts a comma-separated list of modalities (text, image, audio, embeddings) or "all" to include all models. Defaults to "text".}
@returns(200) {data: map{count: int}} # Returns the total count of available models
@errors {400: Bad Request - Invalid output_modalities value, 500: Internal Server Error}

@endpoint GET /models
@desc List all models and their properties
@optional {category: str(programming/roleplay/marketing/marketing/seo/technology/science/translation/legal/finance/health/trivia/academia) # Filter models by use case category, supported_parameters: str, output_modalities: str # Filter models by output modality. Accepts a comma-separated list of modalities (text, image, audio, embeddings) or "all" to include all models. Defaults to "text".}
@returns(200) {data: [map]} # Returns a list of models or RSS feed
@errors {400: Bad Request - Invalid request parameters, 500: Internal Server Error}

@endpoint GET /models/user
@desc List models filtered by user provider preferences, privacy settings, and guardrails
@returns(200) {data: [map]} # Returns a list of models filtered by user provider preferences
@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - No eligible endpoints found, 500: Internal Server Error}

@endpoint GET /models/{author}/{slug}/endpoints
@desc List all endpoints for a model
@required {author: str # The author/organization of the model, slug: str # The model slug}
@returns(200) {data: map{id: str, name: str, created: int, description: str, architecture: any, endpoints: [map]}} # Returns a list of endpoints
@errors {404: Not Found - Model does not exist, 500: Internal Server Error - Unexpected server error}

@endgroup

@group endpoints
@endpoint GET /endpoints/zdr
@desc Preview the impact of ZDR on the available endpoints
@returns(200) {data: [map]} # Returns a list of endpoints
@errors {500: Internal Server Error - Unexpected server error}

@endgroup

@group providers
@endpoint GET /providers
@desc List all providers
@returns(200) {data: [map]} # Returns a list of providers
@errors {500: Internal Server Error - Unexpected server error}

@endgroup

@group keys
@endpoint GET /keys
@desc List API keys
@optional {include_disabled: str # Whether to include disabled API keys in the response, offset: int # Number of API keys to skip for pagination}
@returns(200) {data: [map]} # List of API keys
@errors {401: Unauthorized - Missing or invalid authentication, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}

@endpoint POST /keys
@desc Create a new API key
@required {name: str # Name for the new API key}
@optional {limit: num(double) # Optional spending limit for the API key in USD, limit_reset: str(daily/weekly/monthly) # Type of limit reset for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday., include_byok_in_limit: bool # Whether to include BYOK usage in the limit, expires_at: str(date-time) # Optional ISO 8601 UTC timestamp when the API key should expire. Must be UTC, other timezones will be rejected, creator_user_id: str # Optional user ID of the key creator. Only meaningful for organization-owned keys where a specific member is creating the key.}
@returns(201) {data: map{hash: str, name: str, label: str, disabled: bool, limit: num(double), limit_remaining: num(double), limit_reset: str?, include_byok_in_limit: bool, usage: num(double), usage_daily: num(double), usage_weekly: num(double), usage_monthly: num(double), byok_usage: num(double), byok_usage_daily: num(double), byok_usage_weekly: num(double), byok_usage_monthly: num(double), created_at: str, updated_at: str?, expires_at: str(date-time)?, creator_user_id: str?}, key: str} # API key created successfully
@errors {400: Bad Request - Invalid request parameters, 401: Unauthorized - Missing or invalid authentication, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}
@example_request {"name":"My New API Key","limit":50,"limit_reset":"monthly","include_byok_in_limit":true,"expires_at":"2027-12-31T23:59:59Z"}

@endpoint PATCH /keys/{hash}
@desc Update an API key
@required {hash: str # The hash identifier of the API key to update}
@optional {name: str # New name for the API key, disabled: bool # Whether to disable the API key, limit: num(double) # New spending limit for the API key in USD, limit_reset: str(daily/weekly/monthly) # New limit reset type for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday., include_byok_in_limit: bool # Whether to include BYOK usage in the limit}
@returns(200) {data: map{hash: str, name: str, label: str, disabled: bool, limit: num(double), limit_remaining: num(double), limit_reset: str?, include_byok_in_limit: bool, usage: num(double), usage_daily: num(double), usage_weekly: num(double), usage_monthly: num(double), byok_usage: num(double), byok_usage_daily: num(double), byok_usage_weekly: num(double), byok_usage_monthly: num(double), created_at: str, updated_at: str?, expires_at: str(date-time)?, creator_user_id: str?}} # API key updated successfully
@errors {400: Bad Request - Invalid request parameters, 401: Unauthorized - Missing or invalid authentication, 404: Not Found - API key does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}
@example_request {"name":"Updated API Key Name","disabled":false,"limit":75,"limit_reset":"daily","include_byok_in_limit":true}

@endpoint DELETE /keys/{hash}
@desc Delete an API key
@required {hash: str # The hash identifier of the API key to delete}
@returns(200) {deleted: bool} # API key deleted successfully
@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - API key does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}

@endpoint GET /keys/{hash}
@desc Get a single API key
@required {hash: str # The hash identifier of the API key to retrieve}
@returns(200) {data: map{hash: str, name: str, label: str, disabled: bool, limit: num(double), limit_remaining: num(double), limit_reset: str?, include_byok_in_limit: bool, usage: num(double), usage_daily: num(double), usage_weekly: num(double), usage_monthly: num(double), byok_usage: num(double), byok_usage_daily: num(double), byok_usage_weekly: num(double), byok_usage_monthly: num(double), created_at: str, updated_at: str?, expires_at: str(date-time)?, creator_user_id: str?}} # API key details
@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - API key does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}

@endgroup

@group organization
@endpoint GET /organization/members
@desc List organization members
@optional {offset: int # Number of records to skip for pagination, limit: int # Maximum number of records to return (max 100)}
@returns(200) {data: [map], total_count: int} # List of organization members
@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - Organization not found, 500: Internal Server Error}

@endgroup

@group guardrails
@endpoint GET /guardrails
@desc List guardrails
@optional {offset: int # Number of records to skip for pagination, limit: int # Maximum number of records to return (max 100)}
@returns(200) {data: [map], total_count: int} # List of guardrails
@errors {401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}

@endpoint POST /guardrails
@desc Create a guardrail
@required {name: str # Name for the new guardrail}
@optional {description: str # Description of the guardrail, limit_usd: num(double) # Spending limit in USD, reset_interval: any, allowed_providers: [str] # List of allowed provider IDs, ignored_providers: [str] # List of provider IDs to exclude from routing, allowed_models: [str] # Array of model identifiers (slug or canonical_slug accepted), enforce_zdr: bool # Whether to enforce zero data retention}
@returns(201) {data: any} # Guardrail created successfully
@errors {400: Bad Request - Invalid request parameters, 401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}

@endpoint GET /guardrails/{id}
@desc Get a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail to retrieve}
@returns(200) {data: any} # Guardrail details
@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - Guardrail does not exist, 500: Internal Server Error}

@endpoint PATCH /guardrails/{id}
@desc Update a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail to update}
@optional {name: str # New name for the guardrail, description: str # New description for the guardrail, limit_usd: num(double) # New spending limit in USD, reset_interval: any, allowed_providers: [str] # New list of allowed provider IDs, ignored_providers: [str] # List of provider IDs to exclude from routing, allowed_models: [str] # Array of model identifiers (slug or canonical_slug accepted), enforce_zdr: bool # Whether to enforce zero data retention}
@returns(200) {data: any} # Guardrail updated successfully
@errors {400: Bad Request - Invalid request parameters, 401: Unauthorized - Missing or invalid authentication, 404: Not Found - Guardrail does not exist, 500: Internal Server Error}

@endpoint DELETE /guardrails/{id}
@desc Delete a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail to delete}
@returns(200) {deleted: bool} # Guardrail deleted successfully
@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - Guardrail does not exist, 500: Internal Server Error}

@endpoint GET /guardrails/assignments/keys
@desc List all key assignments
@optional {offset: int # Number of records to skip for pagination, limit: int # Maximum number of records to return (max 100)}
@returns(200) {data: [map], total_count: int} # List of key assignments
@errors {401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}

@endpoint GET /guardrails/assignments/members
@desc List all member assignments
@optional {offset: int # Number of records to skip for pagination, limit: int # Maximum number of records to return (max 100)}
@returns(200) {data: [map], total_count: int} # List of member assignments
@errors {401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}

@endpoint GET /guardrails/{id}/assignments/keys
@desc List key assignments for a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail}
@optional {offset: int # Number of records to skip for pagination, limit: int # Maximum number of records to return (max 100)}
@returns(200) {data: [map], total_count: int} # List of key assignments
@errors {401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}

@endpoint POST /guardrails/{id}/assignments/keys
@desc Bulk assign keys to a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail, key_hashes: [str] # Array of API key hashes to assign to the guardrail}
@returns(200) {assigned_count: int} # Assignment result
@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}

@endpoint GET /guardrails/{id}/assignments/members
@desc List member assignments for a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail}
@optional {offset: int # Number of records to skip for pagination, limit: int # Maximum number of records to return (max 100)}
@returns(200) {data: [map], total_count: int} # List of member assignments
@errors {401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}

@endpoint POST /guardrails/{id}/assignments/members
@desc Bulk assign members to a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail, member_user_ids: [str] # Array of member user IDs to assign to the guardrail}
@returns(200) {assigned_count: int} # Assignment result
@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}

@endpoint POST /guardrails/{id}/assignments/keys/remove
@desc Bulk unassign keys from a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail, key_hashes: [str] # Array of API key hashes to unassign from the guardrail}
@returns(200) {unassigned_count: int} # Unassignment result
@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}

@endpoint POST /guardrails/{id}/assignments/members/remove
@desc Bulk unassign members from a guardrail
@required {id: str(uuid) # The unique identifier of the guardrail, member_user_ids: [str] # Array of member user IDs to unassign from the guardrail}
@returns(200) {unassigned_count: int} # Unassignment result
@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}

@endgroup

@group key
@endpoint GET /key
@desc Get current API key
@returns(200) {data: map{label: str, limit: num(double), usage: num(double), usage_daily: num(double), usage_weekly: num(double), usage_monthly: num(double), byok_usage: num(double), byok_usage_daily: num(double), byok_usage_weekly: num(double), byok_usage_monthly: num(double), is_free_tier: bool, is_management_key: bool, is_provisioning_key: bool, limit_remaining: num(double), limit_reset: str?, include_byok_in_limit: bool, expires_at: str(date-time)?, creator_user_id: str?, rate_limit: map{requests: int, interval: str, note: str}}} # API key details
@errors {401: Unauthorized - Authentication required or invalid credentials, 500: Internal Server Error - Unexpected server error}

@endgroup

@group auth
@endpoint POST /auth/keys
@desc Exchange authorization code for API key
@required {code: str # The authorization code received from the OAuth redirect}
@optional {code_verifier: str # The code verifier if code_challenge was used in the authorization request, code_challenge_method: str(S256/plain) # The method used to generate the code challenge}
@returns(200) {key: str, user_id: str?} # Successfully exchanged code for an API key
@errors {400: Bad Request - Invalid request parameters or malformed input, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}

@endpoint POST /auth/keys/code
@desc Create authorization code
@required {callback_url: str(uri) # The callback URL to redirect to after authorization. Note, only https URLs on ports 443 and 3000 are allowed.}
@optional {code_challenge: str # PKCE code challenge for enhanced security, code_challenge_method: str(S256/plain) # The method used to generate the code challenge, limit: num(double) # Credit limit for the API key to be created, expires_at: str(date-time) # Optional expiration time for the API key to be created, key_label: str # Optional custom label for the API key. Defaults to the app name if not provided., usage_limit_type: str(daily/weekly/monthly) # Optional credit limit reset interval. When set, the credit limit resets on this interval., spawn_agent: str # Agent identifier for spawn telemetry, spawn_cloud: str # Cloud identifier for spawn telemetry}
@returns(200) {data: map{id: str, app_id: int, created_at: str}} # Successfully created authorization code
@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 409: Conflict - App upsert conflict during auth code creation, 500: Internal Server Error - Unexpected server error}

@endgroup

@group embeddings
@endpoint POST /embeddings
@desc Submit an embedding request
@required {input: any # Text, token, or multimodal input(s) to embed, model: str # The model to use for embeddings}
@optional {encoding_format: str(float/base64) # The format of the output embeddings, dimensions: int # The number of dimensions for the output embeddings, user: str # A unique identifier for the end-user, provider: map{allow_fallbacks: bool, require_parameters: bool, data_collection: any, zdr: bool, enforce_distillable_text: bool, order: [any], only: [any], ignore: [any], quantizations: [str], sort: any, max_price: map, preferred_min_throughput: any, preferred_max_latency: any} # Provider routing preferences for the request., input_type: str # The type of input (e.g. search_query, search_document)}
@returns(200) {id: str, object: str, data: [map], model: str, usage: map{prompt_tokens: int, total_tokens: int, cost: num(double)}} # Embedding response
@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 503: Service Unavailable - Service temporarily unavailable, 524: Cloudflare Timeout - Provider request timed out at CDN edge, 529: Provider Overloaded - Provider is temporarily overloaded}

@endpoint GET /embeddings/models
@desc List all embeddings models
@returns(200) {data: [map]} # Returns a list of embeddings models
@errors {400: Bad Request - Invalid request parameters, 500: Internal Server Error}

@endgroup

@group rerank
@endpoint POST /rerank
@desc Submit a rerank request
@required {model: str # The rerank model to use, query: str # The search query to rerank documents against, documents: [str] # The list of documents to rerank}
@optional {top_n: int # Number of most relevant documents to return, provider: map{allow_fallbacks: bool, require_parameters: bool, data_collection: any, zdr: bool, enforce_distillable_text: bool, order: [any], only: [any], ignore: [any], quantizations: [str], sort: any, max_price: map, preferred_min_throughput: any, preferred_max_latency: any} # Provider routing preferences for the request.}
@returns(200) {id: str, model: str, provider: str, results: [map], usage: map{total_tokens: int, search_units: int, cost: num(double)}} # Rerank response
@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 404: Not Found - Resource does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error, 502: Bad Gateway - Provider/upstream API failure, 503: Service Unavailable - Service temporarily unavailable, 524: Cloudflare Timeout - Provider request timed out at CDN edge, 529: Provider Overloaded - Provider is temporarily overloaded}

@endpoint GET /rerank/models
@desc List all rerank models
@returns(200) {data: [map]} # Returns a list of rerank models
@errors {400: Bad Request - Invalid request parameters, 500: Internal Server Error}

@endgroup

@end