Versioning

One version, v1, and a promise about how it changes.

v1

Every path lives under /v1. Within v1, fields, endpoints and error codes are added; nothing is removed or renamed, and no number changes meaning. A change that would break a client lands as /v2, announced on the changelog and in the index, with v1 kept answering alongside it for at least six months and saying so in Deprecation and Sunset headers.

What exists

GET /v1 is the source of truth for what is served: a new endpoint appears there the day it ships.