---
title: "Versioning"
description: "How the Bookatu API changes without breaking you: versions named by date, the Bookatu-Version header, the version your key is pinned to, the policy, and the deprecation headers."
url: "https://bookatu.com/en-nz/developers/versioning"
language: "en"
section: "Developers"
---

# 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](https://bookatu.com/developers/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.

```sh
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
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](https://bookatu.com/developers/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"`. |

```http
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.