API versioning

Qlik Cloud REST APIs and system events follow a quarterly, date-based versioning policy to help you manage changes to your integrations. API versions are released in February, May, August, and November, and use the YYYY-MM format.

REST APIs use the qlik-api-version header to indicate which API release an integration is aware of. Deprecation warnings are communicated through response headers. For system events, deprecations are documented in the AsyncAPI specs.

How API versioning works

For REST APIs, specifying an API version does not select a different API request or response structure. Instead, it tells Qlik which API release your integration is aware of, so Qlik can provide relevant deprecation warnings.

Non-breaking changes, such as new endpoints, optional request parameters, and response properties, can be introduced at any time. These changes are available to all REST API consumers, regardless of the version specified in their requests.

When existing functionality is deprecated, Qlik communicates the deprecation and its sunset date so you can update your integration before the functionality is removed. Deprecated functionality may be removed on or after its sunset date, regardless of the API version specified.

Specify a REST API version

To specify an API version, include the qlik-api-version header in your request:

curl -i "https://<TENANT>.<REGION>.qlikcloud.com/api/core/auth-settings" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "qlik-api-version: 2026-11"

The header accepts a supported dated release, such as 2026-11, or the special value latest.

Versioning applies to both namespaced APIs (/api/<namespace>/...) and legacy APIs (/api/v1/...).

Specify a dated API version rather than the latest value for all integrations. This allows Qlik to identify deprecations introduced after the release your integration is aware of.

By default, qlik-cli and @qlik/api use the latest dated API version available when each tool version is released. They do not use the latest header value.

The latest header value

Set qlik-api-version to latest to acknowledge the most recent API release:

curl -i "https://<TENANT>.<REGION>.qlikcloud.com/api/core/auth-settings" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "qlik-api-version: latest"

When you use latest, your integration is considered aware of the most recent release. You won’t receive version-dependent deprecation warnings for response properties, but you can still receive warnings when using deprecated endpoints or request parameters.

Using latest does not prevent deprecated functionality from being removed after its sunset date.

Available versions and release schedule

Qlik releases API versions quarterly, in February, May, August, and November.

Each release is supported for 12 months, unless otherwise specified.

The following versions are supported from the November 2026 release:

For REST APIs, a supported version does not guarantee that the API’s request or response structure remains unchanged throughout the support period. Non-breaking changes can still be introduced, and deprecated functionality can be removed after its sunset date.

Default and unsupported REST API versions

If you don’t include the qlik-api-version header, Qlik uses the oldest supported release.

The same behavior applies when the requested version is malformed, unknown, not yet available, or no longer supported.

Requests are not rejected because of an invalid or unsupported version. Instead, Qlik uses the oldest supported release as the acknowledged version.

For example, if 2026-05 is the oldest supported release, a request specifying 2026-02 falls back to 2026-05.

Check the accepted REST API version

REST API responses include the qlik-api-version header. You can use it to check whether Qlik accepted your requested version or fell back to the oldest supported release.

For example, a request specifying an unsupported version might return:

HTTP/1.1 200 OK
qlik-api-version: 2026-05

The status code depends on the API operation. An unsupported version does not itself cause an error.

When you request latest, the response header contains the corresponding dated release.

Check the response header, particularly when using an older version that may no longer be supported.

Deprecation and sunset

Qlik uses deprecation periods to give you time to update integrations before functionality is removed.

For stable APIs, the deprecation period is at least 12 months, unless a shorter period is necessary for security reasons.

Deprecated functionality remains available during the deprecation period. It may be removed on or after its sunset date.

Deprecation information in API references and specs

Deprecated REST endpoints, parameters, response properties, and system events are identified in the API references.

For REST APIs, deprecation information may include a description and sunset release. For system events, check the AsyncAPI spec for deprecation and sunset details that aren’t displayed in the API reference.

You can download the OpenAPI or AsyncAPI spec from each API reference page. Deprecations are described using the following extensions:

Not all deprecated items currently include all four extensions. Check the relevant deprecation notices in the changelog for additional information.

REST API deprecation response headers

REST APIs use the following response headers to communicate deprecations:

The sunset header does not mean that functionality will be removed on that exact date. Removal may happen later.

When deprecation headers are returned

For REST APIs, whether deprecation headers appear depends on what is deprecated:

• Endpoint: Headers are returned when you call a deprecated endpoint.
• Request parameter: Headers are returned when you use a deprecated parameter.
• Response property: Headers are returned when the API version your integration acknowledges predates the release in which the property was deprecated.

For response properties, Qlik uses the version header to determine whether your integration has acknowledged the deprecation.

Example: Response property deprecation

Consider an API response containing a legacyName property that is deprecated in the 2026-11 release, with a sunset of 2027-11.

The property remains available during the deprecation period, but the deprecation headers depend on which release your integration acknowledges.

For example, a request acknowledging 2026-08 receives a response similar to:

HTTP/1.1 200 OK
qlik-api-version: 2026-08
deprecation: @1793491200
sunset: Mon, 01 Nov 2027 00:00:00 GMT
link: <DEPRECATION_URL>; rel="deprecation"; type="text/html"
content-type: application/json

{
  "id": "123",
  "legacyName": "Example",
  "displayName": "Example"
}

A request acknowledging 2026-11 receives the same response body, but without deprecation headers for legacyName, because the integration is considered aware of the deprecation.

After the sunset date, Qlik may remove legacyName for all consumers, regardless of the version they specify.

This example is illustrative. The property names and deprecation are not actual Qlik API changes.

Update your REST API version

Before updating the version acknowledged by your integration using the qlik-api-version header:

1. Review the API changelog and relevant deprecation notices.
2. Check whether your integration uses deprecated functionality.
3. Update your integration if necessary and test it against the current API behavior.
4. Change the version header to the newer release.
5. Continue monitoring deprecation and sunset headers.

Changing the version header does not switch to a different API implementation or restore removed functionality. It updates which release your integration acknowledges and therefore which version-dependent deprecation warnings it receives.

Update the version before its support period ends to avoid an automatic fallback to the oldest supported release.

System events

Qlik Cloud system events follow the same quarterly release schedule and deprecation policy as REST APIs, but do not use the qlik-api-version header.

Deprecated events and event payload properties are documented in the AsyncAPI specs, including the release in which they were deprecated and their sunset date.

For more information, see Qlik Cloud system events.