# Versioning & stability

> The /v1 contract — what is promised now, and what is promised at GA


## Before GA

DeepSieve has not reached general availability, and **the stability guarantee
below begins at GA — not today.** Until then `/v1` can change in ways that break
a client, and this page says so rather than promising otherwise.

What we commit to in the meantime:

- **Every breaking change is announced in the
  [changelog](/developers/changelog)**, dated, naming the old path or field and
  what replaces it. That is the mechanism — if it is not in the changelog, it did
  not happen.
- **Breaking changes are deliberate**, weighed one at a time, never incidental.
  Pre-GA is not a licence to churn the contract; it is an acknowledgement that a
  surface still being shaped should not be described as finished.
- Our own clients — the [CLI](/developers/cli), the MCP server, and the Python
  SDK — are updated in the same change, so the changelog entry can tell you the
  version of each that works.

If you are building on `/v1` now, pin the SDK version and read the changelog
before upgrading. Tell us what you have built: it is the only way a change that
would break you gets weighed against you specifically.

## At GA

`/v1` becomes **additive-only**:

- We may add endpoints, optional request fields, response fields, and error
  codes. We will not remove or rename fields, change types, or change
  semantics within v1.
- **Clients must ignore unknown response fields.** (True today too — it is what
  lets an addition stay non-breaking.)
- Run `status` and error `code` registries are closed sets; changes are
  announced ahead of time in the changelog.
- Deprecations are signaled with `Deprecation` and `Sunset` headers at least
  90 days before removal; removal only happens at a major version.

Experimental surfaces ship behind an opt-in `DeepSieve-Beta` header and carry no
stability promise until graduated — before or after GA.

The legacy `/api/*` routes are the web app's private surface — no stability
promise; don't build on them.