> ## Documentation Index > Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List feature flags > Get a list of all feature flags in the given project. You can include information specific to different environments by adding `env` query parameter. For example, setting `env=production` adds configuration details about your production environment to the response. You can also filter feature flags by tag with the `tag` query parameter. > #### Recommended use > > This endpoint can return a large amount of information. We recommend using some or all of these query parameters to decrease response time and overall payload size: `limit`, `env`, `query`, and `filter=creationDate`. ### Filtering flags You can filter on certain fields using the `filter` query parameter. For example, setting `filter=query:dark-mode,tags:beta+test` matches flags with the string `dark-mode` in their key or name, ignoring case, which also have the tags `beta` and `test`. The `filter` query parameter supports the following arguments: | Filter argument | Description | Example | |-----------------------|-------------|----------------------| | `applicationEvaluated` | A string. It filters the list to flags that are evaluated in the application with the given key. | `filter=applicationEvaluated:com.launchdarkly.cafe` | | `archived` | (deprecated) A boolean value. It filters the list to archived flags. | Use `filter=state:archived` instead | | `contextKindsEvaluated` | A `+`-separated list of context kind keys. It filters the list to flags which have been evaluated in the past 30 days for all of the context kinds in the list. | `filter=contextKindsEvaluated:user+application` | | `codeReferences.max` | An integer value. Use `0` to return flags that do not have code references. | `filter=codeReferences.max:0` | | `codeReferences.min` | An integer value. Use `1` to return flags that do have code references. | `filter=codeReferences.min:1` | | `creationDate` | An object with an optional `before` field whose value is Unix time in milliseconds. It filters the list to flags created before the date. | `filter=creationDate:{"before":1690527600000}` | | `evaluated` | An object that contains a key of `after` and a value in Unix time in milliseconds. It filters the list to all flags that have been evaluated since the time you specify, in the environment provided. This filter requires the `filterEnv` filter. | `filter=evaluated:{"after":1690527600000},filterEnv:production` | | `filterEnv` | A valid environment key. You must use this field for filters that are environment-specific. If there are multiple environment-specific filters, you only need to include this field once. | `filter=evaluated:{"after": 1590768455282},filterEnv:production` | | `guardedRollout` | A string, one of `any`, `monitoring`, `regressed`, `rolledBack`, `completed`, `archived`. It filters the list to flags that are part of guarded rollouts. | `filter=guardedRollout:monitoring` | | `hasExperiment` | A boolean value. It filters the list to flags that are used in an experiment. | `filter=hasExperiment:true` | | `maintainerId` | A valid member ID. It filters the list to flags that are maintained by this member. | `filter=maintainerId:12ab3c45de678910abc12345` | | `maintainerTeamKey` | A string. It filters the list to flags that are maintained by the team with this key. | `filter=maintainerTeamKey:example-team-key` | | `query` | A string. It filters the list to flags that include the specified string in their key or name. It is not case sensitive. | `filter=query:example` | | `releasePipeline` | A release pipeline key. It filters the list to flags that are either currently active in the release pipeline or have completed the release pipeline. | `filter=releasePipeline:default-release-pipeline` | | `state` | A string, either `live`, `deprecated`, or `archived`. It filters the list to flags in this state. | `filter=state:archived` | | `sdkAvailability` | A string, one of `client`, `mobile`, `anyClient`, `server`. Using `client` filters the list to flags whose client-side SDK availability is set to use the client-side ID. Using `mobile` filters to flags set to use the mobile key. Using `anyClient` filters to flags set to use either the client-side ID or the mobile key. Using `server` filters to flags set to use neither, that is, to flags only available in server-side SDKs. | `filter=sdkAvailability:client` | | `tags` | A `+`-separated list of tags. It filters the list to flags that have all of the tags in the list. | `filter=tags:beta+test` | | `type` | A string, either `temporary` or `permanent`. It filters the list to flags with the specified type. | `filter=type:permanent` | The documented values for the `filter` query are prior to URL encoding. For example, the `+` in `filter=tags:beta+test` must be encoded to `%2B`. By default, this endpoint returns all flags. You can page through the list with the `limit` parameter and by following the `first`, `prev`, `next`, and `last` links in the returned `_links` field. These links will not be present if the pages they refer to don't exist. For example, the `first` and `prev` links will be missing from the response on the first page. ### Sorting flags You can sort flags based on the following fields: - `creationDate` sorts by the creation date of the flag. - `key` sorts by the key of the flag. - `maintainerId` sorts by the flag maintainer. - `name` sorts by flag name. - `tags` sorts by tags. - `targetingModifiedDate` sorts by the date that the flag's targeting rules were last modified in a given environment. It must be used with `env` parameter and it can not be combined with any other sort. If multiple `env` values are provided, it will perform sort using the first one. For example, `sort=-targetingModifiedDate&env=production&env=staging` returns results sorted by `targetingModifiedDate` for the `production` environment. - `type` sorts by flag type All fields are sorted in ascending order by default. To sort in descending order, prefix the field with a dash ( - ). For example, `sort=-name` sorts the response by flag name in descending order. ### Expanding response LaunchDarkly supports the `expand` query param to include additional fields in the response, with the following fields: - `codeReferences` includes code references for the feature flag - `evaluation` includes evaluation information within returned environments, including which context kinds the flag has been evaluated for in the past 30 days - `migrationSettings` includes migration settings information within the flag and within returned environments. These settings are only included for migration flags, that is, where `purpose` is `migration`. For example, `expand=evaluation` includes the `evaluation` field in the response. ### Migration flags For migration flags, the cohort information is included in the `rules` property of a flag's response, and default cohort information is included in the `fallthrough` property of a flag's response. To learn more, read [Migration Flags](/home/flags/migration). ## OpenAPI ````yaml /api/openapi.json get /api/v2/flags/{projectKey} openapi: 3.0.3 info: title: LaunchDarkly REST API description: > This documentation describes LaunchDarkly's REST API. To access the complete OpenAPI spec directly, use [Get OpenAPI spec](/api/other/gets-the-openapi-spec-in-json). To learn how to use LaunchDarkly using the user interface (UI) instead, read our [product documentation](/home). ## Authentication LaunchDarkly's REST API uses the HTTPS protocol with a minimum TLS version of 1.2. All REST API resources are authenticated with either [personal or service access tokens](/home/account/api), or session cookies. Other authentication mechanisms are not supported. You can manage personal access tokens on your [**Authorization**](https://app.launchdarkly.com/settings/authorization) page in the LaunchDarkly UI. LaunchDarkly also has SDK keys, mobile keys, and client-side IDs that are used by our server-side SDKs, mobile SDKs, and JavaScript-based SDKs, respectively. **These keys cannot be used to access our REST API**. These keys are environment-specific, and can only perform read-only operations such as fetching feature flag settings. | Auth mechanism | Allowed resources | Use cases | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [Personal or service access tokens](/home/account/api) | Can be customized on a per-token basis | Building scripts, custom integrations, data export. | | SDK keys | Can only access read-only resources specific to server-side SDKs. Restricted to a single environment. | Server-side SDKs | | Mobile keys | Can only access read-only resources specific to mobile SDKs, and only for flags marked available to mobile keys. Restricted to a single environment. | Mobile SDKs | | Client-side ID | Can only access read-only resources specific to JavaScript-based client-side SDKs, and only for flags marked available to client-side. Restricted to a single environment. | Client-side JavaScript | > #### Keep your access tokens and SDK keys private > > Access tokens should _never_ be exposed in untrusted contexts. Never put an access token in client-side JavaScript, or embed it in a mobile application. LaunchDarkly has special mobile keys that you can embed in mobile apps. If you accidentally expose an access token or SDK key, you can reset it from your [**Authorization**](https://app.launchdarkly.com/settings/authorization) page. > > The client-side ID is safe to embed in untrusted contexts. It's designed for use in client-side JavaScript. ### Authentication using request header The preferred way to authenticate with the API is by adding an `Authorization` header containing your access token to your requests. The value of the `Authorization` header must be your access token. Manage personal access tokens from the [**Authorization**](https://app.launchdarkly.com/settings/authorization) page. ### Authentication using session cookie For testing purposes, you can make API calls directly from your web browser. If you are logged in to the LaunchDarkly application, the API will use your existing session to authenticate calls. Depending on the permissions granted as part of your [role](/home/account/roles), you may not have permission to perform some API calls. You will receive a `401` response code in that case. > ### Modifying the Origin header causes an error > > LaunchDarkly validates that the Origin header for any API request authenticated by a session cookie matches the expected Origin header. The expected Origin header is `https://app.launchdarkly.com`. > > If the Origin header does not match what's expected, LaunchDarkly returns an error. This error can prevent the LaunchDarkly app from working correctly. > > Any browser extension that intentionally changes the Origin header can cause this problem. For example, Cross-Origin Resource Sharing (CORS) extensions used during development can modify the Origin header and cause the app to fail. > > To prevent this error, do not modify your Origin header. > > LaunchDarkly does not require origin matching when authenticating with an access token, so this issue does not affect normal API usage. ## Representations All resources expect and return JSON response bodies. Error responses also send a JSON body. To learn more about the error format of the API, read [Errors](/api/overview#errors). In practice this means that you always get a response with a `Content-Type` header set to `application/json`. In addition, request bodies for `PATCH`, `POST`, and `PUT` requests must be encoded as JSON with a `Content-Type` header set to `application/json`. ### Summary and detailed representations When you fetch a list of resources, the response includes only the most important attributes of each resource. This is a _summary representation_ of the resource. When you fetch an individual resource, such as a single feature flag, you receive a _detailed representation_ of the resource. The best way to find a detailed representation is to follow links. Every summary representation includes a link to its detailed representation. ### Expanding responses Sometimes the detailed representation of a resource does not include all of the attributes of the resource by default. If this is the case, the request method will clearly document this and describe which attributes you can include in an expanded response. To include the additional attributes, append the `expand` request parameter to your request and add a comma-separated list of the attributes to include. For example, when you append `?expand=members,maintainers` to the [Get team](/api/teams/get-team) endpoint, the expanded response includes both of these attributes. ### Links and addressability The best way to navigate the API is by following links. These are attributes in representations that link to other resources. The API always uses the same format for links: - Links to other resources within the API are encapsulated in a `_links` object - If the resource has a corresponding link to HTML content on the site, it is stored in a special `_site` link Each link has two attributes: - An `href`, which contains the URL - A `type`, which describes the content type For example, a feature resource might return the following: ```json { "_links": { "parent": { "href": "/api/features", "type": "application/json" }, "self": { "href": "/api/features/sort.order", "type": "application/json" } }, "_site": { "href": "/features/sort.order", "type": "text/html" } } ``` From this, you can navigate to the parent collection of features by following the `parent` link, or navigate to the site page for the feature by following the `_site` link. Collections are always represented as a JSON object with an `items` attribute containing an array of representations. Like all other representations, collections have `_links` defined at the top level. Paginated collections include `first`, `last`, `next`, and `prev` links containing a URL with the respective set of elements in the collection. ## Updates Resources that accept partial updates use the `PATCH` verb. Most resources support the [JSON patch](/api/overview#updates-using-json-patch) format. Some resources also support the [JSON merge patch](/api/overview#updates-using-json-merge-patch) format, and some resources support the [semantic patch](/api/overview#updates-using-semantic-patch) format, which is a way to specify the modifications to perform as a set of executable instructions. Each resource supports optional [comments](/api/overview#updates-with-comments) that you can submit with updates. Comments appear in outgoing webhooks, the audit log, and other integrations. When a resource supports both JSON patch and semantic patch, we document both in the request method. However, the specific request body fields and descriptions included in our documentation only match one type of patch or the other. ### Updates using JSON patch [JSON patch](https://datatracker.ietf.org/doc/html/rfc6902) is a way to specify the modifications to perform on a resource. JSON patch uses paths and a limited set of operations to describe how to transform the current state of the resource into a new state. JSON patch documents are always arrays, where each element contains an operation, a path to the field to update, and the new value. For example, in this feature flag representation: ```json { "name": "New recommendations engine", "key": "engine.enable", "description": "This is the description", ... } ``` You can change the feature flag's description with the following patch document: ```json [{ "op": "replace", "path": "/description", "value": "This is the new description" }] ``` You can specify multiple modifications to perform in a single request. You can also test that certain preconditions are met before applying the patch: ```json [ { "op": "test", "path": "/version", "value": 10 }, { "op": "replace", "path": "/description", "value": "The new description" } ] ``` The above patch request tests whether the feature flag's `version` is `10`, and if so, changes the feature flag's description. Attributes that are not editable, such as a resource's `_links`, have names that start with an underscore. ### Updates using JSON merge patch [JSON merge patch](https://datatracker.ietf.org/doc/html/rfc7386) is another format for specifying the modifications to perform on a resource. JSON merge patch is less expressive than JSON patch. However, in many cases it is simpler to construct a merge patch document. For example, you can change a feature flag's description with the following merge patch document: ```json { "description": "New flag description" } ``` ### Updates using semantic patch Some resources support the semantic patch format. A semantic patch is a way to specify the modifications to perform on a resource as a set of executable instructions. Semantic patch allows you to be explicit about intent using precise, custom instructions. In many cases, you can define semantic patch instructions independently of the current state of the resource. This can be useful when defining a change that may be applied at a future date. To make a semantic patch request, you must append `domain-model=launchdarkly.semanticpatch` to your `Content-Type` header. Here's how: ``` Content-Type: application/json; domain-model=launchdarkly.semanticpatch ``` If you call a semantic patch resource without this header, you will receive a `400` response because your semantic patch will be interpreted as a JSON patch. The body of a semantic patch request takes the following properties: * `comment` (string): (Optional) A description of the update. * `environmentKey` (string): (Required for some resources only) The environment key. * `instructions` (array): (Required) A list of actions the update should perform. Each action in the list must be an object with a `kind` property that indicates the instruction. If the instruction requires parameters, you must include those parameters as additional fields in the object. The documentation for each resource that supports semantic patch includes the available instructions and any additional parameters. For example: ```json { "comment": "optional comment", "instructions": [ {"kind": "turnFlagOn"} ] } ``` Semantic patches are not applied partially; either all of the instructions are applied or none of them are. If **any** instruction is invalid, the endpoint returns an error and will not change the resource. If all instructions are valid, the request succeeds and the resources are updated if necessary, or left unchanged if they are already in the state you request. ### Updates with comments You can submit optional comments with `PATCH` changes. To submit a comment along with a JSON patch document, use the following format: ```json { "comment": "This is a comment string", "patch": [{ "op": "replace", "path": "/description", "value": "The new description" }] } ``` To submit a comment along with a JSON merge patch document, use the following format: ```json { "comment": "This is a comment string", "merge": { "description": "New flag description" } } ``` To submit a comment along with a semantic patch, use the following format: ```json { "comment": "This is a comment string", "instructions": [ {"kind": "turnFlagOn"} ] } ``` ## Errors The API always returns errors in a common format. Here's an example: ```json { "code": "invalid_request", "message": "A feature with that key already exists", "id": "30ce6058-87da-11e4-b116-123b93f75cba" } ``` The `code` indicates the general class of error. The `message` is a human-readable explanation of what went wrong. The `id` is a unique identifier. Use it when you're working with LaunchDarkly Support to debug a problem with a specific API call. ### HTTP status error response codes | Code | Definition | Description | Possible Solution | | ---- | ----------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | 400 | Invalid request | The request cannot be understood. | Ensure JSON syntax in request body is correct. | | 401 | Invalid access token | Requestor is unauthorized or does not have permission for this API call. | Ensure your API access token is valid and has the appropriate permissions. | | 403 | Forbidden | Requestor does not have access to this resource. | Ensure that the account member or access token has proper permissions set. | | 404 | Invalid resource identifier | The requested resource is not valid. | Ensure that the resource is correctly identified by ID or key. | | 405 | Method not allowed | The request method is not allowed on this resource. | Ensure that the HTTP verb is correct. | | 409 | Conflict | The API request can not be completed because it conflicts with a concurrent API request. | Retry your request. | | 422 | Unprocessable entity | The API request can not be completed because the update description can not be understood. | Ensure that the request body is correct for the type of patch you are using, either JSON patch or semantic patch. | 429 | Too many requests | Read [Rate limiting](/api/overview#rate-limiting). | Wait and try again later. | ## CORS The LaunchDarkly API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. If an `Origin` header is given in a request, it will be echoed as an explicitly allowed origin. Otherwise the request returns a wildcard, `Access-Control-Allow-Origin: *`. For more information on CORS, read the [CORS W3C Recommendation](http://www.w3.org/TR/cors). Example CORS headers might look like: ```http Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, Authorization Access-Control-Allow-Methods: OPTIONS, GET, DELETE, PATCH Access-Control-Allow-Origin: * Access-Control-Max-Age: 300 ``` You can make authenticated CORS calls just as you would make same-origin calls, using either [token or session-based authentication](/api/overview#authentication). If you are using session authentication, you should set the `withCredentials` property for your `xhr` request to `true`. You should never expose your access tokens to untrusted entities. ## Rate limiting We use several rate-limiting strategies to ensure the availability of our APIs. Rate-limited calls to our APIs return a `429` status code and include headers to indicate the current rate limit status. The specific headers returned depend on the API route that was called. Limits differ based on the route, authentication mechanism, and other factors. Each set of headers below appears only when the corresponding limit is being enforced for your call. A given route may be subject to any combination of these limits, so a response can include one, several, or none of these headers. A missing header indicates that the limit was not applied to this specific call; it does not necessarily indicate that the limit does not exist. To reduce usage before hitting a `429` status, program against whichever rate limit headers are present rather than expecting a specific header. We do not publicly document the specific number of calls permitted by any of these limits, and these limits may change. We encourage clients to program against the specification and rely on the headers described below, rather than hardcoding the current limits. > ### Rate limiting and SDKs > > LaunchDarkly SDKs are never rate limited and do not use the API endpoints defined here. LaunchDarkly uses a different set of approaches, including streaming/server-sent events and a global CDN, to ensure availability to the routes used by LaunchDarkly SDKs. ### Global rate limits Authenticated requests are subject to a global limit. This is the maximum number of calls that your account can make to the API per ten seconds. All service and personal access tokens on the account share this limit, so exceeding the limit with one access token will impact other tokens. Calls that are subject to global rate limits may return the headers below: | Header name | Description | | ------------------------------ | -------------------------------------------------------------------------------- | | `X-Ratelimit-Global-Limit` | The maximum number of requests the account is permitted to make per ten seconds. | | `X-Ratelimit-Global-Remaining` | The number of requests remaining in the current global rate limit window. | | `X-Ratelimit-Reset` | The time at which the current rate limit window resets in epoch milliseconds. | ### Route-level rate limits Some authenticated routes have custom rate limits. These also reset every ten seconds. Any service or personal access tokens hitting the same route share this limit, so exceeding the limit with one access token may impact other tokens. Calls that are subject to route-level rate limits return the headers below: | Header name | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------- | | `X-Ratelimit-Route-Limit` | The maximum number of requests to the current route permitted per ten seconds. | | `X-Ratelimit-Route-Remaining` | The number of requests remaining for the current route in the current rate limit window. | | `X-Ratelimit-Reset` | The time at which the current rate limit window resets in epoch milliseconds. | A _route_ represents a specific URL pattern and verb. For example, the [Delete environment](/api/environments/delete-environment) endpoint is considered a single route, and each call to delete an environment counts against your route-level rate limit for that route. ### Access token rate limits Some calls are rate limited per access token. Unlike the global and route-level limits, this limit applies to a single service or personal access token on its own. Exceeding a limit with one access token does not affect other tokens on the account. Calls that are subject to access token rate limits return these headers: | Header name | Description | | ---------------------------------- | --------------------------------------------------------------------------------------- | | `X-Ratelimit-Auth-Token-Limit` | The maximum number of requests the access token can make per ten seconds. | | `X-Ratelimit-Auth-Token-Remaining` | The number of requests remaining for the access token in the current rate limit window. | | `X-Ratelimit-Auth-Token-Reset` | The time at which the current rate limit window resets in epoch milliseconds. | Unlike the other rate limits, access token rate limits report their own reset time in the `X-Ratelimit-Auth-Token-Reset` header instead of in `X-Ratelimit-Reset`. ### IP-based rate limiting We also employ IP-based rate limiting on some API routes. If you hit an IP-based rate limit, your API response will include a `Retry-After` header indicating how long to wait before re-trying the call. Clients must wait at least `Retry-After` seconds before making additional calls to our API, and should employ jitter and backoff strategies to avoid triggering rate limits again. ## OpenAPI (Swagger) and client libraries We have a [complete OpenAPI (Swagger) specification](https://app.launchdarkly.com/api/v2/openapi.json) for our API. We auto-generate multiple client libraries based on our OpenAPI specification. To learn more, visit the [collection of client libraries on GitHub](https://github.com/search?q=topic%3Alaunchdarkly-api+org%3Alaunchdarkly&type=Repositories). Alternatively, you can use the specification to generate client libraries to interact with our REST API in your language of choice. Or, you can refer to our API endpoints' documentation for guidance on how to make requests with a common HTTP library in your language of choice. Our OpenAPI specification is supported by several API-based tools such as Postman and Insomnia. In many cases, you can directly import our specification to explore our APIs. ## Method overriding Some firewalls and HTTP clients restrict the use of verbs other than `GET` and `POST`. In those environments, our API endpoints that use `DELETE`, `PATCH`, and `PUT` verbs are inaccessible. To avoid this issue, our API supports the `X-HTTP-Method-Override` header, allowing clients to "tunnel" `DELETE`, `PATCH`, and `PUT` requests using a `POST` request. For example, to call a `PATCH` endpoint using a `POST` request, you can include `X-HTTP-Method-Override:PATCH` as a header. ## Beta resources We sometimes release new API resources in **beta** status before we release them with general availability. Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. We try to promote resources into general availability as quickly as possible. This happens after sufficient testing and when we're satisfied that we no longer need to make backwards-incompatible changes. We mark beta resources with a "Beta" callout in our documentation, pictured below: > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. ### Using beta resources To use a beta resource, you must include a header in the request. If you call a beta resource without this header, you receive a `403` response. Use this header: ``` LD-API-Version: beta ``` ## Federal and EU environments In addition to the commercial versions, LaunchDarkly offers instances for federal agencies and those based in the European Union (EU). ### Federal environments The version of LaunchDarkly that is available on domains controlled by the United States government is different from the version of LaunchDarkly available to the general public. If you are an employee or contractor for a United States federal agency and use LaunchDarkly in your work, you likely use the federal instance of LaunchDarkly. If you are working in the federal instance of LaunchDarkly, the base URI for each request is `https://app.launchdarkly.us`. To learn more, read [LaunchDarkly in federal environments](/home/infrastructure/federal). ### EU environments The version of LaunchDarkly that is available in the EU is different from the version of LaunchDarkly available to other regions. If you are based in the EU, you likely use the EU instance of LaunchDarkly. The LaunchDarkly EU instance complies with EU data residency principles, including the protection and confidentiality of EU customer information. If you are working in the EU instance of LaunchDarkly, the base URI for each request is `https://app.eu.launchdarkly.com`. To learn more, read [LaunchDarkly in the European Union (EU)](/home/infrastructure/eu). ## Versioning We try hard to keep our REST API backwards compatible, but we occasionally have to make backwards-incompatible changes in the process of shipping new features. These breaking changes can cause unexpected behavior if you don't prepare for them accordingly. Updates to our REST API include support for the latest features in LaunchDarkly. We also release a new version of our REST API every time we make a breaking change. We provide simultaneous support for multiple API versions so you can migrate from your current API version to a new version at your own pace. ### Setting the API version per request You can set the API version on a specific request by sending an `LD-API-Version` header, as shown in the example below: ``` LD-API-Version: 20240415 ``` The header value is the version number of the API version you would like to request. The number for each version corresponds to the date the version was released in `yyyymmdd` format. In the example above the version `20240415` corresponds to April 15, 2024. ### Setting the API version per access token When you create an access token, you must specify a specific version of the API to use. This ensures that integrations using this token cannot be broken by version changes. Tokens created before versioning was released have their version set to `20160426`, which is the version of the API that existed before the current versioning scheme, so that they continue working the same way they did before versioning. If you would like to upgrade your integration to use a new API version, you can explicitly set the header described above. > ### 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. ### API version changelog
Version Changes End of life (EOL)
`20240415`
  • Changed several endpoints from unpaginated to paginated. Use the `limit` and `offset` query parameters to page through the results.
  • Changed the [list access tokens](/api/access-tokens/list-access-tokens) endpoint:
    • Response is now paginated with a default limit of `25`
  • Changed the [list account members](/api/account-members/list-account-members) endpoint:
    • The `accessCheck` filter is no longer available
  • Changed the [list custom roles](/api/custom-roles/list-custom-roles) endpoint:
    • Response is now paginated with a default limit of `20`
  • Changed the [list feature flags](/api/feature-flags/list-feature-flags) endpoint:
    • Response is now paginated with a default limit of `20`
    • The `environments` field is now only returned if the request is filtered by environment, using the `filterEnv` query parameter
    • The `followerId`, `hasDataExport`, `status`, `contextKindTargeted`, and `segmentTargeted` filters are no longer available
    • The `compare` query parameter is no longer available
  • Changed the [list segments](/api/segments/list-segments) endpoint:
    • Response is now paginated with a default limit of `20`
  • Changed the [list teams](/api/teams/list-teams) endpoint:
    • The `expand` parameter no longer supports including `projects` or `roles`
    • In paginated results, the maximum page size is now 100
  • Changed the [get workflows](/api/workflows/get-workflows) endpoint:
    • Response is now paginated with a default limit of `20`
    • The `_conflicts` field in the response is no longer available
 Current
