Skip to main content
Versioning is a major addition of the v5 Lucca API (latest API generation) compared with the v3 and v4 APIs (legacy generations). It protects clients against breaking changes: each time a breaking change is introduced, a new version is released rather than modifying the existing one. The previous version is marked as deprecated and a sunset (i.e. discontinuation) date is set. Once sunset, the API version can no longer be accessed.
Some v5 API endpoints are still in beta and may not be feature-complete. They are marked with a “BETA” badge in the API Reference.Unlike stable v5 endpoints, beta endpoints are not protected against breaking changes — just like all previous v3 and v4 legacy API endpoints.Once out of beta, endpoints are considered stable and subject to our deprecation policy. Check the lifecycle recap for the up-to-date status of each endpoint.

​
Guarantees

1+ year support

Once a new version is released, it won’t be sunset before at least one year.

6+ months deprecation notice

Once deprecated, a version is supported for at least 6 months.

Changelog & migration guides

All changes are documented. Migration guides when needed.

​
Targeting a Version

All supported versions can be found in the API Reference. You should always pick the latest version for any new integration. Versions are named after their release date (e.g., 2024-11-01). The version must be targeted through the Api-Version header parameter, which is absolutely required. 
GET /lucca-api/leaves HTTPS/1.1
Host: example.ilucca.net
Api-Version: 2024-11-01
Notes:
  • If no API version exactly matches the given date, the closest prior version is chosen by the server.
  • You pin the API version when creating a webhook subscription. The pinned version dictates the structure of the event payload.

​
Lifecycle Terms

All new API versions are supported for at least 12 months. An API version can only be sunset after a at least 6 months deprecation period. A deprecated version is marked as such in this documentation. When the server returns a deprecated response, the Deprecation HTTP header indicates the deprecation date; the complementary Sunset header indicates the sunset date. The sunset date may be postponed, so it may exceed the 6-month minimum.

​
Changelog

Each version has a changelog listing all non-breaking changes. It is available in the Lucca API Reference.
Some changes we consider non-breaking may nonetheless break your code, depending on your implementation / language.

List of breaking changes

Learn what we consider a breaking change, i.e. what triggers the release of a new API version and the deprecation of the previous one.