Contexts

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 instance. You can view these in the LaunchDarkly user interface from the Contexts list, or use the Context APIs. To learn more, read Contexts.

LaunchDarkly provides APIs for you to:

  • retrieve contexts, context instances, and context attribute names and values
  • search for contexts or context instances
  • delete context instances
  • fetch context kinds
  • create and update context kinds

To learn more about context kinds, read Context kinds.

Contexts are always scoped within a project and an environment. Each environment has its own set of context instance records.

Several of the endpoints in the contexts API require a context instance ID or application ID. Both of these IDs are returned as part of the Search for context instances response. The context instance ID is the id field of each element in the items array. The application ID is the applicationId field of each element in the items array. 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.

Filtering contexts and context instances

When you search for contexts or context instances, you can filter on certain fields using the filter parameter 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 or context instances if any of the values in a field, which should be dates, are after the provided time. For example:

  • myField after "2022-09-21T19:03:15+00:00"

anyOf

Returns contexts or context instances if any of the values in a field match any of the values in the match value. For example:

  • myField anyOf [44]
  • myField anyOf ["phone","tablet"]
  • myField anyOf [true]"

before

Returns contexts or context instances if any of the values in a field, which should be dates, are before the provided time. For example:

  • myField before "2022-09-21T19:03:15+00:00"

contains

Returns contexts or context instances if all the match values are found in the list of values in this field. For example:

  • myListField contains 44
  • myListField contains ["phone","tablet"]
  • myListField contains true

equals

Returns contexts or context instances if there is an exact match on the entire field. For example:

  • myField equals 44
  • myField equals "device"
  • myField equals true
  • myField equals [1,2,3,4]
  • myField equals ["hello","goodbye"]

exists

Returns contexts or context instances if the field matches the specified existence. For example:

  • myField exists true
  • myField exists false
  • *.name exists true

notEquals

Returns contexts or context instances if there is not an exact match on the entire field. For example:

  • myField notEquals 44
  • myField notEquals "device"
  • myField notEquals true
  • myField notEquals [1,2,3,4]
  • myField notEquals ["hello","goodbye"]

startsWith

Returns contexts or context instances if the value in a field, which should be a singular string, begins with the provided substring. 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 or context instances where myField is not 0 and is not 1
  • myFirstField equals "device",(mySecondField equals "iPhone"|mySecondField equals "iPad") returns contexts or context instances where myFirstField is equal to "device" and mySecondField is equal to either "iPhone" or "iPad"

Supported fields and operators

You can only filter certain fields in contexts and context instances when using the filter parameter. Additionally, you can only filter some fields with certain operators.

When you search for contexts, the filter parameter supports the following fields and operators:

Field
Description Supported operators
applicationId An identifier representing the application where the LaunchDarkly SDK is running. equals, notEquals, anyOf
id Unique identifier for the context. equals, notEquals, anyOf
key The context key. equals, notEquals, anyOf, startsWith
kind The context kind. equals, notEquals, anyOf
kinds A list of all kinds found in the context. Supply a list of strings to the operator. equals, anyOf, contains
kindKey The kind and key for the context. They are joined with :, for example, user:user-key-abc123. equals, notEquals, anyOf
kindKeys A list of all kinds and keys found in the context. The kind and key are joined with :, for example, user:user-key-abc123. Supply a list of strings to the operator. equals, anyOf, contains
q A "fuzzy" search across context attribute values and the context key. Supply a string or list of strings to the operator. equals
name The name for the context. equals, notEquals, exists, anyOf, startsWith
<a kind>.<an attribute name> 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. You can use either a literal attribute name or a JSON path to specify the attribute. If you use a JSON path, then you must escape the / character, using ~1, and the ~ character, using ~0. For example, use user.job/title or user./job~1title to filter the /job/title field in a user context kind. If the field or value includes whitespace, it should be enclosed in double quotes. equals, notEquals, exists, startsWith, before, after.

When searching for context instances, the filter parameter supports the following fields and operators

Field
Description Supported operators
applicationId An identifier representing the application where the LaunchDarkly SDK is running. equals, notEquals, anyOf
id Unique identifier for the context instance. equals, notEquals, anyOf
kinds A list of all kinds found in the context instance. Supply a list of strings to the operator. equals, anyOf, contains
kindKeys A list of all kinds and keys found in the context instance. The kind and key are joined with :, for example, user:user-key-abc123. Supply a list of strings to the operator. equals, anyOf, contains

Get context kinds

Get all context kinds for a given project.

Request
path Parameters
projectKey
required
string <string>

The project key

Responses
200

Context kinds collection response

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

get/api/v2/projects/{projectKey}/context-kinds
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Create or update context kind

Create or update a context kind by key. Only the included fields will be updated.

Request
path Parameters
projectKey
required
string <string>

The project key

key
required
string <string>

The context kind key

Request Body schema: application/json
required
name
required
string

The context kind name

description
string

The context kind description

hideInTargeting
boolean

Alias for archived.

archived
boolean

