The Lucca API is currently in its beta phase. It requires you to specify the version through the Api-Version header, but there is no guarantee over its stability. There may be breaking changes for as long as it’s in beta.
The Lucca API is versioned in order to avoid breaking your integrations. Each time a breaking change that would potentially break them is introduced in the Lucca API, a new version is released. 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.

​
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. Obviously, you should pick the latest version for any new integration. Versions are named with their release date, and as such are date-formatted strings. The Lucca API version must be targeted through the Api-Version header parameter, which is absolutely required. The Api-Version header is a date-formated string. 
GET /lucca-api/leaves HTTPS/1.1
Host: example.ilucca.net
Api-Version: 2024-11-01
Notes:
  • If there are no API versions exactly matching the given date, then the closest prior version is chosen by the server.
  • You must pin the API version applied to webhook events when creating a webhook subscription, which will dictate the content of the event data.

​
Lifecycle Terms

All new API versions are supported for at least 12 months. An API version can only be sunset after a min 6 months deprecation period. A deprecated version is marked as such in this public documentation. When the server is returning a deprecated response, the Deprecation HTTP header indicates the deprecation date ; and the complementary Sunset header indicates the sunset date. Sunset date may be postponed later down the line and as such may exceed the min 6 months period.

​
Changelog

Any given version offers a changelog that lists all non-breaking changes made to the version. The changelog is available in the Lucca API Reference.
Please, bear in mind that some changes we consider non-breaking may nonetheless break your code.

List of breaking changes

Learn what we consider to be a breaking change, and thus results in the release of a new API version and the deprecation of the old one.