# Versioning & deprecation

## The version is in the path

This API is versioned in the URL path: every endpoint lives under `/v1/`. Your
integration pins the version by construction — nothing about a request opts into
behaviour it did not ask for.

## What a breaking change looks like

A breaking change ships under a new version path (`/v2/...`), never inside the one
you are using. When a new version ships, the prior version remains supported for a
deprecation period of **90 days** from the deprecation announcement, so an
integration has a full quarter to move at its own pace.

## Error types and statuses are part of the contract

The `type` URI and the HTTP status of every documented error are stable identifiers
you can branch on. **They never change without a documented deprecation.** Adding a
new error to the [reference](/errors) is an additive, safe change; renaming or
re-statusing an existing one is a breaking change and is treated exactly like one.

The same holds for the response schema: members are added, not repurposed. A member
documented as absent-when means exactly that, and its absence rule changes only with
a version.