Quick Summary: The version is in the URL —
/api/v1/.... Inside a major version we only ever add; anything breaking waits for the next major, with a long, loudly-announced migration window.What will never change inside v1
- Existing routes, parameters and response fields keep their names and types.
- Optional things stay optional; enum values are never removed or renamed.
- Status codes and error types for existing behaviour stay put.
What may appear without notice
New endpoints, new optional parameters, new response fields, new enum values, new error detail text. Build tolerant clients: ignore fields you do not recognize.How a version retires
See the versioning & deprecation policy — deprecation headers first, a published sunset date, then 410 version-gone after the sunset. The machine-readable contract for the current version is always at/api/v1/openapi.json.