API versioning and deprecation

How the Buzz Dealer AI REST API changes, and how we retire anything.

Versions

Every path starts with the major version, /v1. Within /v1 we only add: new endpoints, new optional fields and new values in answers.
A change that could break a working client (a field taken away or renamed, a different meaning) comes as a new major version, /v2, next to /v1.
The full description is always /openapi.json. Read unknown fields and values without failing.

An endpoint being retired is marked deprecated in the OpenAPI description, and its answers carry a Deprecation header (RFC 9745) with the date it was deprecated and a Link header to this page.
Once a date is set, answers also carry a Sunset header (RFC 8594) with the date the endpoint stops answering. That date is at least 6 months after the deprecation.
Deprecations are also announced on this page, with the replacement to use.
Today no endpoint is deprecated.

Write to [email protected]. The docs cover the endpoints, paging, async jobs and errors.