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.


 
limit
integer <int64> 
Specifies the maximum number of items in the collection to return (max: 100, default: 50)


 
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 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 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": {
    }
}
➔ Next to Custom roles