{"openapi":"3.1.0","info":{"title":"LLM Pricing MCP Server","description":"## LLM Pricing MCP Server\n\nReal-time pricing comparison for **12+ LLM providers** (OpenAI, Anthropic, Google, Cohere, Mistral, Meta, xAI, DeepSeek, and more).\n\n### Key capabilities\n- **Live pricing** — sub-second model cost lookup across all providers\n- **Cost estimation** — token-level cost calculator with batch support\n- **Performance benchmarks** — quality scores and value-index rankings\n- **Intelligent router** — automatically picks the best model for your workload\n- **Price alerts** — webhook notifications when a model's price changes\n- **RAG agent** — conversational assistant with full pricing context\n- **Billing / SaaS** — Stripe-powered free / pro / enterprise tiers\n\n### Authentication\nMost read endpoints are **public** (no key required).\nMutating and admin endpoints require `X-API-Key: <your-key>` in the request header.\n\n### Rate limits\n| Tier | Limit |\n|------|-------|\n| Free | 30 req / min |\n| Pro | 120 req / min |\n| Enterprise | 600 req / min |\n\nPass `X-Api-Key-Tier: free|pro|enterprise` to select your bucket.\n\n### MCP transport\nThe server exposes an HTTP MCP endpoint at `/mcp` for direct integration with Claude Desktop, Cursor, and other MCP-compatible clients.\n","contact":{"name":"LLM Pricing MCP Server","url":"https://llm-pricing-api.fly.dev/"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"version":"1.73.2"},"paths":{"/models":{"get":{"tags":["Pricing"],"summary":"Get Models","description":"Get a list of all available model names.\n\nThis is a lightweight endpoint for quick model discovery without full pricing data.\nUse this to find valid model names for cost estimation or performance comparison.\n\nSupported providers: OpenAI, Anthropic, Google, Cohere, Mistral AI\n\nArgs:\n    provider: Optional provider filter\n\nReturns:\n    dict: List of model names organized by provider","operationId":"get_models_models_get","parameters":[{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by provider (e.g., 'openai', 'anthropic', 'google', 'cohere', 'mistral')","title":"Provider"},"description":"Filter by provider (e.g., 'openai', 'anthropic', 'google', 'cohere', 'mistral')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing":{"get":{"tags":["Pricing"],"summary":"Get Pricing","description":"Get aggregated pricing data from multiple LLM providers.\n\nThis endpoint fetches real-time pricing data from all configured providers\nasynchronously. If a provider is unavailable, partial data is returned with\nstatus information about each provider.\n\nSupported providers: OpenAI, Anthropic, Google, Cohere, Mistral AI\n\nArgs:\n    provider: Optional provider filter\n    supports_vision: Filter to vision-capable models\n    supports_function_calling: Filter to function-calling models\n    supports_json_mode: Filter to JSON-mode models\n    batch_available: Filter to batch-API models\n    is_reasoning_model: Filter to reasoning models\n\nReturns:\n    PricingResponse: Aggregated pricing data with metrics and provider status","operationId":"get_pricing_pricing_get","parameters":[{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by provider (e.g., 'openai', 'anthropic', 'google', 'azure', 'vertex ai')","title":"Provider"},"description":"Filter by provider (e.g., 'openai', 'anthropic', 'google', 'azure', 'vertex ai')"},{"name":"supports_vision","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter to vision-capable models","title":"Supports Vision"},"description":"Filter to vision-capable models"},{"name":"supports_function_calling","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter to function-calling models","title":"Supports Function Calling"},"description":"Filter to function-calling models"},{"name":"supports_json_mode","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter to JSON-mode models","title":"Supports Json Mode"},"description":"Filter to JSON-mode models"},{"name":"batch_available","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter to batch-API models","title":"Batch Available"},"description":"Filter to batch-API models"},{"name":"is_reasoning_model","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter to reasoning/chain-of-thought models","title":"Is Reasoning Model"},"description":"Filter to reasoning/chain-of-thought models"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/data-quality":{"get":{"tags":["Pricing"],"summary":"Get Data Quality","description":"Get an aggregate accuracy summary for the pricing catalogue.\n\nReports what percentage of models have a confirmed, fresh price, how many\nare currently withheld from serving due to price drift against the\nreference registry, how many are newly discovered and not yet priced, and\nhow many confirmed prices are over 90 days old. A single trust signal for\nthe whole catalogue — see `/pricing`'s `price_confirmed`/`price_as_of`\nfields or the `check_price_drift` MCP tool for per-model detail.\n\nReturns:\n    dict: Aggregate data-quality report","operationId":"get_data_quality_data_quality_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Simple health check endpoint (backwards compatible).\n\nReturns basic health status. For production orchestrators (K8s, ECS),\nuse /health/live or /health/ready instead.\n\nReturns:\n    dict: Server health status","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/detailed":{"get":{"tags":["Health"],"summary":"Health Check Detailed","description":"Detailed health check for monitoring and load balancers.\n\nIncludes:\n- Service status and version\n- Environment and deployment information\n- Active request count and uptime\n- Dependency health (if available)\n- Graceful shutdown status\n\nUse this endpoint for comprehensive monitoring of the service.\n\nReturns:\n    HealthCheckResponse: Detailed health information","operationId":"health_check_detailed_health_detailed_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthCheckResponse"}}}}}}},"/health/ready":{"get":{"tags":["Health"],"summary":"Health Ready","description":"Kubernetes readinessProbe endpoint.\n\nReturns ready=true if the service is ready to accept traffic.\nReturns ready=false during graceful shutdown.\n\nLoad balancers should use this to determine if traffic should be routed here.\n\nReturns:\n    DeploymentReadiness: Ready status for traffic routing","operationId":"health_ready_health_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentReadiness"}}}}}}},"/health/live":{"get":{"tags":["Health"],"summary":"Health Live","description":"Kubernetes livenessProbe endpoint.\n\nReturns alive=true if the process should continue running.\nOrchestrators will restart the container if this returns false.\n\nReturns:\n    dict: Alive status","operationId":"health_live_health_live_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/deployment/metadata":{"get":{"tags":["Deployment"],"summary":"Get Deployment Metadata","description":"Get deployment metadata including version and API versioning information.\n\nIncludes:\n- Current application version\n- Supported API versions\n- Breaking changes documentation\n- Backwards compatibility information\n\nUse this endpoint to:\n- Detect breaking changes before updating clients\n- Determine API version compatibility\n- Understand deprecation timeline\n\nReturns:\n    DeploymentMetadata: Version and breaking change information","operationId":"get_deployment_metadata_deployment_metadata_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeploymentMetadata"}}}}}}},"/deployment/info":{"get":{"tags":["Deployment"],"summary":"Get Deployment Info","description":"Get deployment and blue-green environment information.\n\nIncludes:\n- Environment (production/staging)\n- Deployment group (blue/green)\n- Region and availability zone\n- Instance/container ID\n- Deployment timestamp\n\nUse this endpoint to:\n- Verify blue/green deployment during traffic switching\n- Identify which instance handled a request\n- Monitor deployment consistency\n- Debug region/zone issues\n\nReturns:\n    dict: Deployment environment information","operationId":"get_deployment_info_deployment_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/deployment/shutdown":{"post":{"tags":["Deployment"],"summary":"Initiate Graceful Shutdown","description":"Initiate graceful shutdown of the service.\n\nBlue-Green Deployment Use Case:\n1. Load balancer removes this instance from traffic routing\n2. Load balancer calls this endpoint with drain_timeout_seconds\n3. Service stops accepting new requests\n4. Service waits up to drain_timeout_seconds for in-flight requests to complete\n5. Service exits cleanly\n6. Orchestrator (K8s, ECS) replaces the instance\n\n**Important**: This endpoint should only be called by orchestrators/load balancers,\nnot by end users. Implement proper access controls.\n\nArgs:\n    request: GracefulShutdownRequest with drain timeout\n\nReturns:\n    GracefulShutdownStatus: Current shutdown status\n\nSecurity Note:\n    In production, restrict access to this endpoint using:\n    - Network policies (allow only from orchestrator/load balancer IP)\n    - API gateway authentication\n    - Service-to-service authentication","operationId":"initiate_graceful_shutdown_deployment_shutdown_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GracefulShutdownRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GracefulShutdownStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/deployment/shutdown/status":{"get":{"tags":["Deployment"],"summary":"Get Shutdown Status","description":"Get current graceful shutdown status.\n\nReturns:\n    GracefulShutdownStatus: Current shutdown state, active requests count, timeout","operationId":"get_shutdown_status_deployment_shutdown_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GracefulShutdownStatus"}}}}}}},"/api/versions":{"get":{"tags":["API Info"],"summary":"Get Api Versions","description":"Get API version information and migration guides.\n\nHelps clients understand:\n- Current stable API version\n- All available versions\n- Deprecated versions still supported\n- Breaking changes in each version\n\nUse this to plan API version upgrades.\n\nReturns:\n    ApiVersionInfo: Version compatibility information","operationId":"get_api_versions_api_versions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiVersionInfo"}}}}}}},"/cost-estimate":{"post":{"tags":["Cost Estimation"],"summary":"Estimate Cost","description":"Estimate the cost for a specific model based on token usage.\n\nThis endpoint calculates the total cost for using a specific LLM model\ngiven the number of input and output tokens. It fetches the latest pricing\ndata for the model and computes the costs.\n\nArgs:\n    request: CostEstimateRequest containing model name and token counts\n\nReturns:\n    CostEstimateResponse: Detailed cost breakdown\n\nRaises:\n    HTTPException: If the model is not found (404)","operationId":"estimate_cost_cost_estimate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostEstimateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostEstimateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cost-estimate/batch":{"post":{"tags":["Cost Estimation"],"summary":"Estimate Cost Batch","description":"Compare cost estimates across multiple models.\n\nThis endpoint calculates and compares costs for multiple LLM models\ngiven the same token usage. Useful for finding the most cost-effective\nmodel for your use case.\n\nArgs:\n    request: BatchCostEstimateRequest with model names and token counts\n\nReturns:\n    BatchCostEstimateResponse: Cost comparison across all requested models","operationId":"estimate_cost_batch_cost_estimate_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCostEstimateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCostEstimateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/performance":{"get":{"tags":["Performance"],"summary":"Get Performance","description":"Get performance metrics and comparisons for LLM models.\n\nThis endpoint provides performance data including throughput, latency,\ncontext window sizes, and calculated performance scores. Use this to\ncompare models based on performance characteristics rather than just cost.\n\nArgs:\n    provider: Optional provider filter\n    sort_by: Optional sort criteria\n\nReturns:\n    PerformanceResponse: Performance metrics with comparisons","operationId":"get_performance_performance_get","parameters":[{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by provider (e.g., 'openai', 'anthropic')","title":"Provider"},"description":"Filter by provider (e.g., 'openai', 'anthropic')"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sort by metric: 'throughput', 'latency', 'context_window', 'cost', 'value'","title":"Sort By"},"description":"Sort by metric: 'throughput', 'latency', 'context_window', 'cost', 'value'"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerformanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/use-cases":{"get":{"tags":["Performance"],"summary":"Get Use Cases","description":"Get recommended use cases and strengths for each LLM model.\n\nThis endpoint provides curated use case recommendations, key strengths,\nand ideal application areas for each available model. Use this to find\nthe best model for your specific use case.\n\nSupported providers: OpenAI, Anthropic, Google, Cohere, Mistral AI\n\nArgs:\n    provider: Optional provider filter\n\nReturns:\n    UseCaseResponse: Use case information for each model","operationId":"get_use_cases_use_cases_get","parameters":[{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by provider (e.g., 'openai', 'anthropic', 'google', 'cohere', 'mistral')","title":"Provider"},"description":"Filter by provider (e.g., 'openai', 'anthropic', 'google', 'cohere', 'mistral')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCaseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cache-stats":{"get":{"tags":["Router"],"summary":"Cache Stats","description":"Report process-lifetime hit/miss counters for the recommendation cache.\n\nCovers the two call sites the ~5-minute recommendation cache\n(introduced alongside `recommend_model` / `POST /router/recommend`) is\nwired into: the `recommend_model` MCP tool and this `POST /router/recommend`\nendpoint. Reported separately per call site, never combined — a hit via\none call site never affects the other's counts. Counts reset on process\nrestart; not persisted, not shared across replicas. Reading this endpoint\nnever itself changes the counts.\n\nReturns:\n    dict: `{\"recommend_model\": {...}, \"router_recommend\": {...}}`, each\n    with `hits`, `misses`, `total`, and `hit_rate` (percentage).","operationId":"cache_stats_cache_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/router/recommend":{"post":{"tags":["Router"],"summary":"Router Recommend","description":"Recommend the optimal LLM model for the caller's constraints.\n\nFetches live pricing, enriches with benchmark quality scores, applies hard\nfilters (cost, quality, context window), and scores survivors by\nquality_value_score.  Returns the best match and up to 3 alternatives.\n\nIdentical (normalized-equivalent) requests made within ~5 minutes of each\nother are served from an in-memory cache instead of being recomputed;\nthe response's `cached` field indicates which happened.\n\nOptionally pass `X-Organization-Id` and `X-Api-Key-Tier` headers to enable\nper-org savings tracking.","operationId":"router_recommend_router_recommend_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/telemetry/savings":{"get":{"tags":["Telemetry"],"summary":"Telemetry Savings","description":"Return routing decisions and estimated cost savings per organisation.\n\nPass `X-Organization-Id` header (or `org_id` query param) when calling\n`/router/recommend` to enable per-org tracking.  This endpoint aggregates\nthose records and computes the total savings vs. the most expensive\nalternative considered at the time of each routing decision.","operationId":"telemetry_savings_telemetry_savings_get","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by organisation ID","title":"Org Id"},"description":"Filter by organisation ID"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look-back window in days","default":30,"title":"Days"},"description":"Look-back window in days"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Max rows to return","default":100,"title":"Limit"},"description":"Max rows to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/telemetry/ide-savings":{"get":{"tags":["Telemetry"],"summary":"Ide Savings Breakdown","description":"Return routing decision counts, total savings, and acceptance rate broken down by IDE context.","operationId":"ide_savings_breakdown_telemetry_ide_savings_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look-back window in days","default":30,"title":"Days"},"description":"Look-back window in days"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage":{"post":{"tags":["Usage"],"summary":"Record Usage","description":"Record an actual LLM usage event and compute its cost from current pricing.\n\nThis is the \"actual spend\" counterpart to /cost-estimate's hypothetical numbers —\ncall this after an LLM request completes with the real token counts, and this\nendpoint looks up current pricing itself rather than trusting a client-supplied cost.\nResubmitting the same `request_id` for the same org is a no-op (idempotent).","operationId":"record_usage_usage_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageEventRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageEventResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage/batch":{"post":{"tags":["Usage"],"summary":"Record Usage Batch","description":"Record multiple usage events in one call. Best-effort: an unknown model in one\nevent does not fail the rest of the batch.","operationId":"record_usage_batch_usage_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageBatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageBatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage/summary":{"get":{"tags":["Usage"],"summary":"Usage Summary","description":"Return actual recorded spend for the last `days` days, optionally filtered by org.\n\nPass `X-Organization-Id` header (or `org_id` query param) when calling\nPOST /usage to enable per-org tracking, the same way /router/recommend and\n/telemetry/savings already work.","operationId":"usage_summary_usage_summary_get","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by organisation ID","title":"Org Id"},"description":"Filter by organisation ID"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look-back window in days","default":30,"title":"Days"},"description":"Look-back window in days"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage/session/{session_id}":{"get":{"tags":["Usage"],"summary":"Usage Session Analysis","description":"Analyze one specific session's actual recorded usage, on demand.\n\nReads back the rows previously recorded via POST /usage or POST /usage/batch with\nthis `session_id`, reports the session's real token/cost/model-mix totals, and runs\nthe session's own observed token pattern through the same routing engine behind\nPOST /router/recommend to produce a grounded recommendation (or confirm the current\nchoice is already optimal) with the estimated dollar savings/increase versus this\nsession's actual cost. Returns `has_data: false` with no `recommendation` if nothing\nhas been recorded yet for this session_id. Advisory only — never re-prices history\nor switches anything.\n\nsession_id values are caller-generated and not guaranteed unguessable, so an\nauthenticated request is scoped to the caller's own org_id (resolved the same way as\nPOST /usage — see `_resolve_org_id`), the same as an authenticated caller can never\nsee another org's data. A caller without a per-customer API key (or a self-reported\n`X-Organization-Id` header) is not scoped, matching /usage/summary's existing\ntrust model for unauthenticated/global-key access.","operationId":"usage_session_analysis_usage_session__session_id__get","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionUsageAnalysisResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage/alerts":{"get":{"tags":["Usage"],"summary":"List Budget Alerts","description":"Return all registered budget-spend alert webhooks.","operationId":"list_budget_alerts_usage_alerts_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetAlertListResponse"}}}}}},"post":{"tags":["Usage"],"summary":"Create Budget Alert","description":"Register a webhook alert for actual spend crossing a USD threshold.\n\nThe webhook URL will receive a `POST` request whenever recorded spend (from\nPOST /usage) for `org_id` (or across all orgs, if omitted) reaches\n`threshold_usd` within the trailing `period_days`. Checked inline after every\nusage event is recorded, and fires at most once per `period_days` while spend\nstays over threshold. Uses the same HMAC-SHA256 signing as /pricing/alerts —\nsee GET /pricing/alerts/signing-info.","operationId":"create_budget_alert_usage_alerts_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetAlertRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetAlertRecord"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/usage/alerts/{alert_id}":{"delete":{"tags":["Usage"],"summary":"Delete Budget Alert","description":"Delete a registered budget alert by ID.","operationId":"delete_budget_alert_usage_alerts__alert_id__delete","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"integer","title":"Alert Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/router/feedback":{"post":{"tags":["Router"],"summary":"Router Feedback","description":"Record feedback for a prior routing recommendation.\n\nPass the `routing_id` returned by `/router/recommend` along with whether\nthe recommended model was actually used.  Duplicate feedback for the same\n`routing_id` is silently ignored.","operationId":"router_feedback_router_feedback_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterFeedbackRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterFeedbackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/router/recommend/stream":{"post":{"tags":["Router"],"summary":"Router Recommend Stream","description":"Streaming version of /router/recommend — emits SSE progress events.\n\nEvents: start → fetching_models → models_loaded → enriching_quality →\nquality_enriched → filtering → candidates_ready → recommendation →\nalternatives → done.","operationId":"router_recommend_stream_router_recommend_stream_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouterRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rate-limits/tiers":{"get":{"tags":["API Info"],"summary":"Rate Limit Tiers","description":"Return the rate limit (requests/minute) for each API key tier.","operationId":"rate_limit_tiers_rate_limits_tiers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/billing":{"get":{"summary":"Billing Index","description":"Serve the self-serve billing dashboard SPA.","operationId":"billing_index_billing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/billing/signup":{"post":{"tags":["Billing"],"summary":"Billing Signup","description":"Free-tier signup — create (or retrieve) a customer record and return an API key.\n\nIdempotent: the same email always returns the same API key.","operationId":"billing_signup_billing_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/checkout":{"post":{"tags":["Billing"],"summary":"Billing Checkout","description":"Create a Stripe Checkout session for the requested tier (pro|enterprise).\n\nRequires authentication (x-api-key header with a billing API key).\nReturns 503 if Stripe is not configured.","operationId":"billing_checkout_billing_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/webhook":{"post":{"tags":["Billing"],"summary":"Billing Webhook","description":"Stripe webhook receiver.\n\nVerifies the Stripe-Signature header and processes subscription events.\nReturns 400 on signature failure, 200 on success.","operationId":"billing_webhook_billing_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/billing/portal":{"get":{"tags":["Billing"],"summary":"Billing Portal","description":"Create a Stripe Customer Portal session for the authenticated customer.\n\nReturns 503 if Stripe is not configured.","operationId":"billing_portal_billing_portal_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalResponse"}}}}}}},"/billing/me":{"get":{"tags":["Billing"],"summary":"Billing Me","description":"Return the authenticated customer's dashboard data.\n\nRequires a valid billing API key in the x-api-key header.","operationId":"billing_me_billing_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDashboard"}}}}}}},"/telemetry":{"get":{"tags":["Telemetry"],"summary":"Get Telemetry","description":"Get real-time telemetry data including endpoint usage, provider adoption, feature usage,\nand client geolocation/browser statistics.\n\nThis endpoint provides comprehensive metrics about API usage patterns, which providers\nand models are most requested, response times, error rates, geographic distribution,\nbrowser usage, and overall system health.\n\nReturns:\n    TelemetryResponse: Comprehensive telemetry data with overall stats, endpoint metrics,\n                     provider adoption metrics, feature usage statistics, client locations,\n                     and browser statistics","operationId":"get_telemetry_telemetry_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryResponse"}}}}}}},"/agent/chat":{"post":{"tags":["Agent"],"summary":"Agent Chat","description":"Natural language interface to the LLM Pricing Agent.\n\nThe agent uses RAG (indexed docs + live pricing) and existing pricing tools\nto answer questions about LLM costs, capabilities, and use cases.\n\n- Set `autonomous: true` to run a multi-step autonomous workflow (no history).\n- Provide `conversation_id` from a previous response to continue a conversation.","operationId":"agent_chat_agent_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentChatResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/chat/stream":{"post":{"tags":["Agent"],"summary":"Agent Chat Stream","description":"SSE streaming version of /agent/chat. Emits progress events as the ReAct loop runs.","operationId":"agent_chat_stream_agent_chat_stream_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing/history":{"get":{"tags":["Pricing History"],"summary":"Pricing History","description":"Return historical pricing snapshots.\n\nSnapshots are captured automatically every `pricing_snapshot_interval_hours` hours\nand stored locally in SQLite.  Use `days`, `model_name`, and `provider` to narrow\nthe results.","operationId":"pricing_history_pricing_history_get","parameters":[{"name":"model_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by model name","title":"Model Name"},"description":"Filter by model name"},{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by provider","title":"Provider"},"description":"Filter by provider"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look-back window in days","default":30,"title":"Days"},"description":"Look-back window in days"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Max rows to return","default":100,"title":"Limit"},"description":"Max rows to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing/trends":{"get":{"tags":["Pricing History"],"summary":"Pricing Trends","description":"Return models with the largest price change over the last `days` days.\n\nThe response is sorted by absolute percentage change (largest first) and\nincludes both input and output price deltas along with a human-readable\n`direction` field (`'increased'`, `'decreased'`, or `'unchanged'`).","operationId":"pricing_trends_pricing_trends_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look-back window in days","default":30,"title":"Days"},"description":"Look-back window in days"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max models to return","default":20,"title":"Limit"},"description":"Max models to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingTrendsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing/subscription-trends":{"get":{"tags":["Pricing"],"summary":"Subscription Price Trends","description":"Return IDE/subscription tools whose monthly price changed the most.","operationId":"subscription_price_trends_pricing_subscription_trends_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look-back window in days","default":30,"title":"Days"},"description":"Look-back window in days"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max models to return","default":20,"title":"Limit"},"description":"Max models to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionTrendsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing/history/export":{"get":{"tags":["Pricing History"],"summary":"Pricing History Export","description":"Export pricing snapshot history as CSV or JSON.\n\nReturns a downloadable file with all snapshot rows matching the supplied\nfilters.  The CSV variant includes a computed `cost_per_*_per_1m_usd`\ncolumn for convenience.  Set `format=json` for a machine-readable export\nwith metadata (`exported_at`, `filters`, `count`).","operationId":"pricing_history_export_pricing_history_export_get","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(csv|json)$","description":"Output format: 'csv' or 'json'","default":"csv","title":"Format"},"description":"Output format: 'csv' or 'json'"},{"name":"model_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by model name","title":"Model Name"},"description":"Filter by model name"},{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by provider","title":"Provider"},"description":"Filter by provider"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look-back window in days","default":30,"title":"Days"},"description":"Look-back window in days"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":1,"description":"Max rows to export","default":10000,"title":"Limit"},"description":"Max rows to export"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing/alerts":{"get":{"tags":["Pricing Alerts"],"summary":"List Pricing Alerts","description":"Return all registered price-change alert webhooks.","operationId":"list_pricing_alerts_pricing_alerts_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingAlertListResponse"}}}}}},"post":{"tags":["Pricing Alerts"],"summary":"Create Pricing Alert","description":"Register a webhook alert for price changes.\n\nThe webhook URL will receive a `POST` request with a JSON body whenever a\npricing snapshot detects that a model's input or output price has changed by\nmore than `threshold_pct` percent since the previous snapshot taken on the\nsame day.  Use `provider` and `model_name` to limit the alert to specific\nmodels.","operationId":"create_pricing_alert_pricing_alerts_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingAlertRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingAlertRecord"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing/alerts/{alert_id}":{"delete":{"tags":["Pricing Alerts"],"summary":"Delete Pricing Alert","description":"Delete a registered alert by ID.","operationId":"delete_pricing_alert_pricing_alerts__alert_id__delete","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"integer","title":"Alert Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/conversations":{"get":{"tags":["Agent"],"summary":"List Conversations","description":"List all stored chat conversations with metadata.\n\nReturns each conversation's ID, last-updated timestamp, turn count, and a\nshort preview of the most recent user message.  Conversations are sorted\nnewest first.  When the conversation store is in-memory (no\n``CONVERSATION_DB_PATH`` configured) the list reflects only conversations\ncreated since the server started.","operationId":"list_conversations_agent_conversations_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListResponse"}}}}}}},"/agent/conversations/{conversation_id}":{"delete":{"tags":["Agent"],"summary":"Delete Conversation","description":"Delete a stored conversation by its ID.\n\nRemoves the conversation from both the in-process cache and the persistent\nSQLite database (if configured).  Returns **204 No Content** on success and\n**404 Not Found** if the conversation does not exist.","operationId":"delete_conversation_agent_conversations__conversation_id__delete","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing/alerts/signing-info":{"get":{"tags":["Pricing Alerts"],"summary":"Webhook Signing Info","description":"Return information about webhook payload signing.\n\nWhen ``WEBHOOK_SECRET`` is configured, every price-change webhook (from\n/pricing/alerts) and budget-spend webhook (from /usage/alerts) POST will\ncarry an ``X-LLM-Pricing-Signature: sha256=<hex>`` header.  Use the\n``verify_webhook_signature`` helper (from\n``src.services.pricing_alerts``) on the receiving end to verify it —\nboth alert types use the same signing helper.\n\nReturns whether signing is active and the header name to look for.\nIntentionally never returns the secret itself.","operationId":"webhook_signing_info_pricing_alerts_signing_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/pricing/public":{"get":{"tags":["Pricing"],"summary":"Get Public Pricing","description":"Public pricing endpoint — no API key required.\n\nReturns a simplified list of models with per-1M-token prices suitable for\nembedding in third-party pages via the LLM Pricing widget.\n\nArgs:\n    models:   Comma-separated model names to include (e.g. ``gpt-4o,claude-sonnet-4-6``).\n              When omitted all available models are returned.\n    provider: Optional provider filter (e.g. ``openai``).\n\nReturns:\n    JSON with ``models`` list and ``updated_at`` timestamp.","operationId":"get_public_pricing_pricing_public_get","parameters":[{"name":"models","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated model names to include (omit for all models)","title":"Models"},"description":"Comma-separated model names to include (omit for all models)"},{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by provider name","title":"Provider"},"description":"Filter by provider name"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/stats":{"get":{"tags":["Admin"],"summary":"Admin Stats","description":"Aggregated server statistics for the admin dashboard.\n\nReturns overall telemetry, per-endpoint metrics, provider health,\nfeature usage counts, deployment uptime, and the server version.\nRequires a valid ``x-api-key`` header when ``MCP_API_KEY`` is configured.","operationId":"admin_stats_admin_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/rate-limits":{"get":{"tags":["Admin"],"summary":"Admin Rate Limits","description":"Current rate-limit consumer snapshot.\n\nReturns the number of tracked IPs and the top consumers ranked by\nrequests in the last 60 seconds.  Requires a valid ``x-api-key`` header.","operationId":"admin_rate_limits_admin_rate_limits_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin/customers":{"get":{"tags":["Admin"],"summary":"Admin Customers","description":"List all billing customers for the admin dashboard.\n\nReturns customer count by tier, plus a full customer list (api_key\nmasked to first 8 chars).  Requires a valid ``x-api-key`` header.","operationId":"admin_customers_admin_customers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/chat/completions":{"post":{"tags":["OpenAI Proxy"],"summary":"Openai Proxy","description":"OpenAI-compatible routing proxy.\n\nAccepts an OpenAI-format chat completions request and returns a routing\nrecommendation in OpenAI response format.  No live LLM call is made.\nPoint your OpenAI SDK ``base_url`` here to get intelligent model routing\nwithout any code changes.\n\nThis endpoint is **unauthenticated** for broad client compatibility.","operationId":"openai_proxy_v1_chat_completions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_ProxyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentChatRequest":{"properties":{"message":{"type":"string","maxLength":10000,"minLength":1,"title":"Message","description":"Natural language question or task (max 10,000 characters)"},"conversation_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Conversation Id","description":"UUID of an existing conversation to continue (optional)"},"autonomous":{"type":"boolean","title":"Autonomous","description":"Run as autonomous multi-step task (no history)","default":false}},"type":"object","required":["message"],"title":"AgentChatRequest","description":"Request body for POST /agent/chat."},"AgentChatResponse":{"properties":{"reply":{"type":"string","title":"Reply"},"conversation_id":{"type":"string","title":"Conversation Id"},"tool_calls":{"items":{},"type":"array","title":"Tool Calls","default":[]},"sources":{"items":{},"type":"array","title":"Sources","default":[]}},"type":"object","required":["reply","conversation_id"],"title":"AgentChatResponse","description":"Response body for POST /agent/chat."},"ApiVersionInfo":{"properties":{"current_version":{"type":"string","title":"Current Version","description":"Current stable API version"},"all_versions":{"items":{"type":"string"},"type":"array","title":"All Versions","description":"All available API versions"},"deprecated_versions":{"items":{"type":"string"},"type":"array","title":"Deprecated Versions","description":"Deprecated API versions still supported"},"migration_guide_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Migration Guide Url","description":"URL to migration guide for old API versions"}},"type":"object","required":["current_version","all_versions"],"title":"ApiVersionInfo","description":"Information about API versioning."},"BatchCostEstimateRequest":{"properties":{"model_names":{"items":{"type":"string"},"type":"array","title":"Model Names","description":"List of LLM model names to compare"},"input_tokens":{"type":"integer","minimum":0.0,"title":"Input Tokens","description":"Number of input tokens"},"output_tokens":{"type":"integer","minimum":0.0,"title":"Output Tokens","description":"Number of output tokens"}},"type":"object","required":["model_names","input_tokens","output_tokens"],"title":"BatchCostEstimateRequest","description":"Request model for batch cost estimation (compare multiple models)."},"BatchCostEstimateResponse":{"properties":{"input_tokens":{"type":"integer","title":"Input Tokens","description":"Number of input tokens used for comparison"},"output_tokens":{"type":"integer","title":"Output Tokens","description":"Number of output tokens used for comparison"},"models":{"items":{"$ref":"#/components/schemas/ModelCostComparison"},"type":"array","title":"Models","description":"Cost comparison for each model"},"cheapest_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cheapest Model","description":"Name of the cheapest model"},"most_expensive_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Most Expensive Model","description":"Name of the most expensive model"},"cost_range":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Cost Range","description":"Min and max costs across all models"},"currency":{"type":"string","title":"Currency","description":"Currency for costs","default":"USD"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Calculation timestamp"}},"type":"object","required":["input_tokens","output_tokens","models"],"title":"BatchCostEstimateResponse","description":"Response model for batch cost estimation endpoint."},"BillingPortalResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url"}},"type":"object","required":["portal_url"],"title":"BillingPortalResponse"},"BrowserStats":{"properties":{"browser_name":{"type":"string","title":"Browser Name","description":"Browser name (e.g., Chrome, Firefox)"},"request_count":{"type":"integer","title":"Request Count","description":"Number of requests from this browser"},"unique_clients":{"type":"integer","title":"Unique Clients","description":"Number of unique clients using this browser"}},"type":"object","required":["browser_name","request_count","unique_clients"],"title":"BrowserStats","description":"Statistics about browsers used by clients."},"BudgetAlertListResponse":{"properties":{"alerts":{"items":{"$ref":"#/components/schemas/BudgetAlertRecord"},"type":"array","title":"Alerts","description":"All registered budget alerts"},"total":{"type":"integer","title":"Total","description":"Number of registered budget alerts"}},"type":"object","required":["alerts","total"],"title":"BudgetAlertListResponse","description":"Response for GET /usage/alerts."},"BudgetAlertRecord":{"properties":{"id":{"type":"integer","title":"Id","description":"Unique alert ID"},"url":{"type":"string","title":"Url","description":"Webhook URL"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organisation filter (None = all orgs)"},"threshold_usd":{"type":"number","title":"Threshold Usd","description":"Spend threshold in USD"},"period_days":{"type":"integer","title":"Period Days","description":"Rolling look-back window in days"},"created_at":{"type":"number","title":"Created At","description":"Unix timestamp when the alert was registered"},"last_fired_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Last Fired At","description":"Unix timestamp this alert last fired, if ever"}},"type":"object","required":["id","url","threshold_usd","period_days","created_at"],"title":"BudgetAlertRecord","description":"A stored budget alert."},"BudgetAlertRequest":{"properties":{"url":{"type":"string","title":"Url","description":"Webhook URL to POST when spend crosses threshold_usd"},"threshold_usd":{"type":"number","exclusiveMinimum":0.0,"title":"Threshold Usd","description":"Spend level in USD that triggers the alert"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organisation to monitor (None = total spend across all orgs)"},"period_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Period Days","description":"Rolling look-back window for the spend check, in days","default":30}},"type":"object","required":["url","threshold_usd"],"title":"BudgetAlertRequest","description":"Request body for POST /usage/alerts."},"CheckoutRequest":{"properties":{"tier":{"type":"string","title":"Tier"}},"type":"object","required":["tier"],"title":"CheckoutRequest"},"CheckoutResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url"}},"type":"object","required":["checkout_url"],"title":"CheckoutResponse"},"ClientLocationStats":{"properties":{"country":{"type":"string","title":"Country","description":"Country name"},"country_code":{"type":"string","title":"Country Code","description":"ISO country code"},"request_count":{"type":"integer","title":"Request Count","description":"Number of requests from this country"},"unique_clients":{"type":"integer","title":"Unique Clients","description":"Number of unique IP addresses from this country"}},"type":"object","required":["country","country_code","request_count","unique_clients"],"title":"ClientLocationStats","description":"Statistics about client locations."},"ConversationListResponse":{"properties":{"conversations":{"items":{"$ref":"#/components/schemas/ConversationSummary"},"type":"array","title":"Conversations","description":"Stored conversations, newest first"},"total":{"type":"integer","title":"Total","description":"Total number of stored conversations"}},"type":"object","required":["conversations","total"],"title":"ConversationListResponse","description":"Response for GET /agent/conversations."},"ConversationSummary":{"properties":{"id":{"type":"string","title":"Id","description":"Unique conversation ID (UUID)"},"updated_at":{"type":"number","title":"Updated At","description":"Unix timestamp of the last update (0.0 for in-memory)"},"turn_count":{"type":"integer","title":"Turn Count","description":"Total number of messages (user + assistant turns)"},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"First 120 chars of the most recent user message"}},"type":"object","required":["id","updated_at","turn_count"],"title":"ConversationSummary","description":"Metadata summary for a single stored conversation."},"CostEstimateRequest":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Name of the LLM model"},"input_tokens":{"type":"integer","minimum":0.0,"title":"Input Tokens","description":"Number of input tokens"},"output_tokens":{"type":"integer","minimum":0.0,"title":"Output Tokens","description":"Number of output tokens"}},"type":"object","required":["model_name","input_tokens","output_tokens"],"title":"CostEstimateRequest","description":"Request model for cost estimation endpoint."},"CostEstimateResponse":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Name of the LLM model"},"provider":{"type":"string","title":"Provider","description":"Provider of the model"},"input_tokens":{"type":"integer","title":"Input Tokens","description":"Number of input tokens"},"output_tokens":{"type":"integer","title":"Output Tokens","description":"Number of output tokens"},"input_cost":{"type":"number","title":"Input Cost","description":"Cost for input tokens in USD"},"output_cost":{"type":"number","title":"Output Cost","description":"Cost for output tokens in USD"},"total_cost":{"type":"number","title":"Total Cost","description":"Total cost in USD"},"currency":{"type":"string","title":"Currency","description":"Currency for cost","default":"USD"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Calculation timestamp"}},"type":"object","required":["model_name","provider","input_tokens","output_tokens","input_cost","output_cost","total_cost"],"title":"CostEstimateResponse","description":"Response model for cost estimation endpoint."},"CustomerDashboard":{"properties":{"email":{"type":"string","title":"Email"},"tier":{"type":"string","title":"Tier"},"org_id":{"type":"string","title":"Org Id"},"api_key_preview":{"type":"string","title":"Api Key Preview"},"router_calls_30d":{"type":"integer","title":"Router Calls 30D"},"savings_per_1m_30d":{"type":"number","title":"Savings Per 1M 30D"},"acceptance_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Acceptance Rate"}},"type":"object","required":["email","tier","org_id","api_key_preview","router_calls_30d","savings_per_1m_30d","acceptance_rate"],"title":"CustomerDashboard"},"DeploymentMetadata":{"properties":{"version":{"type":"string","title":"Version","description":"Application version"},"build_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Build Date","description":"Build timestamp"},"deployment_date":{"type":"string","format":"date-time","title":"Deployment Date"},"api_versions":{"items":{"type":"string"},"type":"array","title":"Api Versions","description":"Supported API versions"},"backwards_compatible_until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backwards Compatible Until","description":"Version until which backwards compatibility is maintained"},"breaking_changes":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Breaking Changes","description":"Breaking changes by version (e.g., {'v2': ['removed endpoint X']})"}},"type":"object","required":["version"],"title":"DeploymentMetadata","description":"Metadata about the current deployment for blue-green awareness."},"DeploymentReadiness":{"properties":{"ready":{"type":"boolean","title":"Ready","description":"Whether the service is ready to receive traffic"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason if not ready"},"checks":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Checks","description":"Individual readiness checks"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["ready"],"title":"DeploymentReadiness","description":"Deployment readiness check response."},"DeploymentStatus":{"type":"string","enum":["healthy","degraded","unhealthy","shutting_down"],"title":"DeploymentStatus","description":"Deployment status enumeration."},"EndpointMetricResponse":{"properties":{"endpoint":{"type":"string","title":"Endpoint","description":"Endpoint path and method (method path)"},"path":{"type":"string","title":"Path","description":"Request path"},"method":{"type":"string","title":"Method","description":"HTTP method"},"call_count":{"type":"integer","title":"Call Count","description":"Total number of calls to this endpoint"},"error_count":{"type":"integer","title":"Error Count","description":"Number of failed requests"},"success_rate":{"type":"number","title":"Success Rate","description":"Success rate as percentage"},"avg_response_time_ms":{"type":"number","title":"Avg Response Time Ms","description":"Average response time in milliseconds"},"min_response_time_ms":{"type":"number","title":"Min Response Time Ms","description":"Minimum response time in milliseconds"},"max_response_time_ms":{"type":"number","title":"Max Response Time Ms","description":"Maximum response time in milliseconds"},"first_called":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Called","description":"ISO timestamp of first call"},"last_called":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Called","description":"ISO timestamp of last call"}},"type":"object","required":["endpoint","path","method","call_count","error_count","success_rate","avg_response_time_ms","min_response_time_ms","max_response_time_ms"],"title":"EndpointMetricResponse","description":"Metrics for a single endpoint."},"EnvironmentInfo":{"properties":{"environment":{"type":"string","title":"Environment","description":"Deployment environment (e.g., production, staging)"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region","description":"Geographic region or deployment region"},"availability_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Availability Zone","description":"Availability zone or datacenter"},"deployment_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployment Group","description":"Deployment group (e.g., blue, green)"},"instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Id","description":"Instance or container ID"},"deployment_timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deployment Timestamp","description":"When this instance was deployed"}},"type":"object","required":["environment"],"title":"EnvironmentInfo","description":"Information about the deployment environment."},"FeatureUsageResponse":{"properties":{"feature_name":{"type":"string","title":"Feature Name","description":"Name of the feature"},"usage_count":{"type":"integer","title":"Usage Count","description":"Total number of times feature was used"},"last_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used","description":"ISO timestamp of last usage"}},"type":"object","required":["feature_name","usage_count"],"title":"FeatureUsageResponse","description":"Usage metrics for a feature."},"GracefulShutdownRequest":{"properties":{"drain_timeout_seconds":{"type":"integer","title":"Drain Timeout Seconds","description":"Time to wait for in-flight requests to complete","default":30}},"type":"object","title":"GracefulShutdownRequest","description":"Request to initiate graceful shutdown."},"GracefulShutdownStatus":{"properties":{"shutting_down":{"type":"boolean","title":"Shutting Down","description":"Whether shutdown is in progress"},"active_requests":{"type":"integer","title":"Active Requests","description":"Number of active requests"},"drain_timeout_seconds":{"type":"integer","title":"Drain Timeout Seconds","description":"Drain timeout configured"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When shutdown started"}},"type":"object","required":["shutting_down","active_requests","drain_timeout_seconds"],"title":"GracefulShutdownStatus","description":"Status of graceful shutdown process."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthCheckResponse":{"properties":{"status":{"$ref":"#/components/schemas/DeploymentStatus","description":"Overall service status"},"version":{"type":"string","title":"Version","description":"Application version"},"uptime_seconds":{"type":"number","title":"Uptime Seconds","description":"Uptime in seconds"},"environment":{"$ref":"#/components/schemas/EnvironmentInfo","description":"Environment information"},"services":{"items":{"$ref":"#/components/schemas/ServiceHealth"},"type":"array","title":"Services","description":"Health of dependencies"},"metrics":{"additionalProperties":true,"type":"object","title":"Metrics","description":"Current performance metrics (requests/sec, avg response time, etc.)"},"graceful_shutdown":{"type":"boolean","title":"Graceful Shutdown","description":"Whether graceful shutdown is in progress","default":false},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["status","version","uptime_seconds","environment"],"title":"HealthCheckResponse","description":"Comprehensive health check response for load balancers and orchestrators."},"ModelCostComparison":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Name of the LLM model"},"provider":{"type":"string","title":"Provider","description":"Provider of the model"},"input_cost":{"type":"number","title":"Input Cost","description":"Cost for input tokens in USD"},"output_cost":{"type":"number","title":"Output Cost","description":"Cost for output tokens in USD"},"total_cost":{"type":"number","title":"Total Cost","description":"Total cost in USD"},"cost_per_1m_tokens":{"type":"number","title":"Cost Per 1M Tokens","description":"Estimated cost per 1M tokens (average of input/output)"},"is_available":{"type":"boolean","title":"Is Available","description":"Whether the model pricing was found","default":true},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if model not found"}},"type":"object","required":["model_name","provider","input_cost","output_cost","total_cost","cost_per_1m_tokens"],"title":"ModelCostComparison","description":"Cost comparison for a single model."},"ModelUseCase":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Name of the LLM model"},"provider":{"type":"string","title":"Provider","description":"Provider of the model"},"best_for":{"type":"string","title":"Best For","description":"Quick summary of what this model is best for"},"use_cases":{"items":{"type":"string"},"type":"array","title":"Use Cases","description":"List of ideal use cases"},"strengths":{"items":{"type":"string"},"type":"array","title":"Strengths","description":"Key strengths of this model"},"context_window":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Window","description":"Maximum context window size"},"cost_tier":{"type":"string","title":"Cost Tier","description":"Cost tier: low, medium, high"}},"type":"object","required":["model_name","provider","best_for","use_cases","strengths","cost_tier"],"title":"ModelUseCase","description":"Use case information for a specific LLM model."},"PerformanceMetrics":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Name of the LLM model"},"provider":{"type":"string","title":"Provider","description":"Provider of the model"},"throughput":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Throughput","description":"Tokens per second throughput"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms","description":"Average latency in milliseconds"},"context_window":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Window","description":"Maximum context window size"},"cost_per_input_token":{"type":"number","title":"Cost Per Input Token","description":"Cost per input token in USD"},"cost_per_output_token":{"type":"number","title":"Cost Per Output Token","description":"Cost per output token in USD"},"performance_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Performance Score","description":"Calculated performance score (throughput/cost ratio)"},"value_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Score","description":"Value score (context_window/cost ratio)"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score","description":"Benchmark quality score 0-100"}},"type":"object","required":["model_name","provider","cost_per_input_token","cost_per_output_token"],"title":"PerformanceMetrics","description":"Performance metrics for an LLM model."},"PerformanceResponse":{"properties":{"models":{"items":{"$ref":"#/components/schemas/PerformanceMetrics"},"type":"array","title":"Models","description":"Performance metrics for each model"},"total_models":{"type":"integer","title":"Total Models","description":"Total number of models"},"best_throughput":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best Throughput","description":"Model with best throughput"},"lowest_latency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lowest Latency","description":"Model with lowest latency"},"largest_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Largest Context","description":"Model with largest context window"},"best_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best Value","description":"Model with best value score"},"best_quality_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best Quality Value","description":"Model with best quality/cost ratio"},"provider_status":{"items":{"$ref":"#/components/schemas/ProviderStatusInfo"},"type":"array","title":"Provider Status","description":"Status of each provider"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Response timestamp"}},"type":"object","required":["models","total_models"],"title":"PerformanceResponse","description":"Response model for performance comparison endpoint."},"PricingAlertListResponse":{"properties":{"alerts":{"items":{"$ref":"#/components/schemas/PricingAlertRecord"},"type":"array","title":"Alerts","description":"All registered alerts"},"total":{"type":"integer","title":"Total","description":"Number of registered alerts"}},"type":"object","required":["alerts","total"],"title":"PricingAlertListResponse","description":"Response for GET /pricing/alerts."},"PricingAlertRecord":{"properties":{"id":{"type":"integer","title":"Id","description":"Unique alert ID"},"url":{"type":"string","title":"Url","description":"Webhook URL"},"threshold_pct":{"type":"number","title":"Threshold Pct","description":"Trigger threshold in percentage"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"Provider filter (None = all)"},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Name","description":"Model filter (None = all)"},"created_at":{"type":"number","title":"Created At","description":"Unix timestamp when the alert was registered"}},"type":"object","required":["id","url","threshold_pct","created_at"],"title":"PricingAlertRecord","description":"A stored price-change alert."},"PricingAlertRequest":{"properties":{"url":{"type":"string","title":"Url","description":"Webhook URL to POST when the alert fires"},"threshold_pct":{"type":"number","exclusiveMinimum":0.0,"title":"Threshold Pct","description":"Minimum absolute % price change that triggers the alert","default":5.0},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"Limit to a specific provider (None = all)"},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Name","description":"Limit to a specific model name (None = all)"}},"type":"object","required":["url"],"title":"PricingAlertRequest","description":"Request body for POST /pricing/alerts."},"PricingHistoryResponse":{"properties":{"snapshots":{"items":{"$ref":"#/components/schemas/PricingSnapshotRecord"},"type":"array","title":"Snapshots","description":"Snapshot rows"},"total":{"type":"integer","title":"Total","description":"Total matching rows (before limit)"}},"type":"object","required":["snapshots","total"],"title":"PricingHistoryResponse","description":"Response for GET /pricing/history."},"PricingMetrics":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Name of the LLM model"},"provider":{"type":"string","title":"Provider","description":"Provider of the model (e.g., OpenAI, Anthropic)"},"cost_per_input_token":{"type":"number","title":"Cost Per Input Token","description":"Cost per input token in USD"},"cost_per_output_token":{"type":"number","title":"Cost Per Output Token","description":"Cost per output token in USD"},"throughput":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Throughput","description":"Tokens per second throughput"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms","description":"Average latency in milliseconds"},"context_window":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Context Window","description":"Maximum context window size"},"currency":{"type":"string","title":"Currency","description":"Currency for pricing (default: USD)","default":"USD"},"unit":{"type":"string","title":"Unit","description":"Unit for pricing (default: per 1k tokens)","default":"per_1k_tokens"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source of the pricing data (e.g., API, documentation)"},"last_updated":{"type":"string","format":"date-time","title":"Last Updated","description":"Last update timestamp"},"use_cases":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Use Cases","description":"List of ideal use cases for this model"},"strengths":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Strengths","description":"Key strengths of this model"},"best_for":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best For","description":"Quick summary of what this model is best for"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Score","description":"Benchmark quality score 0-100"},"supports_vision":{"type":"boolean","title":"Supports Vision","description":"Whether the model supports image/vision input","default":false},"supports_function_calling":{"type":"boolean","title":"Supports Function Calling","description":"Whether the model supports function/tool calling","default":false},"supports_json_mode":{"type":"boolean","title":"Supports Json Mode","description":"Whether the model supports structured JSON output mode","default":false},"batch_available":{"type":"boolean","title":"Batch Available","description":"Whether batch processing API is available for this model","default":false},"is_reasoning_model":{"type":"boolean","title":"Is Reasoning Model","description":"Whether this is a reasoning/thinking model (e.g., o1, R1)","default":false},"pricing_model":{"type":"string","title":"Pricing Model","description":"Pricing model type: 'per_token', 'subscription', or 'hybrid'","default":"per_token"},"subscription_monthly_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Subscription Monthly Usd","description":"Monthly subscription cost in USD (for subscription-based tools like Copilot, Cursor)"},"supports_inline_completion":{"type":"boolean","title":"Supports Inline Completion","description":"Whether the model/tool supports real-time inline code completion","default":false},"ide_native":{"type":"boolean","title":"Ide Native","description":"Whether this is an IDE-native tool (GitHub Copilot, Cursor, Windsurf, etc.)","default":false},"price_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price As Of","description":"ISO date (YYYY-MM-DD) when this price was last confirmed against the provider"},"price_confirmed":{"type":"boolean","title":"Price Confirmed","description":"False when the model is known to exist but its per-token price has not been confirmed. Such models are listed for discoverability but excluded from cost ranking and budget math, so an unknown price is never mistaken for a cheap one.","default":true},"price_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Price Age Days","description":"Days since the price was last confirmed. None when unknown.","readOnly":true},"price_is_stale":{"type":"boolean","title":"Price Is Stale","description":"True when the price is older than the staleness threshold, or undated.\n\nAn undated price counts as stale: unknown provenance is not a clean bill\nof health, and callers making budget decisions should see that.","readOnly":true},"quality_value_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quality Value Score","description":"Quality per dollar: quality_score / average_cost_per_1M_tokens.","readOnly":true},"cost_at_10k_tokens":{"$ref":"#/components/schemas/TokenVolumePrice","description":"Calculate cost for 10,000 tokens (small volume).","readOnly":true},"cost_at_100k_tokens":{"$ref":"#/components/schemas/TokenVolumePrice","description":"Calculate cost for 100,000 tokens (medium volume).","readOnly":true},"cost_at_1m_tokens":{"$ref":"#/components/schemas/TokenVolumePrice","description":"Calculate cost for 1,000,000 tokens (large volume).","readOnly":true},"estimated_time_1m_tokens":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Estimated Time 1M Tokens","description":"Estimate time to process 1M tokens based on throughput (in seconds).","readOnly":true}},"type":"object","required":["model_name","provider","cost_per_input_token","cost_per_output_token","price_age_days","price_is_stale","quality_value_score","cost_at_10k_tokens","cost_at_100k_tokens","cost_at_1m_tokens","estimated_time_1m_tokens"],"title":"PricingMetrics","description":"Metrics for a specific LLM model."},"PricingResponse":{"properties":{"models":{"items":{"$ref":"#/components/schemas/PricingMetrics"},"type":"array","title":"Models","description":"List of model pricing information"},"total_models":{"type":"integer","title":"Total Models","description":"Total number of models returned"},"provider_status":{"items":{"$ref":"#/components/schemas/ProviderStatusInfo"},"type":"array","title":"Provider Status","description":"Status of each provider"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Response timestamp"}},"type":"object","required":["models","total_models"],"title":"PricingResponse","description":"Response model for pricing endpoint."},"PricingSnapshotRecord":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"LLM model name"},"provider":{"type":"string","title":"Provider","description":"Provider name"},"cost_per_input_token":{"type":"number","title":"Cost Per Input Token","description":"Input token cost in USD"},"cost_per_output_token":{"type":"number","title":"Cost Per Output Token","description":"Output token cost in USD"},"captured_at":{"type":"number","title":"Captured At","description":"Unix timestamp of the snapshot"},"subscription_monthly_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Subscription Monthly Usd","description":"Monthly subscription cost in USD (for subscription-based tools)"}},"type":"object","required":["model_name","provider","cost_per_input_token","cost_per_output_token","captured_at"],"title":"PricingSnapshotRecord","description":"A single pricing snapshot row."},"PricingTrendRecord":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"LLM model name"},"provider":{"type":"string","title":"Provider","description":"Provider name"},"input_change_pct":{"type":"number","title":"Input Change Pct","description":"Input price change percentage"},"output_change_pct":{"type":"number","title":"Output Change Pct","description":"Output price change percentage"},"direction":{"type":"string","title":"Direction","description":"'increased', 'decreased', or 'unchanged'"},"first_seen":{"type":"number","title":"First Seen","description":"Unix timestamp of first snapshot in range"},"last_seen":{"type":"number","title":"Last Seen","description":"Unix timestamp of most recent snapshot"},"first_input":{"type":"number","title":"First Input","description":"Input price at first snapshot"},"last_input":{"type":"number","title":"Last Input","description":"Input price at most recent snapshot"},"first_output":{"type":"number","title":"First Output","description":"Output price at first snapshot"},"last_output":{"type":"number","title":"Last Output","description":"Output price at most recent snapshot"}},"type":"object","required":["model_name","provider","input_change_pct","output_change_pct","direction","first_seen","last_seen","first_input","last_input","first_output","last_output"],"title":"PricingTrendRecord","description":"Price trend for a single model over a time period."},"PricingTrendsResponse":{"properties":{"trends":{"items":{"$ref":"#/components/schemas/PricingTrendRecord"},"type":"array","title":"Trends","description":"Models with largest price changes"},"days":{"type":"integer","title":"Days","description":"Look-back window in days"}},"type":"object","required":["trends","days"],"title":"PricingTrendsResponse","description":"Response for GET /pricing/trends."},"ProviderAdoptionResponse":{"properties":{"provider_name":{"type":"string","title":"Provider Name","description":"Name of the provider"},"model_requests":{"type":"integer","title":"Model Requests","description":"Total number of model requests for this provider"},"unique_models_requested":{"type":"integer","title":"Unique Models Requested","description":"Number of unique models requested"},"total_cost_estimated":{"type":"number","title":"Total Cost Estimated","description":"Total estimated cost (USD)"},"last_requested":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Requested","description":"ISO timestamp of last request"}},"type":"object","required":["provider_name","model_requests","unique_models_requested","total_cost_estimated"],"title":"ProviderAdoptionResponse","description":"Adoption metrics for a provider."},"ProviderStatusInfo":{"properties":{"provider_name":{"type":"string","title":"Provider Name","description":"Name of the provider"},"is_available":{"type":"boolean","title":"Is Available","description":"Whether the provider is currently available"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if provider is unavailable"},"models_count":{"type":"integer","title":"Models Count","description":"Number of models returned by this provider","default":0}},"type":"object","required":["provider_name","is_available"],"title":"ProviderStatusInfo","description":"Provider availability status information."},"RouterFeedbackRequest":{"properties":{"routing_id":{"type":"string","title":"Routing Id","description":"routing_id from a prior /router/recommend response"},"was_used":{"type":"boolean","title":"Was Used","description":"Whether the recommended model was actually used"},"actual_model_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actual Model Used","description":"Model actually used if different from recommendation"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Free-text notes about the routing decision"}},"type":"object","required":["routing_id","was_used"],"title":"RouterFeedbackRequest","description":"Request body for POST /router/feedback."},"RouterFeedbackResponse":{"properties":{"routing_id":{"type":"string","title":"Routing Id","description":"The routing ID feedback was recorded for"},"recorded":{"type":"boolean","title":"Recorded","description":"Whether feedback was recorded successfully"}},"type":"object","required":["routing_id","recorded"],"title":"RouterFeedbackResponse","description":"Response body for POST /router/feedback."},"RouterRequest":{"properties":{"max_cost_per_1m_tokens":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Cost Per 1M Tokens","description":"Maximum acceptable average cost per 1M tokens (USD)"},"min_quality_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Min Quality Score","description":"Minimum required quality score (0-100)"},"min_context_window":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Min Context Window","description":"Minimum required context window size (tokens)"},"preferred_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Provider","description":"Preferred provider name (10% score boost applied)"},"task_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Type","description":"Task type hint: 'code' | 'chat' | 'analysis' | 'summarization' | 'code_completion' | 'code_chat' | 'code_refactor' | 'agentic_coding'"},"prefer_low_latency":{"type":"boolean","title":"Prefer Low Latency","description":"Prioritise lower-latency models; important for inline code completions","default":false},"exclude_reasoning_models":{"type":"boolean","title":"Exclude Reasoning Models","description":"Exclude slow thinking/reasoning models (e.g. o1, o3, R1, claude-3-7-sonnet)","default":false},"ide_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ide Context","description":"IDE context hint — boosts IDE-native tools when set: 'copilot' | 'cursor' | 'windsurf' | 'claude_code' | 'jetbrains' | 'amazon_q'"},"monthly_budget_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Monthly Budget Usd","description":"Monthly spend ceiling in USD. Combined with estimated_monthly_requests, avg_input_tokens, and avg_output_tokens to compute projected monthly cost and hard-filter models that exceed it. For subscription tools, filters by subscription_monthly_usd <= monthly_budget_usd."},"estimated_monthly_requests":{"type":"integer","minimum":1.0,"title":"Estimated Monthly Requests","description":"Estimated number of API requests per month (used with monthly_budget_usd)","default":1000},"avg_input_tokens":{"type":"integer","minimum":1.0,"title":"Avg Input Tokens","description":"Average input tokens per request (used with monthly_budget_usd)","default":500},"avg_output_tokens":{"type":"integer","minimum":1.0,"title":"Avg Output Tokens","description":"Average output tokens per request (used with monthly_budget_usd)","default":200}},"type":"object","title":"RouterRequest","description":"Request body for POST /router/recommend."},"RouterResponse":{"properties":{"recommended":{"$ref":"#/components/schemas/PricingMetrics","description":"Best matching model"},"score":{"type":"number","title":"Score","description":"Composite routing score"},"reason":{"type":"string","title":"Reason","description":"Human-readable explanation of the recommendation"},"alternatives":{"items":{"$ref":"#/components/schemas/PricingMetrics"},"type":"array","title":"Alternatives","description":"Up to 3 alternative models"},"routing_id":{"type":"string","title":"Routing Id","description":"Unique routing decision ID (UUID4) for feedback"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"cached":{"type":"boolean","title":"Cached","description":"True if this recommendation was served from the ~5 minute in-memory recommendation cache rather than freshly computed","default":false}},"type":"object","required":["recommended","score","reason","routing_id"],"title":"RouterResponse","description":"Response body for POST /router/recommend."},"SavingsRecord":{"properties":{"id":{"type":"integer","title":"Id","description":"Unique record ID"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organisation identifier"},"api_key_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Tier","description":"API key tier"},"requested_at":{"type":"number","title":"Requested At","description":"Unix timestamp of the routing request"},"recommended_model":{"type":"string","title":"Recommended Model","description":"Recommended model name"},"recommended_provider":{"type":"string","title":"Recommended Provider","description":"Recommended model provider"},"recommended_cost_per_1m":{"type":"number","title":"Recommended Cost Per 1M","description":"Recommended model cost per 1M tokens"},"baseline_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Baseline Model","description":"Most expensive alternative considered"},"baseline_cost_per_1m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Baseline Cost Per 1M","description":"Baseline model cost per 1M tokens"},"savings_per_1m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Savings Per 1M","description":"Cost savings per 1M tokens vs baseline"},"task_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Type","description":"Task type hint provided by caller"},"ide_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ide Context","description":"IDE context hint used in the routing request"}},"type":"object","required":["id","requested_at","recommended_model","recommended_provider","recommended_cost_per_1m"],"title":"SavingsRecord","description":"A single routing savings record."},"SavingsResponse":{"properties":{"records":{"items":{"$ref":"#/components/schemas/SavingsRecord"},"type":"array","title":"Records","description":"Routing savings records"},"total":{"type":"integer","title":"Total","description":"Total matching records"},"total_savings_per_1m":{"type":"number","title":"Total Savings Per 1M","description":"Sum of savings_per_1m across records"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organisation filter applied"},"days":{"type":"integer","title":"Days","description":"Look-back window in days"},"acceptance_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Acceptance Rate","description":"Fraction of routing decisions where the recommendation was used (0-1)"}},"type":"object","required":["records","total","total_savings_per_1m","days"],"title":"SavingsResponse","description":"Response for GET /telemetry/savings."},"ServiceHealth":{"properties":{"name":{"type":"string","title":"Name","description":"Name of the service"},"status":{"$ref":"#/components/schemas/DeploymentStatus","description":"Health status"},"response_time_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Response Time Ms","description":"Response time in milliseconds"},"last_checked":{"type":"string","format":"date-time","title":"Last Checked"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error details if unhealthy"}},"type":"object","required":["name","status"],"title":"ServiceHealth","description":"Health status of a service/dependency."},"SessionModelBreakdown":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Model name"},"provider":{"type":"string","title":"Provider","description":"Provider"},"request_count":{"type":"integer","title":"Request Count","description":"Number of usage events recorded for this model in the session"},"input_tokens":{"type":"integer","title":"Input Tokens","description":"Input tokens for this model in the session"},"output_tokens":{"type":"integer","title":"Output Tokens","description":"Output tokens for this model in the session"},"cost_usd":{"type":"number","title":"Cost Usd","description":"Actual cost in USD for this model in the session"},"estimated_request_count":{"type":"integer","title":"Estimated Request Count","description":"Of this model's request_count, how many were recorded from text-derived estimates","default":0}},"type":"object","required":["model_name","provider","request_count","input_tokens","output_tokens","cost_usd"],"title":"SessionModelBreakdown","description":"Actual usage breakdown for a single model within one session."},"SessionRecommendation":{"properties":{"is_optimal":{"type":"boolean","title":"Is Optimal","description":"True if the session already used exactly the model the router would recommend"},"recommended_model":{"type":"string","title":"Recommended Model","description":"Recommended model name"},"recommended_provider":{"type":"string","title":"Recommended Provider","description":"Recommended model's provider"},"recommended_cost_per_1m_tokens":{"type":"number","title":"Recommended Cost Per 1M Tokens","description":"Recommended model's blended $/1M tokens rate (equal input/output weight)"},"session_actual_cost_per_1m_tokens":{"type":"number","title":"Session Actual Cost Per 1M Tokens","description":"This session's actual blended $/1M tokens, from its real token mix and cost"},"estimated_cost_if_recommended_usd":{"type":"number","title":"Estimated Cost If Recommended Usd","description":"What this session's actual token volumes would have cost on the recommended model"},"savings_usd":{"type":"number","title":"Savings Usd","description":"total_cost_usd minus estimated_cost_if_recommended_usd. Positive means the recommended model would have been cheaper; negative means more expensive; 0 when is_optimal is true."},"rationale":{"type":"string","title":"Rationale","description":"Plain-language reasoning grounded in this session's request count, tokens, and cost"},"caveats":{"anyOf":[{"items":{"$ref":"#/components/schemas/SessionRecommendationCaveat"},"type":"array"},{"type":"null"}],"title":"Caveats","description":"Present only when a caveat applies, e.g. a quality_tradeoff warning when the recommended model's quality_score is below the shared quality-tradeoff threshold. Never present when is_optimal is true."}},"type":"object","required":["is_optimal","recommended_model","recommended_provider","recommended_cost_per_1m_tokens","session_actual_cost_per_1m_tokens","estimated_cost_if_recommended_usd","savings_usd","rationale"],"title":"SessionRecommendation","description":"A model recommendation grounded in one session's actual observed usage."},"SessionRecommendationCaveat":{"properties":{"type":{"type":"string","title":"Type","description":"Caveat type, e.g. 'quality_tradeoff'"},"message":{"type":"string","title":"Message","description":"Plain-language description of the tradeoff"},"quality_score":{"type":"number","title":"Quality Score","description":"The recommended model's quality_score"},"quality_threshold":{"type":"number","title":"Quality Threshold","description":"The quality_score threshold that triggered this caveat"}},"type":"object","required":["type","message","quality_score","quality_threshold"],"title":"SessionRecommendationCaveat","description":"A caveat attached to a SessionRecommendation, e.g. a quality/cost tradeoff warning."},"SessionUsageAnalysisResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"False if no usage was recorded for this session_id"},"has_data":{"type":"boolean","title":"Has Data","description":"False when session_id has zero recorded usage events"},"session_id":{"type":"string","title":"Session Id","description":"The session_id analyzed"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Present when has_data is false"},"total_requests":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Requests","description":"Total usage events recorded for this session"},"total_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Input Tokens","description":"Total input tokens for this session"},"total_output_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Output Tokens","description":"Total output tokens for this session"},"total_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Cost Usd","description":"Total actual cost in USD for this session"},"by_model":{"items":{"$ref":"#/components/schemas/SessionModelBreakdown"},"type":"array","title":"By Model","description":"Per-model breakdown; more than one entry if the session mixed models"},"first_occurred_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"First Occurred At","description":"Unix timestamp of the earliest event"},"last_occurred_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Last Occurred At","description":"Unix timestamp of the latest event"},"estimated_request_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Estimated Request Count","description":"Of total_requests, how many were recorded from text-derived estimates (e.g. via import_session_usage)"},"has_estimated_usage":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Estimated Usage","description":"True if any of this session's usage was recorded from an estimate, not exact counts"},"recommendation":{"anyOf":[{"$ref":"#/components/schemas/SessionRecommendation"},{"type":"null"}],"description":"Absent when has_data is false or no model could be matched"}},"type":"object","required":["success","has_data","session_id"],"title":"SessionUsageAnalysisResponse","description":"Response for GET /usage/session/{session_id}."},"SignupRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"SignupRequest"},"SignupResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"org_id":{"type":"string","title":"Org Id"},"tier":{"type":"string","title":"Tier"},"message":{"type":"string","title":"Message"}},"type":"object","required":["api_key","org_id","tier","message"],"title":"SignupResponse"},"SubscriptionTrendRecord":{"properties":{"model_name":{"type":"string","title":"Model Name"},"provider":{"type":"string","title":"Provider"},"subscription_change_pct":{"type":"number","title":"Subscription Change Pct"},"direction":{"type":"string","title":"Direction"},"first_seen":{"type":"number","title":"First Seen"},"last_seen":{"type":"number","title":"Last Seen"},"first_price":{"type":"number","title":"First Price"},"last_price":{"type":"number","title":"Last Price"}},"type":"object","required":["model_name","provider","subscription_change_pct","direction","first_seen","last_seen","first_price","last_price"],"title":"SubscriptionTrendRecord","description":"Price trend for a single subscription-based tool over a time period."},"SubscriptionTrendsResponse":{"properties":{"trends":{"items":{"$ref":"#/components/schemas/SubscriptionTrendRecord"},"type":"array","title":"Trends"},"days":{"type":"integer","title":"Days"}},"type":"object","required":["trends","days"],"title":"SubscriptionTrendsResponse","description":"Response for GET /pricing/subscription-trends."},"TelemetryOverallStats":{"properties":{"total_requests":{"type":"integer","title":"Total Requests","description":"Total API requests since startup"},"total_errors":{"type":"integer","title":"Total Errors","description":"Total failed requests"},"error_rate":{"type":"number","title":"Error Rate","description":"Error rate as percentage"},"total_endpoints":{"type":"integer","title":"Total Endpoints","description":"Number of unique endpoints called"},"total_providers_adopted":{"type":"integer","title":"Total Providers Adopted","description":"Number of providers adopted"},"total_features_used":{"type":"integer","title":"Total Features Used","description":"Number of distinct features used"},"avg_response_time_ms":{"type":"number","title":"Avg Response Time Ms","description":"Average response time across all endpoints"},"unique_clients":{"type":"integer","title":"Unique Clients","description":"Number of unique client IP addresses"},"unique_countries":{"type":"integer","title":"Unique Countries","description":"Number of unique countries"},"uptime_since":{"type":"string","title":"Uptime Since","description":"ISO timestamp when telemetry tracking started"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO timestamp of this response"}},"type":"object","required":["total_requests","total_errors","error_rate","total_endpoints","total_providers_adopted","total_features_used","avg_response_time_ms","unique_clients","unique_countries","uptime_since","timestamp"],"title":"TelemetryOverallStats","description":"Overall telemetry statistics."},"TelemetryResponse":{"properties":{"overall_stats":{"$ref":"#/components/schemas/TelemetryOverallStats","description":"Overall statistics"},"endpoints":{"items":{"$ref":"#/components/schemas/EndpointMetricResponse"},"type":"array","title":"Endpoints","description":"Per-endpoint metrics"},"provider_adoption":{"items":{"$ref":"#/components/schemas/ProviderAdoptionResponse"},"type":"array","title":"Provider Adoption","description":"Provider adoption metrics"},"features":{"items":{"$ref":"#/components/schemas/FeatureUsageResponse"},"type":"array","title":"Features","description":"Feature usage metrics"},"client_locations":{"items":{"$ref":"#/components/schemas/ClientLocationStats"},"type":"array","title":"Client Locations","description":"Geographic distribution of requests"},"top_browsers":{"items":{"$ref":"#/components/schemas/BrowserStats"},"type":"array","title":"Top Browsers","description":"Top browsers used by clients"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Response timestamp"}},"type":"object","required":["overall_stats","endpoints","provider_adoption","features"],"title":"TelemetryResponse","description":"Complete telemetry data response."},"TokenVolumePrice":{"properties":{"input_cost":{"type":"number","title":"Input Cost","description":"Cost for input tokens in USD"},"output_cost":{"type":"number","title":"Output Cost","description":"Cost for output tokens in USD"},"total_cost":{"type":"number","title":"Total Cost","description":"Total cost (50/50 input/output split) in USD"}},"type":"object","required":["input_cost","output_cost","total_cost"],"title":"TokenVolumePrice","description":"Price breakdown for a specific token volume."},"UsageBatchRequest":{"properties":{"events":{"items":{"$ref":"#/components/schemas/UsageEventRequest"},"type":"array","maxItems":500,"minItems":1,"title":"Events","description":"Usage events to record"}},"type":"object","required":["events"],"title":"UsageBatchRequest","description":"Request model for reporting multiple usage events at once."},"UsageBatchResponse":{"properties":{"recorded":{"type":"integer","title":"Recorded","description":"Number of new events recorded"},"duplicates":{"type":"integer","title":"Duplicates","description":"Number of events skipped as duplicates"},"failed":{"type":"integer","title":"Failed","description":"Number of events that failed (e.g. unknown model)"},"errors":{"items":{"type":"string"},"type":"array","title":"Errors","description":"Error messages for failed events"},"total_cost_usd":{"type":"number","title":"Total Cost Usd","description":"Sum of cost_usd across newly recorded events"}},"type":"object","required":["recorded","duplicates","failed","total_cost_usd"],"title":"UsageBatchResponse","description":"Response for POST /usage/batch."},"UsageEventRequest":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Name of the LLM model that was called"},"input_tokens":{"type":"integer","minimum":0.0,"title":"Input Tokens","description":"Number of input tokens actually used"},"output_tokens":{"type":"integer","minimum":0.0,"title":"Output Tokens","description":"Number of output tokens actually used"},"occurred_at":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Occurred At","description":"Unix timestamp when the call happened; defaults to ingestion time"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"Idempotency key — resubmitting the same request_id for the same org is a no-op"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Optional session ID to tag this event with, so it can later be grouped and retrieved via GET /usage/session/{session_id} — e.g. a bounded burst of calls like a coding-agent run or a chat session"}},"type":"object","required":["model_name","input_tokens","output_tokens"],"title":"UsageEventRequest","description":"Request model for reporting a single actual LLM usage event."},"UsageEventResponse":{"properties":{"recorded":{"type":"boolean","title":"Recorded","description":"Whether a new row was recorded"},"duplicate":{"type":"boolean","title":"Duplicate","description":"True if this request_id was already recorded for this org"},"model_name":{"type":"string","title":"Model Name","description":"Resolved model name"},"provider":{"type":"string","title":"Provider","description":"Resolved provider"},"input_tokens":{"type":"integer","title":"Input Tokens","description":"Input tokens as submitted"},"output_tokens":{"type":"integer","title":"Output Tokens","description":"Output tokens as submitted"},"cost_usd":{"type":"number","title":"Cost Usd","description":"Cost computed server-side from current pricing, in USD"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organisation this event was attributed to"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session this event was tagged with, if any"}},"type":"object","required":["recorded","duplicate","model_name","provider","input_tokens","output_tokens","cost_usd"],"title":"UsageEventResponse","description":"Response for POST /usage."},"UsageModelBreakdown":{"properties":{"model_name":{"type":"string","title":"Model Name","description":"Model name"},"provider":{"type":"string","title":"Provider","description":"Provider"},"request_count":{"type":"integer","title":"Request Count","description":"Number of usage events recorded for this model"},"total_cost_usd":{"type":"number","title":"Total Cost Usd","description":"Total cost in USD for this model"}},"type":"object","required":["model_name","provider","request_count","total_cost_usd"],"title":"UsageModelBreakdown","description":"Spend breakdown for a single model within a usage summary."},"UsageProviderBreakdown":{"properties":{"provider":{"type":"string","title":"Provider","description":"Provider"},"request_count":{"type":"integer","title":"Request Count","description":"Number of usage events recorded for this provider"},"total_cost_usd":{"type":"number","title":"Total Cost Usd","description":"Total cost in USD for this provider"}},"type":"object","required":["provider","request_count","total_cost_usd"],"title":"UsageProviderBreakdown","description":"Spend breakdown for a single provider within a usage summary."},"UsageSummaryResponse":{"properties":{"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organisation filter applied"},"days":{"type":"integer","title":"Days","description":"Look-back window in days"},"total_requests":{"type":"integer","title":"Total Requests","description":"Total usage events in the window"},"total_cost_usd":{"type":"number","title":"Total Cost Usd","description":"Total actual spend in USD across all recorded events"},"total_input_tokens":{"type":"integer","title":"Total Input Tokens","description":"Total input tokens across all recorded events"},"total_output_tokens":{"type":"integer","title":"Total Output Tokens","description":"Total output tokens across all recorded events"},"by_model":{"items":{"$ref":"#/components/schemas/UsageModelBreakdown"},"type":"array","title":"By Model","description":"Spend broken down by model"},"by_provider":{"items":{"$ref":"#/components/schemas/UsageProviderBreakdown"},"type":"array","title":"By Provider","description":"Spend broken down by provider"},"estimated_request_count":{"type":"integer","title":"Estimated Request Count","description":"Number of usage events in this window whose tokens were text-derived estimates","default":0},"has_estimated_usage":{"type":"boolean","title":"Has Estimated Usage","description":"True if any usage event in this window was recorded from an estimate, not exact counts","default":false}},"type":"object","required":["days","total_requests","total_cost_usd","total_input_tokens","total_output_tokens"],"title":"UsageSummaryResponse","description":"Response for GET /usage/summary."},"UseCaseResponse":{"properties":{"models":{"items":{"$ref":"#/components/schemas/ModelUseCase"},"type":"array","title":"Models","description":"Use case information for each model"},"total_models":{"type":"integer","title":"Total Models","description":"Total number of models"},"providers":{"items":{"type":"string"},"type":"array","title":"Providers","description":"List of providers included"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"Response timestamp"}},"type":"object","required":["models","total_models","providers"],"title":"UseCaseResponse","description":"Response model for use cases endpoint."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"_ProxyRequest":{"properties":{"model":{"type":"string","title":"Model"},"messages":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Messages"},"max_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens"}},"type":"object","required":["model","messages"],"title":"_ProxyRequest"}}},"tags":[{"name":"Pricing","description":"Live LLM model pricing data across 26 providers (150+ models). Supports filtering by provider and capability."},{"name":"Pricing History","description":"Historical pricing snapshots, trend analysis, and CSV/JSON export."},{"name":"Pricing Alerts","description":"Register and manage webhook-based price-change alerts for specific models."},{"name":"Cost Estimation","description":"Estimate and compare token-based costs across models for single or batched workloads."},{"name":"Performance","description":"Quality scores, benchmark data, and use-case routing recommendations."},{"name":"Router","description":"Intelligent model routing — recommend the best model for a given prompt, stream routing events, and submit feedback to improve future recommendations."},{"name":"Telemetry","description":"API usage metrics, endpoint adoption stats, and per-org cost savings tracking."},{"name":"Usage","description":"Record and summarize actual LLM usage/spend — the real-cost counterpart to /cost-estimate's hypothetical numbers. Cost is always computed server-side from current pricing, never trusted from the caller."},{"name":"Agent","description":"RAG-powered pricing assistant. Supports streaming and persistent conversation history."},{"name":"Billing","description":"Customer sign-up, Stripe checkout, subscription portal, and account dashboard."},{"name":"Health","description":"Liveness, readiness, and detailed health check endpoints for orchestrators."},{"name":"Deployment","description":"Deployment metadata, API version info, and graceful shutdown control."},{"name":"API Info","description":"Rate-limit tier definitions and API version negotiation."},{"name":"Admin","description":"Internal admin endpoints — aggregate stats, rate-limit state, and customer list."},{"name":"OpenAI Proxy","description":"OpenAI-compatible `/v1/chat/completions` proxy that transparently routes requests through the LLM router and returns pricing metadata in the response."}]}