# Versioning and stability

> What v1 promises, what changes in SDK 0.x, and how deprecations will work.

## The API: `/v1`

`/v1` is the current public API version. Within v1 we only make **additive** changes: new endpoints, new optional request fields, new response fields, and new values for values the API returns (such as a new payment status or event type). A **breaking** change — removing or renaming a field, endpoint or value, making an optional request field required, or changing a type — requires a **new major API version** (`/v2`) or an explicit, announced deprecation process. We do not promise a support timeline for old versions yet.

Because v1 can gain new values, **write clients that tolerate them**: keep a default branch when you switch on a status, channel, method or event type. The official SDKs already do this — an unknown value is passed through instead of crashing. Requests stay strict: sending a value the API doesn't know is rejected.

## The SDKs: `0.x`

SDK packages follow their own semantic versioning and are **0.x**: the *package's* API may still change between minor versions while we learn from real use. That is separate from the REST contract: an SDK release never changes what `/v1` means, and `/v1` compatibility does not depend on which SDK version you use. Pin an exact SDK version and read the changelog when you upgrade.

## The docs

`/v1` documents API v1, whichever SDK version you use.

## Deprecations

Nothing is deprecated today. When something is, we will: mark it deprecated in the API reference and changelog, add a notice in these docs, send a `Deprecation` response header where useful, and only announce a sunset date once a real timeline exists. We won't invent dates.