{"openapi":"3.1.0","info":{"title":"OneAPIKey","version":"1.0.0","description":"One key, all the AI providers. OpenAI-compatible chat completions, wallet ledger, cost predictor, and recommendation engine across 12+ providers.","contact":{"url":"https://oneapikey.app/contact","email":"elia@oneapikey.app"},"license":{"name":"Proprietary","url":"https://oneapikey.app/terms"}},"servers":[{"url":"https://oneapikey.app","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Chat","description":"OpenAI-compatible chat completions across all providers"},{"name":"Wallet","description":"Prepaid credit balance + ledger"},{"name":"Cost","description":"Cross-provider cost prediction (no auth)"},{"name":"Recommend","description":"Cheaper alternatives suggestions"},{"name":"Proxy","description":"Native pass-through to any provider"},{"name":"OAuth","description":"Sign in with OneAPIKey"}],"paths":{"/api/v1/chat/completions":{"post":{"tags":["Chat"],"summary":"Chat completion (OpenAI-compatible)","description":"Drop-in replacement for OpenAI's /v1/chat/completions. Set `model` to any OneAPIKey slug (gpt-5, claude-opus-4-7, gemini-2-5-pro, ...), a meta-model (`auto/frontier`, `auto/cheap`, ...), or your custom RoutingPolicy slug.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Success","headers":{"x-oneapikey-cost-usd":{"schema":{"type":"string"},"description":"Cost of this call in USD"},"x-oneapikey-cheaper-available":{"schema":{"type":"string"},"description":"Slug of a cheaper model with similar quality (when applicable)"},"x-oneapikey-cheaper-savings-pct":{"schema":{"type":"string"},"description":"Savings percent vs. current model"},"x-oneapikey-fallback-chain":{"schema":{"type":"string"},"description":"Chain of attempted models with status codes"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/predict-cost":{"post":{"tags":["Cost"],"summary":"Predict cost across all models","description":"Public, no auth. Returns ranked cost estimates for every active model.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string"},"output_tokens":{"type":"integer","minimum":0},"task_type":{"type":"string","description":"Optional: enables quality-aware ranking"}}}}}},"responses":{"200":{"description":"Ranked model cost estimates"}}}},"/api/v1/recommend":{"post":{"tags":["Recommend"],"summary":"Suggest cheaper alternatives","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["current_model","input_tokens"],"properties":{"current_model":{"type":"string"},"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"task_type":{"type":"string"},"max_quality_drop":{"type":"number","minimum":0,"maximum":100,"default":10}}}}}},"responses":{"200":{"description":"Top alternatives ranked by savings"}}}},"/api/v1/wallet/balance":{"get":{"tags":["Wallet"],"summary":"Get wallet balance","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Balance in micros + USD"}}}},"/api/v1/wallet/charge":{"post":{"tags":["Wallet"],"summary":"Debit the wallet","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount_micros","description"],"properties":{"amount_micros":{"type":"integer"},"description":{"type":"string"},"idempotency_key":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated balance"},"402":{"description":"Insufficient funds"}}}},"/api/v1/wallet/ledger":{"get":{"tags":["Wallet"],"summary":"List recent ledger entries","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Ledger entries"}}}},"/api/proxy/{productSlug}":{"post":{"tags":["Proxy"],"summary":"Native pass-through to a provider","parameters":[{"name":"productSlug","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Upstream response"}}}},"/api/oauth/token":{"post":{"tags":["OAuth"],"summary":"Token endpoint (RFC 6749)","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"code":{"type":"string"},"redirect_uri":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string"},"code_verifier":{"type":"string"},"refresh_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Tokens"}}}},"/api/oauth/userinfo":{"get":{"tags":["OAuth"],"summary":"UserInfo endpoint (OIDC)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"User claims"},"401":{"description":"Invalid token"}}}},"/api/oauth/revoke":{"post":{"tags":["OAuth"],"summary":"Revoke a token (RFC 7009)","responses":{"200":{"description":"Always returns 200"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"OneAPIKey","description":"Use your API key as a bearer token: `Authorization: Bearer oak_live_...`"}},"schemas":{"ChatRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","description":"Model slug or meta-model or routing policy"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{"type":"string"}}}},"temperature":{"type":"number","minimum":0,"maximum":2},"max_tokens":{"type":"integer","minimum":1},"stream":{"type":"boolean","default":false},"tools":{"type":"array","items":{"type":"object"}}}},"ChatResponse":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object"}},"usage":{"type":"object"}}}},"responses":{"Error":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}