Skip to main content
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 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. 
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 for the changes introduced in each version.

​
Upgrading and rolling back

To upgrade, open the API keys page 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.
Changes to your account version can take a few minutes to take effect for requests made with an API key.

​
Webhook endpoints

Each webhook endpoint 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.