API stability
How the API is versioned, what can change under you, and what cannot.
Versioning
There is one version, in the path: https://api.multigrid.ai/v1. There is no date header, no ?version= parameter and nothing to pin. A second major version would be a second path, not a header that quietly changes behaviour on a request you already wrote.
What will not change
| Guarantee | Description |
|---|---|
| The request shape | It is OpenAI’s, and staying compatible with it is the product. Our own additions are optional top-level fields, so a body that works today works if you delete every one of them. |
| Parameters we do not know | Are passed upstream rather than rejected. We validate model and messages and forward the rest, so a parameter a vendor ships next month works here on the day they ship it. The exceptions are all cases where honouring it is impossible and pretending otherwise would cost you money or silently change your answer: n > 1; response_format, seed, reasoning_effort and thinking when every candidate route is Anthropic; metadata that breaks the tag limits; and a plugins entry this deployment cannot run. Each is a 400 or a 503 that names the problem, never a silent drop. |
| The error envelope | { error: { message, type, code, request_id } }. New codes may be added; the shape does not change, and an unfamiliar code still carries a usable type. One endpoint adds to it rather than changing it: POST /batches puts an issues array of line-numbered parse failures beside error on a 400, because somebody who generated a JSONL file with a script needs the line numbers far more than the summary sentence. |
| Additive responses | Fields get added to multigrid; they do not get renamed or repurposed. Parse it leniently and ignore what you do not know. |
What can move
- The catalogue. Models and providers are added, repriced and retired — by us and by them. Never hard-code a model id you have not checked against
GET /models, and never hard-code a price at all: the same rows the catalogue serves are the rows you are billed from. - Which provider serves a request. That is the whole point of a gateway, and the response tells you which one did.
- Defaults inside our own fields. Retry counts, ranking for
sort: "latency", and whatmultigrid/autoresolves to all depend on live measurements and a live catalogue. If you need a fixed answer, name the model and the provider — or pin a preset version.
transforms and route are stripped before a request leaves us. They exist so a configuration carried over from another gateway does not break — but nothing behind them is implemented, and they will not start working without being announced.Where changes are announced
On the changelog, which records model additions, behaviour changes and anything breaking. For the catalogue specifically the endpoints are the live answer and this page is not: GET /models for what exists and what it costs, GET /providers for who can serve it, and GET /models/{vendor}/{model}/endpoints for the exact route order behind one id.
Something here disagrees with what the API actually did? That is a bug in this page, and worth reporting.
Report it