{"openapi":"3.1.0","info":{"title":"TokenWatch Pricing API","version":"v1","description":"Read-only, public JSON API for TokenWatch text, image, video, provider, organization, pricing catalog data, and workload-aware recommendations."},"servers":[{"url":"https://tokenwatch.wyrdwerk.com"}],"paths":{"/api/v1/":{"get":{"summary":"API metadata and endpoint directory","operationId":"getApiV1","parameters":[],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/use-cases":{"get":{"summary":"List workload recommendation presets and their assumed mixes, weights, requirements, and quality floors","description":"Returns the nine use-case presets used by /choose/ and the recommend endpoints. Every mix is flagged assumed: true; weights and floors are documented judgments, not measurements.","operationId":"getApiV1UseCases","parameters":[],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/recommend":{"get":{"summary":"Recommend models for a workload; chat and creative-writing also return an Arena preference favorite with source metadata","description":"Open-weight model shortlist for one use case: picks.bestQuality, picks.bestValue (quality/price Pareto frontier) and picks.cheapestAboveFloor, each with a recommended provider, explanation, and confidence (stable, moderately_stable, close_call). Also returns alsoConsidered, partiallyBenchmarked, unbenchmarked, and unverified groups. Arena ratings in preference are from the LMArena leaderboard dataset (CC BY 4.0); display the attribution in preference.source.","operationId":"getApiV1Recommend","parameters":[{"name":"use_case","in":"query","required":true,"description":"Required workload preset id. See /api/v1/use-cases for assumed mixes, weights, requirements, and quality floors.","schema":{"type":"string","enum":["agentic-coding","tool-agents","long-context-rag","structured-extraction","high-volume-cheap","chat-assistant","creative-writing","reasoning-math","frontend-ui"]}},{"name":"priority","in":"query","required":false,"description":"Provider-rank weighting preset; defaults to balanced.","schema":{"type":"string","enum":["balanced","cheapest","fastest","most-reliable"]}},{"name":"zdr","in":"query","required":false,"description":"Set to true to keep only offerings or providers marked zero data retention.","schema":{"type":"boolean"}},{"name":"exclude_hq","in":"query","required":false,"description":"Comma-separated two-letter headquarters country codes to exclude; providers with unknown headquarters are not excluded.","schema":{"type":"string","pattern":"^[A-Za-z]{2}(,[A-Za-z]{2})*$"}},{"name":"include_proprietary","in":"query","required":false,"description":"Include models not confirmed open-weight; defaults to false for model recommendations.","schema":{"type":"boolean"}},{"name":"detail","in":"query","required":false,"description":"Defaults to compact; full returns explanations for all returned rows.","schema":{"type":"string","enum":["compact","full"],"default":"compact"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows per recommendation group; defaults to 10 (range 1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"pretty","in":"query","required":false,"description":"Set to 1 for indented JSON; responses are compact (unindented) by default.","schema":{"type":"string","enum":["1","0","true","false"],"default":"0"}}],"responses":{"200":{"description":"Successful JSON response. Chat and creative-writing include Arena preference.favorite and source attribution/date/license metadata in preference.source.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/recommend/providers":{"get":{"summary":"Rank providers for one model with full explanations for the top three and compact remaining rows","description":"Ranks eligible providers for one canonical model at the use case assumed mix on blended price, TTFT p50, throughput p50, and uptime, weighted by priority. Providers missing required capability or context metadata are returned in unverified, never ranked.","operationId":"getApiV1RecommendProviders","parameters":[{"name":"use_case","in":"query","required":true,"description":"Required workload preset id. See /api/v1/use-cases for assumed mixes, weights, requirements, and quality floors.","schema":{"type":"string","enum":["agentic-coding","tool-agents","long-context-rag","structured-extraction","high-volume-cheap","chat-assistant","creative-writing","reasoning-math","frontend-ui"]}},{"name":"model","in":"query","required":true,"description":"Required canonical model id. An unknown model returns 404.","schema":{"type":"string"}},{"name":"priority","in":"query","required":false,"description":"Provider-rank weighting preset; defaults to balanced.","schema":{"type":"string","enum":["balanced","cheapest","fastest","most-reliable"]}},{"name":"zdr","in":"query","required":false,"description":"Set to true to keep only offerings or providers marked zero data retention.","schema":{"type":"boolean"}},{"name":"exclude_hq","in":"query","required":false,"description":"Comma-separated two-letter headquarters country codes to exclude; providers with unknown headquarters are not excluded.","schema":{"type":"string","pattern":"^[A-Za-z]{2}(,[A-Za-z]{2})*$"}},{"name":"include_proprietary","in":"query","required":false,"description":"Include models not confirmed open-weight; defaults to false for model recommendations.","schema":{"type":"boolean"}},{"name":"detail","in":"query","required":false,"description":"Defaults to compact; full returns explanations for all returned rows.","schema":{"type":"string","enum":["compact","full"],"default":"compact"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows per recommendation group; defaults to 10 (range 1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"pretty","in":"query","required":false,"description":"Set to 1 for indented JSON; responses are compact (unindented) by default.","schema":{"type":"string","enum":["1","0","true","false"],"default":"0"}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/models":{"get":{"summary":"List text-generation model offerings","operationId":"getApiV1Models","parameters":[{"name":"org","in":"query","required":false,"description":"Filter or control parameter: org.","schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"description":"Filter or control parameter: provider.","schema":{"type":"string"}},{"name":"min_context","in":"query","required":false,"description":"Filter or control parameter: min_context.","schema":{"type":"number","minimum":0}},{"name":"min_output","in":"query","required":false,"description":"Filter or control parameter: min_output.","schema":{"type":"number","minimum":0}},{"name":"min_intelligence","in":"query","required":false,"description":"Filter or control parameter: min_intelligence.","schema":{"type":"number","minimum":0}},{"name":"quantization","in":"query","required":false,"description":"Filter or control parameter: quantization.","schema":{"type":"string"}},{"name":"open_weights","in":"query","required":false,"description":"Filter to models with resolved open_weights=true or false; unknown statuses are excluded.","schema":{"type":"boolean"}},{"name":"cache_read","in":"query","required":false,"description":"Filter or control parameter: cache_read.","schema":{"type":"boolean"}},{"name":"cache_write","in":"query","required":false,"description":"Filter or control parameter: cache_write.","schema":{"type":"boolean"}},{"name":"promo","in":"query","required":false,"description":"Filter or control parameter: promo.","schema":{"type":"boolean"}},{"name":"zdr","in":"query","required":false,"description":"Set to true to keep only offerings or providers marked zero data retention.","schema":{"type":"boolean"}},{"name":"sub","in":"query","required":false,"description":"Filter or control parameter: sub.","schema":{"type":"boolean"}},{"name":"benchmarked","in":"query","required":false,"description":"Filter or control parameter: benchmarked.","schema":{"type":"boolean"}},{"name":"search","in":"query","required":false,"description":"Filter or control parameter: search.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Filter or control parameter: sort.","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"Filter or control parameter: order.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size; defaults to 100 and is clamped to 1–500.","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Filter or control parameter: offset.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/models/{canonicalId}/providers":{"get":{"summary":"List providers for one canonical model, ordered by cost","operationId":"getApiV1ModelsCanonicalIdProviders","parameters":[{"name":"canonicalId","in":"path","required":true,"description":"Canonical resource identifier: canonicalId.","schema":{"type":"string"}},{"name":"tokens","in":"query","required":false,"description":"Filter or control parameter: tokens.","schema":{"type":"number","minimum":0}},{"name":"mix","in":"query","required":false,"description":"Comma-separated input, cached-input, and output percentages.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/models/{canonicalId}/history":{"get":{"summary":"Daily cheapest-provider price history, blended at read time","operationId":"getApiV1ModelsCanonicalIdHistory","parameters":[{"name":"canonicalId","in":"path","required":true,"description":"Canonical resource identifier: canonicalId.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Filter or control parameter: days.","schema":{"type":"string"}},{"name":"mix","in":"query","required":false,"description":"Comma-separated input, cached-input, and output percentages.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/stats":{"get":{"summary":"Return catalog, provider, organization, privacy, cache, and quantization counts","operationId":"getApiV1Stats","parameters":[],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/orgs":{"get":{"summary":"List model organizations with offering counts","operationId":"getApiV1Orgs","parameters":[],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/providers":{"get":{"summary":"List provider metadata and policy fields","operationId":"getApiV1Providers","parameters":[{"name":"zdr","in":"query","required":false,"description":"Set to true to keep only offerings or providers marked zero data retention.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/images":{"get":{"summary":"List image-generation models","operationId":"getApiV1Images","parameters":[{"name":"org","in":"query","required":false,"description":"Filter or control parameter: org.","schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"description":"Filter or control parameter: provider.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Filter or control parameter: search.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Filter or control parameter: sort.","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"Filter or control parameter: order.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size; defaults to 100 and is clamped to 1–500.","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Filter or control parameter: offset.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/images/{id}":{"get":{"summary":"Return one image model with its pricing variants","operationId":"getApiV1ImagesId","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical resource identifier: id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/videos":{"get":{"summary":"List video-generation models","operationId":"getApiV1Videos","parameters":[{"name":"org","in":"query","required":false,"description":"Filter or control parameter: org.","schema":{"type":"string"}},{"name":"provider","in":"query","required":false,"description":"Filter or control parameter: provider.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Filter or control parameter: search.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Filter or control parameter: sort.","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"Filter or control parameter: order.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size; defaults to 100 and is clamped to 1–500.","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","required":false,"description":"Filter or control parameter: offset.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/videos/{id}":{"get":{"summary":"Return one video model with its pricing variants","operationId":"getApiV1VideosId","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical resource identifier: id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful JSON response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request parameter or malformed model ID.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown API route or resource.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A required catalog asset is unavailable.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}