> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> What we promise not to change, what we may change, and how long you get to migrate.

The API is versioned in the URL: `https://api.waterr.ai/v1`. Everything below
describes what `v1` guarantees.

## What will not change without a new version

These are the things your integration is allowed to depend on. Breaking any of
them requires a new major version and the deprecation process below.

* **An endpoint disappearing or moving.** A path that exists in `v1` keeps
  existing in `v1`.
* **A parameter becoming required.** Adding a new required field to an existing
  request breaks every caller that was already correct.
* **An `error.type` value disappearing.** Client code branches on these, and
  both official SDKs map them to exception classes. The set is fixed:
  `invalid_request_error`, `authentication_error`, `permission_error`,
  `not_found_error`, `conflict_error`, `rate_limit_error`, `api_error`.
* **An `operationId` changing.** SDK method names and documentation anchors are
  generated from these.
* **The meaning of an existing field.** We will add a new field rather than
  repurpose an old one.

<Note>
  This is enforced, not just promised. The public contract is fingerprinted
  into a snapshot committed to our repository, and CI refuses any change that
  removes an operation, renames an `operationId`, tightens a requirement, or
  drops an error type. A breaking change cannot ship by accident.
</Note>

## What may change at any time

Treat these as normal, expected evolution. Your client must tolerate them.

* **New endpoints.**
* **New optional parameters.**
* **New fields in a response object.** Do not use strict schema validation
  that rejects unknown fields — you will break on a routine release.
* **New `error.code` values** within an existing `error.type`. Handle an
  unrecognised `code` by falling back to its `type`.
* **New enum values** in a response field.
* **Ordering of results** where no order is documented.
* **The exact wording of `error.message`.** Never parse it; branch on `code`.
* **Opaque values** — cursors, ids, signing secrets. Never parse their
  internals.

## Deprecation

When something must be withdrawn:

1. **Announcement** in the [changelog](/api-reference/changelog), with a
   migration path.
2. **A `Deprecation` response header** on the affected endpoints, plus a
   `Sunset` header carrying the removal date (RFC 8594).
3. **A minimum of 90 days** between announcement and removal. Where an
   endpoint has active traffic, we contact the accounts using it directly
   before removing anything.

Security issues are the sole exception: a change required to close a
vulnerability may ship immediately, and we will say so plainly in the
changelog.

## Building something that survives releases

* Parse JSON permissively — ignore fields you don't recognise.
* Branch on `error.type` first, `error.code` second, never `error.message`.
* Treat `next_cursor`, ids and `whsec_` secrets as opaque strings.
* Log `request_id` on every failure; it is what support needs.
* Pin an SDK version and upgrade deliberately. Both official SDKs follow
  semver, and a major bump there means a contract change here.

## Getting notified

The [changelog](/api-reference/changelog) is the record of every change. For
runtime signals, subscribe to [webhooks](/api-reference/webhooks) rather than
polling — new event types are added additively, and unknown ones are safe to
ignore.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.