`20220603`
  • Changed the [list projects](/api/projects/list-projects) return value:
    • Response is now paginated with a default limit of `20`.
    • Added support for filter and sort.
    • The project `environments` field is now expandable. This field is omitted by default.
  • Changed the [get project](/api/projects/get-project) return value:
    • The `environments` field is now expandable. This field is omitted by default.
 2025-04-15
`20210729`
  • Changed the [create approval request](/api/approvals/create-approval-request) return value. It now returns HTTP Status Code `201` instead of `200`.
  • Changed the [get user](/api/users/get-user) return value. It now returns a user record, not a user.
  • Added additional optional fields to environment, segments, flags, members, and segments, including the ability to create big segments.
  • Added default values for flag variations when new environments are created.
  • Added filtering and pagination for getting flags and members, including `limit`, `number`, `filter`, and `sort` query parameters.
  • Added endpoints for expiring user targets for flags and segments, scheduled changes, access tokens, Relay Proxy configuration, integrations and subscriptions, and approvals.
2023-06-03
`20191212`
  • [List feature flags](/api/feature-flags/list-feature-flags) now defaults to sending summaries of feature flag configurations, equivalent to setting the query parameter `summary=true`. Summaries omit flag targeting rules and individual user targets from the payload.
  • Added endpoints for flags, flag status, projects, environments, audit logs, members, users, custom roles, segments, usage, streams, events, and data export.
2022-07-29
`20160426`
  • Initial versioning of API. Tokens created before versioning have their version set to this.
 2020-12-12
