# Versioning & deprecation

## 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".