Document the model catalogue API (GET /v1/models)

[aleksandr-sudo]

Why

GET /v1/models serves roughly 1.2k requests a day and is documented nowhere: no page in this repo, and no Swagger decorators on the handler, so it is absent from Scalar too. Its entire query surface lives in a JSDoc comment in the gateway.

The practical cost: a customer (Help Scout #8265) has been maintaining our prices by hand and polling the deprecated-models HTML page, because nothing told them ?include=pricing exists — or that ?id=<model>&include=pricing answers in ~4 KB instead of 1.3 MB.

What this adds

• docs/api-references/service-endpoints/models-catalogue.md — the page
• docs/service-endpoints/models-catalogue.json — OpenAPI spec for the operation, same pattern as billing-balance.json
• a SUMMARY.md entry under Service Endpoints, next to Account Balance

What it documents

Every parameter, with the semantics verified against production:

• include (pricing / modalities / capabilities / all) and details as its synonym; unknown values ignored, not rejected
• the seven filters — id, type, tags, modalities, input_modalities, output_modalities, capabilities
• the matching rules: OR within one parameter, AND across parameters, case-insensitive, comma-separated or repeated params both accepted
• filters work independently of include — you can filter on capabilities without requesting that section

Plus the two things integrators actually get wrong:

1. Matching on id alone. A model can be published under a canonical id while the name someone integrated against lives on as an alias — it still serves, but an id-only comparison reports it as gone. The page gives the alias-map snippet.
2. Comparing price without per. per is 1000000 for most token rates, 1000 for some, 1 for per-second and per-megapixel ones. Comparing bare price is wrong by orders of magnitude.

Also covers how to read pricing.kind (fixed / variants / variable) and the ETag / If-None-Match flow, with the caveat that the ETag covers the whole body — it is a "something changed, re-read and diff" signal, not a price feed.

Checked

The JSON parses. Every example — parameter names, filter behaviour, response shapes, the ETag round-trip, the per-second variant sample — was run against api.aimlapi.com rather than written from the source.

Note

There is no docs preview environment to check this in: the staging branch here last moved in May 2025 and is 2331 commits behind main, and no GitBook preview is wired to PRs. Rendering is worth a look after merge.