{"openapi":"3.0.3","info":{"title":"AI Rate Limit Tracker API","version":"1.2.0","description":"Track and forecast AI provider rate limit usage across OpenAI, Anthropic, Gemini, Groq, Cohere, Mistral, and more. Sliding-window counters, exhaustion forecasting, scheduling recommendations.","contact":{"url":"https://api.lazy-mac.com/ai-rate-limit-tracker"}},"servers":[{"url":"https://api.lazy-mac.com/ai-rate-limit-tracker"}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"version":{"type":"string"},"ts":{"type":"string","format":"date-time"}}},"example":{"ok":true,"service":"ai-rate-limit-tracker","version":"1.2.0","ts":"2026-06-01T00:00:00.000Z"}}}}}}},"/providers":{"get":{"summary":"List all supported AI providers and their models","operationId":"listProviders","responses":{"200":{"description":"Provider list with default limits","content":{"application/json":{"schema":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"}}}}}}}}},"/limits/{provider}":{"get":{"summary":"Get published rate limit specs for a provider and optional model","operationId":"getLimits","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["openai","anthropic","gemini","groq","cohere","mistral","together","deepseek"]},"description":"AI provider name"},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Specific model (e.g. gpt-4o, claude-3-5-sonnet-20241022)"}],"responses":{"200":{"description":"Rate limit spec","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string","nullable":true},"limits":{"type":"object","properties":{"rpm":{"type":"integer","description":"Requests per minute"},"tpm":{"type":"integer","description":"Tokens per minute"},"rpd":{"type":"integer","nullable":true,"description":"Requests per day"},"context":{"type":"integer","description":"Max context window tokens"},"tier":{"type":"string"}}}}},"example":{"provider":"openai","model":"gpt-4o","limits":{"rpm":500,"tpm":30000,"rpd":10000,"context":128000,"tier":"tier1"}}}}},"404":{"description":"Unknown provider or model"}}}},"/track":{"post":{"summary":"Record a completed API call and get real-time usage + warnings","operationId":"trackUsage","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","description":"AI provider (openai, anthropic, gemini, …)"},"model":{"type":"string","description":"Model name (optional)"},"tokens_used":{"type":"integer","description":"Total tokens consumed (prompt+completion)"},"request_tokens":{"type":"integer","description":"Prompt tokens (alternative to tokens_used)"},"response_tokens":{"type":"integer","description":"Completion tokens (alternative to tokens_used)"},"latency_ms":{"type":"integer","description":"Request latency in ms (optional, for observability)"}}},"example":{"provider":"openai","model":"gpt-4o","tokens_used":1500,"latency_ms":420}}}},"responses":{"200":{"description":"Usage tracked; includes warnings if approaching limits","content":{"application/json":{"schema":{"type":"object","properties":{"tracked":{"type":"boolean"},"usage":{"type":"object"},"warnings":{"type":"array","items":{"type":"object"}},"alert":{"type":"boolean"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Missing API key"}}}},"/usage":{"get":{"summary":"Get current window usage for a provider+model","operationId":"getUsage","security":[{"apiKey":[]}],"parameters":[{"name":"provider","in":"query","required":true,"schema":{"type":"string"}},{"name":"model","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current usage counters","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string","nullable":true},"usage":{"type":"object"},"limits":{"type":"object"}}}}}},"401":{"description":"Missing API key"}}}},"/forecast":{"get":{"summary":"Forecast when rate limits will be exhausted based on current usage velocity","operationId":"forecastLimits","security":[{"apiKey":[]}],"parameters":[{"name":"provider","in":"query","required":true,"schema":{"type":"string"}},{"name":"model","in":"query","required":false,"schema":{"type":"string"}},{"name":"rate_rpm","in":"query","required":false,"schema":{"type":"number"},"description":"Override: your actual requests/min rate"}],"responses":{"200":{"description":"Forecast with recommendations","content":{"application/json":{"schema":{"type":"object","properties":{"forecast":{"type":"object"},"recommendations":{"type":"array","items":{"type":"object"}},"effective_rate_rpm":{"type":"number"}}},"example":{"provider":"openai","model":"gpt-4o","effective_rate_rpm":12.5,"forecast":{"rpm":{"exhausts_in_minutes":28.3,"pct":30,"current":150,"limit":500,"reset_at":"2026-06-01T00:01:00Z"},"rpd":{"exhausts_in_minutes":null,"pct":5,"current":500,"limit":10000,"reset_at":"2026-06-02T00:00:00Z"}},"recommendations":[{"urgency":"none","action":"continue","msg":"Usage within safe bounds."}]}}}},"401":{"description":"Missing API key"}}}},"/mcp":{"get":{"summary":"MCP endpoint info (browser-friendly)","operationId":"mcpInfo","responses":{"200":{"description":"MCP connection info"}}},"post":{"summary":"MCP endpoint (JSON-RPC 2.0)","operationId":"mcpEndpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"method":{"type":"string","example":"tools/list"},"id":{"type":"integer"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}