Reference

Versioning

One version, v1, under /v1. It only ever grows; nothing in it changes or disappears without a year's notice.

What can change in v1

Only additive changes: new routes, new optional request fields, new response fields, new enum values in responses, new error reasons, new webhook events and payload fields. Write clients that ignore unknown fields and tolerate unknown enum values.

A breaking change is a new major version (/v2) served next to v1.

Deprecation

A route or field may be deprecated, never changed in place. From the day it is deprecated, every response that touches it carries Deprecation: @<unix seconds> (RFC 9745), Sunset: <HTTP date> (RFC 8594) and a Link to its changelog entry with rel="deprecation". It keeps working for at least 365 days after that.

Log or alert on the Deprecation header and you will hear about every deprecation long before it matters. Every one is listed in the changelog.

Webhook payloads

Webhook payloads are versioned by date (2026-09-01 today). Each endpoint keeps the payload version it was created with, so a future breaking change to a payload reaches only endpoints that opt into it.