---
updatedAt: 2026-09-02T23:26:12.000Z
---

Fetch the complete documentation index at: https://docs.lithic.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# API Versioning

Choose which dated version of the Lithic API serves your requests, and control when changes reach your integration.

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](https://docs.lithic.com/docs/api-basics#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

| Version      | Notes                                            |
| ------------ | ------------------------------------------------ |
| `2024-01-15` | Served when a request does not specify a version |
| `2026-07-01` | Latest                                           |

## Specifying a version

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

```curl cURL
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](https://docs.lithic.com/docs/api-libraries) 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](https://docs.lithic.com/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](https://docs.lithic.com/docs/enviornments) first, then roll the header out in Production. If you have questions about a specific version, contact [support.lithic.com](https://support.lithic.com/) or your Lithic representative.