{"openapi":"3.1.0","info":{"title":"Key Router API","version":"0.1.0","description":"OpenAPI reference for the internal key-routing platform. Dashboard APIs use an authenticated Clerk browser session. The proxy API uses a virtual-key bearer token."},"servers":[{"url":"https://muxapi.dev","description":"Application server"}],"tags":[{"name":"Real Keys","description":"Manage upstream provider credentials."},{"name":"Virtual Keys","description":"Create and manage client-facing virtual keys."},{"name":"Routes","description":"Attach real keys to virtual keys in priority order."},{"name":"Logs","description":"Inspect recent proxy attempts and request outcomes."},{"name":"Usage","description":"Read plan capabilities and usage summaries."},{"name":"Security","description":"Password-protected virtual-key reveal flows."},{"name":"Proxy","description":"OpenAI-compatible chat completion proxy."},{"name":"Debug","description":"Internal-only debugging helpers for plan switching."}],"components":{"securitySchemes":{"ClerkBrowserSession":{"type":"apiKey","in":"cookie","name":"__session","description":"Dashboard APIs expect an authenticated Clerk browser session."},"VirtualKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Use `Bearer <virtual-key>` when calling the proxy route."}},"schemas":{"ErrorStringResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ValidationErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"required":["error","details"]},"ProxyErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"scope":{"type":"string","enum":["user","virtualKey"],"nullable":true},"limit":{"type":"integer","nullable":true},"current":{"type":"integer","nullable":true},"remaining":{"type":"integer","nullable":true},"retryAfterSeconds":{"type":"integer","nullable":true},"resetAt":{"type":"string","format":"date-time","nullable":true},"period":{"type":"string","nullable":true},"latencyMs":{"type":"integer","nullable":true}},"required":["message"]}},"required":["error"]},"RealKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"last4":{"type":"string"},"baseUrl":{"type":["string","null"],"format":"uri"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","last4","baseUrl","isActive","createdAt","updatedAt"]},"RealKeyCreateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"apiKey":{"type":"string","minLength":10,"description":"Stored encrypted. Input is sanitized to remove hidden characters and whitespace."},"baseUrl":{"type":"string","format":"uri","nullable":true}},"required":["name","apiKey"]},"RealKeyToggleRequest":{"type":"object","properties":{"isActive":{"type":"boolean"}},"required":["isActive"]},"VirtualKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"isActive":{"type":"boolean"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"rpmLimit":{"type":["integer","null"]},"monthlyRequestLimit":{"type":["integer","null"]},"monthlyTokenLimit":{"type":["integer","null"],"description":"Per-key monthly token cap, available on all plans (no plan-level token quota)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","keyPrefix","isActive","lastUsedAt","rpmLimit","monthlyRequestLimit","monthlyTokenLimit","createdAt","updatedAt"]},"VirtualKeyListItem":{"allOf":[{"$ref":"#/components/schemas/VirtualKey"},{"type":"object","properties":{"_count":{"type":"object","properties":{"routes":{"type":"integer"}},"required":["routes"]}},"required":["_count"]}]},"VirtualKeyCreateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"]},"VirtualKeyPatchRequest":{"type":"object","description":"At least one field must be provided. `monthlyTokenLimit` sets a per-key token cap and is accepted on all plans.","properties":{"isActive":{"type":"boolean"},"rpmLimit":{"type":["integer","null"],"minimum":0},"monthlyRequestLimit":{"type":["integer","null"],"minimum":0},"monthlyTokenLimit":{"type":["integer","null"],"minimum":0}},"additionalProperties":false},"VirtualKeyRouteCreateRequest":{"type":"object","properties":{"realKeyId":{"type":"string"},"priority":{"type":"integer","minimum":1}},"required":["realKeyId","priority"]},"VirtualKeyRouteUpdateRequest":{"type":"object","properties":{"priority":{"type":"integer","minimum":1},"enabled":{"type":"boolean"}},"additionalProperties":false},"RouteRealKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"last4":{"type":"string"},"baseUrl":{"type":["string","null"],"format":"uri"},"isActive":{"type":"boolean"}},"required":["id","name","last4","baseUrl","isActive"]},"VirtualKeyRoute":{"type":"object","properties":{"id":{"type":"string"},"priority":{"type":"integer"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"realKey":{"$ref":"#/components/schemas/RouteRealKey"}},"required":["id","priority","enabled","createdAt","realKey"]},"RequestLogEntry":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string"},"model":{"type":["string","null"]},"success":{"type":"boolean"},"statusCode":{"type":["integer","null"]},"errorMessage":{"type":["string","null"]},"latencyMs":{"type":["integer","null"]},"attemptNumber":{"type":"integer"},"inputTokens":{"type":["integer","null"]},"outputTokens":{"type":["integer","null"]},"totalTokens":{"type":["integer","null"]},"sourceIp":{"type":["string","null"],"description":"Enterprise-only. Omitted entirely for lower plans."},"originHeader":{"type":["string","null"],"description":"Enterprise-only. Omitted entirely for lower plans."},"refererHeader":{"type":["string","null"],"description":"Enterprise-only. Omitted entirely for lower plans."},"userAgent":{"type":["string","null"],"description":"Enterprise-only. Omitted entirely for lower plans."},"createdAt":{"type":"string","format":"date-time"},"virtualKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"}},"required":["id","name","keyPrefix"]},"realKey":{"anyOf":[{"$ref":"#/components/schemas/RouteRealKey"},{"type":"null"}]}},"required":["id","endpoint","model","success","statusCode","errorMessage","latencyMs","attemptNumber","inputTokens","outputTokens","totalTokens","createdAt","virtualKey","realKey"]},"SetRevealPasswordRequest":{"type":"object","properties":{"password":{"type":"string","minLength":8,"maxLength":100},"currentPassword":{"type":"string","minLength":8,"maxLength":100,"nullable":true}},"required":["password"]},"RevealVirtualKeyRequest":{"type":"object","properties":{"password":{"type":"string","minLength":8,"maxLength":100}},"required":["password"]},"DebugPlanResponse":{"type":"object","properties":{"planTier":{"type":"string"},"supportedPlans":{"type":"array","items":{"type":"string"}},"capabilities":{"type":"object","properties":{"limits":{"type":"object","properties":{"accountRpmLimit":{"type":"integer"},"defaultVirtualKeyRpmLimit":{"type":"integer"},"monthlyRequestLimit":{"type":["integer","null"]},"monthlyTokenLimit":{"type":["integer","null"]}},"required":["accountRpmLimit","defaultVirtualKeyRpmLimit","monthlyRequestLimit","monthlyTokenLimit"]},"features":{"type":"object","additionalProperties":{"type":"boolean"}}},"required":["limits","features"]},"security":{"type":"object","properties":{"hasRevealPassword":{"type":"boolean"}},"required":["hasRevealPassword"]}},"required":["planTier","supportedPlans","capabilities","security"]},"UpdatePlanTierRequest":{"type":"object","properties":{"planTier":{"type":"string","enum":["trial","starter","pro","scale","enterprise"]}},"required":["planTier"]},"UsageSummary":{"type":"object","description":"Aggregated plan, account, and per-virtual-key usage details for the current month and recent daily activity.","properties":{"plan":{"type":"object","additionalProperties":true},"security":{"type":"object","additionalProperties":true},"period":{"type":"object","additionalProperties":true},"account":{"type":"object","additionalProperties":true},"virtualKeys":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["plan","security","period","account","virtualKeys"]},"ChatCompletionProxyRequest":{"type":"object","description":"OpenAI-compatible chat completions request. Additional upstream-supported fields are forwarded as-is.","properties":{"model":{"type":"string"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{}},"required":["role","content"],"additionalProperties":true}},"stream":{"type":"boolean","description":"Accepted for compatibility, but streaming responses are not supported by this proxy."}},"required":["model","messages"],"additionalProperties":true},"ChatCompletionProxyResponse":{"type":"object","description":"Pass-through upstream response body. Successful responses often include a `usage` object.","additionalProperties":true}}},"paths":{"/api/real-keys":{"get":{"tags":["Real Keys"],"summary":"List real keys","security":[{"ClerkBrowserSession":[]}],"responses":{"200":{"description":"Real keys for the authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"realKeys":{"type":"array","items":{"$ref":"#/components/schemas/RealKey"}}},"required":["realKeys"]}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}}}},"post":{"tags":["Real Keys"],"summary":"Create a real key","security":[{"ClerkBrowserSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealKeyCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"realKey":{"$ref":"#/components/schemas/RealKey"}},"required":["realKey"]}}}},"400":{"description":"Invalid payload or unsafe real key","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ErrorStringResponse"},{"$ref":"#/components/schemas/ValidationErrorResponse"}]}}}}}}},"/api/real-keys/{id}":{"patch":{"tags":["Real Keys"],"summary":"Toggle a real key","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealKeyToggleRequest"}}}},"responses":{"200":{"description":"Updated real key","content":{"application/json":{"schema":{"type":"object","properties":{"realKey":{"$ref":"#/components/schemas/RealKey"}},"required":["realKey"]}}}},"404":{"description":"Real key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}}}}},"/api/virtual-keys":{"get":{"tags":["Virtual Keys"],"summary":"List virtual keys","security":[{"ClerkBrowserSession":[]}],"responses":{"200":{"description":"Virtual keys for the authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"virtualKeys":{"type":"array","items":{"$ref":"#/components/schemas/VirtualKeyListItem"}}},"required":["virtualKeys"]}}}}}},"post":{"tags":["Virtual Keys"],"summary":"Create a virtual key","security":[{"ClerkBrowserSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VirtualKeyCreateRequest"}}}},"responses":{"201":{"description":"Created virtual key. The raw key is returned once and should be stored immediately.","content":{"application/json":{"schema":{"type":"object","properties":{"virtualKey":{"$ref":"#/components/schemas/VirtualKey"},"rawKey":{"type":"string"},"message":{"type":"string"}},"required":["virtualKey","rawKey","message"]}}}},"400":{"description":"Invalid payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/api/virtual-keys/{id}":{"patch":{"tags":["Virtual Keys"],"summary":"Update a virtual key","description":"Toggle active state and update per-key limits. The monthly token cap can be set on all plans.","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VirtualKeyPatchRequest"}}}},"responses":{"200":{"description":"Updated virtual key","content":{"application/json":{"schema":{"type":"object","properties":{"virtualKey":{"$ref":"#/components/schemas/VirtualKey"}},"required":["virtualKey"]}}}},"403":{"description":"Monthly token limit is not available for the current plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}},"404":{"description":"Virtual key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}}}}},"/api/virtual-keys/{id}/routes":{"get":{"tags":["Routes"],"summary":"List routes for a virtual key","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current route chain for the virtual key","content":{"application/json":{"schema":{"type":"object","properties":{"virtualKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"routes":{"type":"array","items":{"$ref":"#/components/schemas/VirtualKeyRoute"}}},"required":["virtualKey","routes"]}}}}}},"post":{"tags":["Routes"],"summary":"Create a route","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VirtualKeyRouteCreateRequest"}}}},"responses":{"201":{"description":"Created route","content":{"application/json":{"schema":{"type":"object","properties":{"route":{"$ref":"#/components/schemas/VirtualKeyRoute"}},"required":["route"]}}}},"409":{"description":"Priority conflict or duplicate real-key attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}}}}},"/api/routes/{routeId}":{"patch":{"tags":["Routes"],"summary":"Update a route","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VirtualKeyRouteUpdateRequest"}}}},"responses":{"200":{"description":"Updated route","content":{"application/json":{"schema":{"type":"object","properties":{"route":{"$ref":"#/components/schemas/VirtualKeyRoute"}},"required":["route"]}}}},"404":{"description":"Route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}}}},"delete":{"tags":["Routes"],"summary":"Delete a route","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted route","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}}}}},"/api/logs":{"get":{"tags":["Logs"],"summary":"List recent request logs","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"query","name":"virtualKeyId","required":false,"schema":{"type":"string"},"description":"Filter logs to a specific virtual key"},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Recent request logs","content":{"application/json":{"schema":{"type":"object","properties":{"logs":{"type":"array","items":{"$ref":"#/components/schemas/RequestLogEntry"}}},"required":["logs"]}}}}}}},"/api/usage/summary":{"get":{"tags":["Usage"],"summary":"Get usage summary","security":[{"ClerkBrowserSession":[]}],"responses":{"200":{"description":"Plan, quota, and usage summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}}}}}},"/api/user/reveal-password":{"post":{"tags":["Security"],"summary":"Set or change reveal password","security":[{"ClerkBrowserSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetRevealPasswordRequest"}}}},"responses":{"200":{"description":"Reveal password saved","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/virtual-keys/{id}/reveal":{"post":{"tags":["Security"],"summary":"Reveal the raw virtual key","description":"Returns the actual raw virtual key after password verification.","security":[{"ClerkBrowserSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealVirtualKeyRequest"}}}},"responses":{"200":{"description":"Revealed virtual key","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"rawKey":{"type":"string"}},"required":["id","name","keyPrefix","rawKey"]}}}},"403":{"description":"Invalid password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorStringResponse"}}}}}}},"/api/plan":{"get":{"tags":["Usage"],"summary":"Get current plan details","description":"Returns the current user's plan limits, feature flags, and reveal-password status.","security":[{"ClerkBrowserSession":[]}],"responses":{"200":{"description":"Current plan and capabilities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebugPlanResponse"}}}}}}},"/v1/chat/completions":{"post":{"tags":["Proxy"],"summary":"OpenAI-compatible chat completions proxy","description":"Authenticates with a virtual key, applies account and per-key limits, then forwards the request to the configured upstream route chain.","security":[{"VirtualKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionProxyRequest"}}}},"responses":{"200":{"description":"Successful upstream response body, passed through by the proxy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionProxyResponse"}}}},"400":{"description":"No routes or no active real keys are available for the virtual key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyErrorResponse"}}}},"401":{"description":"Invalid or inactive virtual key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyErrorResponse"}}}},"429":{"description":"Rate limit, monthly request quota, or monthly token quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyErrorResponse"}}}},"502":{"description":"All upstream attempts failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyErrorResponse"}}}}}}}}}