diff --git a/public/docs/api/index.html b/public/docs/api/index.html index d98ae2ca..d31340d9 100644 --- a/public/docs/api/index.html +++ b/public/docs/api/index.html @@ -50,24 +50,32 @@
include_proprietary=true: also consider models not confirmed open-weight.detail: compact (default) or full; 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 | — | — |
| Endpoint | Response | Query parameters | Sort values |
|---|---|---|---|
/api/v1/ | API metadata and endpoint directory | pretty | — |
/api/v1/use-cases | List workload recommendation presets and their assumed mixes, weights, requirements, and quality floors | pretty | — |
/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/estimate | Per-provider cost for a model at a token count and mix, cheapest first | model, tokens, mix, use_case | — |
/api/v1/compare | Compare cheapest per-provider cost across up to 20 models | models, tokens, mix, use_case | — |
/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 | — | — |
/api/v1/modelsorg, provider, min_context, min_output, min_intelligence, quantization, open_weights, cache_read, cache_write, promo, zdr, sub, benchmarked, search, sort, order, limit, offset, prettyid, input, output, cache_read, cache_write, context, max_output, uptime, discount, intelligence, coding, agentic/api/v1/models/:canonicalId/providerstokens, mix, pretty/api/v1/models/:canonicalId/historydays, mix, pretty/api/v1/estimatemodel, tokens, mix, use_case, pretty/api/v1/comparemodels, tokens, mix, use_case, pretty/api/v1/statspretty/api/v1/orgspretty/api/v1/providerszdr, pretty/api/v1/imagesorg, provider, search, sort, order, limit, offset, prettyid, org, provider/api/v1/images/:idpretty/api/v1/videosorg, provider, search, sort, order, limit, offset, prettyid, org, provider/api/v1/videos/:idprettyEvery parameter below is documented with its type, default and the behaviour you should expect, including the cases where a value is accepted but has no effect. Prices in responses are USD per million tokens, and an unknown price or timestamp is null — never 0 and never "free". The same descriptions are published as JSON Schemas and parameter objects in the OpenAPI 3.1 document, including components.schemas for model rows, provider offerings, price history, recommendations and errors.
/api/v1/pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/use-casespretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/recommenduse_case (required) string — Workload preset id. See /api/v1/use-cases for each preset's assumed mix, weights, requirements and quality floor./api/v1/modelsorder string, default asc (asc, desc) — Sort direction, case-insensitive (DESC works). Any other value is a 400.limit integer, default 100 — Page size, a positive integer. Values above 500 are clamped to 500 and the response limit reports the applied value; 0, negative, fractional or non-numeric values are a 400.offset integer, default 0 — Zero-based index of the first row, a non-negative integer; anything else is a 400. An offset past the end returns an empty page with an honest total.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/models/:canonicalId/providerstokens number — Positive token count. It scales the cost figure only and never changes the order; zero, negative or non-numeric values are a 400.mix string — Comma-separated input, cached-input, output percentages used to blend each offering's rates. Must sum to 100, validated like /history. When present, offerings sort by the blended rate at this mix with unpriceable offerings last; tokens is not required. Without it, offerings sort by input + output, unpriced offerings last.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/models/:canonicalId/historydays integer, default 90 — Window length in days, today inclusive. Values outside 1-90 or non-numeric return 400.mix string — Three percentages (fresh input, cached input, output) summing to 100 ±0.5, blended at read time against the stored raw tariffs. Malformed mixes return 400. Defaults to the agentic mix 2.5, 97, 0.5.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/estimate/api/v1/estimatetokens (required) number — Raw token count to price (for example 1000000 for one million). Must be positive.mix string — Fresh input, cached input and output percentages summing to 100. Required unless use_case is given; the two are mutually exclusive.use_case string — Take the mix from this workload preset instead of mix. The response marks the mix assumed: true.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/compare/api/v1/comparetokens (required) number — Raw token count to price (for example 1000000 for one million). Must be positive.mix string — Fresh input, cached input and output percentages summing to 100. Required unless use_case is given; the two are mutually exclusive.use_case string — Take the mix from this workload preset instead of mix. The response marks the mix assumed: true.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/statspretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/orgspretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/providerszdr boolean — When true, keep only providers whose metadata says retains_prompts: false.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/images/api/v1/imagesorder string, default asc (asc, desc) — Sort direction, case-insensitive (DESC works). Any other value is a 400.limit integer, default 100 — Page size, a positive integer. Values above 500 are clamped to 500 and the response limit reports the applied value; 0, negative, fractional or non-numeric values are a 400.offset integer, default 0 — Zero-based index of the first row, a non-negative integer; anything else is a 400. An offset past the end returns an empty page with an honest total.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/images/:idpretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/videos/api/v1/videosorder string, default asc (asc, desc) — Sort direction, case-insensitive (DESC works). Any other value is a 400.limit integer, default 100 — Page size, a positive integer. Values above 500 are clamped to 500 and the response limit reports the applied value; 0, negative, fractional or non-numeric values are a 400.offset integer, default 0 — Zero-based index of the first row, a non-negative integer; anything else is a 400. An offset past the end returns an empty page with an honest total.pretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients./api/v1/videos/:idpretty string, default 0 (1, 0, true, false) — When 1 or true, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.curl 'https://tokenwatch.wyrdwerk.com/api/v1/models?provider=aster&sort=input&limit=20'
diff --git a/public/openapi.json b/public/openapi.json
index cf327bc6..bff858f3 100644
--- a/public/openapi.json
+++ b/public/openapi.json
@@ -3,7 +3,7 @@
"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. Prices are USD per million tokens unless a response says otherwise, and every unknown value is null rather than zero."
+ "description": "Read-only, public JSON API for TokenWatch text, image, video, provider, organization, pricing catalog data, and workload-aware recommendations. Prices are USD per million tokens unless a response says otherwise, and every unknown value is null rather than zero. Responses are compact JSON (`pretty=1` to indent) and carry a strong `ETag`: send `If-None-Match` to get a bodyless 304. Successful GETs are cacheable for 300 seconds with a 600-second stale-while-revalidate window; errors are `no-store`. `HEAD` returns the same status and headers as `GET` without a body."
},
"servers": [
{
@@ -15,7 +15,24 @@
"get": {
"summary": "API metadata and endpoint directory",
"operationId": "getApiV1",
- "parameters": [],
+ "parameters": [
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
+ }
+ ],
"responses": {
"200": {
"description": "Catalog counts and the rendered endpoint directory.",
@@ -65,7 +82,24 @@
"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": [],
+ "parameters": [
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
+ }
+ ],
"responses": {
"200": {
"description": "The nine workload presets with their assumed mixes, benchmark and provider weights, hard requirements, quantization policy and quality floors.",
@@ -629,6 +663,22 @@
"minimum": 0,
"default": 0
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -707,6 +757,22 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -788,6 +854,22 @@
"type": "string",
"pattern": "^\\d+(\\.\\d+)?(,\\d+(\\.\\d+)?){2}$"
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -888,6 +970,22 @@
"frontend-ui"
]
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -988,6 +1086,22 @@
"frontend-ui"
]
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -1038,7 +1152,24 @@
"get": {
"summary": "Return catalog, provider, organization, privacy, cache, and quantization counts",
"operationId": "getApiV1Stats",
- "parameters": [],
+ "parameters": [
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
+ }
+ ],
"responses": {
"200": {
"description": "Catalog, provider, organization, privacy, cache and quantization counts. Each bucket map sums to `model_count`.",
@@ -1087,7 +1218,24 @@
"get": {
"summary": "List model organizations with offering counts",
"operationId": "getApiV1Orgs",
- "parameters": [],
+ "parameters": [
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
+ }
+ ],
"responses": {
"200": {
"description": "Organizations with offering counts, sorted by count descending.",
@@ -1145,6 +1293,22 @@
"schema": {
"type": "boolean"
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -1274,6 +1438,22 @@
"minimum": 0,
"default": 0
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -1333,6 +1513,22 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -1462,6 +1658,22 @@
"minimum": 0,
"default": 0
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
@@ -1521,6 +1733,22 @@
"schema": {
"type": "string"
}
+ },
+ {
+ "name": "pretty",
+ "in": "query",
+ "required": false,
+ "description": "When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.",
+ "schema": {
+ "type": "string",
+ "enum": [
+ "1",
+ "0",
+ "true",
+ "false"
+ ],
+ "default": "0"
+ }
}
],
"responses": {
diff --git a/scripts/seo-pages.mjs b/scripts/seo-pages.mjs
index 8da0904b..a17f6cd2 100644
--- a/scripts/seo-pages.mjs
+++ b/scripts/seo-pages.mjs
@@ -1419,7 +1419,7 @@ export function buildOpenApiDocument() {
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. Prices are USD per million tokens unless a response says otherwise, and every unknown value is null rather than zero.',
+ description: 'Read-only, public JSON API for TokenWatch text, image, video, provider, organization, pricing catalog data, and workload-aware recommendations. Prices are USD per million tokens unless a response says otherwise, and every unknown value is null rather than zero. Responses are compact JSON (`pretty=1` to indent) and carry a strong `ETag`: send `If-None-Match` to get a bodyless 304. Successful GETs are cacheable for 300 seconds with a 600-second stale-while-revalidate window; errors are `no-store`. `HEAD` returns the same status and headers as `GET` without a body.',
},
servers: [{ url: SITE }],
paths,
diff --git a/shared/api-meta.mjs b/shared/api-meta.mjs
index 11e50938..072690bb 100644
--- a/shared/api-meta.mjs
+++ b/shared/api-meta.mjs
@@ -4,14 +4,14 @@ export const API_ENDPOINTS = [
{
path: '/api/v1/',
summary: 'API metadata and endpoint directory',
- params: [],
+ params: ['pretty'],
sort: [],
},
{
path: '/api/v1/use-cases',
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.',
- params: [],
+ params: ['pretty'],
sort: [],
},
{
@@ -37,7 +37,7 @@ export const API_ENDPOINTS = [
{
path: '/api/v1/models',
summary: 'List text-generation model offerings',
- params: ['org', 'provider', 'min_context', 'min_output', 'min_intelligence', 'quantization', 'open_weights', 'cache_read', 'cache_write', 'promo', 'zdr', 'sub', 'benchmarked', 'search', 'sort', 'order', 'limit', 'offset'],
+ params: ['org', 'provider', 'min_context', 'min_output', 'min_intelligence', 'quantization', 'open_weights', 'cache_read', 'cache_write', 'promo', 'zdr', 'sub', 'benchmarked', 'search', 'sort', 'order', 'limit', 'offset', 'pretty'],
errorNote: 'Invalid parameters return 400 with { error, parameter, code: "invalid_parameter" }. Booleans accept only true or false; minimums are non-negative integers.',
parameterLimits: { limit: 500 },
parameterFormats: { order: 'asc or desc (case-insensitive); default asc' },
@@ -46,7 +46,7 @@ export const API_ENDPOINTS = [
{
path: '/api/v1/models/:canonicalId/providers',
summary: 'List providers for one canonical model, ordered by cost',
- params: ['tokens', 'mix'],
+ params: ['tokens', 'mix', 'pretty'],
errorNote: 'Invalid mix or non-positive tokens return 400. Supplying mix without tokens sorts by the blended rate at that mix.',
parameterFormats: { mix: 'inputPct,cacheReadPct,outputPct summing to 100' },
sort: [],
@@ -54,14 +54,14 @@ export const API_ENDPOINTS = [
{
path: '/api/v1/models/:canonicalId/history',
summary: 'Daily cheapest-provider price history, blended at read time',
- params: ['days', 'mix'],
+ params: ['days', 'mix', 'pretty'],
sort: [],
},
{
path: '/api/v1/estimate',
summary: 'Per-provider cost for a model at a token count and mix, cheapest first',
description: 'Returns { provider, provider_display, quantization, rate_per_mtok, cost_usd } for every offering of one canonical model, sorted cheapest first. Offerings that cannot be priced at the requested mix return cost_usd: null with an unpriceable_reason and are listed last — never $0. Supply either mix=inputPct,cacheReadPct,outputPct or use_case=.',
- params: ['model', 'tokens', 'mix', 'use_case'],
+ params: ['model', 'tokens', 'mix', 'use_case', 'pretty'],
requiredParams: ['model', 'tokens'],
errorNote: 'Invalid parameters return 400 with { error, parameter, code: "invalid_parameter" }; an unknown model returns 404 with code "model_not_found".',
parameterFormats: { mix: 'inputPct,cacheReadPct,outputPct summing to 100; mutually exclusive with use_case' },
@@ -71,7 +71,7 @@ export const API_ENDPOINTS = [
path: '/api/v1/compare',
summary: 'Compare cheapest per-provider cost across up to 20 models',
description: 'Returns per model the cheapest provider and cost, the most expensive provider cost, the spread, and the savings versus the most expensive option. Unknown ids are reported in a not_found array instead of failing the whole request.',
- params: ['models', 'tokens', 'mix', 'use_case'],
+ params: ['models', 'tokens', 'mix', 'use_case', 'pretty'],
requiredParams: ['models', 'tokens'],
parameterLimits: { models: 20 },
errorNote: 'Invalid parameters return 400 with { error, parameter, code: "invalid_parameter" }. More than 20 model ids is a 400.',
@@ -81,43 +81,43 @@ export const API_ENDPOINTS = [
{
path: '/api/v1/stats',
summary: 'Return catalog, provider, organization, privacy, cache, and quantization counts',
- params: [],
+ params: ['pretty'],
sort: [],
},
{
path: '/api/v1/orgs',
summary: 'List model organizations with offering counts',
- params: [],
+ params: ['pretty'],
sort: [],
},
{
path: '/api/v1/providers',
summary: 'List provider metadata and policy fields',
- params: ['zdr'],
+ params: ['zdr', 'pretty'],
sort: [],
},
{
path: '/api/v1/images',
summary: 'List image-generation models',
- params: ['org', 'provider', 'search', 'sort', 'order', 'limit', 'offset'],
+ params: ['org', 'provider', 'search', 'sort', 'order', 'limit', 'offset', 'pretty'],
sort: ['id', 'org', 'provider'],
},
{
path: '/api/v1/images/:id',
summary: 'Return one image model with its pricing variants',
- params: [],
+ params: ['pretty'],
sort: [],
},
{
path: '/api/v1/videos',
summary: 'List video-generation models',
- params: ['org', 'provider', 'search', 'sort', 'order', 'limit', 'offset'],
+ params: ['org', 'provider', 'search', 'sort', 'order', 'limit', 'offset', 'pretty'],
sort: ['id', 'org', 'provider'],
},
{
path: '/api/v1/videos/:id',
summary: 'Return one video model with its pricing variants',
- params: [],
+ params: ['pretty'],
sort: [],
},
];
diff --git a/shared/openapi-params.mjs b/shared/openapi-params.mjs
index d2f1c7ee..026c0e52 100644
--- a/shared/openapi-params.mjs
+++ b/shared/openapi-params.mjs
@@ -44,6 +44,18 @@ const ORDER = {
description: 'Sort direction, case-insensitive (`DESC` works). Any other value is a 400.',
};
+/**
+ * JSON indentation. Every data route returns compact JSON by default and
+ * accepts `pretty=1`/`pretty=true` to indent it, so one definition is reused
+ * instead of restated per route.
+ */
+const PRETTY = {
+ type: 'string',
+ enum: ['1', '0', 'true', 'false'],
+ default: '0',
+ description: 'When `1` or `true`, indent the JSON. Every data route returns compact JSON by default and honours this flag; indenting inflates the payload, so it is meant for reading, not for clients.',
+};
+
const TEXT_FILTERS = {
org: {
type: 'string',
@@ -190,15 +202,16 @@ const COST_QUERY = {
};
export const PARAMETER_DOCS = {
- '/api/v1/': {},
- '/api/v1/use-cases': {},
- '/api/v1/stats': {},
- '/api/v1/orgs': {},
+ '/api/v1/': { pretty: PRETTY },
+ '/api/v1/use-cases': { pretty: PRETTY },
+ '/api/v1/stats': { pretty: PRETTY },
+ '/api/v1/orgs': { pretty: PRETTY },
'/api/v1/providers': {
zdr: {
type: 'boolean',
description: 'When `true`, keep only providers whose metadata says `retains_prompts: false`.',
},
+ pretty: PRETTY,
},
'/api/v1/recommend': {
use_case: RECOMMENDATION_COMMON.use_case,
@@ -234,6 +247,7 @@ export const PARAMETER_DOCS = {
order: ORDER,
limit: PAGINATION.limit,
offset: PAGINATION.offset,
+ pretty: PRETTY,
},
'/api/v1/models/:canonicalId/providers': {
tokens: {
@@ -245,6 +259,7 @@ export const PARAMETER_DOCS = {
type: 'string',
description: 'Comma-separated input, cached-input, output percentages used to blend each offering\'s rates. Must sum to 100, validated like `/history`. When present, offerings sort by the blended rate at this mix with unpriceable offerings last; `tokens` is not required. Without it, offerings sort by `input + output`, unpriced offerings last.',
},
+ pretty: PRETTY,
},
'/api/v1/models/:canonicalId/history': {
days: {
@@ -259,6 +274,7 @@ export const PARAMETER_DOCS = {
pattern: '^\\d+(\\.\\d+)?(,\\d+(\\.\\d+)?){2}$',
description: 'Three percentages (fresh input, cached input, output) summing to 100 ±0.5, blended at read time against the stored raw tariffs. Malformed mixes return 400. Defaults to the agentic mix 2.5, 97, 0.5.',
},
+ pretty: PRETTY,
},
'/api/v1/estimate': {
model: {
@@ -267,6 +283,7 @@ export const PARAMETER_DOCS = {
description: 'Canonical or org/model id.',
},
...COST_QUERY,
+ pretty: PRETTY,
},
'/api/v1/compare': {
models: {
@@ -275,6 +292,7 @@ export const PARAMETER_DOCS = {
description: 'Comma-separated canonical or org/model ids, at most 20 after de-duplication. Unknown ids are reported in `not_found` rather than failing the request.',
},
...COST_QUERY,
+ pretty: PRETTY,
},
'/api/v1/images': {
...MEDIA_FILTERS,
@@ -282,16 +300,18 @@ export const PARAMETER_DOCS = {
order: ORDER,
limit: PAGINATION.limit,
offset: PAGINATION.offset,
+ pretty: PRETTY,
},
- '/api/v1/images/:id': {},
+ '/api/v1/images/:id': { pretty: PRETTY },
'/api/v1/videos': {
...MEDIA_FILTERS,
sort: MEDIA_SORT,
order: ORDER,
limit: PAGINATION.limit,
offset: PAGINATION.offset,
+ pretty: PRETTY,
},
- '/api/v1/videos/:id': {},
+ '/api/v1/videos/:id': { pretty: PRETTY },
};
/** Path parameter docs for the templated routes. */
diff --git a/test/openapi.test.mjs b/test/openapi.test.mjs
index c3a894d1..a56cb83a 100644
--- a/test/openapi.test.mjs
+++ b/test/openapi.test.mjs
@@ -224,3 +224,24 @@ test('the committed openapi.json matches what the generator produces', () => {
assert.deepEqual(committed, doc,
'public/openapi.json is stale — run `npm run seo` and commit the result');
});
+
+// The handler applies `pretty` centrally in withETag, so it is honoured by
+// every data route. Documenting it on only some routes understates the API
+// (and once did: it was published for /recommend alone while working
+// everywhere), so pin the full set here.
+test('pretty is documented on every data route', () => {
+ const missing = [];
+ for (const path of Object.keys(doc.paths)) {
+ const names = doc.paths[path].get.parameters.map((parameter) => parameter.name);
+ if (!names.includes('pretty')) missing.push(path);
+ }
+ assert.deepEqual(missing, [], 'these routes honour pretty but do not document it');
+
+ // And it must not be advertised on a route the router rejects it on: every
+ // documented pretty parameter belongs to a registered endpoint.
+ for (const path of Object.keys(doc.paths)) {
+ const parameter = doc.paths[path].get.parameters.find((p) => p.name === 'pretty');
+ assert.equal(parameter.in, 'query');
+ assert.ok(parameter.description.length > 20, `${path}?pretty needs a real description`);
+ }
+});