Versioning & changelog

#Versioning & changelog

Every path on this site is under /api/v1/…. While v1 exists, we will not change:

• an existing field's type or meaning, or remove a field a documented response already has,
• an existing endpoint's URL, required scope, or success status code,
• the shape of an error response (application/problem+json with a code) for an existing code.

We will, without a version bump (these are additive and safe to ignore if you don't use them):

• add new optional fields to existing responses,
• add new endpoints and new scopes,
• add new error code values for situations that previously didn't exist.

A breaking change ships as /api/v2/… alongside v1, with v1 kept running for a announced deprecation window — never turned off underneath an integration without notice.

#Machine-readable spec

GET /api/v1/openapi.json (OpenAPI 3.1, no auth needed) is the definitive, current shape of every v1 endpoint — every field on this site is generated or checked against it at our build time. If this page and the spec ever disagree, the spec is correct; please tell us so we can fix the docs.

#Changelog