# Versions and compatibility

The version is in the path, and it is `v1`. There is no header to negotiate, no date to
pin, and no minor version: a URL that worked keeps working, or the version number changes.

What that promise is worth is the list below — the changes that are forbidden inside a
version, and the ones you should expect at any time. The second list is the one to build
against: **a new field can appear in any response, and a new value in any enum**, so a
client that rejects what it does not recognise will break on a release that broke nothing.
Ignore unknown fields, and treat an unknown enum value as a value you do not handle rather
than as an error.

Watching for a change is reading the reference: the documents this site renders are
generated from the running service, in the same build that produces it, so a release moves
them both. There is no changelog that can be out of date with respect to the API, because
there is no step between them.

## 18. Versioning and compatibility

- The version is a path segment: `v1`, `v2`. No dotted or dated versions, no
  `Accept` header negotiation — the CDN in front of this API does not vary on
  `Accept` (a fact already paid for once, in the markdown-twin design).
- Within a version, these are **breaking** and forbidden: removing or renaming
  a field, path or parameter; narrowing a type; adding a REQUIRED request
  field; changing a default; changing a status code for an existing condition;
  changing an id's format.
- These are **non-breaking** and allowed any time: adding an optional request
  field, adding a response field, adding an enum value (clients tolerate
  unknowns, [§11](/concepts/json)), adding an endpoint, adding a `details` entry.
- Removing anything takes a new version running side by side. A version is
  removed only when its last consumer is gone — verified by access logs, not by
  belief.
- A field being retired is marked deprecated in the OpenAPI document with the
  replacement named, and keeps working for the life of the version.