v1 is stable
Additive changes ship without notice. New endpoints, new fields on existing responses, new event types, new enum values. Write clients that ignore fields they do not recognise, and that do not crash on an unfamiliar enum value.
Breaking changes get a new version and a 12-month deprecation window on the old one. A breaking change is: removing or renaming a field, changing a field's type, removing an endpoint, tightening validation, or changing the meaning of an existing value.
We will not sunset a version out from under you on a few months' notice. That has happened to customers of other platforms in this market and it is a bad enough experience to be worth promising against in writing.
Deprecation signals
A deprecated endpoint keeps working and starts returning:
Deprecation: true
Sunset: Wed, 13 Aug 2027 00:00:00 GMT
Link: <https://zellerai.co/developers/changelog>; rel="deprecation"IDs
All ids are opaque strings (cuid). They are never numeric, so there is no 64-bit precision problem and no language-specific workaround to read about. Do not parse them; do not assume a length.
Timestamps
ISO-8601 with a Z offset, always UTC. Fields ending _at are timestamps; a null means "has not happened", not "unknown".