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 @@

Recommendation parameters

  • 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.
  • -
    - +
    TokenWatch API endpoints
    EndpointResponseQuery parametersSort values
    /api/v1/API metadata and endpoint directory——
    /api/v1/use-casesList workload recommendation presets and their assumed mixes, weights, requirements, and quality floors——
    + - - - - - - - - - - - -
    TokenWatch API endpoints
    EndpointResponseQuery parametersSort values
    /api/v1/API metadata and endpoint directorypretty—
    /api/v1/use-casesList workload recommendation presets and their assumed mixes, weights, requirements, and quality floorspretty—
    /api/v1/recommendRecommend models for a workload; chat and creative-writing also return an Arena preference favorite with source metadatause_case, priority, zdr, exclude_hq, include_proprietary, detail, limit, pretty—
    /api/v1/recommend/providersRank providers for one model with full explanations for the top three and compact remaining rowsuse_case, model, priority, zdr, exclude_hq, include_proprietary, detail, limit, pretty—
    /api/v1/modelsList text-generation model offeringsorg, provider, min_context, min_output, min_intelligence, quantization, open_weights, cache_read, cache_write, promo, zdr, sub, benchmarked, search, sort, order, limit, offsetid, input, output, cache_read, cache_write, context, max_output, uptime, discount, intelligence, coding, agentic
    /api/v1/models/:canonicalId/providersList providers for one canonical model, ordered by costtokens, mix—
    /api/v1/models/:canonicalId/historyDaily cheapest-provider price history, blended at read timedays, mix—
    /api/v1/estimatePer-provider cost for a model at a token count and mix, cheapest firstmodel, tokens, mix, use_case—
    /api/v1/compareCompare cheapest per-provider cost across up to 20 modelsmodels, tokens, mix, use_case—
    /api/v1/statsReturn catalog, provider, organization, privacy, cache, and quantization counts——
    /api/v1/orgsList model organizations with offering counts——
    /api/v1/providersList provider metadata and policy fieldszdr—
    /api/v1/imagesList image-generation modelsorg, provider, search, sort, order, limit, offsetid, org, provider
    /api/v1/images/:idReturn one image model with its pricing variants——
    /api/v1/videosList video-generation modelsorg, provider, search, sort, order, limit, offsetid, org, provider
    /api/v1/videos/:idReturn one video model with its pricing variants——
    +/api/v1/modelsList text-generation model offeringsorg, 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/providersList providers for one canonical model, ordered by costtokens, mix, pretty— +/api/v1/models/:canonicalId/historyDaily cheapest-provider price history, blended at read timedays, mix, pretty— +/api/v1/estimatePer-provider cost for a model at a token count and mix, cheapest firstmodel, tokens, mix, use_case, pretty— +/api/v1/compareCompare cheapest per-provider cost across up to 20 modelsmodels, tokens, mix, use_case, pretty— +/api/v1/statsReturn catalog, provider, organization, privacy, cache, and quantization countspretty— +/api/v1/orgsList model organizations with offering countspretty— +/api/v1/providersList provider metadata and policy fieldszdr, pretty— +/api/v1/imagesList image-generation modelsorg, provider, search, sort, order, limit, offset, prettyid, org, provider +/api/v1/images/:idReturn one image model with its pricing variantspretty— +/api/v1/videosList video-generation modelsorg, provider, search, sort, order, limit, offset, prettyid, org, provider +/api/v1/videos/:idReturn one video model with its pricing variantspretty—

    Parameter reference

    Every 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/

    + +

    /api/v1/use-cases

    +

    /api/v1/recommend

    /api/v1/models/:canonicalId/providers

    /api/v1/models/:canonicalId/history

    /api/v1/estimate

    /api/v1/compare

    +

    /api/v1/stats

    + +

    /api/v1/orgs

    +

    /api/v1/providers

    /api/v1/images

    +

    /api/v1/images/:id

    +

    /api/v1/videos

    +

    /api/v1/videos/:id

    +

    Examples

    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`);
    +  }
    +});