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

# API versions

> Send your account's API version with every request.

We sometimes change what requests and responses look like. To make sure those changes never break your app, your business is **pinned to one API version**. You only move to a new version when you're ready.

## The current version

| Version | Released | Status |
| - | - | - |
| `2026-10-29-atlas` | 29 October 2026 | Latest |

New businesses are pinned to the latest version automatically.

## Send the version with every request

Every request must include the `API-Version` header, set to the version your business is pinned to:

```bash theme={null}
API-Version: 2026-10-29-atlas
```

We send the same header back in every response, so you can confirm which version answered.

You can see your version in the Bridge app under **Settings → Integration → API version**.

## How versions are named

A version is a date and a name: `YYYY-MM-DD-name`. The date is when the version was released.

## Moving to a new version

**1. Read what changed**

Check the [Changelog](https://docs.bridge.linkio.world/changelog.md) for what's different in the new version.

**2. Update your code**

Update and test your app in the sandbox first.

**3. Change the version in the Bridge app**

Go to **Settings → Integration → API version** and choose the new version.

**4. Send the new version**

Change the `API-Version` header your app sends at the same time.

> [!WARNING]
>
> As soon as you change the version in the Bridge app, requests that still send the old version fail. Change both at the same time.

## How often versions change

We release a new API version every **3 months**:

**1. Month 1**

The latest version is the only new version. Nothing changes.

**2. Month 2: a new experimental version**

We release the next version as **experimental**. You can try it in the sandbox and send it in the `API-Version` header to test your app.

**3. Month 3: testing**

The experimental version is tested for 1 month.

**4. The next cycle starts**

The experimental version becomes the **latest**, and the version that was latest moves to **stable**. Your business stays on its version until you choose to move.

## Version lifecycle

A version goes through these stages:

| Stage | What it means |
| - | - |
| Experimental | The next version, released for 1 month of testing. Try it, but don't rely on it yet. |
| Latest | The newest version. |
| Stable | Still fully supported. |
| Deprecated | Still works, but will be retired. Plan to move. |
| Sunset | Retired. Requests are rejected. |

## Version errors

All of these return `400`:

| Code | Message | Fix |
| - | - | - |
| `api_version_required` | The API-Version header is required and must be the version set on this account. | Add the `API-Version` header. |
| `invalid_api_version` | '…' is not a valid API version. Expected YYYY-MM-DD-name, for example 2026-10-29-atlas. | Check the spelling. |
| `api_version_mismatch` | The API-Version '…' does not match the version set on this account ('…'). | Send the version shown in the Bridge app. |
| `unsupported_api_version` | The requested API version '…' is not supported. | Use a version from the table above. |
| `api_version_sunset` | API version '…' is no longer supported. Migrate to '…'. | Move to the version named in the message. |

Some of these errors include extra fields to help you, such as `requested_version`, `account_version`, or `supported_versions`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.