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, 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, 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.