What we promise about v1

The product API is served under /api/v1/. Anything you build against it keeps working, and the rules below are what that sentence means in practice.

v1 only ever gains things

We add endpoints, we add optional request fields, and we add fields to responses. We do not remove a field, rename one, narrow what a field accepts, add a required request field, or change what a status code means. Write your client so an unknown field in a response is ignored rather than an error, and additions cost you nothing.

New values can appear in an enumerated field — a new booking status, a new webhook event. Handle an unrecognised value by leaving it alone rather than refusing it.

A removal gets ninety days, and says so on every response

If an endpoint has to go, it stays live for at least ninety days after we announce it, and during that window every response from it carries three headers:

• Deprecation — the moment it was announced.
• Sunset — the date it stops answering.
• Link — this page, and the endpoint that replaces it where there is one.

The same operations are marked deprecated in the OpenAPI document, so the generated SDK and the API reference show it too. We email every studio with an active API key when the window opens.

A break means a second version

A change that would break a working client is not made to v1. It is made at /api/v2/, and v1 keeps answering. Infrastructure paths outside the product API — health checks, webhook receivers, the OpenAPI document itself — are unversioned and are not part of this promise.

Nothing is deprecated today

No v1 endpoint carries a sunset date. When one does, it will be listed here and on the API reference before the headers start.

If something breaks anyway

Tell us at [email protected] — a change that broke a client is a bug on our side, and we would rather roll it back than argue about it. See also the developer overview and what we connect to.