Whether the context kind is archived. Archived context kinds are unavailable for targeting.

version
integer

The context kind version. If not specified when the context kind is created, defaults to 1.

Responses
200

Context kind upsert response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

put/api/v2/projects/{projectKey}/context-kinds/{key}
Request samples
application/json
{
  • "name": "organization",
  • "description": "An example context kind for organizations",
  • "hideInTargeting": false,
  • "archived": false,
  • "version": 1
}
Response samples
application/json
{
  • "status": "success",
  • "_links": {
    }
}

Get context attribute names

Get context attribute names. Returns only the first 100 attribute names per context.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

query Parameters
filter
string <string>

A comma-separated list of context filters. This endpoint only accepts kind filters, with the equals operator, and name filters, with the startsWith operator. To learn more about the filter syntax, read Filtering contexts and context instances.

Responses
200

Context attribute names collection response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/projects/{projectKey}/environments/{environmentKey}/context-attributes
Request samples
Response samples
application/json
{
  • "items": [
    ]
}

Get context attribute values

Get context attribute values.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

attributeName
required
string <string>

The attribute name

query Parameters
filter
string <string>

A comma-separated list of context filters. This endpoint only accepts kind filters, with the equals operator, and value filters, with the startsWith operator. To learn more about the filter syntax, read Filtering contexts and context instances.

Responses
200

Context attribute values collection response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/projects/{projectKey}/environments/{environmentKey}/context-attributes/{attributeName}
Request samples
Response samples
application/json
{
  • "items": [
    ]
}

Search for context instances

Search for context instances.

You can use either the query parameters or the request body parameters. If both are provided, there is an error.

To learn more about the filter syntax, read Filtering contexts and context instances. To learn more about context instances, read Understanding context instances.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

query Parameters
limit
integer <int64>

Specifies the maximum number of items in the collection to return (max: 50, default: 20)

continuationToken
string <string>

Limits results to context instances with sort values after the value specified. You can use this for pagination, however, we recommend using the next link we provide instead.

sort
string <string>

Specifies a field by which to sort. LaunchDarkly supports sorting by timestamp in ascending order by specifying ts for this value, or descending order by specifying -ts.

filter
string <string>

A comma-separated list of context filters. This endpoint only accepts an applicationId filter. To learn more about the filter syntax, read Filtering contexts and context instances.

includeTotalCount
boolean

Specifies whether to include or omit the total count of matching context instances. Defaults to true.

Request Body schema: application/json
required
filter
string

A collection of context instance filters

sort
string

Specifies a field by which to sort. LaunchDarkly supports sorting by timestamp in ascending order by specifying ts for this value, or descending order by specifying -ts.

limit
integer

Specifies the maximum number of items in the collection to return (max: 50, default: 20)

continuationToken
string

Limits results to context instances with sort values after the value specified. You can use this for pagination, however, we recommend using the next link instead, because this value is an obfuscated string.

Responses
200

Context instances collection response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

post/api/v2/projects/{projectKey}/environments/{environmentKey}/context-instances/search
Request samples
application/json
{
  • "filter": "{\"filter\": \"kindKeys:{\"contains\": [\"user:Henry\"]},\"sort\": \"-ts\",\"limit\": 50}",
  • "sort": "-ts",
  • "limit": 10,
  • "continuationToken": "QAGFKH1313KUGI2351"
}
Response samples
application/json
{
  • "_links": {
    },
  • "totalCount": 100,
  • "_environmentId": "57be1db38b75bf0772d11384",
  • "continuationToken": "QAGFKH1313KUGI2351",
  • "items": [
    ]
}

Get context instances

Get context instances by ID.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

id
required
string <string>

The context instance ID

query Parameters
limit
integer <int64>

Specifies the maximum number of context instances to return (max: 50, default: 20)

continuationToken
string <string>

Limits results to context instances with sort values after the value specified. You can use this for pagination, however, we recommend using the next link we provide instead.

sort
string <string>

Specifies a field by which to sort. LaunchDarkly supports sorting by timestamp in ascending order by specifying ts for this value, or descending order by specifying -ts.

filter
string <string>

A comma-separated list of context filters. This endpoint only accepts an applicationId filter. To learn more about the filter syntax, read Filtering contexts and context instances.

includeTotalCount
boolean

Specifies whether to include or omit the total count of matching context instances. Defaults to true.

Responses
200

Context instances collection response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/projects/{projectKey}/environments/{environmentKey}/context-instances/{id}
Request samples
Response samples
application/json
{
  • "_links": {
    },
  • "totalCount": 100,
  • "_environmentId": "57be1db38b75bf0772d11384",
  • "continuationToken": "QAGFKH1313KUGI2351",
  • "items": [
    ]
}

Delete context instances

Delete context instances by ID.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

id
required
string <string>

The context instance ID

Responses
204

Action succeeded

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

delete/api/v2/projects/{projectKey}/environments/{environmentKey}/context-instances/{id}
Request samples
Response samples
application/json
{
  • "code": "invalid_request",
  • "message": "Invalid request body"
}

