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

# API versioning

> Learn how Yorlet versions its API and how to upgrade safely.

The Yorlet API is versioned with dated releases, so we can evolve the API and change response shapes without breaking your existing integration. Each version is a date, for example `2025-08-21`.

## Your account API version

Every account is pinned to an API version. The first time you make an API request, your account is pinned to the latest version available at that time. From then on, requests keep using that pinned version unless you explicitly upgrade, so the shape of API responses and webhook payloads stays stable for your integration.

You can see and change your account's version on the [API keys page](https://dashboard.yorlet.com/developers/api-keys) in the Dashboard.

## Overriding the version per request

You can override your account's pinned version for a single request by sending the `Yorlet-Version` header. This is useful for testing a newer version before you upgrade your account.

```http theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/subscriptions \
  -H "Authorization: Bearer {{SECRET_KEY}}" \
  -H "Yorlet-Version: 2025-08-21"
```

Every response echoes the version it was rendered with back in the `Yorlet-Version` response header. Sending an unrecognised version returns a `400` error.

## Backwards compatibility

When we change the shape of an object in a new version, older versions keep receiving the previous shape. For example, if a field is removed in a new version, accounts pinned to an earlier version continue to receive that field. This means upgrading is the only time a response shape changes for you, and you can do it on your own schedule.

See the [API changelog](/development/api-changelog) for the changes introduced in each version.

## Upgrading and rolling back

To upgrade, open the [API keys page](https://dashboard.yorlet.com/developers/api-keys) in the Dashboard and select **Upgrade available** in the **API version** section. Review the changes, then confirm.

After upgrading you have **72 hours** to roll back to your previous version if you need more time to adapt your integration. Within that window, a **Roll back** option appears in the same section. Once the window passes, the upgrade is final.

<Note>
  Changes to your account version can take a few minutes to take effect for requests made with an API key.
</Note>

## Webhook endpoints

Each [webhook endpoint](/development/webhooks) has its own API version, set to your account version when the endpoint is created. Events delivered to an endpoint are rendered with that endpoint's version, so you can upgrade your account without changing the payloads an existing endpoint receives. You can set an endpoint's version when you create it, or change it later.