API Versioning

The Lithic API is versioned with dated releases in YYYY-MM-DD format. A version fixes the request and response shape of every endpoint at a point in time. A breaking change ships in a new version so that you are able to update your integration.

Most changes we make are backwards compatible and reach every version. See Versioning and backwards compatibility for what we consider a non-breaking change. New versions are created when Lithic needs to make breaking changes to our API contract.

Initial Versioning

Since establishing API versioning, clients who do not pass a version header, will interact with our 2024-01-15 version. This is our initial first version. This behavior will end when 2024-01-15 retires.

Available versions

Specifying a version

Send the api-version request header with the version you want:

curl --request GET \
     --url 'https://api.lithic.com/v1/cards' \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'api-version: 2026-07-01'

The header is per request. This makes it possible to send different versions per request if needed.

Unrecognized versions

A request that sends api-version with a value we do not recognize is rejected with a 400. That covers a malformed date, a version we have never published, and one that is not available to you. The request is not served against a different version in its place.

Omitting the header is not an error. Those requests are served against 2024-01-15, as described above.

Because an invalid value fails on the first request rather than quietly resolving to something else, a typo surfaces while you are integrating instead of as a behavior difference later.

Deprecation notices

When a version is scheduled for retirement, responses to requests on that version carry the X-LITHIC-API-VERSION-DEPRECATION response header naming the version and the date after which it will no longer be supported. No version currently carries a deprecation date.

We will contact you before retiring a version you are using. Log this header in your integration so you learn about a retirement from your own traffic as well.

Matching the docs to your version

The version selector at the top of this site switches both the API reference and these guides together. Select the version you send in the api-version header, and the parameters, response shapes, and behavior described throughout the docs are the ones your requests will get.

The selector in our docs labels versions with a v prefix, v2026-07-01, which is not used in the API header value.

SDKs

Each Lithic API library is built against a single API version. The release you install determines the API version your requests use. Check the SDK release notes, SDK documentation and our changelog to know which API version the SDK is using. To move to a newer API version, upgrade to the library release built for it.

Choosing a version

If you call the API directly, send an explicit api-version on every request rather than relying on defaulting.

To move to a newer version, test it in Sandbox first, then roll the header out in Production. If you have questions about a specific version, contact support.lithic.com or your Lithic representative.