Search for contexts

Search for contexts.

You can use either the query parameters or the request body parameters. If both are provided, there is an error.

To learn more about the filter syntax, read Filtering contexts and context instances. To learn more about contexts, read Understanding contexts and context kinds.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

query Parameters
limit
integer <int64>

Specifies the maximum number of items in the collection to return (max: 50, default: 20)

continuationToken
string <string>

Limits results to contexts with sort values after the value specified. You can use this for pagination, however, we recommend using the next link we provide instead.

sort
string <string>

Specifies a field by which to sort. LaunchDarkly supports sorting by timestamp in ascending order by specifying ts for this value, or descending order by specifying -ts.

filter
string <string>

A comma-separated list of context filters. To learn more about the filter syntax, read Filtering contexts and context instances.

includeTotalCount
boolean

Specifies whether to include or omit the total count of matching contexts. Defaults to true.

Request Body schema: application/json
required
filter
string

A collection of context filters

sort
string

Specifies a field by which to sort. LaunchDarkly supports sorting by timestamp in ascending order by specifying ts for this value, or descending order by specifying -ts.

limit
integer

Specifies the maximum number of items in the collection to return (max: 50, default: 20)

continuationToken
string

Limits results to contexts with sort values after the value specified. You can use this for pagination, however, we recommend using the next link instead, because this value is an obfuscated string.

Responses
200

Contexts collection response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

post/api/v2/projects/{projectKey}/environments/{environmentKey}/contexts/search
Request samples
application/json
{
  • "filter": "*.name startsWith Jo,kind anyOf [\"user\",\"organization\"]",
  • "sort": "-ts",
  • "limit": 10,
  • "continuationToken": "QAGFKH1313KUGI2351"
}
Response samples
application/json
{
  • "_links": {
    },
  • "totalCount": 100,
  • "_environmentId": "57be1db38b75bf0772d11384",
  • "continuationToken": "QAGFKH1313KUGI2351",
  • "items": [
    ]
}

Get contexts

Get contexts based on kind and key.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

kind
required
string <string>

The context kind

key
required
string <string>

The context key

query Parameters
limit
integer <int64>

Specifies the maximum number of items in the collection to return (max: 50, default: 20)

continuationToken
string <string>

Limits results to contexts with sort values after the value specified. You can use this for pagination, however, we recommend using the next link we provide instead.

sort
string <string>

Specifies a field by which to sort. LaunchDarkly supports sorting by timestamp in ascending order by specifying ts for this value, or descending order by specifying -ts.

filter
string <string>

A comma-separated list of context filters. This endpoint only accepts an applicationId filter. To learn more about the filter syntax, read Filtering contexts and context instances.

includeTotalCount
boolean

Specifies whether to include or omit the total count of matching contexts. Defaults to true.

Responses
200

Contexts collection response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/projects/{projectKey}/environments/{environmentKey}/contexts/{kind}/{key}
Request samples
Response samples
application/json
{
  • "_links": {
    },
  • "totalCount": 100,
  • "_environmentId": "57be1db38b75bf0772d11384",
  • "continuationToken": "QAGFKH1313KUGI2351",
  • "items": [
    ]
}

Evaluate flags for context instance

Evaluate flags for a context instance, for example, to determine the expected flag variation. Do not use this API instead of an SDK. The LaunchDarkly SDKs are specialized for the tasks of evaluating feature flags in your application at scale and generating analytics events based on those evaluations. This API is not designed for that use case. Any evaluations you perform with this API will not be reflected in features such as flag statuses and flag insights. Context instances evaluated by this API will not appear in the Contexts list. To learn more, read Comparing LaunchDarkly's SDKs and REST API.

Filtering

LaunchDarkly supports the filter query param for filtering, with the following fields:

  • query filters for a string that matches against the flags' keys and names. It is not case sensitive. For example: filter=query equals dark-mode.
  • tags filters the list to flags that have all of the tags in the list. For example: filter=tags contains ["beta","q1"].

You can also apply multiple filters at once. For example, setting filter=query equals dark-mode, tags contains ["beta","q1"] matches flags which match the key or name dark-mode and are tagged beta and q1.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

query Parameters
limit
integer <int64>

The number of feature flags to return. Defaults to -1, which returns all flags

offset
integer <int64>

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.

sort
string <string>

A comma-separated list of fields to sort by. Fields prefixed by a dash ( - ) sort in descending order

filter
string <string>

A comma-separated list of filters. Each filter is of the form field operator value. Supported fields are explained above.

Request Body schema: application/json
required
property name*
additional property
any
Responses
200

Flag evaluation collection response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

post/api/v2/projects/{projectKey}/environments/{environmentKey}/flags/evaluate
Request samples
application/json
{
  • "key": "user-key-123abc",
  • "kind": "user",
  • "otherAttribute": "other attribute value"
}
Response samples
application/json
{
  • "items": [
    ],
  • "totalCount": 2,
  • "_links": {
    }
}