To learn more about how EOL is determined, read LaunchDarkly's [End of Life (EOL) Policy](https://launchdarkly.com/policies/end-of-life-policy/). contact: name: LaunchDarkly Technical Support Team url: https://support.launchdarkly.com email: support@launchdarkly.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: '2.0' servers: - url: https://app.launchdarkly.com description: ' Default' - url: https://app.launchdarkly.us description: ' Federal' security: - ApiKey: - read - write tags: - name: Access tokens description: > The access tokens API allows you to list, create, modify, and delete access tokens programmatically. When using access tokens to manage access tokens, the following restrictions apply: - Personal tokens can see all service tokens and other personal tokens created by the same team member. If the personal token has the "Admin" role, it may also see other member's personal tokens. To learn more, read [Personal tokens](/home/account/api#personal-tokens). - Service tokens can see all service tokens. If the token has the "Admin" role, it may also see all personal tokens. To learn more, read [Service tokens](/home/account/api#service-tokens). - Tokens can only manage other tokens, including themselves, if they have "Admin" role or explicit permission via a custom role. To learn more, read [Personal access token actions](/home/account/roles/role-actions#personal-access-token-actions). Several of the endpoints in the access tokens API require an access token ID. The access token ID is returned as part of the [Create access token](/api/access-tokens/create-access-token) and [List access tokens](/api/access-tokens/list-access-tokens) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. To learn more about access tokens, read [API access tokens](/home/account/api). - name: Account members description: > The account members API allows you to invite new members to an account by making a `POST` request to `/api/v2/members`. When you invite a new member to an account, an invitation is sent to the email you provided. Members with Admin or Owner roles may create new members, as well as anyone with a `createMember` permission for "member/\*". To learn more, read [LaunchDarkly account members](/home/account/members). Any member may request the complete list of account members with a `GET` to `/api/v2/members`. Several of the endpoints in the account members API require a member ID. The member ID is returned as part of the [Invite new members](/api/account-members/invite-new-members) and [List account members](/api/account-members/list-account-members) responses. It is the `_id` field of each element in the `items` array. - name: Account usage (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The account usage API lets you query for metrics about how your account is using LaunchDarkly. To learn more, read [Account usage metrics](/home/account/metrics). Each endpoint returns time-series data in the form of an array of data points with timestamps. Each one contains data for that time from one or more series. It also includes a metadata array describing what each of the series is. - name: Adaptive triggers description: > Adaptive triggers automatically update the targeting of a feature flag or AgentControl config when a trigger source, such as an observability alert, fires. Each adaptive trigger pairs a trigger source with a task that describes the change to make, such as updating the variation served by the default rule or by a specific targeting rule. Using the adaptive triggers API, you can create, read, update, enable, disable, and delete adaptive triggers. - name: AgentControl description: > The AgentControl API allows you to create, retrieve, and edit AgentControl configs, config variations, and AI model configurations. **This product name has changed, but the API has not.** AgentControl was previously called AI Configs. Resources previously called "AI Configs" are now referred to as "AgentControl configs" or "configs." This is not a breaking change to the API. Existing AI Configs API endpoints, paths, request/response bodies, and operation IDs are unchanged. Integrations that use those resources still work and do not need modification. An AgentControl config is a resource in LaunchDarkly that you can use to customize, test, and roll out new large language models (LLMs) within your generative AI applications. Within each config, you define one or more variations, each of which includes a model configuration and one or more messages. The model configuration can be a standard one from the list provided by LaunchDarkly, or you can define your own custom AI model configuration. To learn more, read [AgentControl](/home/agentcontrol). - name: Announcements description: > The announcements API lets you create and update a custom announcement banner that appears in the LaunchDarkly user interface for everyone in your organization. You can use the banner to display organization-wide information, such as upcoming holidays, code freeze periods, or reminders on best practices. You can have one banner visible at a time. To learn more, read [Organization announcements](/home/account/org-announcements). - name: Applications (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The applications API lets you create, update, delete, and search for applications and application versions. Each application includes information about the app you're creating, and a set of versions of the app that you've released. You can use applications to target particular application versions in your feature flags more easily, and to handle unsupported application versions more gracefully. In addition to creating applications through the applications API, you can also create applications in the LaunchDarkly user interface. To learn more, read [Applications and application versions](/home/releases/applications). LaunchDarkly also creates applications and application versions automatically when a LaunchDarkly SDK evaluates a feature flag for a context that includes application information. To learn more, read [Automatic environment attributes](/sdk/features/environment-attributes). You can use an application in any project in your LaunchDarkly account. ### Filtering applications and application versions The `filter` parameter supports the following operators: `equals`, `notEquals`, `anyOf`, `startsWith`. You can also combine filters in the following ways: - Use a comma (`,`) as an AND operator - Use a vertical bar (`|`) as an OR operator - Use parentheses (`()`) to group filters #### Supported fields and operators You can only filter certain fields in applications when using the `filter` parameter. Additionally, you can only filter some fields with certain operators. When you search for applications, the `filter` parameter supports the following fields and operators: |
Field
|Description |Supported operators | |---|---|---| |`key` | The application or application version key, a unique identifier |`equals`, `notEquals`, `anyOf` | |`name` | The application name or application version name |`equals`, `notEquals`, `anyOf`, `startsWith` | |`autoAdded` | Whether the application or application version was automatically created because it was included in a context when a LaunchDarkly SDK evaluated a feature flag, or was created through the LaunchDarkly UI or REST API |`equals`, `notEquals` | |`kind` | The application kind, one of `mobile`, `server`, `browser`. Only available for [Get applications](/api/applications-beta/get-applications). |`equals`, `notEquals`, `anyOf` | |`supported` | Whether a mobile application version is supported or unsupported. Only available for [Get application versions by application key](/api/applications-beta/get-application-versions-by-application-key).|`equals`, `notEquals` | For example, the filter `?filter=kind anyOf ["mobile", "server"]` matches applications whose `kind` is either `mobile` or `server`. The filter is not case-sensitive. The documented values for `filter` query parameters are prior to URL encoding. For example, the `[` in `?filter=kind anyOf ["mobile", "server"]` must be encoded to `%5B`. ### Sorting applications and application versions LaunchDarkly supports the following fields for sorting: - `name` sorts by application name. - `creationDate` sorts by the creation date of the application. By default, the sort is in ascending order. Use `-` to sort in descending order. For example, `?sort=name` sorts the response by application name in ascending order, and `?sort=-name` sorts in descending order. - name: Approvals description: > An account member can request approval on changes to a flag or AgentControl config's targeting or variations, or to a segment's targeting. Members may be required to request approval depending on the settings in their LaunchDarkly project. Members can optionally request an approval even if it is not required. An approval request prevents a change from being applied without approval from another member. Select up to ten members as reviewers. Reviewers receive an email notification, but anyone with sufficient permissions can review a pending approval request. A change needs at least one approval before you can apply it. To learn more, read [Approvals](/home/releases/approvals). Changes that conflict will fail if approved and applied, and the flag or segment will not be updated. Several of the endpoints in the approvals API require an approval request ID. The approval request ID is returned as part of the [Create approval request](/api/approvals/create-approval-request) and [List approval requests for a flag](/api/approvals/list-approval-requests-for-a-flag) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. If you created the approval request as part of a [workflow](/api/workflows), you can also use a workflow ID as the approval request ID. The workflow ID is returned as part of the [Create workflow](/api/workflows/create-workflow) and [Get workflows](/api/workflows/get-workflows) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. - name: Approvals (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. - name: Audit log description: > LaunchDarkly maintains a record of all the changes made to any resource in the system. You can access this history using the audit log API, including filtering by timestamps, or using a custom policy to select which entries to receive. Several of the endpoints in the audit log API require an audit log entry ID. The audit log entry ID is returned as part of the [List audit log entries](/api/audit-log/list-audit-log-entries) response. It is the `_id` field of each element in the `items` array. In the LaunchDarkly UI, this information appears on the **Change history** page. To learn more, read [Change history](/home/releases/change-history). - name: Code references description: > > ### Code references is an Enterprise feature > > Code references is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). > ### Use ld-find-code-refs > > LaunchDarkly provides the [ld-find-code-refs utility](https://github.com/launchdarkly/ld-find-code-refs) that creates repository connections, generates code reference data, and creates calls to the code references API. Most customers do not need to call this API directly. The code references API provides access to all resources related to each connected repository, and associated feature flag code reference data for all branches. To learn more, read [Code references](/home/flags/code-references). - name: Context settings description: > You can use the context settings API to assign a context to a specific variation for any feature flag. To learn more, read [View and manage contexts](/home/flags/context-attributes#view-and-manage-context-attributes). - name: Contexts description: > Contexts are people, services, machines, or other resources that encounter feature flags in your product. Contexts are identified by their `kind`, which describes the type of resources encountering flags, and by their `key`. Each unique combination of one or more contexts that have encountered a feature flag in your product is called a context instance. When you use the LaunchDarkly SDK to evaluate a flag, you provide a context to that call. LaunchDarkly records the key and attributes of each context. You can view these in the LaunchDarkly user interface from the **Contexts** list, or use the Context APIs. To learn more, read [Contexts](/home/flags/contexts). LaunchDarkly provides APIs for you to: * retrieve contexts and context attribute names and values * search for contexts * fetch context kinds * create and update context kinds To learn more about context kinds, read [Context kinds](/home/flags/context-kinds). Contexts are always scoped within a project and an environment. Each environment has its own set of context records. Context records reflect the contexts that LaunchDarkly has received within the last 30 days. Some of the endpoints in the contexts API accept an application ID. The application ID is returned as the `applicationId` field of each element in the `items` array of the [Get contexts](/api/contexts/get-contexts) response. By default, the application ID is set to the SDK you are using. In the LaunchDarkly UI, the application ID and application version appear on the context details page in the "From source" field. You can change the application ID as part of your SDK configuration. To learn more, read [Application metadata configuration](/sdk/features/app-config). ### Filtering contexts When you [search for contexts](/api/contexts/search-for-contexts), you can filter the results using fields and operators with the `filter` parameter. Specify `filter` either as a query parameter or as a request body parameter. The `filter` parameter supports the following operators: `after`, `anyOf`, `before`, `contains`, `equals`, `exists`, `notEquals`, `startsWith`.
Expand for details on operators and syntax #### after Returns contexts if the field's date value occurs after the specified time. Provide an RFC 3339 timestamp or Unix epoch milliseconds. For example: * `myField after "2022-09-21T19:03:15+00:00"` #### anyOf Returns contexts if the field value matches any of the provided values. The `anyOf` operator is supported for the `applicationId`, `key`, `kind`, `kindKey`, `kindKeys`, and `kinds` fields only. To match an attribute against multiple values, use `equals` with an array value instead. For example: * `kind anyOf ["user","device"]` * `key anyOf ["user-key-123abc","user-key-456def"]` #### before Returns contexts if the field's date value occurs before the provided time. Provide an RFC 3339 timestamp or Unix epoch milliseconds. For example: * `myField before "2022-09-21T19:03:15+00:00"` #### contains Returns contexts whose kind or kind and key match the provided value. The `contains` operator is supported for the `kinds` and `kindKeys` fields only, and accepts exactly one value. For example: * `kinds contains ["user"]` * `kindKeys contains ["user:user-key-123abc"]` #### equals Returns contexts only if the field value exactly matches the provided value. If you provide an array, the filter matches if the field value equals any element of the array. For example: * `myField equals 44` * `myField equals "device"` * `myField equals true` * `myField equals [1,2,3,4]` * `myField equals ["hello","goodbye"]` #### exists Returns contexts based on whether the specified field exists. The `exists` operator is supported for the `name` field and attribute fields only. For example: * `myField exists true` * `myField exists false` * `*.name exists true` #### notEquals Returns contexts if the field value does not exactly match the provided value. If you provide an array, the filter matches if the field value does not equal any element of the array. For example: * `myField notEquals 44` * `myField notEquals "device"` * `myField notEquals true` * `myField notEquals [1,2,3,4]` * `myField notEquals ["hello","goodbye"]` #### startsWith Returns contexts if a singular string field value begins with the provided substring. The substring can be at most 500 characters. Matching is case-sensitive. For example: * `myField startsWith "do"`
You can also combine filters in the following ways: * Use a comma (`,`) as an AND operator * Use a vertical bar (`|`) as an OR operator * Use parentheses `()` to group filters For example: * `myField notEquals 0, myField notEquals 1` returns contexts where `myField` is not 0 and is not 1 * `myFirstField equals "device",(mySecondField equals "iPhone"|mySecondField equals "iPad")` returns contexts where `myFirstField` is equal to "device" and `mySecondField` is equal to either "iPhone" or "iPad" #### Supported fields and operators You can only filter some fields using certain operators. When you search for [contexts](/api/contexts/search-for-contexts), the `filter` parameter supports the following fields and operators: |
Field
|Description |Supported operators | |---|---|---| |`applicationId` |An identifier that represents the application where the LaunchDarkly SDK is running. |`equals`, `notEquals`, `anyOf`, `startsWith` | |`key` |The context key. |`equals`, `notEquals`, `anyOf`, `startsWith` | |`kind` |The context kind. |`equals`, `notEquals`, `anyOf`, `startsWith` | |`kinds` |The context's kind. Supply a list of strings to the operator. The filter matches contexts whose kind is any of the provided values. The `contains` operator accepts exactly one value. |`equals`, `anyOf`, `contains` | |`kindKey` |The kind and key for the context, joined with a `:`. For example, `user:user-key-abc123`. |`equals`, `notEquals`, `anyOf` | |`kindKeys` |The kind and key for the context, joined with a `:`. For example, `user:user-key-abc123`. Supply a list of strings to the operator. The filter matches contexts whose kind and key match any of the provided values. The `contains` operator accepts exactly one value. |`equals`, `anyOf`, `contains` | |`q` |A prefix search across the context key and the `name`, `firstName`, `lastName`, and `email` attributes. Supply a single string to the operator. |`equals` | |`name` |The name for the context. |`equals`, `notEquals`, `exists`, `startsWith` | |`.` |A kind and the name of any attribute that appears in a context of that kind, for example, `user.email`. To filter all kinds use `*` in place of the kind. For example, `*.email`. Reference a nested attribute by joining path segments with periods. For example, `user.address.city` filters on the `city` field within the `address` attribute of a user context. Each path segment may contain letters, numbers, underscores, and hyphens, and may not start with a number. JSON pointer escaping (`~0`, `~1`) is not supported. If the value includes whitespace, enclose it in double quotes. A filter may include at most 10 attribute clauses. |`equals`, `notEquals`, `exists`, `startsWith`, `before`, `after`.| - name: Custom roles description: > > ### Custom roles is an Enterprise feature > > Custom roles is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). Custom roles allow you to create flexible policies providing fine-grained access control to everything in LaunchDarkly, including feature flags, environments, and teams. With roles, it's possible to enforce access policies that meet your exact workflow needs. The custom roles API allows you to create, update, and delete roles. You can also use the API to list roles or get a role by key or ID. This API works with roles that you create, and with [preset roles](/home/getting-started/vocabulary#preset-roles) provided by LaunchDarkly. You cannot use this API to work with [base roles](/home/getting-started/vocabulary#base-role). For more information about roles and the syntax for role policies, read the product documentation for [Roles](/home/account/roles). - name: Data Export destinations description: > > ### Data Export is an add-on feature > > Data Export is available as an add-on for customers on a Foundation or Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). Data Export provides a real-time export of raw analytics data, including feature flag requests, analytics events, custom events, and more. Data Export destinations are locations that receive exported data. The Data Export destinations API allows you to configure destinations so that your data can be exported. Several of the endpoints in the Data Export destinations API require a Data Export destination ID. The Data Export destination ID is returned as part of the [Create a Data Export destination](/api/data-export-destinations/create-data-export-destination) and [List destinations](/api/data-export-destinations/list-destinations) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. To learn more, read [Data Export](/integrations/data-export). - name: Environment releases (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Environment releases progressively or guardedly roll out a flag targeting change in one environment. Use the environment releases API to list and retrieve releases, start a release, or stop an active release. - name: Environments description: > Environments allow you to maintain separate rollout rules in different contexts, from local development to QA, staging, and production. With the LaunchDarkly Environments API, you can programmatically list, create, and manage environments. To learn more, read [Environments](/home/account/environment). - name: Experiments description: > > ### Available for subscription customers > > Experimentation is available to all customers on a Developer, Foundation, Enterprise, or Guardian plan. If you're on an older Pro or Enterprise plan, Experimentation is available as an add-on. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To change your plan, [contact Sales](https://launchdarkly.com/contact-sales/). Experimentation lets you validate the impact of features you roll out to your app or infrastructure. You can measure things like page views, clicks, load time, infrastructure costs, and more. By connecting metrics you create to flags in your LaunchDarkly environment, you can measure the changes in your customers' behavior based on what flags they evaluate. You can run experiments with any type of flag, including boolean, string, number, and JSON flags. To learn more, read [Experimentation](/home/experimentation). You can manage experiments by using the dedicated experiment endpoints described below. Several of the endpoints require a treatment ID or a flag rule ID. Treatment IDs are returned as part of the expanded [Get experiment](/api/experiments/get-experiment#expanding-the-experiment-response) response. Winning treatment IDs are also returned as part of the [Get experiment](/api/experiments/get-experiment) response. They are the `winningTreatmentId` in the `currentIteration`, the `winningTreatmentId` in the `draftIteration`, and the `winningTreatmentId` in each element of the `previousIterations` array. In the flags object, the rule ID is the ID of the variation or rollout of the flag. Each flag variation ID is returned as part of the [Get feature flag](/api/feature-flags/get-feature-flag) response. It is the `_id` field in each element of the `variations` array. - name: Feature flags description: > The feature flags API allows you to list, create, and modify feature flags and their targeting. For example, you can control percentage rollouts, target specific contexts, or even toggle off a feature flag programmatically. ## Sample feature flag representation Every feature flag has a set of top-level attributes, as well as an `environments` map containing the flag rollout and targeting rules specific to each environment. To learn more, read [Using feature flags](/home/flags/create).
Click to expand an example of a complete feature flag representation ```json { "name": "Alternate product page", "kind": "boolean", "description": "This is a description", "key": "alternate.page", "_version": 2, "creationDate": 1418684722483, "includeInSnippet": true, "clientSideAvailability" { "usingMobileKey": false, "usingEnvironmentId": true, }, "variations": [ { "value": true, "name": "true", "_id": "86208e6e-468f-4425-b334-7f318397f95c" }, { "value": false, "name": "false", "_id": "7b32de80-f346-4276-bb77-28dfa7ddc2d8" } ], "variationJsonSchema": null, "defaults": { "onVariation": 0, "offVariation": 1 }, "temporary": false, "tags": ["ops", "experiments"], "_links": { "parent": { "href": "/api/v2/flags/default", "type": "application/json" }, "self": { "href": "/api/v2/flags/default/alternate.page", "type": "application/json" } }, "maintainerId": "548f6741c1efad40031b18ae", "_maintainer": { "_links": { "self": { "href": "/api/v2/members/548f6741c1efad40031b18ae", "type": "application/json" } }, "_id": "548f6741c1efad40031b18ae", "firstName": "Ariel", "lastName": "Flores", "role": "reader", "email": "ariel@acme.com" }, "goalIds": [], "experiments": { "baselineIdx": 0, "items": [] }, "environments": { "production": { "on": true, "archived": false, "salt": "YWx0ZXJuYXRlLnBhZ2U=", "sel": "45501b9314dc4641841af774cb038b96", "lastModified": 1469326565348, "version": 61, "targets": [{ "values": ["user-key-123abc"], "variation": 0, "contextKind": "user" }], "contextTargets": [{ "values": [], "variation": 0, "contextKind": "user" }, { "values": ["org-key-123abc"], "variation": 0, "contextKind": "organization" }], "rules": [ { "_id": "f3ea72d0-e473-4e8b-b942-565b790ffe18", "variation": 0, "clauses": [ { "_id": "6b81968e-3744-4416-9d64-74547eb0a7d1", "attribute": "groups", "op": "in", "values": ["Top Customers"], "contextKind": "user", "negate": false }, { "_id": "9d60165d-82b8-4b9a-9136-f23407ba1718", "attribute": "email", "op": "endsWith", "values": ["gmail.com"], "contextKind": "user", "negate": false } ], "trackEvents": false, "ref": "73257308-472b-4d9c-a556-10aa7adbf857" } ], "fallthrough": { "rollout": { "variations": [ { "variation": 0, "weight": 60000 }, { "variation": 1, "weight": 40000 } ], "contextKind": "user" } }, "offVariation": 1, "prerequisites": [], "_site": { "href": "/default/production/features/alternate.page", "type": "text/html" }, "_environmentName": "Production", "trackEvents": false, "trackEventsFallthrough": false, "_summary": { "variations": { "0": { "rules": 1, "nullRules": 0, "targets": 2, "rollout": 60000 }, "1": { "rules": 0, "nullRules": 0, "targets": 0, "isOff": true, "rollout": 40000 } }, "prerequisites": 0 } } } ```
## Anatomy of a feature flag This section describes the sample feature flag representation in more detail. ### Top-level attributes Most of the top-level attributes have a straightforward interpretation, for example `name` and `description`. The `variations` array represents the different variation values that a feature flag has. For a boolean flag, there are two variations: `true` and `false`. Multivariate flags have more variation values, and those values could be any JSON type: numbers, strings, objects, or arrays. In targeting rules, the variations are referred to by their index into this array. To update these attributes, read [Update feature flag](#operation/patchFeatureFlag), especially the instructions for **updating flag settings**. ### Per-environment configurations Each entry in the `environments` map contains a JSON object that represents the environment-specific flag configuration data available in the flag's targeting page. To learn more, read [Targeting with flags](/home/flags/target). To update per-environment information for a flag, read [Update feature flag](#operation/patchFeatureFlag), especially the instructions for **turning flags on and off** and **working with targeting and variations**. ### Individual context targets The `targets` and `contextTargets` arrays in the per-environment configuration data correspond to the individual context targeting on the flag's targeting page. To learn more, read [Individual targeting](/home/flags/individual-targeting). Each object in the `targets` and `contextTargets` arrays represents a list of context keys assigned to a particular variation. The `targets` array includes contexts with `contextKind` of "user" and the `contextTargets` array includes contexts with context kinds other than "user." For example: ```json { ... "environments" : { "production" : { ... "targets": [ { "values": ["user-key-123abc"], "variation": 0, "contextKind": "user" } ], "contextTargets": [ { "values": ["org-key-123abc"], "variation": 0, "contextKind": "organization" } ] } } } ``` The `targets` array means that any user context instance with the key `user-key-123abc` receives the first variation listed in the `variations` array. The `contextTargets` array means that any organization context with the key `org-key-123abc` receives the first variation listed in the `variations` array. Recall that the variations are stored at the top level of the flag JSON in an array, and the per-environment configuration rules point to indexes into this array. If this is a boolean flag, both contexts are receiving the `true` variation. ### Targeting rules The `rules` array corresponds to the rules section of the flag's targeting page. This is where you can express complex rules on attributes with conditions and operators. For example, you might create a rule that specifies "roll out the `true` variation to 80% of contexts whose email address ends with `gmail.com`". To learn more, read [Targeting rules](/home/flags/target-rules). ### The fallthrough rule The `fallthrough` object is a special rule that contains no conditions. It is the rollout strategy that is applied when none of the individual or custom targeting rules match. In the LaunchDarkly UI, it is called the "Default rule." ### The off variation The off variation represents the variation to serve if the feature flag targeting is turned off, meaning the `on` attribute is `false`. For boolean flags, this is usually `false`. For multivariate flags, set the off variation to whatever variation represents the control or baseline behavior for your application. If you don't set the off variation, LaunchDarkly will serve the fallback value defined in your code. ### Percentage rollouts When you work with targeting rules and with the default rule, you can specify either a single variation or a percentage rollout. The `weight` attribute defines the percentage rollout for each variation. Weights range from 0 (a 0% rollout) to 100000 (a 100% rollout). The weights are scaled by a factor of 1000 so that fractions of a percent can be represented without using floating-point. For example, a weight of `60000` means that 60% of contexts will receive that variation. The sum of weights across all variations should be 100%. - name: Feature flags (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. - name: Flag import configurations (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Flag import configurations allow you to import feature flags from another feature management system. Use the flag import configuration endpoints to create, delete, and manage flag import configurations. You can import flags from other feature management tools into LaunchDarkly. For example, you can import flags from Split.io. Several of the endpoints in the flag import configuration API require an integration ID. The integration ID is returned as part of the [Create a flag import configuration](/api/flag-import-configurations-beta/create-a-flag-import-configuration) response, in the `_id` field. It is also returned as part of the [List all flag import configurations](/api/flag-import-configurations-beta/list-all-flag-import-configurations) response, in the `_id` field of each element in the `items` array. To learn more about flag import configurations, read [Import flags](/home/flags/import). - name: Flag links (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Flag links let you view external mentions of flags from other tools and services. Links to external conversations and references to your flags allow you to collaborate more easily and quickly review relevant flag contexts. To learn more, read [Flag links](/home/flags/links). You can create custom flag links by associating an external URL with a feature flag. After you create a flag link, it applies across all your environments. You should use caution when you delete a flag link, because it will be deleted from all your environments. With the flag links API, you can view, create, update, and delete links to flags. Several of the endpoints in the flag links API require a flag link ID. The flag link ID is returned as part of the [Create flag link](/api/flag-links-beta/create-flag-link) and [List flag links](/api/flag-links-beta/list-flag-links) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. - name: Flag triggers description: > > ### Flag triggers is an Enterprise feature > > Flag triggers is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). Flag triggers let you initiate flag changes remotely using a unique webhook URL. For example, you can integrate triggers with your existing tools to enable or disable flags when you hit specific operational health thresholds or receive certain alerts. To learn more, read [Flag triggers](/home/releases/triggers). With the flag triggers API, you can create, delete, and manage triggers. Several of the endpoints in the flag triggers API require a flag trigger ID. The flag trigger ID is returned as part of the [Create flag trigger](/api/flag-triggers/create-flag-trigger) and [List flag triggers](/api/flag-triggers/list-flag-triggers) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. - name: Follow flags description: > Follow flags to receive email updates about targeting changes to a flag in a project and environment. Several of the endpoints in the follow flags API require a member ID. The member ID is returned as part of the [Invite new members](/api/account-members/invite-new-members) and [List account members](/api/account-members/list-account-members) responses. It is the `_id` field of each element in the `items` array. - name: Holdouts description: > > ### Available for customers using Experimentation > > Holdouts are available to customers using [Experimentation](/api/experiments). Holdouts let you exclude a percentage of your audience from your Experimentation program. This enables you to see the overall effect of your experiments on your customer base, and helps determine how effective the experiments you're running are. Using the holdouts API, you can create, delete, and manage holdouts. To learn more, read [Holdouts](/home/holdouts). - name: Insights charts (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The charts API provides access to the data used in engineering insights project metrics. To learn more, read [Project metrics](/home/releases/project-metrics). - name: Insights deployments (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The deployments API provides access to deployment information in engineering insights. To learn more, read [Deployments](/home/releases/deployments). - name: Insights flag events (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The flag events API provides access to flag-event data used in engineering insights project metrics. To learn more, read [Flag health](/home/releases/flag-health). - name: Insights pull requests (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The pull requests API provides access to information used for lead time calculations. To learn more, read [Lead time](/home/releases/lead-time). - name: Insights repositories (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Engineering insights automatically creates repository associations when it receives deployments or code references. Optionally, you can manually configure additional associations. You can use the repositories API to list repositories and create associations to projects. To learn more, read [Send deployment information](/home/releases/config-deployment). - name: Insights scores (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The insights scores API provides scores for data used in engineering insights project metrics. To learn more, read [Project overview](/home/releases/project-overview) and [Project metrics](/home/releases/project-metrics). - name: Integration audit log subscriptions description: > Audit log integration subscriptions allow you to send audit log events hooks to one of dozens of external tools. For example, you can send flag change event webhooks to external third party software. To learn more, read [Building your own integrations](/integrations/building-integrations#building-your-own-integrations). You can use the integration subscriptions API to create, delete, and manage your integration audit log subscriptions. Each of these operations requires an `integrationKey` that refers to the type of integration. The required `config` fields to create a subscription vary depending on the `integrationKey`. You can find a full list of the fields for each integration below. Several of these operations require a subscription ID. The subscription ID is returned as part of the [Create audit log subscription](/api/integration-audit-log-subscriptions/create-audit-log-subscription) and [Get audit log subscriptions by integration](/api/integration-audit-log-subscriptions/get-audit-log-subscriptions-by-integration) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. ### Configuration bodies by integrationKey #### datadog `apiKey` is a sensitive value. `hostURL` must evaluate to either `"https://api.datadoghq.com"` or `"https://api.datadoghq.eu"` and will default to the former if not explicitly defined. ``` "config": { "apiKey": , # sensitive value "hostURL": } ``` #### dynatrace `apiToken` is a sensitive value. `entity` must evaluate to one of the following fields and will default to `"APPLICATION"` if not explicitly defined:
Click to expand list of fields
"APPLICATION"
"APPLICATION_METHOD"
"APPLICATION_METHOD_GROUP"
"AUTO_SCALING_GROUP"
"AUXILIARY_SYNTHETIC_TEST"
"AWS_APPLICATION_LOAD_BALANCER"
"AWS_AVAILABILITY_ZONE"
"AWS_CREDENTIALS"
"AWS_LAMBDA_FUNCTION"
"AWS_NETWORK_LOAD_BALANCER"
"AZURE_API_MANAGEMENT_SERVICE"
"AZURE_APPLICATION_GATEWAY"
"AZURE_COSMOS_DB"
"AZURE_CREDENTIALS"
"AZURE_EVENT_HUB"
"AZURE_EVENT_HUB_NAMESPACE"
"AZURE_FUNCTION_APP"
"AZURE_IOT_HUB"
"AZURE_LOAD_BALANCER"
"AZURE_MGMT_GROUP"
"AZURE_REDIS_CACHE"
"AZURE_REGION"
"AZURE_SERVICE_BUS_NAMESPACE"
"AZURE_SERVICE_BUS_QUEUE"
"AZURE_SERVICE_BUS_TOPIC"
"AZURE_SQL_DATABASE"
"AZURE_SQL_ELASTIC_POOL"
"AZURE_SQL_SERVER"
"AZURE_STORAGE_ACCOUNT"
"AZURE_SUBSCRIPTION"
"AZURE_TENANT"
"AZURE_VM"
"AZURE_VM_SCALE_SET"
"AZURE_WEB_APP"
"CF_APPLICATION"
"CF_FOUNDATION"
"CINDER_VOLUME"
"CLOUD_APPLICATION"
"CLOUD_APPLICATION_INSTANCE"
"CLOUD_APPLICATION_NAMESPACE"
"CONTAINER_GROUP"
"CONTAINER_GROUP_INSTANCE"
"CUSTOM_APPLICATION"
"CUSTOM_DEVICE"
"CUSTOM_DEVICE_GROUP"
"DCRUM_APPLICATION"
"DCRUM_SERVICE"
"DCRUM_SERVICE_INSTANCE"
"DEVICE_APPLICATION_METHOD"
"DISK"
"DOCKER_CONTAINER_GROUP_INSTANCE"
"DYNAMO_DB_TABLE"
"EBS_VOLUME"
"EC2_INSTANCE"
"ELASTIC_LOAD_BALANCER"
"ENVIRONMENT"
"EXTERNAL_SYNTHETIC_TEST_STEP"
"GCP_ZONE"
"GEOLOCATION"
"GEOLOC_SITE"
"GOOGLE_COMPUTE_ENGINE"
"HOST"
"HOST_GROUP"
"HTTP_CHECK"
"HTTP_CHECK_STEP"
"HYPERVISOR"
"KUBERNETES_CLUSTER"
"KUBERNETES_NODE"
"MOBILE_APPLICATION"
"NETWORK_INTERFACE"
"NEUTRON_SUBNET"
"OPENSTACK_PROJECT"
"OPENSTACK_REGION"
"OPENSTACK_VM"
"OS"
"PROCESS_GROUP"
"PROCESS_GROUP_INSTANCE"
"RELATIONAL_DATABASE_SERVICE"
"SERVICE"
"SERVICE_INSTANCE"
"SERVICE_METHOD"
"SERVICE_METHOD_GROUP"
"SWIFT_CONTAINER"
"SYNTHETIC_LOCATION"
"SYNTHETIC_TEST"
"SYNTHETIC_TEST_STEP"
"VIRTUALMACHINE"
"VMWARE_DATACENTER"
``` "config": { "apiToken": , "url": , "entity": } ``` #### elastic `token` is a sensitive field. ``` "config": { "url": , "token": , "index": } ``` #### honeycomb `apiKey` is a sensitive field. ``` "config": { "datasetName": , "apiKey": } ``` #### logdna `ingestionKey` is a sensitive field. ``` "config": { "ingestionKey": , "level": } ``` #### msteams ``` "config": { "url": } ``` #### new-relic-apm `apiKey` is a sensitive field. `domain` must evaluate to either `"api.newrelic.com"` or `"api.eu.newrelic.com"` and will default to the former if not explicitly defined. ``` "config": { "apiKey": , "applicationId": , "domain": } ``` #### signalfx `accessToken` is a sensitive field. ``` "config": { "accessToken": , "realm": } ``` #### splunk `token` is a sensitive field. ``` "config": { "base-url": , "token": , "skip-ca-verification": } ``` - name: Integration delivery configurations (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The integration delivery configurations API allow you to create, modify, validate, and delete delivery configurations. Several of the endpoints require a delivery configuration ID. The delivery configuration ID is returned as part of the [Create delivery configuration](/api/integration-delivery-configurations-beta/create-delivery-configuration) and [List all delivery configurations](/api/integration-delivery-configurations-beta/list-all-delivery-configurations) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. - name: Integrations (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. > ### Integration configuration is an Enterprise feature > > Integration configuration is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). You can use the integrations API to create, delete, and manage integration configurations. An integration configuration stores and manages configuration details for an integration between LaunchDarkly and a third-party application. To learn more about building an integration, read [Using the LaunchDarkly integration framework](/integrations/building-integrations) and [Building partner integrations](/integrations/partner-integrations). - name: IP Allowlist (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The IP allowlist feature lets you configure specific IP addresses that can access your LaunchDarkly app using a browser, the LaunchDarkly REST API, or both. This gives you control over the locations from which your members can access their LaunchDarkly account. The IP allowlist supports both individual IP addresses and classless inter-domain routing (CIDR) ranges. The allowlist only supports IPv4 values. Use of the IP allowlist is an Enterprise and Guardian feature. To learn more, read [IP allowlist](/home/account/ip-allowlist). - name: Layers description: > > ### Available for customers using Experimentation > > Layers are available to customers using [Experimentation](/api/experiments). There are some cases in which you may not want to include a context in more than one experiment at a time. For example, you may be concerned about collisions between experiments that are testing similar parts of your app, like two different changes to the same section of your app's user interface (UI), or experiments running on both the back end and front end of the same functionality. In this case you can eliminate the interaction effect between experiments using layers. A layer contains a set of experiments that cannot share traffic with each other. All of the experiments within a layer are mutually exclusive, which means that if a context is included in one experiment, LaunchDarkly will exclude it from any other experiments in the same layer. To learn more, read [Mutually exclusive experiments](/home/experimentation/mutually-exclusive). - name: Metrics description: > Metrics track flag behavior over time when an experiment is running. The data generated from experiments gives you more insight into the impact of a particular flag. To learn more, read [Metrics](/home/metrics). Using the metrics API, you can create, delete, and manage metrics. > ### Metric keys and event keys are different > > LaunchDarkly automatically generates a metric key when you create a metric. You can use the metric key to identify the metric in API calls. > > Custom conversion/binary and custom numeric metrics also require an event key. You can set the event key to anything you want. Adding this event key to your codebase lets your SDK track actions customers take in your app as events. To learn more, read [Sending custom events](/sdk/features/events). ### Importing metric events The metric import API is separate from the metrics API. The metric import API lets you import metric events from your data pipeline for use with Experimentation and guarded rollouts. This means you can send your already-instrumented metrics into LaunchDarkly without writing and deploying new code for each metric. For details on the metric import API, read [Importing metric events](/home/metrics/import-events). > #### The metric import API uses a different base URL > > The metric import API differs from other LaunchDarkly REST APIs because it uses a different base URL: it requires `https://events.launchdarkly.com` rather than `https://app.launchdarkly.com`. For this reason, the metric import API is also not included as part of LaunchDarkly's [generated client libraries](/api/overview#openapi-swagger-and-client-libraries), and details are not included in the [OpenAPI specification](/api/other/gets-the-openapi-spec-in-json). To learn more, read [Importing metric events](/home/metrics/import-events). - name: Metrics (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Metrics measure audience behaviors affected by the flags in your experiments. Metric groups are reusable, ordered lists of metrics you can use to standardize metrics across multiple experiments. To learn more, read [Metrics](/home/metrics) and [Metric groups](/home/metrics/metric-groups). Using the metrics API, you can create, delete, and manage metrics and metric groups. - name: OAuth2 Clients description: > The OAuth2 client API allows you to register a LaunchDarkly OAuth client for use in your own custom integrations. Registering a LaunchDarkly OAuth client allows you to use LaunchDarkly as an identity provider so that account members can log into your application with their LaunchDarkly account. You can create and manage LaunchDarkly OAuth clients using the LaunchDarkly OAuth client API. This API acknowledges creation of your client with a response containing a one-time, unique `_clientSecret`. If you lose your client secret, you will have to register a new client. LaunchDarkly does not store client secrets in plain text. Several of the endpoints in the OAuth2 client API require an OAuth client ID. The OAuth client ID is returned as part of the [Create a LaunchDarkly OAuth 2.0 client](/api/oauth2-clients/create-a-launchdarkly-oauth-20-client) and [Get clients](/api/oauth2-clients/get-clients) responses. It is the `_clientId` field, or the `_clientId` field of each element in the `items` array. OAuth clients created through this API cannot be used for SCIM provisioning. If you need OAuth credentials for SCIM setup, [contact LaunchDarkly Support](https://support.launchdarkly.com/hc/en-us/requests/new) to have them generated for you. You must have _Admin_ privileges or an access token created by a member with _Admin_ privileges in order to be able to use this feature. `redirectUri`s must be absolute URIs that conform to the https URI scheme. If you wish to register a client with a different URI scheme, please contact LaunchDarkly Support. - name: Persistent store integrations (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. ### Persistent store integrations Persistent store integrations, also called "big segment" store integrations, are required when you use a server-side SDK and big segments. You can use the persistent store integrations API endpoints to manage these integrations. > ### Synced segments and larger list-based segments are an Enterprise feature > > Segments synced from external tools and larger list-based segments with more than 15,000 entries are the two kinds of "big segment." LaunchDarkly uses different implementations for different types of segments so that all of your segments have good performance. > > These segments are available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). [Segments synced from external tools](/home/flags/synced-segments) and [larger list-based segments](/home/flags/list-based-segments) are the two kinds of big segment. If you are using server-side SDKs, these segments require a persistent store within your infrastructure. LaunchDarkly keeps the persistent store up to date and consults it during flag evaluation. You need either a persistent store integration or a [Relay Proxy](/sdk/relay-proxy) to support these segments. The persistent store integrations API lets you manage the persistent store integrations. To learn more about segments, read [Segments](/home/flags/segments) and [Segment configuration](/home/flags/segment-config). Several of the endpoints in the persistent store integrations API require an integration ID. The integration ID is returned as part of the [Create big segment store integration](/api/persistent-store-integrations-beta/create-big-segment-store-integration) response, in the `_id` field. It is also returned as part of the [List all big segment store integrations](/api/persistent-store-integrations-beta/list-all-big-segment-store-integrations) response, in the `_id` field of each element in the `items` array. You can find other APIs for working with big segments under [Segments](/api/segments). - name: Projects description: > Projects allow you to manage multiple different software projects under one LaunchDarkly account. Each project has its own unique set of environments and feature flags. To learn more, read [Projects](/home/account/project). Using the projects API, you can list, create, and manage projects. - name: Relay Proxy configurations description: > > ### Relay Proxy automatic configuration is an Enterprise feature > > Relay Proxy automatic configuration is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). The Relay Proxy automatic configuration API provides access to all resources related to relay tokens. To learn more, read [Automatic configuration](/sdk/relay-proxy/automatic-configuration). Several of the endpoints in the Relay Proxy automatic configuration API require a configuration ID. The Relay Proxy configuration ID is returned as part of the [Create a new Relay Proxy config](/api/relay-proxy-configurations/create-a-new-relay-proxy-config) and [List Relay Proxy configs](/api/relay-proxy-configurations/list-relay-proxy-configs) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. - name: Release pipelines (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Release pipelines standardize and automate the release process for feature flags across a series of phases, where each phase consists of one or more environments and audiences. Each phase can use an immediate or guarded rollout to a designated audience, and can require approvals for selected environments. You can use release pipelines to ensure that you correctly roll out a flag in one environment before moving on to the next. To learn more, read [Release pipelines](/home/releases/release-pipelines). Use the release pipelines API to view, create, update, and delete release pipelines. You can also use this API to view the progress of all ongoing releases across all flags in a project for a given release pipeline. ### Creating releases and updating release phases When you add a flag to a release pipeline, you create a new "release" to automate that flag's progress through phases in the pipeline. Use the related [releases API](/api/releases) to create a new release, or to view or update a release for a given flag. For example, you can use the releases API to add a flag to an existing release pipeline, or to start the next phase of a flag's ongoing release. - name: Release policies (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Release policies let you specify your preferred rollout method for a given set of environments. - name: Releases (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. Release pipelines standardize and automate the release process for feature flags across a series of phases, where each phase consists of one or more environments and audiences. When you add a flag to an existing release pipeline, you create a "release" to automate that flag's progress through the pipeline. Use the releases API to add a flag to an existing release pipeline, or to monitor or update an ongoing release for a flag. Updating an ongoing release generally involves the following steps: 1. Obtain the release phases associated with the release. The `phases` field provides an ordered list of all pipeline phases associated with the flag's release. `phases` is returned in the response when you [Create a new release for a flag](/api/releases-beta/create-a-new-release-for-flag) or [Get the release for a flag](/api/releases-beta/get-release-for-flag). 2. Determine the `_id` of the phase you want to start. Release pipeline phases take place in their configured order, so find the first incomplete, unstarted phase in the `phases` list. For example, in a newly-created release the first phase in the `phases` list has both the `complete` and `started` fields set to `false`. 3. Use the phase `_id` value with the [Update phase status for release](/api/releases-beta/update-phase-status-for-release) endpoint to start the release phase. At a minimum, you must provide `{"status": active}` in the request object to start a pipeline phase. If the phase requires approvals or guarded rollouts, provide the additional required information in the `audiences` list. ### Configuring release pipelines Use the related [release pipelines API](/api/release-pipelines) to view, create, update, and delete release pipelines, or to view the progress of all ongoing releases across all flags in a project for a given release pipeline. - name: Scheduled changes description: > > ### Scheduled flag changes is an Enterprise feature > > Scheduled flag changes is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). You can schedule flag targeting rule changes to take place at a selected time. You may schedule multiple changes for a single flag with each change having a different `ExecutionDate`. To learn more, read [Scheduled flag changes](/home/releases/scheduled-changes). Several endpoints in the scheduled changes API require an existing scheduled change ID. This ID is returned in the `_id` field from the [Create scheduled changes workflow](/api/scheduled-changes/create-scheduled-changes-workflow) response, or in the `_id` field of each element in the `items` array from the [List scheduled changes](/api/scheduled-changes/list-scheduled-changes) response. - name: SDK Keys (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The SDK keys API lets you create, retrieve, and manage additional server-side and mobile SDK keys for your environments. To learn more, read [SDK keys](/sdk/concepts/client-side-server-side#keys-and-credentials). - name: Segments description: > > ### Synced segments and larger list-based segments are an Enterprise feature > > This section documents endpoints for rule-based, list-based, and synced segments. > > A "big segment" is a segment that is either a synced segment, or a list-based segment with more than 15,000 entries that includes only one targeted context kind. LaunchDarkly uses different implementations for different types of segments so that all of your segments have good performance. > > In the segments API, a big segment is indicated by the `unbounded` field being set to `true`. > > These segments are available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). Segments are groups of contexts that you can use to manage flag targeting behavior in bulk. LaunchDarkly supports: * rule-based segments, which let you target groups of contexts individually or by attribute, * list-based segments, which let you target individual contexts or uploaded lists of contexts, and * synced segments, which let you target groups of contexts backed by an external data store. To learn more, read [Segments](/home/flags/segments). The segments API allows you to list, create, modify, and delete segments programmatically. You can find other APIs for working with big segments under [Persistent store integrations (beta)](/api/persistent-store-config). - name: Tags description: > Tags are simple strings that you can attach to most resources in LaunchDarkly. Tags are useful for grouping resources into a set that you can name in a resource specifier. To learn more, read [Custom role concepts](/home/account/roles/role-concepts#tags). Using the tags API, you can list existing tags for resources. - name: Teams description: > > ### Teams is an Enterprise feature > > Teams is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). A team is a group of members in your LaunchDarkly account. Members of the team have access to various resources in LaunchDarkly, such as projects or flags, based on the role or roles you assign to the team. To learn more, read [Teams](/home/account/teams). The Teams API allows you to create, read, update, and delete a team. Several of the endpoints in the Teams API require one or more member IDs. The member ID is returned as part of the [List account members](/api/account-members/list-account-members) response. It is the `_id` field of each element in the `items` array. - name: Teams (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. > ### Teams is an Enterprise feature > > Teams is available to customers on an Enterprise plan. To learn more, [read about our pricing](https://launchdarkly.com/pricing/). To upgrade your plan, [contact Sales](https://launchdarkly.com/contact-sales/). A team is a group of members in your LaunchDarkly account. A team can have maintainers who are able to add and remove team members. It also can have custom roles assigned to it that allows shared access to those roles for all team members. To learn more, read [Teams](/home/account/teams). - name: User settings description: > > ### Contexts are now available > > After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use [Contexts](/api/contexts) instead of the user settings API. To learn more, read [Contexts](/home/flags/contexts). LaunchDarkly's user settings API provides a picture of all feature flags and their current values for a specific user. This gives you instant visibility into how a particular user experiences your site or application. To learn more, read [View and manage contexts](/home/flags/context-attributes#view-and-manage-context-attributes). You can also use the user settings API to assign a user to a specific variation for any feature flag. - name: Users description: > > ### Contexts are now available > > After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use [Contexts](/api/contexts) instead of these endpoints. To learn more, read [Contexts](/home/flags/contexts). LaunchDarkly creates a record for each user passed in to `variation` calls. This record powers the autocomplete functionality on the feature flag dashboard, as well as the Users page. To learn more, read [Contexts](/home/flags/contexts). LaunchDarkly also offers an API that lets you tap into this data. You can use the users API to see what user data is available to LaunchDarkly, as well as determine which flag values a user will receive. You can also explicitly set which flag value a user will receive via this API. Users are always scoped within a project and environment. In other words, each environment has its own set of user records. - name: Views (beta) description: > > ### This feature is in beta > > To use this feature, pass in a header including the `LD-API-Version` key with value set to `beta`. Use this header with each call. To learn more, read [Beta resources](/api/overview#beta-resources). > > Resources that are in beta are still undergoing testing and development. They may change without notice, including becoming backwards incompatible. The views API allows you to create, retrieve, and edit views, and link other resources to views. A view is a resource in LaunchDarkly that you can use to logically group other resources within a project, such as flags or segments. For example, views let you restrict access to sets of flags, so that members of your organization can focus on just the flags they work with. To learn more, read [Views](/home/account/views). - name: Webhooks description: > The webhooks API lets you build your own integrations that subscribe to activities in LaunchDarkly. When you generate an activity in LaunchDarkly, such as when you change a flag or you create a project, LaunchDarkly sends an HTTP POST payload to the webhook's URL. Use webhooks to update external issue trackers, update support tickets, notify customers of new feature rollouts, and more. Several of the endpoints in the webhooks API require a webhook ID. The webhook ID is returned as part of the [Creates a webhook](/api/webhooks/creates-a-webhook) and [List webhooks](/api/webhooks/list-webhooks) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. ## Designating the payload The webhook payload is identical to an audit log entry. To learn more, read [Get audit log entry](/api/audit-log/get-audit-log-entry). Here's a sample payload: > ### Webhook delivery order > > Webhooks may not be delivered in chronological order. We recommend using the payload's "date" field as a timestamp to reorder webhooks as they are received. ```json { "_links": { "canonical": { "href": "/api/v2/projects/alexis/environments/test", "type": "application/json" }, "parent": { "href": "/api/v2/auditlog", "type": "application/json" }, "self": { "href": "/api/v2/auditlog/57c0a8e29969090743529965", "type": "application/json" }, "site": { "href": "/settings#/projects", "type": "text/html" } }, "_id": "57c0a8e29969090743529965", "date": 1472243938774, "accesses": [ { "action": "updateName", "resource": "proj/alexis:env/test" } ], "kind": "environment", "name": "Testing", "description": "- Changed the name from ~~Test~~ to *Testing*", "member": { "_links": { "parent": { "href": "/internal/account/members", "type": "application/json" }, "self": { "href": "/internal/account/members/548f6741c1efad40031b18ae", "type": "application/json" } }, "_id": "548f6741c1efad40031b18ae", "email": "ariel@acme.com", "firstName": "Ariel", "lastName": "Flores" }, "titleVerb": "changed the name of", "title": "[Ariel Flores](mailto:ariel@acme.com) changed the name of [Testing](https://app.launchdarkly.com/settings#/projects)", "target": { "_links": { "canonical": { "href": "/api/v2/projects/alexis/environments/test", "type": "application/json" }, "site": { "href": "/settings#/projects", "type": "text/html" } }, "name": "Testing", "resources": ["proj/alexis:env/test"] } } ``` ## Signing the webhook Optionally, you can define a `secret` when you create a webhook. If you define the secret, the webhook `POST` request will include an `X-LD-Signature header`, whose value will contain an HMAC SHA256 hex digest of the webhook payload, using the `secret` as the key. Compute the signature of the payload using the same shared secret in your code to verify that the webhook was triggered by LaunchDarkly. ## Understanding connection retries If LaunchDarkly receives a non-`2xx` response to a webhook `POST`, it will retry the delivery one time. Webhook delivery is not guaranteed. If you build an integration on webhooks, make sure it is tolerant of delivery failures. - name: Workflow templates description: > > ### Workflows are in maintenance mode > > The workflows feature is in maintenance mode, and is planned for future deprecation at a date not yet specified. We will work with existing customers using workflows to migrate to a replacement solution when deprecation occurs. Workflow templates allow you to define a set of workflow stages that you can use as a starting point for new workflows. You can create these workflows for any flag in any environment and any project, and you can create as many workflows as you like from a given template. You can create workflow templates in two ways: * by specifying the desired stages, using the `stages` property of the request body * by specifying an existing workflow to save as a template, using the `workflowId` property of the request body You can use templates to create a workflow in any project, environment, or flag. However, when you create a template, you must specify a particular project, environment, and flag. This means that when you create a template using the `stages` property, you must also include `projectKey`, `environmentKey`, and `flagKey` properties in the request body. When you create a template from an existing workflow, it will use the project, environment, and flag of the existing workflow, so those properties can be omitted from the request body. To learn more, read [Workflows documentation](/home/releases/workflows) and [Workflows API documentation](/api/workflows). - name: Workflows description: > > ### Workflows are in maintenance mode > > The workflows feature is in maintenance mode, and is planned for future deprecation at a date not yet specified. We will work with existing customers using workflows to migrate to a replacement solution when deprecation occurs. A workflow is a set of actions that you can schedule in advance to make changes to a feature flag at a future date and time. You can also include approval requests at different stages of a workflow. To learn more, read [Workflows](/home/releases/workflows). The actions supported are as follows: - Turning targeting `ON` or `OFF` - Setting the default variation - Adding targets to a given variation - Creating a rule to target by segment - Modifying the rollout percentage for rules You can create multiple stages of a flag release workflow. Unique stages are defined by their conditions: either approvals and/or scheduled changes. Several of the endpoints in the workflows API require a workflow ID or one or more member IDs. The workflow ID is returned as part of the [Create workflow](/api/workflows/create-workflow) and [Get workflows](/api/workflows/get-workflows) responses. It is the `_id` field, or the `_id` field of each element in the `items` array. The member ID is returned as part of the [List account members](/api/account-members/list-account-members) response. It is the `_id` field of each element in the `items` array. - name: Other description: | Other requests available in the LaunchDarkly API. paths: /api/v2/flags/{projectKey}: get: tags: - Feature flags summary: List feature flags description: > Get a list of all feature flags in the given project. You can include information specific to different environments by adding `env` query parameter. For example, setting `env=production` adds configuration details about your production environment to the response. You can also filter feature flags by tag with the `tag` query parameter. > #### Recommended use > > This endpoint can return a large amount of information. We recommend using some or all of these query parameters to decrease response time and overall payload size: `limit`, `env`, `query`, and `filter=creationDate`. ### Filtering flags You can filter on certain fields using the `filter` query parameter. For example, setting `filter=query:dark-mode,tags:beta+test` matches flags with the string `dark-mode` in their key or name, ignoring case, which also have the tags `beta` and `test`. The `filter` query parameter supports the following arguments: | Filter argument | Description | Example | |-----------------------|-------------|----------------------| | `applicationEvaluated` | A string. It filters the list to flags that are evaluated in the application with the given key. | `filter=applicationEvaluated:com.launchdarkly.cafe` | | `archived` | (deprecated) A boolean value. It filters the list to archived flags. | Use `filter=state:archived` instead | | `contextKindsEvaluated` | A `+`-separated list of context kind keys. It filters the list to flags which have been evaluated in the past 30 days for all of the context kinds in the list. | `filter=contextKindsEvaluated:user+application` | | `codeReferences.max` | An integer value. Use `0` to return flags that do not have code references. | `filter=codeReferences.max:0` | | `codeReferences.min` | An integer value. Use `1` to return flags that do have code references. | `filter=codeReferences.min:1` | | `creationDate` | An object with an optional `before` field whose value is Unix time in milliseconds. It filters the list to flags created before the date. | `filter=creationDate:{"before":1690527600000}` | | `evaluated` | An object that contains a key of `after` and a value in Unix time in milliseconds. It filters the list to all flags that have been evaluated since the time you specify, in the environment provided. This filter requires the `filterEnv` filter. | `filter=evaluated:{"after":1690527600000},filterEnv:production` | | `filterEnv` | A valid environment key. You must use this field for filters that are environment-specific. If there are multiple environment-specific filters, you only need to include this field once. | `filter=evaluated:{"after": 1590768455282},filterEnv:production` | | `guardedRollout` | A string, one of `any`, `monitoring`, `regressed`, `rolledBack`, `completed`, `archived`. It filters the list to flags that are part of guarded rollouts. | `filter=guardedRollout:monitoring` | | `hasExperiment` | A boolean value. It filters the list to flags that are used in an experiment. | `filter=hasExperiment:true` | | `maintainerId` | A valid member ID. It filters the list to flags that are maintained by this member. | `filter=maintainerId:12ab3c45de678910abc12345` | | `maintainerTeamKey` | A string. It filters the list to flags that are maintained by the team with this key. | `filter=maintainerTeamKey:example-team-key` | | `query` | A string. It filters the list to flags that include the specified string in their key or name. It is not case sensitive. | `filter=query:example` | | `releasePipeline` | A release pipeline key. It filters the list to flags that are either currently active in the release pipeline or have completed the release pipeline. | `filter=releasePipeline:default-release-pipeline` | | `state` | A string, either `live`, `deprecated`, or `archived`. It filters the list to flags in this state. | `filter=state:archived` | | `sdkAvailability` | A string, one of `client`, `mobile`, `anyClient`, `server`. Using `client` filters the list to flags whose client-side SDK availability is set to use the client-side ID. Using `mobile` filters to flags set to use the mobile key. Using `anyClient` filters to flags set to use either the client-side ID or the mobile key. Using `server` filters to flags set to use neither, that is, to flags only available in server-side SDKs. | `filter=sdkAvailability:client` | | `tags` | A `+`-separated list of tags. It filters the list to flags that have all of the tags in the list. | `filter=tags:beta+test` | | `type` | A string, either `temporary` or `permanent`. It filters the list to flags with the specified type. | `filter=type:permanent` | The documented values for the `filter` query are prior to URL encoding. For example, the `+` in `filter=tags:beta+test` must be encoded to `%2B`. By default, this endpoint returns all flags. You can page through the list with the `limit` parameter and by following the `first`, `prev`, `next`, and `last` links in the returned `_links` field. These links will not be present if the pages they refer to don't exist. For example, the `first` and `prev` links will be missing from the response on the first page. ### Sorting flags You can sort flags based on the following fields: - `creationDate` sorts by the creation date of the flag. - `key` sorts by the key of the flag. - `maintainerId` sorts by the flag maintainer. - `name` sorts by flag name. - `tags` sorts by tags. - `targetingModifiedDate` sorts by the date that the flag's targeting rules were last modified in a given environment. It must be used with `env` parameter and it can not be combined with any other sort. If multiple `env` values are provided, it will perform sort using the first one. For example, `sort=-targetingModifiedDate&env=production&env=staging` returns results sorted by `targetingModifiedDate` for the `production` environment. - `type` sorts by flag type All fields are sorted in ascending order by default. To sort in descending order, prefix the field with a dash ( - ). For example, `sort=-name` sorts the response by flag name in descending order. ### Expanding response LaunchDarkly supports the `expand` query param to include additional fields in the response, with the following fields: - `codeReferences` includes code references for the feature flag - `evaluation` includes evaluation information within returned environments, including which context kinds the flag has been evaluated for in the past 30 days - `migrationSettings` includes migration settings information within the flag and within returned environments. These settings are only included for migration flags, that is, where `purpose` is `migration`. For example, `expand=evaluation` includes the `evaluation` field in the response. ### Migration flags For migration flags, the cohort information is included in the `rules` property of a flag's response, and default cohort information is included in the `fallthrough` property of a flag's response. To learn more, read [Migration Flags](/home/flags/migration). operationId: getFeatureFlags parameters: - name: projectKey in: path description: The project key required: true schema: type: string format: string description: The project key - name: env in: query description: Filter configurations by environment schema: type: string format: string description: Filter configurations by environment - name: tag in: query description: Filter feature flags by tag schema: type: string format: string description: Filter feature flags by tag - name: limit in: query description: The number of feature flags to return. Defaults to 20. schema: type: integer format: int64 description: The number of feature flags to return. Defaults to 20. - name: offset in: query description: >- Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query `limit`. schema: type: integer format: int64 description: >- Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query `limit`. - name: archived in: query description: >- Deprecated, use `filter=archived:true` instead. A boolean to filter the list to archived flags. When this is absent, only unarchived flags will be returned deprecated: true schema: type: boolean description: >- Deprecated, use `filter=archived:true` instead. A boolean to filter the list to archived flags. When this is absent, only unarchived flags will be returned - name: summary in: query description: >- By default, flags do _not_ include their lists of prerequisites, targets, or rules for each environment. Set `summary=0` and include the `env` query parameter to include these fields for each flag returned. schema: type: boolean description: >- By default, flags do _not_ include their lists of prerequisites, targets, or rules for each environment. Set `summary=0` and include the `env` query parameter to include these fields for each flag returned. - name: filter in: query description: >- A comma-separated list of filters. Each filter is of the form field:value. Read the endpoint description for a full list of available filter fields. schema: type: string format: string description: >- A comma-separated list of filters. Each filter is of the form field:value. Read the endpoint description for a full list of available filter fields. - name: sort in: query description: >- A comma-separated list of fields to sort by. Fields prefixed by a dash ( - ) sort in descending order. Read the endpoint description for a full list of available sort fields. schema: type: string format: string description: >- A comma-separated list of fields to sort by. Fields prefixed by a dash ( - ) sort in descending order. Read the endpoint description for a full list of available sort fields. - name: compare in: query description: >- Deprecated, unavailable in API version `20240415`. A boolean to filter results by only flags that have differences between environments. deprecated: true schema: type: boolean description: >- Deprecated, unavailable in API version `20240415`. A boolean to filter results by only flags that have differences between environments. - name: expand in: query description: >- A comma-separated list of fields to expand in the response. Supported fields are explained above. schema: type: string format: string description: >- A comma-separated list of fields to expand in the response. Supported fields are explained above. responses: '200': description: Global flags collection response content: application/json: schema: $ref: '#/components/schemas/FeatureFlags' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/InvalidRequestErrorRep' '401': description: Invalid access token content: application/json: schema: $ref: '#/components/schemas/UnauthorizedErrorRep' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorRep' '404': description: Invalid resource identifier content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorRep' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/RateLimitedErrorRep' components: schemas: FeatureFlags: type: object required: - items - _links properties: items: type: array description: An array of feature flags items: $ref: '#/components/schemas/FeatureFlag' _links: type: object additionalProperties: $ref: '#/components/schemas/Link' description: The location and content type of related resources example: self: href: /api/v2/flags/default type: application/json totalCount: type: integer description: The total number of flags example: 1 totalCountWithDifferences: type: integer description: >- The number of flags that have differences between environments. Only shown when query parameter compare is true. example: 0 InvalidRequestErrorRep: type: object required: - code - message properties: code: type: string description: Specific error code encountered example: invalid_request message: type: string description: Description of the error example: Invalid request body UnauthorizedErrorRep: type: object required: - code - message properties: code: type: string description: Specific error code encountered example: unauthorized message: type: string description: Description of the error example: Invalid access token ForbiddenErrorRep: type: object required: - code - message properties: code: type: string description: Specific error code encountered example: forbidden message: type: string description: Description of the error example: Forbidden. Access to the requested resource was denied. NotFoundErrorRep: type: object required: - code - message properties: code: type: string description: Specific error code encountered example: not_found message: type: string description: Description of the error example: Invalid resource identifier RateLimitedErrorRep: type: object required: - code - message properties: code: type: string description: Specific error code encountered example: rate_limited message: type: string description: Description of the error example: You've exceeded the API rate limit. Try again later. FeatureFlag: type: object required: - name - kind - key - _version - creationDate - variations - temporary - tags - _links - experiments - customProperties - archived properties: name: type: string description: A human-friendly name for the feature flag example: My Flag kind: type: string description: Kind of feature flag example: boolean enum: - boolean - multivariate description: type: string description: Description of the feature flag example: This flag controls the example widgets key: type: string description: A unique key used to reference the flag in your code example: flag-key-123abc _version: type: integer description: Version of the feature flag example: 1 creationDate: $ref: '#/components/schemas/UnixMillis' description: Timestamp of flag creation date example: '1494437420312' includeInSnippet: type: boolean description: >- Deprecated, use clientSideAvailability. Whether this flag should be made available to the client-side JavaScript SDK example: true deprecated: true clientSideAvailability: $ref: '#/components/schemas/ClientSideAvailability' description: Which type of client-side SDKs the feature flag is available to example: '{"usingMobileKey":true,"usingEnvironmentId":false}' variations: type: array description: An array of possible variations for the flag items: $ref: '#/components/schemas/Variation' example: - _id: e432f62b-55f6-49dd-a02f-eb24acf39d05 value: true - _id: a00bf58d-d252-476c-b915-15a74becacb4 value: false temporary: type: boolean description: Whether the flag is a temporary flag example: true tags: type: array description: Tags for the feature flag items: type: string example: - example-tag _links: type: object additionalProperties: $ref: '#/components/schemas/Link' description: The location and content type of related resources example: parent: href: /api/v2/flags/my-project type: application/json self: href: /api/v2/flags/my-project/my-flag type: application/json maintainerId: type: string description: Associated maintainerId for the feature flag example: 569f183514f4432160000007 _maintainer: $ref: '#/components/schemas/MemberSummary' description: Associated maintainer member info for the feature flag maintainerTeamKey: type: string description: The key of the associated team that maintains this feature flag example: team-1 _maintainerTeam: $ref: '#/components/schemas/MaintainerTeam' description: Associated maintainer team info for the feature flag goalIds: type: array description: Deprecated, use experiments instead items: type: string example: [] deprecated: true experiments: $ref: '#/components/schemas/ExperimentInfoRep' description: Experimentation data for the feature flag example: '{"baselineIdx": 0,"items": []}' customProperties: $ref: '#/components/schemas/CustomProperties' description: >- Metadata attached to the feature flag, in the form of the property key associated with a name and array of values for the metadata to associate with this flag. Typically used to store data related to an integration. example: '{"jira.issues":{"name":"Jira issues","value":["is-123","is-456"]}}' archived: type: boolean description: Boolean indicating if the feature flag is archived example: false archivedDate: $ref: '#/components/schemas/UnixMillis' description: If archived is true, date of archive example: '1494437420312' deprecated: type: boolean description: Boolean indicating if the feature flag is deprecated example: false deprecatedDate: $ref: '#/components/schemas/UnixMillis' description: If deprecated is true, date of deprecation example: '1494437420312' defaults: $ref: '#/components/schemas/Defaults' description: >- The indices, from the array of variations, for the variations to serve by default when targeting is on and when targeting is off. These variations will be used for this flag in new environments. If omitted, the first and last variation will be used. example: '{"onVariation":0,"offVariation":1}' _purpose: type: string migrationSettings: $ref: '#/components/schemas/FlagMigrationSettingsRep' description: Migration-related settings for the flag stale: $ref: '#/components/schemas/StaleFlagData' description: Information about a flag's stale states environments: type: object additionalProperties: $ref: '#/components/schemas/FeatureFlagConfig' description: >- Details on the environments for this flag. Only returned if the request is filtered by environment, using the filterEnv query parameter. example: my-environment: _environmentName: My Environment _site: href: /default/my-environment/features/client-side-flag type: text/html _summary: prerequisites: 0 variations: '0': contextTargets: 1 isFallthrough: true nullRules: 0 rules: 0 targets: 1 '1': isOff: true nullRules: 0 rules: 0 targets: 0 archived: false contextTargets: - contextKind: device values: - device-key-123abc variation: 0 fallthrough: variation: 0 lastModified: 1627071171347 offVariation: 1 'on': false prerequisites: [] rules: [] salt: 61eddeadbeef4da1facecafe3a60a397 sel: 810edeadbeef4844facecafe438f2999492 targets: - contextKind: user values: - user-key-123abc variation: 0 trackEvents: false trackEventsFallthrough: false version: 1 Link: type: object properties: href: type: string type: type: string UnixMillis: type: integer format: int64 ClientSideAvailability: type: object properties: usingMobileKey: type: boolean usingEnvironmentId: type: boolean Variation: type: object required: - value properties: _id: type: string description: The ID of the variation. Leave empty when you are creating a flag. value: description: >- The value of the variation. For boolean flags, this must be true or false. For multivariate flags, this may be a string, number, or JSON object. valueHash: type: string description: >- A deterministic hash of the canonicalized variation value. Computed server-side; ignored if supplied in request bodies. description: type: string description: >- Description of the variation. Defaults to an empty string, but is omitted from the response if not set. name: type: string description: >- A human-friendly name for the variation. Defaults to an empty string, but is omitted from the response if not set. MemberSummary: type: object required: - _links - _id - role - email properties: _links: type: object additionalProperties: $ref: '#/components/schemas/Link' description: The location and content type of related resources example: self: href: /api/v2/members/569f183514f4432160000007 type: application/json _id: type: string description: The member's ID example: 569f183514f4432160000007 firstName: type: string description: The member's first name example: Ariel lastName: type: string description: The member's last name example: Flores role: type: string description: >- The member's base role. If the member has no additional roles, this role will be in effect. example: admin email: type: string description: The member's email address example: ariel@acme.com MaintainerTeam: type: object required: - key - name properties: key: type: string description: The key of the maintainer team example: team-key-123abc name: type: string description: A human-friendly name for the maintainer team example: Example team _links: type: object additionalProperties: $ref: '#/components/schemas/Link' description: The location and content type of related resources example: parent: href: /api/v2/teams type: application/json roles: href: /api/v2/teams/example-team/roles type: application/json self: href: /api/v2/teams/example-team type: application/json ExperimentInfoRep: type: object required: - baselineIdx - items properties: baselineIdx: type: integer items: type: array items: $ref: '#/components/schemas/LegacyExperimentRep' CustomProperties: type: object additionalProperties: $ref: '#/components/schemas/customProperty' Defaults: type: object required: - onVariation - offVariation properties: onVariation: type: integer description: >- The index, from the array of variations for this flag, of the variation to serve by default when targeting is on. example: 0 offVariation: type: integer description: >- The index, from the array of variations for this flag, of the variation to serve by default when targeting is off. example: 1 FlagMigrationSettingsRep: type: object properties: contextKind: type: string description: >- The context kind targeted by this migration flag. Only applicable for six-stage migrations. example: device stageCount: type: integer description: The number of stages for this migration flag example: 6 StaleFlagData: type: object properties: readyForCodeRemoval: type: boolean description: Whether the flag is ready for code removal readyToArchive: type: boolean description: Whether the flag is ready to be archived cleanupId: type: string description: >- If a third-party system helps clean up the flag, the ID from that system FeatureFlagConfig: type: object required: - 'on' - archived - salt - sel - lastModified - version - _site - _environmentName - trackEvents - trackEventsFallthrough properties: 'on': type: boolean description: Whether the flag is on archived: type: boolean description: Boolean indicating if the feature flag is archived salt: type: string sel: type: string lastModified: $ref: '#/components/schemas/UnixMillis' description: Timestamp of when the flag configuration was most recently modified version: type: integer description: Version of the feature flag targets: type: array description: >- An array of the individual targets that will receive a specific variation based on their key. Individual targets with a context kind of 'user' are included here. items: $ref: '#/components/schemas/Target' contextTargets: type: array description: >- An array of the individual targets that will receive a specific variation based on their key. Individual targets with context kinds other than 'user' are included here. items: $ref: '#/components/schemas/Target' rules: type: array description: >- An array of the rules for how to serve a variation to specific targets based on their attributes items: $ref: '#/components/schemas/Rule' fallthrough: $ref: '#/components/schemas/VariationOrRolloutRep' description: >- Details on the variation or rollout to serve as part of the flag's default rule offVariation: type: integer description: The ID of the variation to serve when the flag is off prerequisites: type: array description: >- An array of the prerequisite flags and their variations that are required before this flag takes effect items: $ref: '#/components/schemas/Prerequisite' _site: $ref: '#/components/schemas/Link' description: >- A link to access the flag configuration in the LaunchDarkly UI. The href is an opaque URL; do not parse or rely on its structure. Use resource keys or _links for programmatic navigation. _access: $ref: '#/components/schemas/Access' description: Details on the allowed and denied actions for this flag _environmentName: type: string description: The environment name trackEvents: type: boolean description: >- Whether the SDK sends a detailed event for every evaluation of this flag, across all rules, instead of only summary counts. Required for Data Export, but doesn't enable Data Export on its own. trackEventsFallthrough: type: boolean description: >- Whether the SDK sends a detailed event for every evaluation of this flag's default rule, instead of only summary counts. Required for Data Export, but doesn't enable Data Export on its own. _debugEventsUntilDate: $ref: '#/components/schemas/UnixMillis' _summary: $ref: '#/components/schemas/FlagSummary' description: A summary of the prerequisites and variations for this flag evaluation: $ref: '#/components/schemas/FlagConfigEvaluation' description: Evaluation information for the flag migrationSettings: $ref: '#/components/schemas/FlagConfigMigrationSettingsRep' description: Migration-related settings for the flag configuration LegacyExperimentRep: type: object properties: metricKey: type: string example: my-metric _metric: $ref: '#/components/schemas/MetricListingRep' environments: type: array items: type: string example: - production - test - my-environment _environmentSettings: type: object additionalProperties: $ref: '#/components/schemas/ExperimentEnvironmentSettingRep' customProperty: type: object required: - name - value properties: name: type: string description: The name of the custom property of this type. example: Jira issues value: type: array description: >- An array of values for the custom property data to associate with this flag. items: type: string example: - is-123 - is-456 Target: type: object required: - values - variation properties: values: type: array description: >- A list of the keys for targets that will receive this variation because of individual targeting items: type: string variation: type: integer description: >- The index, from the array of variations for this flag, of the variation to serve this list of targets contextKind: type: string description: The context kind of the individual target Rule: type: object required: - clauses - trackEvents properties: _id: type: string description: The flag rule ID disabled: type: boolean description: Whether the rule is disabled variation: type: integer description: >- The index of the variation, from the array of variations for this flag rollout: $ref: '#/components/schemas/Rollout' description: Details on the percentage rollout, if it exists clauses: type: array description: >- An array of clauses used for individual targeting based on attributes items: $ref: '#/components/schemas/Clause' trackEvents: type: boolean description: >- Whether the SDK sends a detailed event for every evaluation of this rule, instead of only summary counts. Required for Data Export, but doesn't enable Data Export on its own. description: type: string description: The rule description ref: type: string VariationOrRolloutRep: type: object properties: variation: type: integer description: >- The index of the variation, from the array of variations for this flag rollout: $ref: '#/components/schemas/Rollout' description: Details on the percentage rollout, if it exists Prerequisite: type: object required: - key - variation properties: key: type: string variation: type: integer Access: type: object required: - denied - allowed properties: denied: type: array items: $ref: '#/components/schemas/AccessDenied' allowed: type: array items: $ref: '#/components/schemas/AccessAllowedRep' FlagSummary: type: object required: - variations - prerequisites properties: variations: $ref: '#/components/schemas/AllVariationsSummary' description: A summary of the variations for this flag prerequisites: type: integer description: The number of prerequisites for this flag FlagConfigEvaluation: type: object properties: contextKinds: type: array items: type: string FlagConfigMigrationSettingsRep: type: object properties: checkRatio: type: integer MetricListingRep: type: object required: - _id - _versionId - key - name - kind - _links - tags - _creationDate - dataSource properties: experimentCount: type: integer description: The number of experiments using this metric example: 0 metricGroupCount: type: integer description: The number of metric groups using this metric example: 0 activeExperimentCount: type: integer description: The number of active experiments using this metric example: 2 activeGuardedRolloutCount: type: integer description: The number of active guarded rollouts using this metric example: 1 _id: type: string description: The ID of this metric example: 5902deadbeef667524a01290 _versionId: type: string description: The version ID of the metric example: version-id-123abc _version: type: integer description: Version of the metric example: 1 key: type: string description: A unique key to reference the metric example: metric-key-123abc name: type: string description: A human-friendly name for the metric example: My metric kind: type: string description: The kind of event the metric tracks example: custom enum: - pageview - click - custom - trace _attachedFlagCount: type: integer description: The number of feature flags currently attached to this metric example: 0 _links: type: object additionalProperties: $ref: '#/components/schemas/Link' description: The location and content type of related resources example: parent: href: /api/v2/metrics/my-project type: application/json self: href: /api/v2/metrics/my-project/my-metric type: application/json _site: $ref: '#/components/schemas/Link' description: Details on how to access the metric in the LaunchDarkly UI example: '{"href":"/my-project/metrics/my-metric/details","type":"text/html"}' _access: $ref: '#/components/schemas/Access' description: Details on the allowed and denied actions for this metric tags: type: array description: Tags for the metric items: type: string example: [] _creationDate: $ref: '#/components/schemas/UnixMillis' description: Timestamp of when the metric was created example: '1628192791148' lastModified: $ref: '#/components/schemas/Modification' maintainerId: type: string description: The ID of the member who maintains this metric example: 569fdeadbeef1644facecafe _maintainer: $ref: '#/components/schemas/MemberSummary' description: Details on the member who maintains this metric example: >- {"_links":{"self":{"href":"/api/v2/members/569fdeadbeef1644facecafe","type":"application/json"}},"_id":"569fdeadbeef1644facecafe","firstName":"Ariel","lastName":"Flores","role":"owner","email":"ariel@acme.com"} description: type: string description: Description of the metric category: type: string description: The category of the metric example: Error monitoring isNumeric: type: boolean description: >- For custom and trace metrics, whether to track numeric changes in value against a baseline (true) or to track a conversion when an end user takes an action (false). example: true successCriteria: type: string description: For custom and trace metrics, the success criteria enum: - HigherThanBaseline - LowerThanBaseline unit: type: string description: For numeric custom and trace metrics, the unit of measure eventKey: type: string description: For custom metrics, the event key to use in your code example: Order placed randomizationUnits: type: array description: Deprecated, use analysisUnits instead. items: type: string example: - user deprecated: true analysisUnits: type: array description: An array of analysis units allowed for this metric. items: type: string example: - user filters: $ref: '#/components/schemas/Filter' description: >- The filters narrowing down the audience based on context attributes or event properties. example: >- {"type":"group","op":"and","values":[{"type":"contextAttribute","op":"in","contextKind":"user","attribute":"country","values":["JP"],"negate":false},{"type":"eventProperty","op":"in","attribute":"category","values":["magic-wands"],"negate":false}]} unitAggregationType: type: string description: The method by which multiple unit event values are aggregated example: average enum: - average - sum - count_distinct analysisType: type: string description: The method for analyzing metric events example: mean enum: - mean - percentile percentileValue: type: integer description: >- The percentile for the analysis method. An integer denoting the target percentile between 0 and 100. Required when analysisType is percentile. example: 95 eventDefault: $ref: '#/components/schemas/MetricEventDefaultRep' dataSource: $ref: '#/components/schemas/MetricDataSourceRefRep' lastSeen: $ref: '#/components/schemas/UnixMillis' description: Timestamp of most recent data for this metric, at one-hour fidelity archived: type: boolean description: Whether the metric version is archived archivedAt: $ref: '#/components/schemas/UnixMillis' description: Timestamp when the metric version was archived example: '1609459200000' selector: type: string description: For click metrics, the CSS selectors urls: $ref: '#/components/schemas/UrlMatchers' description: For click and pageview metrics, the target URLs example: '[{"kind":"exact","url":"https://www.example.com/page1"}]' windowStartOffset: type: integer format: int64 description: >- Not yet implemented - The start of the measurement window, in milliseconds relative to the unit's first exposure to a flag variation windowEndOffset: type: integer format: int64 description: >- Not yet implemented - The end of the measurement window, in milliseconds relative to the unit's first exposure to a flag variation winsorLowerPercentile: type: number description: >- Lower winsorization percentile, expressed as a percent in the open interval (0, 100). When both bounds are set, defines a two-sided clamp range. Otherwise lower-only winsorization. example: 1 winsorUpperPercentile: type: number description: >- Upper winsorization percentile, expressed as a percent in the open interval (0, 100). When both bounds are set, must be greater than winsorLowerPercentile. example: 99.5 winsorIncludeImputed: type: boolean description: >- When true, the percentile bound calculation includes imputed zeros. Only meaningful when at least one bound is set and the metric includes units that didn't send events. example: false traceQuery: type: string description: For trace metrics, the trace query to use for the metric. example: service.name = "checkout" traceValueLocation: type: string description: >- For trace metrics, the location in the trace to use for numeric values. example: duration unitAggregationField: type: string description: For count_distinct metrics, the column to count distinct values of denominator: $ref: '#/components/schemas/MetricDenominatorRep' description: For ratio metrics, the denominator event configuration ExperimentEnvironmentSettingRep: type: object properties: startDate: $ref: '#/components/schemas/UnixMillis' stopDate: $ref: '#/components/schemas/UnixMillis' enabledPeriods: type: array items: $ref: '#/components/schemas/ExperimentEnabledPeriodRep' Rollout: type: object required: - variations properties: variations: type: array items: $ref: '#/components/schemas/WeightedVariation' experimentAllocation: $ref: '#/components/schemas/ExperimentAllocationRep' seed: type: integer bucketBy: type: string contextKind: type: string Clause: type: object required: - attribute - op - values - negate properties: _id: type: string attribute: type: string op: $ref: '#/components/schemas/Operator' values: type: array items: {} contextKind: type: string negate: type: boolean AccessDenied: type: object required: - action - reason properties: action: $ref: '#/components/schemas/ActionIdentifier' reason: $ref: '#/components/schemas/AccessDeniedReason' AccessAllowedRep: type: object required: - action - reason properties: action: $ref: '#/components/schemas/ActionIdentifier' reason: $ref: '#/components/schemas/AccessAllowedReason' AllVariationsSummary: type: object additionalProperties: $ref: '#/components/schemas/VariationSummary' Modification: type: object properties: date: type: string format: date-time example: '2021-08-05T19:46:31.148082Z' Filter: type: object required: - type - op - values - negate properties: type: type: string description: Filter type. One of [contextAttribute, eventProperty, group] example: contextAttribute enum: - group - contextAttribute - eventProperty attribute: type: string description: >- If not a group node, the context attribute name or event property name to filter on example: country op: $ref: '#/components/schemas/Operator' description: The function to perform example: in values: type: array description: The context attribute / event property values or group member nodes items: {} example: - JP contextKind: type: string description: For context attribute filters, the context kind. example: user negate: type: boolean description: >- If set, then take the inverse of the operator. 'in' becomes 'not in'. example: false MetricEventDefaultRep: type: object properties: disabled: type: boolean description: >- Whether to disable defaulting missing unit events when calculating results. Defaults to false value: type: number description: >- The default value applied to missing unit events. Set to 0 when disabled is false. No other values are currently supported. example: 0 MetricDataSourceRefRep: type: object required: - key properties: key: type: string environmentKey: type: string _name: type: string _integrationKey: type: string UrlMatchers: items: $ref: '#/components/schemas/UrlMatcher' type: array MetricDenominatorRep: type: object properties: eventName: type: string description: The warehouse event column for the denominator isNumeric: type: boolean description: Whether the denominator aggregates a numeric value unitAggregationType: type: string description: How individual unit values are aggregated for the denominator unitAggregationField: type: string description: >- The column to count distinct values of; required when unitAggregationType is count_distinct valueColumn: type: string description: For a numeric denominator, the column holding the numeric value dataSource: $ref: '#/components/schemas/MetricDataSourceRefRep' description: >- The data source for the denominator events. Uses 'launchdarkly-hosted' for SDK-tracked events. filters: $ref: '#/components/schemas/Filter' description: Optional filters to narrow which denominator events are included windowStartOffset: type: integer format: int64 description: Start of the measurement window in milliseconds windowEndOffset: type: integer format: int64 description: End of the measurement window in milliseconds winsorLowerPercentile: type: number description: Lower winsorization percentile in the open interval (0, 100) winsorUpperPercentile: type: number description: Upper winsorization percentile in the open interval (0, 100) winsorIncludeImputed: type: boolean description: When true, the percentile bound calculation includes imputed zeros ExperimentEnabledPeriodRep: type: object properties: startDate: $ref: '#/components/schemas/UnixMillis' stopDate: $ref: '#/components/schemas/UnixMillis' WeightedVariation: type: object required: - variation - weight properties: variation: type: integer weight: type: integer _untracked: type: boolean ExperimentAllocationRep: type: object required: - defaultVariation - canReshuffle properties: defaultVariation: type: integer canReshuffle: type: boolean Operator: type: string ActionIdentifier: type: string AccessDeniedReason: type: object required: - effect properties: resources: type: array description: Resource specifier strings items: type: string example: - proj/*:env/*;qa_*:/flag/* notResources: type: array description: >- Targeted resources are the resources NOT in this list. The resources and notActions fields must be empty to use this field. items: type: string actions: type: array description: Actions to perform on a resource items: $ref: '#/components/schemas/ActionSpecifier' example: - '*' notActions: type: array description: >- Targeted actions are the actions NOT in this list. The actions and notResources fields must be empty to use this field. items: $ref: '#/components/schemas/ActionSpecifier' effect: type: string description: >- Whether this statement should allow or deny actions on the resources. example: allow enum: - allow - deny role_name: type: string AccessAllowedReason: type: object required: - effect properties: resources: type: array description: Resource specifier strings items: type: string example: - proj/*:env/*;qa_*:/flag/* notResources: type: array description: >- Targeted resources are the resources NOT in this list. The resources and notActions fields must be empty to use this field. items: type: string actions: type: array description: Actions to perform on a resource items: $ref: '#/components/schemas/ActionSpecifier' example: - '*' notActions: type: array description: >- Targeted actions are the actions NOT in this list. The actions and notResources fields must be empty to use this field. items: $ref: '#/components/schemas/ActionSpecifier' effect: type: string description: >- Whether this statement should allow or deny actions on the resources. example: allow enum: - allow - deny role_name: type: string VariationSummary: type: object required: - rules - nullRules - targets - contextTargets properties: rules: type: integer nullRules: type: integer targets: type: integer contextTargets: type: integer isFallthrough: type: boolean isOff: type: boolean rollout: type: integer bucketBy: type: string UrlMatcher: type: object additionalProperties: {} ActionSpecifier: type: string securitySchemes: ApiKey: type: apiKey in: header name: Authorization ````