> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flatpeak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning

Each major platform release may include changes that are not backwards-compatible. Upgrading to a new major release can require updates to your code.

Backwards-compatible changes introduced outside a major release are announced in the [Changelog](/changelog), but the version number is not incremented.

## Setting API version for a single request

By default, requests use your Flatpeak account’s default API version (set in the Dashboard).

You can override it by adding the `Flatpeak-Version` header:

```http Example request highlight {4} theme={"system"}
❯ curl -I --request GET \
  --url "https://api.flatpeak.com/devices/dev_66b1ea3cbbfa0d30b978ce37" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Flatpeak-Version: 2025-09-14.anode'
```

The response headers will include the `flatpeak-version` header:

```http Response header highlight {3} theme={"system"}
date: Thu, 13 Nov 2025 20:10:17 GMT
content-type: application/json
flatpeak-version: 2025-09-14.anode
```

## Permanently changing API version

You can upgrade your default API version in the [Dashboard](https://dashboard.flatpeak.com/settings/versions) > **Settings** > **Versions** > **API Versions**. As best practice, test the new version by adding the header before upgrading. It is **not possible** to downgrade once you have upgraded to the higher version in the Dashboard.

## Webhooks

Webhook events are emitted according to the API version used when the related object was created, unless you have permanently changed the API version via the Dashboard.

For example:

* Creating a location with `2024-08-24.zero` will emit events in the Zero version.
* Creating a location with `2025-09-14.anode` will emit events in the Anode version.

### Errors

If you are trying to pass the `Flatpeak-Version` header for a version that is lower than the one you configured in the Dashboard (your default version), you will receive the following error

```json HTTP 422 Error theme={"system"}
{
  "object": "error",
  "live_mode": true,
  "context": "api",
  "type": "invalid_request",
  "code": "api_version_not_supported",
  "message": "Requested API version 2024-08-24 older than account default 2025-08-01.anode",
  "time_created": "2025-08-24T14:15:22.003"
}
```