Skip to main content
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.
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.

​
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, 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 is the record of every change. For runtime signals, subscribe to webhooks rather than polling — new event types are added additively, and unknown ones are safe to ignore.