{"files":{"SKILL.md":"---\nname: openrouter-api\ndescription: \"OpenRouter API skill. Use when working with OpenRouter for responses, messages, activity. Covers 39 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# OpenRouter API\nAPI version: 1.0.0\n\n## Auth\nBearer bearer | Bearer bearer\n\n## Base URL\nhttps://openrouter.ai/api/v1\n\n## Setup\n1. Set Authorization header with Bearer token\n2. GET /activity -- get user activity grouped by endpoint\n3. POST /responses -- create first response\n\n## Endpoints\n39 endpoints across 16 groups. See references/api-spec.lap for full details.\n\n### Responses\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /responses | Create a response |\n\n### Messages\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /messages | Create a message |\n\n### Activity\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /activity | Get user activity grouped by endpoint |\n\n### Chat\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /chat/completions | Create a chat completion |\n\n### Credits\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /credits | Get remaining credits |\n| POST | /credits/coinbase | Deprecated Coinbase Commerce charge endpoint |\n\n### Generation\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /generation | Get request & usage metadata for a generation |\n\n### Models\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /models/count | Get total count of available models |\n| GET | /models | List all models and their properties |\n| GET | /models/user | List models filtered by user provider preferences, privacy settings, and guardrails |\n| GET | /models/{author}/{slug}/endpoints | List all endpoints for a model |\n\n### Endpoints\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /endpoints/zdr | Preview the impact of ZDR on the available endpoints |\n\n### Providers\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /providers | List all providers |\n\n### Keys\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /keys | List API keys |\n| POST | /keys | Create a new API key |\n| PATCH | /keys/{hash} | Update an API key |\n| DELETE | /keys/{hash} | Delete an API key |\n| GET | /keys/{hash} | Get a single API key |\n\n### Organization\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /organization/members | List organization members |\n\n### Guardrails\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /guardrails | List guardrails |\n| POST | /guardrails | Create a guardrail |\n| GET | /guardrails/{id} | Get a guardrail |\n| PATCH | /guardrails/{id} | Update a guardrail |\n| DELETE | /guardrails/{id} | Delete a guardrail |\n| GET | /guardrails/assignments/keys | List all key assignments |\n| GET | /guardrails/assignments/members | List all member assignments |\n| GET | /guardrails/{id}/assignments/keys | List key assignments for a guardrail |\n| POST | /guardrails/{id}/assignments/keys | Bulk assign keys to a guardrail |\n| GET | /guardrails/{id}/assignments/members | List member assignments for a guardrail |\n| POST | /guardrails/{id}/assignments/members | Bulk assign members to a guardrail |\n| POST | /guardrails/{id}/assignments/keys/remove | Bulk unassign keys from a guardrail |\n| POST | /guardrails/{id}/assignments/members/remove | Bulk unassign members from a guardrail |\n\n### Key\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /key | Get current API key |\n\n### Auth\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /auth/keys | Exchange authorization code for API key |\n| POST | /auth/keys/code | Create authorization code |\n\n### Embeddings\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /embeddings | Submit an embedding request |\n| GET | /embeddings/models | List all embeddings models |\n\n### Rerank\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | /rerank | Submit a rerank request |\n| GET | /rerank/models | List all rerank models |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"Create a response?\" -> POST /responses\n- \"Create a message?\" -> POST /messages\n- \"List all activity?\" -> GET /activity\n- \"Create a completion?\" -> POST /chat/completions\n- \"List all credits?\" -> GET /credits\n- \"Create a coinbase?\" -> POST /credits/coinbase\n- \"List all generation?\" -> GET /generation\n- \"List all count?\" -> GET /models/count\n- \"List all models?\" -> GET /models\n- \"List all user?\" -> GET /models/user\n- \"List all endpoints?\" -> GET /models/{author}/{slug}/endpoints\n- \"List all zdr?\" -> GET /endpoints/zdr\n- \"List all providers?\" -> GET /providers\n- \"List all keys?\" -> GET /keys\n- \"Create a key?\" -> POST /keys\n- \"Partially update a key?\" -> PATCH /keys/{hash}\n- \"Delete a key?\" -> DELETE /keys/{hash}\n- \"Get key details?\" -> GET /keys/{hash}\n- \"List all members?\" -> GET /organization/members\n- \"List all guardrails?\" -> GET /guardrails\n- \"Create a guardrail?\" -> POST /guardrails\n- \"Get guardrail details?\" -> GET /guardrails/{id}\n- \"Partially update a guardrail?\" -> PATCH /guardrails/{id}\n- \"Delete a guardrail?\" -> DELETE /guardrails/{id}\n- \"Create a member?\" -> POST /guardrails/{id}/assignments/members\n- \"Create a remove?\" -> POST /guardrails/{id}/assignments/keys/remove\n- \"List all key?\" -> GET /key\n- \"Create a code?\" -> POST /auth/keys/code\n- \"Create a embedding?\" -> POST /embeddings\n- \"Create a rerank?\" -> POST /rerank\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api OpenRouter API\n@base https://openrouter.ai/api/v1\n@version 1.0.0\n@auth Bearer bearer | Bearer bearer\n@endpoints 36\n@hint download_for_search\n@toc responses(1), messages(1), activity(1), chat(1), credits(2), embeddings(2), generation(1), models(4), endpoints(1), providers(1), keys(5), guardrails(13), key(1), auth(2)\n\n@group responses\n@endpoint POST /responses\n@desc Create a response\n@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: num, temperature: num, top_p: num, top_logprobs: int, max_tool_calls: int, presence_penalty: num, frequency_penalty: num, top_k: num, 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.}\n@returns(200) Successful response\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 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}\n\n@endgroup\n\n@group messages\n@endpoint POST /messages\n@desc Create a message\n@required {model: str, messages: [map{role!: str, content!: any}]}\n@optional {max_tokens: num, system: any, metadata: map{user_id: str}, stop_sequences: [str], temperature: num, top_p: num, top_k: num, 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: 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., 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.}\n@returns(200) Successful response\n@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}\n\n@endgroup\n\n@group activity\n@endpoint GET /activity\n@desc Get user activity grouped by endpoint\n@optional {date: str # Filter by a single UTC date in the last 30 days (YYYY-MM-DD format).}\n@returns(200) {data: [map]} # Returns user activity data grouped by endpoint\n@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, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group chat\n@endpoint POST /chat/completions\n@desc Create a chat completion\n@required {messages: [any] # List of messages for the conversation}\n@optional {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 # 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 # Frequency penalty (-2.0 to 2.0), logit_bias: map # Token logit bias adjustments, logprobs: bool # Return log probabilities, top_logprobs: num # Number of top log probabilities to return (0-20), max_completion_tokens: num # Maximum tokens in completion, max_tokens: num # 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 # Presence penalty (-2.0 to 2.0), reasoning: map{effort: str, summary: any} # 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=1 # Sampling temperature (0-2), parallel_tool_calls: bool, tool_choice: any # Tool choice configuration, tools: [any] # Available tools for function calling, top_p: num=1 # 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: map{type!: str, ttl: str} # Enable automatic prompt caching. When set, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models., service_tier: str(auto/default/flex/priority/scale) # The service tier to use for processing this request.}\n@returns(200) {id: str, choices: [map], created: num, model: str, object: str, system_fingerprint: str?, service_tier: str?, usage: map{completion_tokens: num, prompt_tokens: num, total_tokens: num, completion_tokens_details: map?{reasoning_tokens: num?, audio_tokens: num?, accepted_prediction_tokens: num?, rejected_prediction_tokens: num?}, prompt_tokens_details: map?{cached_tokens: num, cache_write_tokens: num, audio_tokens: num, video_tokens: num}}} # Successful chat completion response\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 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}\n\n@endgroup\n\n@group credits\n@endpoint GET /credits\n@desc Get remaining credits\n@returns(200) {data: map{total_credits: num, total_usage: num}} # Returns the total credits purchased and used\n@errors {401: Unauthorized - Authentication required or invalid credentials, 403: Forbidden - Only management keys can fetch credits, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /credits/coinbase\n@desc Create a Coinbase charge for crypto payment\n@required {amount: num, sender: str, chain_id: int(1/137/8453)}\n@returns(200) {data: map{id: str, created_at: str, expires_at: str, web3_data: map{transfer_intent: map{call_data: map, metadata: map}}}} # Returns the calldata to fulfill the transaction\n@errors {400: Bad Request - Invalid credit amount or request body, 401: Unauthorized - Authentication required or invalid credentials, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group embeddings\n@endpoint POST /embeddings\n@desc Submit an embedding request\n@required {input: any, model: str}\n@optional {encoding_format: str(float/base64), dimensions: int, user: str, 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} # Provider routing preferences for the request., input_type: str}\n@returns(200) {id: str, object: str, data: [map], model: str, usage: map{prompt_tokens: num, total_tokens: num, cost: num}} # Embedding response\n@errors {400: Bad Request - Invalid request parameters or malformed input, 401: Unauthorized - Authentication required or invalid credentials, 402: Payment Required - Insufficient credits or quota to complete request, 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}\n\n@endpoint GET /embeddings/models\n@desc List all embeddings models\n@returns(200) {data: [map]} # Returns a list of embeddings models\n@errors {400: Bad Request - Invalid request parameters, 500: Internal Server Error}\n\n@endgroup\n\n@group generation\n@endpoint GET /generation\n@desc Get request & usage metadata for a generation\n@required {id: str}\n@returns(200) {data: map{id: str, upstream_id: str?, total_cost: num, cache_discount: num?, upstream_inference_cost: num?, created_at: str, model: str, app_id: num?, streamed: bool?, cancelled: bool?, provider_name: str?, latency: num?, moderation_latency: num?, generation_time: num?, finish_reason: str?, tokens_prompt: num?, tokens_completion: num?, native_tokens_prompt: num?, native_tokens_completion: num?, native_tokens_completion_images: num?, native_tokens_reasoning: num?, native_tokens_cached: num?, num_media_prompt: num?, num_input_audio_prompt: num?, num_media_completion: num?, num_search_results: num?, origin: str, usage: num, is_byok: bool, native_finish_reason: str?, external_user: str?, api_type: str?, router: str?, provider_responses: [map]?, user_agent: str?, http_referer: str?}} # Returns the request metadata for this generation\n@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}\n\n@endgroup\n\n@group models\n@endpoint GET /models/count\n@desc Get total count of available models\n@optional {output_modalities: str # Filter models by output modality. Accepts a comma-separated list of modalities (text, image, audio, embeddings) or \"all\" to include all models. Defaults to \"text\".}\n@returns(200) {data: map{count: num}} # Returns the total count of available models\n@errors {400: Bad Request - Invalid output_modalities value, 500: Internal Server Error}\n\n@endpoint GET /models\n@desc List all models and their properties\n@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\".}\n@returns(200) {data: [map]} # Returns a list of models or RSS feed\n@errors {400: Bad Request - Invalid request parameters, 500: Internal Server Error}\n\n@endpoint GET /models/user\n@desc List models filtered by user provider preferences, privacy settings, and guardrails\n@returns(200) {data: [map]} # Returns a list of models filtered by user provider preferences\n@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - No eligible endpoints found, 500: Internal Server Error}\n\n@endpoint GET /models/{author}/{slug}/endpoints\n@desc List all endpoints for a model\n@required {author: str, slug: str}\n@returns(200) {data: map{id: str, name: str, created: num, description: str, architecture: any, endpoints: [map]}} # Returns a list of endpoints\n@errors {404: Not Found - Model does not exist, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group endpoints\n@endpoint GET /endpoints/zdr\n@desc Preview the impact of ZDR on the available endpoints\n@returns(200) {data: [map]} # Returns a list of endpoints\n@errors {500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group providers\n@endpoint GET /providers\n@desc List all providers\n@returns(200) {data: [map]} # Returns a list of providers\n@errors {500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group keys\n@endpoint GET /keys\n@desc List API keys\n@optional {include_disabled: str # Whether to include disabled API keys in the response, offset: str # Number of API keys to skip for pagination}\n@returns(200) {data: [map]} # List of API keys\n@errors {401: Unauthorized - Missing or invalid authentication, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}\n\n@endpoint POST /keys\n@desc Create a new API key\n@required {name: str # Name for the new API key}\n@optional {limit: num # 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}\n@returns(201) {data: map{hash: str, name: str, label: str, disabled: bool, limit: num?, limit_remaining: num?, limit_reset: str?, include_byok_in_limit: bool, usage: num, usage_daily: num, usage_weekly: num, usage_monthly: num, byok_usage: num, byok_usage_daily: num, byok_usage_weekly: num, byok_usage_monthly: num, created_at: str, updated_at: str?, expires_at: str(date-time)?, creator_user_id: str?}, key: str} # API key created successfully\n@errors {400: Bad Request - Invalid request parameters, 401: Unauthorized - Missing or invalid authentication, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}\n\n@endpoint PATCH /keys/{hash}\n@desc Update an API key\n@required {hash: str # The hash identifier of the API key to update}\n@optional {name: str # New name for the API key, disabled: bool # Whether to disable the API key, limit: num # 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}\n@returns(200) {data: map{hash: str, name: str, label: str, disabled: bool, limit: num?, limit_remaining: num?, limit_reset: str?, include_byok_in_limit: bool, usage: num, usage_daily: num, usage_weekly: num, usage_monthly: num, byok_usage: num, byok_usage_daily: num, byok_usage_weekly: num, byok_usage_monthly: num, created_at: str, updated_at: str?, expires_at: str(date-time)?, creator_user_id: str?}} # API key updated successfully\n@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}\n\n@endpoint DELETE /keys/{hash}\n@desc Delete an API key\n@required {hash: str # The hash identifier of the API key to delete}\n@returns(200) {deleted: bool} # API key deleted successfully\n@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - API key does not exist, 429: Too Many Requests - Rate limit exceeded, 500: Internal Server Error}\n\n@endpoint GET /keys/{hash}\n@desc Get a single API key\n@required {hash: str # The hash identifier of the API key to retrieve}\n@returns(200) {data: map{hash: str, name: str, label: str, disabled: bool, limit: num?, limit_remaining: num?, limit_reset: str?, include_byok_in_limit: bool, usage: num, usage_daily: num, usage_weekly: num, usage_monthly: num, byok_usage: num, byok_usage_daily: num, byok_usage_weekly: num, byok_usage_monthly: num, created_at: str, updated_at: str?, expires_at: str(date-time)?, creator_user_id: str?}} # API key details\n@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}\n\n@endgroup\n\n@group guardrails\n@endpoint GET /guardrails\n@desc List guardrails\n@optional {offset: str # Number of records to skip for pagination, limit: str # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: num} # List of guardrails\n@errors {401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}\n\n@endpoint POST /guardrails\n@desc Create a guardrail\n@required {name: str # Name for the new guardrail}\n@optional {description: str # Description of the guardrail, limit_usd: num # Spending limit in USD, reset_interval: str(daily/weekly/monthly) # Interval at which the limit resets (daily, weekly, monthly), 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}\n@returns(201) {data: map{id: str(uuid), name: str, description: str?, limit_usd: num?, reset_interval: str?, allowed_providers: [str]?, ignored_providers: [str]?, allowed_models: [str]?, enforce_zdr: bool?, created_at: str, updated_at: str?}} # Guardrail created successfully\n@errors {400: Bad Request - Invalid request parameters, 401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}\n\n@endpoint GET /guardrails/{id}\n@desc Get a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail to retrieve}\n@returns(200) {data: map{id: str(uuid), name: str, description: str?, limit_usd: num?, reset_interval: str?, allowed_providers: [str]?, ignored_providers: [str]?, allowed_models: [str]?, enforce_zdr: bool?, created_at: str, updated_at: str?}} # Guardrail details\n@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - Guardrail does not exist, 500: Internal Server Error}\n\n@endpoint PATCH /guardrails/{id}\n@desc Update a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail to update}\n@optional {name: str # New name for the guardrail, description: str # New description for the guardrail, limit_usd: num # New spending limit in USD, reset_interval: str(daily/weekly/monthly) # Interval at which the limit resets (daily, weekly, monthly), 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}\n@returns(200) {data: map{id: str(uuid), name: str, description: str?, limit_usd: num?, reset_interval: str?, allowed_providers: [str]?, ignored_providers: [str]?, allowed_models: [str]?, enforce_zdr: bool?, created_at: str, updated_at: str?}} # Guardrail updated successfully\n@errors {400: Bad Request - Invalid request parameters, 401: Unauthorized - Missing or invalid authentication, 404: Not Found - Guardrail does not exist, 500: Internal Server Error}\n\n@endpoint DELETE /guardrails/{id}\n@desc Delete a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail to delete}\n@returns(200) {deleted: bool} # Guardrail deleted successfully\n@errors {401: Unauthorized - Missing or invalid authentication, 404: Not Found - Guardrail does not exist, 500: Internal Server Error}\n\n@endpoint GET /guardrails/assignments/keys\n@desc List all key assignments\n@optional {offset: str # Number of records to skip for pagination, limit: str # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: num} # List of key assignments\n@errors {401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}\n\n@endpoint GET /guardrails/assignments/members\n@desc List all member assignments\n@optional {offset: str # Number of records to skip for pagination, limit: str # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: num} # List of member assignments\n@errors {401: Unauthorized - Missing or invalid authentication, 500: Internal Server Error}\n\n@endpoint GET /guardrails/{id}/assignments/keys\n@desc List key assignments for a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail}\n@optional {offset: str # Number of records to skip for pagination, limit: str # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: num} # List of key assignments\n@errors {401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}\n\n@endpoint POST /guardrails/{id}/assignments/keys\n@desc Bulk assign keys to a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, key_hashes: [str] # Array of API key hashes to assign to the guardrail}\n@returns(200) {assigned_count: num} # Assignment result\n@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}\n\n@endpoint GET /guardrails/{id}/assignments/members\n@desc List member assignments for a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail}\n@optional {offset: str # Number of records to skip for pagination, limit: str # Maximum number of records to return (max 100)}\n@returns(200) {data: [map], total_count: num} # List of member assignments\n@errors {401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}\n\n@endpoint POST /guardrails/{id}/assignments/members\n@desc Bulk assign members to a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, member_user_ids: [str] # Array of member user IDs to assign to the guardrail}\n@returns(200) {assigned_count: num} # Assignment result\n@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}\n\n@endpoint POST /guardrails/{id}/assignments/keys/remove\n@desc Bulk unassign keys from a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, key_hashes: [str] # Array of API key hashes to unassign from the guardrail}\n@returns(200) {unassigned_count: num} # Unassignment result\n@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}\n\n@endpoint POST /guardrails/{id}/assignments/members/remove\n@desc Bulk unassign members from a guardrail\n@required {id: str(uuid) # The unique identifier of the guardrail, member_user_ids: [str] # Array of member user IDs to unassign from the guardrail}\n@returns(200) {unassigned_count: num} # Unassignment result\n@errors {400: Bad Request - Invalid input, 401: Unauthorized - Missing or invalid authentication, 404: Guardrail not found, 500: Internal Server Error}\n\n@endgroup\n\n@group key\n@endpoint GET /key\n@desc Get current API key\n@returns(200) {data: map{label: str, limit: num?, usage: num, usage_daily: num, usage_weekly: num, usage_monthly: num, byok_usage: num, byok_usage_daily: num, byok_usage_weekly: num, byok_usage_monthly: num, is_free_tier: bool, is_management_key: bool, is_provisioning_key: bool, limit_remaining: num?, limit_reset: str?, include_byok_in_limit: bool, expires_at: str(date-time)?, creator_user_id: str?, rate_limit: map{requests: num, interval: str, note: str}}} # API key details\n@errors {401: Unauthorized - Authentication required or invalid credentials, 500: Internal Server Error - Unexpected server error}\n\n@endgroup\n\n@group auth\n@endpoint POST /auth/keys\n@desc Exchange authorization code for API key\n@required {code: str # The authorization code received from the OAuth redirect}\n@optional {code_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}\n@returns(200) {key: str, user_id: str?} # Successfully exchanged code for an API key\n@errors {400: Bad Request - Invalid request parameters or malformed input, 403: Forbidden - Authentication successful but insufficient permissions, 500: Internal Server Error - Unexpected server error}\n\n@endpoint POST /auth/keys/code\n@desc Create authorization code\n@required {callback_url: str(uri) # The callback URL to redirect to after authorization. Note, only https URLs on ports 443 and 3000 are allowed.}\n@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 # 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}\n@returns(200) {data: map{id: str, app_id: num, created_at: str}} # Successfully created authorization code\n@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}\n\n@endgroup\n\n@end\n"}}