Versioning

The API has versions named for the day they were released, such as 2026-10-30. Your integration keeps the behaviour of the version it is on until you choose to move; what is added in the meantime reaches every version.

The versions

Version	Status	Sunset	What it is
`2026-10-30`	current	Not announced	The first named version: the v1 REST API, the MCP server and webhooks as they stood on 2026-10-30, with test mode, rate-limit headers on every answer and the Bookatu-Version header. Every key and connected app made before versioning is pinned to it.

New keys and apps are pinned to 2026-10-30. Every change, and every version, is in the changelog.

Asking for a version

Send Bookatu-Version with the version your integration was written and tested against. Every answer says the version it was answered in, in the same header.

curl https://bookatu.com/api/v1/{slug}/services \
  -H "Bookatu-Version: 2026-10-30"

HTTP/1.1 200 OK
Bookatu-Version: 2026-10-30

Without the header, a call made with a key or a connected app is answered in the version it is pinned to, and a call with neither in the oldest version still supported (2026-10-30 today).

A version that does not exist, has been switched off, or is not a date is refused before anything runs:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ "ok": false, "error": "Bookatu-Version \"2025-01-01\" is not a version this API answers in. ...", "code": "UNSUPPORTED_API_VERSION", "supportedVersions": ["2026-10-30"], "livemode": true }

Over MCP the same refusal is a JSON-RPC error whose data carries the code and supportedVersions.

Pinning

A key is pinned to the version current when it is made, and a connected app to the version current when it is approved. Every key and app made before versions existed is pinned to 2026-10-30. The header overrides the pin for one call, so you can try a newer version before you move; to move for good, send the header on every call, or make a new key, which is pinned to the current version.

A key pinned to a version that has since been switched off is answered in the oldest version still supported, never refused for it.

What changes, and when

An additive change needs no new version and reaches every version: a new endpoint, a new optional parameter, a new field in an answer or a webhook payload, a new error code where a call could already be refused, a new header. Write clients that ignore fields they do not know.
A breaking change ships only in a new version: a field removed or renamed, a type or a meaning changed, a parameter made required, a default or a status code changed.
A version is supported for at least 12 months after the next one is released.
A version's deprecation, with the date it is switched off, is announced at least 6 months before that date: in the changelog, and on every answer in it.

Deprecation headers

An answer in a deprecated version carries three headers:

Header	What it says
`Deprecation`	When the version was deprecated: `@` and a Unix time (RFC 9745).
`Sunset`	The day it stops being served, as an HTTP date (RFC 8594).
`Link`	Its changelog entry, with `rel="deprecation"`.

Bookatu-Version: 2026-10-30
Deprecation: @1811808000
Sunset: Thu, 01 Jun 2028 00:00:00 GMT
Link: <https://bookatu.com/developers/changelog#v-2026-10-30>; rel="deprecation"; type="text/html"

An example only: no version is deprecated today. Look for Deprecation in your logs or monitoring; it is your notice to move.