Public JSON API
All endpoints accept GET requests and return JSON with permissive CORS headers. List endpoints paginate with limit and offset; the limit is clamped to 1–500 and defaults to 100. A machine-readable OpenAPI 3.1 description is also available.
Recommendation mixes are assumed workload defaults, not claims about your traffic. Model picks include best quality, best value, and the cheapest model above an absolute quality floor; explanations label benchmark coverage, provider ranking, missing signals, and confidence. Provider ranking requires confirmed capability and context metadata and keeps unverified options separate.
For chat-assistant and creative-writing, /api/v1/recommend also returns preference separately from model picks: the Arena favorite, board, rating, eligible providers, and source metadata with linked dataset, rating date, attribution, and CC BY 4.0 license. Creative writing is preference-led; chat picks remain capability-ranked. The source metadata lets API consumers display the required attribution alongside Arena ratings.
Recommendation responses default to compact candidate groups (up to 10 rows each, with total counts) and full explanations on the three model picks. Provider results keep full explanations on the top three. Add detail=full to expand explanations for returned rows, or set limit=1..100 to change each group cap. Recommendation JSON is compact (no indentation); add pretty=1 for indented output.
Recommendation parameters
The recommendation endpoints power the open model finder. Unknown values return HTTP 400 naming the rejected parameter; an unknown model returns 404.
use_case(required):agentic-coding,tool-agents,long-context-rag,structured-extraction,high-volume-cheap,chat-assistant,creative-writing,reasoning-math,frontend-ui.model(required for/api/v1/recommend/providers): a canonical model ID from the catalog.priority:balanced,cheapest,fastest,most-reliable(defaultbalanced); re-weights provider ranking.zdr=true: only providers marked zero data retention.exclude_hq: comma-separated two-letter headquarters country codes to exclude; providers with unknown headquarters are not excluded.include_proprietary=true: also consider models not confirmed open-weight.detail:compact(default) orfull;limit: rows per group, 1–100 (default 10);pretty=1: indented JSON.
| Endpoint | Response | Query parameters | Sort values |
|---|---|---|---|
/api/v1/ | API metadata and endpoint directory | — | — |
/api/v1/use-cases | List workload recommendation presets and their assumed mixes, weights, requirements, and quality floors | — | — |
/api/v1/recommend | Recommend models for a workload; chat and creative-writing also return an Arena preference favorite with source metadata | use_case, priority, zdr, exclude_hq, include_proprietary, detail, limit, pretty | — |
/api/v1/recommend/providers | Rank providers for one model with full explanations for the top three and compact remaining rows | use_case, model, priority, zdr, exclude_hq, include_proprietary, detail, limit, pretty | — |
/api/v1/models | List text-generation model offerings | org, provider, min_context, min_output, min_intelligence, quantization, open_weights, cache_read, cache_write, promo, zdr, sub, benchmarked, search, sort, order, limit, offset | id, input, output, cache_read, cache_write, context, max_output, uptime, discount, intelligence, coding, agentic |
/api/v1/models/:canonicalId/providers | List providers for one canonical model, ordered by cost | tokens, mix | — |
/api/v1/models/:canonicalId/history | Daily cheapest-provider price history, blended at read time | days, mix | — |
/api/v1/stats | Return catalog, provider, organization, privacy, cache, and quantization counts | — | — |
/api/v1/orgs | List model organizations with offering counts | — | — |
/api/v1/providers | List provider metadata and policy fields | zdr | — |
/api/v1/images | List image-generation models | org, provider, search, sort, order, limit, offset | id, org, provider |
/api/v1/images/:id | Return one image model with its pricing variants | — | — |
/api/v1/videos | List video-generation models | org, provider, search, sort, order, limit, offset | id, org, provider |
/api/v1/videos/:id | Return one video model with its pricing variants | — | — |
Examples
curl 'https://tokenwatch.wyrdwerk.com/api/v1/models?provider=aster&sort=input&limit=20'
curl 'https://tokenwatch.wyrdwerk.com/api/v1/models?open_weights=true&limit=20'
curl 'https://tokenwatch.wyrdwerk.com/api/v1/models/glm-5.2/providers?tokens=1000000&mix=30,50,20'
curl 'https://tokenwatch.wyrdwerk.com/api/v1/use-cases'
curl 'https://tokenwatch.wyrdwerk.com/api/v1/recommend?use_case=agentic-coding&priority=balanced&zdr=true&exclude_hq=CN&limit=5'
curl 'https://tokenwatch.wyrdwerk.com/api/v1/recommend/providers?use_case=agentic-coding&model=deepseek-v4-flash&priority=fastest&detail=full'
curl 'https://tokenwatch.wyrdwerk.com/api/v1/providers?zdr=true'
curl 'https://tokenwatch.wyrdwerk.com/api/v1/videos?provider=fal&limit=25'Errors and freshness
Malformed model-ID encoding returns HTTP 400, unknown routes return 404, and unavailable catalog assets return 503. Every catalog response includes its source generation timestamp. Raw API and JSON files are marked noindex; this page is the crawlable reference.
Embeddable pricing cards
The widget demo shows the Shadow DOM pricing card. Add data-tw-model to an element and load https://tokenwatch.wyrdwerk.com/widget/embed.js.