Versioning

The API has one version, v1. Within it, we only add: new operations, new fields, new optional arguments. Your code keeps working because we never change what an existing field means.

Removing something

A field is removed in three steps, and never faster:

1. We ship the replacement first and mark the old field @deprecated(reason: "Use contacts — removal after 2026-12-31").
2. We track which app versions still call it. A field is removed only after 60 days with zero calls, or two app releases, whichever is later.
3. The removal is its own change. CI refuses any schema change that breaks a client unless the field was deprecated and its date has passed.

Deprecated fields are marked in the reference and listed in the changelog. Compare versions will show a side-by-side diff when a second version exists.

What counts as breaking

Removing or renaming a field, changing a field’s type, making an optional argument required, removing an enum value. All of these are blocked until the deprecation date has passed.

What does not break you

Adding fields, adding operations, adding enum values (treat unknown values as “other”), adding optional arguments, and adding error codes. Write clients that ignore what they do not know.