{"openapi":"3.0.3","info":{"title":"AI Budget Planner API","version":"1.1.0","description":"Stateless LLM spend tracking — allocate monthly budgets per team/department, monitor utilisation across OpenAI/Anthropic/Google/Mistral/Cohere, receive threshold alerts, and pull weekly + department digest reports.","contact":{"url":"https://api.lazy-mac.com/ai-budget-planner"}},"servers":[{"url":"https://api.lazy-mac.com/ai-budget-planner"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Budget":{"type":"object","properties":{"id":{"type":"string","example":"bgt_k9xm2qa3rl7z"},"name":{"type":"string","example":"Engineering AI Budget"},"department":{"type":"string","example":"engineering"},"monthly_limit_usd":{"type":"number","example":500},"spent_usd":{"type":"number","example":187.4},"remaining_usd":{"type":"number","example":312.6},"utilisation_pct":{"type":"number","example":37.48},"status":{"type":"string","enum":["healthy","warning","critical","exhausted"]},"currency":{"type":"string","example":"USD"},"providers_covered":{"type":"array","items":{"type":"string"}},"spend_by_provider":{"type":"object"},"triggered_alerts":{"type":"array","items":{"type":"object"}},"cycle":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Alert":{"type":"object","properties":{"threshold_pct":{"type":"number"},"triggered_at":{"type":"string","format":"date-time"},"message":{"type":"string"},"severity":{"type":"string","enum":["low","medium","high","critical"]}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"hint":{"type":"string"}}}}},"security":[{"apiKey":[]}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"healthCheck","security":[],"responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"version":{"type":"string"},"ts":{"type":"string"}}}}}}}}},"/providers":{"get":{"summary":"List supported LLM providers and models","operationId":"listProviders","security":[],"responses":{"200":{"description":"Providers list with blended cost estimates"}}}},"/budgets":{"post":{"summary":"Create a budget allocation","operationId":"createBudget","description":"Define a monthly spend limit for a team/department across specified LLM providers. Returns a budget record with a deterministic ID derived from (api_key + name + department + limit).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","monthly_limit_usd"],"properties":{"name":{"type":"string","example":"Engineering AI Budget"},"department":{"type":"string","example":"engineering"},"monthly_limit_usd":{"type":"number","minimum":1,"example":500},"providers":{"type":"array","items":{"type":"string","enum":["openai","anthropic","google","mistral","cohere"]},"example":["openai","anthropic"]}}}}}},"responses":{"201":{"description":"Budget created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Budget"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/budgets/{id}":{"get":{"summary":"Get budget by ID","operationId":"getBudget","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bgt_k9xm2qa3rl7z"}],"responses":{"200":{"description":"Budget record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Budget"}}}},"401":{"description":"Missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Budget not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/budgets/{id}/alerts":{"get":{"summary":"List triggered alerts for a budget","operationId":"getBudgetAlerts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alerts list","content":{"application/json":{"schema":{"type":"object","properties":{"budget_id":{"type":"string"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"total":{"type":"integer"},"next_threshold_pct":{"type":"number","nullable":true},"generated_at":{"type":"string"}}}}}},"401":{"description":"Missing API key"},"404":{"description":"Budget not found"}}}},"/reports/weekly":{"get":{"summary":"Weekly spend digest","operationId":"getWeeklyReport","description":"7-day aggregated LLM spend broken down by department and provider. Optionally filter by department or provider.","parameters":[{"name":"department","in":"query","required":false,"schema":{"type":"string"},"example":"engineering"},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","anthropic","google","mistral","cohere"]}}],"responses":{"200":{"description":"Weekly digest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/reports/department":{"get":{"summary":"Per-department spend summary","operationId":"getDepartmentReport","description":"Month-to-date spend totals, budget utilisation, and alert status per department.","parameters":[{"name":"department","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Department report","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/mcp":{"get":{"summary":"MCP server info (browser-friendly)","operationId":"mcpInfo","security":[],"responses":{"200":{"description":"MCP server metadata and tool list"}}},"post":{"summary":"MCP endpoint (JSON-RPC 2.0)","operationId":"mcpEndpoint","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"method":{"type":"string","example":"initialize"},"id":{"type":"integer","example":1},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC response"}}}}}}