> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API migration guide: 20220603 to 20240415

> This topic explains changes in the 20240415 version of the LaunchDarkly REST API and how to migrate to that version.

> For the complete documentation index, see [llms.txt](/llms.txt). For the full documentation snapshot, see [llms-full.txt](/llms-full.txt).

## Overview

This topic explains changes in the `20240415` version of the LaunchDarkly REST API and how to migrate to that version.

**The `20240415` REST API version includes breaking changes. We strongly recommend upgrading to the latest API version as soon as possible.** All customers will be required to use version `20240415` as of January 1, 2027.

<Warning title="The `20220603` REST API version reaches its end of life on December 31, 2026">
  The `20220603` REST API version reaches its end of life on December 31,

  2026. After this date, you will no longer be able to access version `20220603`, and must upgrade to version `20240415`.
</Warning>

Specifically, the `20240415` version:

* changes several endpoints from unpaginated to paginated result sets, following common industry best practices
* removes a few infrequently used or less performant filters from some endpoints
* removes the previously deprecated Users, Users (beta), and User settings APIs

These changes are focused on improving performance and stability of the API. There are two ways to upgrade to the latest API version:

* Create a new access token and set it to use the latest version, `20240415`. Replace all uses of your existing access token with this new token.
* Update the `LD-API-Version` header in all of your requests to `20240415`. Here's how:

<CodeGroup>
  ```title="To use the new version, update your request header" theme={null}
        LD-API-Version: 20240415
  ```
</CodeGroup>

The following sections describe how to migrate your API access tokens, the details of the API changes, and how to work with the new version. You can find a summary of these changes under [Versioning](/api#versioning) in the [LaunchDarkly REST API documentation](/api). This section also includes the End of Life (EOL) information for each REST API version. The `20220603` version has reached EOL as of April 15, 2025.

If you have questions or would like assistance during this transition, [start a Support ticket](https://support.launchdarkly.com/hc/en-us/requests/new).

<Note title="No LaunchDarkly SDKs are being deprecated as part of this work">
  This guide applies **only** to the LaunchDarkly REST APIs. No LaunchDarkly SDKs are being deprecated as part of the changes described in this guide.

  To learn more about the differences between these offerings, read [Comparing LaunchDarkly's SDKs and REST API](/guides/api/comparing-sdk-rest-api). To review information on currently supported LaunchDarkly SDK versions, read [Supported versions](/sdk/concepts/supported-versions).
</Note>

## Migrating your API access tokens

When you create a new API access token, by default its version is now `20240415`.

Only currently supported versions are available when you create new access tokens. However, you may have older API access tokens that are set to unsupported versions.

To upgrade your integration to use a new API version, you can either create a new access token, or  explicitly set the `LD-API-Version` header in each request. We recommend that you set the API version header explicitly.

### Updating your request header

To use the new version, update your request header to include `LD-API-Version: 20240415`. For example:

<CodeGroup>
  ```bash title="Example curl" theme={null}
      curl -X GET 'https://app.launchdarkly.com/api/v2/projects/MY-PROJECT-KEY' \
        -H 'LD-API-Version: 20240415' \
        -H 'Authorization: EXAMPLE-API-ACCESS-TOKEN' \
        -H 'Content-Type: application/json'
  ```
</CodeGroup>

<Tip title="Best practice: Set the header for every client or integration">
  We recommend that you set the API version header explicitly in any client or integration you build. Only rely on the access token API version during manual testing.
</Tip>

## Migrating your client libraries

If you are using the LaunchDarkly REST API through one of our [generated client libraries](/api#openapi-swagger-and-client-libraries), upgrade to version 21.x or later to use the `20240415` version.

## Working with paginated endpoints

The following endpoints previously served unpaginated results, and now serve paginated results in version `20240415`:

* [List access tokens](/api-reference/access-tokens/list-access-tokens)
* [List custom roles](/api-reference/custom-roles/list-custom-roles)
* [List feature flags](/api-reference/feature-flags/list-feature-flags)
* [List segments](/api-reference/segments/list-segments)

In each case, you can use the `limit` and `offset` query parameters to page through the results.

To page through the results, repeat each request, increasing the `offset` by the `limit` each time, until one of the following is true:

* you have found the particular result you are looking for
* the `items` array in the response is empty
* the `offset` is greater than the `totalCount` in the response, if available

Each paginated endpoint includes a default page size, typically

20. You can customize this as needed using the `limit` query parameter.

### Example: Working with paginated endpoints

For example, previously your request may have looked like:

<CodeGroup>
  ```title="Previous API version, unpaginated request to 'List feature flags'" theme={null}
      curl -X GET 'https://app.launchdarkly.com/api/v2/flags/{projectKey}' \
        -H 'LD-API-Version: 20240415' \
        -H 'Authorization: EXAMPLE-API-ACCESS-TOKEN'
  ```
</CodeGroup>

Now, it should look like:

<CodeGroup>
  ```title="20240415 API version, paginated request to 'List feature flags'" theme={null}
      curl -X GET 'https://app.launchdarkly.com/api/v2/flags/{projectKey}?limit=20&offset=0' \
        -H 'LD-API-Version: 20240415' \
        -H 'Authorization: EXAMPLE-API-ACCESS-TOKEN'
  ```
</CodeGroup>

You should repeat this request, increasing the `offset` by the `limit` each time, until you find the result you are looking for, or have paged through all of the results.

## Changes to the access tokens API

In the `20240415` API version, the [List access tokens](/api-reference/access-tokens/list-access-tokens) endpoint is now paginated. It has a default page size of

25. The maximum for the `limit` query parameter is 1000.

## Changes to the account members API

In the `20240415` API version, the [List account members](/api-reference/account-members/list-account-members) endpoint no longer supports the `accessCheck` filter. Additionally, the maximum for the `limit` query parameter is now 1000.

## Changes to the custom roles API

In the `20240415` API version, the [List custom roles](/api-reference/custom-roles/list-custom-roles) endpoint is now paginated. It has a default page size of

20. The maximum for the `limit` query parameter is 1000.

## Changes to the feature flags API

In the `20240415` API version, the [List feature flags](/api-reference/feature-flags/list-feature-flags) endpoint is now paginated. It has a default page size of

20. The maximum for the `limit` query parameter is 100.

Additionally, the following filters are no longer available:

* `codeReferences`
* `contextKindTargeted`
* `contextKindsEvaluated`
* `followerId`
* `hasDataExport`
* `hasExperiment`
* `segmentTargeted`
* `status`
* `targeting`
* `targetingModifiedDate` (sorting filter)

The `compare` query parameter has also been removed.

Finally, the `environments` field is now only included in the response if the request is filtered by environment, using the `env` query parameter.

## Changes to the segments API

In the `20240415` API version, the [List segments](/api-reference/segments/list-segments) endpoint is now paginated. It has a default page size of

20. The maximum for the `limit` query parameter is 50.

## Changes to the teams API

In the `20240415` API version, the [List teams](/api-reference/teams/list-teams) endpoint no longer supports expanding the `projects` or `roles` fields in the response.

Additionally, the maximum for the `limit` query parameter is now 100.

## Changes to the workflows API

In the `20240415` API version, the [Get workflows](/api-reference/workflows/get-workflows) endpoint is now paginated. It has a default page size of

20. The maximum for the `limit` query parameter is 200.

Additionally, the `_conflicts` field in the response is no longer available.

## Removal of deprecated users APIs

The Users API, Users (beta) API, and User settings API were deprecated in May

2023. Following the release of the `20240415` API version, these deprecated APIs are being removed completely.

\| If you were using...

| ...you should now use |
| - |

\| --- |
\| Users API: Find users ( <code>getSearchUsers</code> )

\| Contexts API: [Search for context instances](/api-reference/contexts/search-for-context-instances) ( <code>searchContextInstances</code> ) |
\| Users API: List users ( <code>getUsers</code> )

\| Contexts API: [Search for contexts](/api-reference/contexts/search-for-contexts) ( <code>searchContexts</code> ) |
\| Users API: Get user ( <code>getUser</code> )

\| Contexts API: [Get context instances](/api-reference/contexts/get-context-instances) ( <code>getContextInstances</code> ) |
\| Users API: Delete user ( <code>deleteUser</code> )

\| Contexts API: [Delete context instances](/api-reference/contexts/delete-context-instances) ( <code>deleteContextInstances</code> ) |
\| Users (beta) API: Get user attribute names ( <code>getUserAttributeNames</code> )

\| Contexts API: [Get context attribute names](/api-reference/contexts/get-context-attribute-names) ( <code>getContextAttributeNames</code> ) |
\| User settings API: List flag settings for user ( <code>getUserFlagSettings</code> )

\| No direct equivalent. Contexts API: [Evaluate flags for context instance](/api-reference/contexts/get-contexts) ( <code>evaluateContextInstance</code> ) may be equivalent in some situations. |
\| User settings API: Get flag setting for user ( <code>getUserFlagSetting</code> )

\| No direct equivalent. Consider using the [Flag evaluation reasons](/sdk/features/evaluation-reasons) feature in the LaunchDarkly SDK. |
\| User settings API: Update flag settings for user ( <code>putFlagSetting</code> )

\| Context settings API: [Update flag settings for context](/api-reference/context-settings/update-flag-settings-for-context) ( <code>putContextFlagSetting</code> ) |
\| User settings API: Get expiring dates on flags for user ( <code>getExpiringFlagsForUser</code> )

\| No direct equivalent. |
\| User settings API: Update expiring user target for flags ( <code>patchExpiringFlagsForUser</code> )

\| Feature flags API: [Update expiring context targets on feature flag](/api-reference/feature-flags/update-expiring-context-targets-on-feature-flag) ( <code>patchExpiringTargets</code> ), use the semantic patch instruction `addExpiringTarget` |