Big Segments is an add-on feature
This section documents endpoints for both standard segements and Big Segments. Big Segments is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.
Segments allow you to create targeting rules and lists of users that can be shared by one or more feature flags in an environment. Creating a segment is a lot like creating a flag. You can include individual users from a segment. You can also create targeting rules, same as those for flags, that include or exclude users based on attributes your application has provided about those users. Finally, you can explicitly exclude users that would otherwise be included by those rules. To learn more, read Building user segments.
The segments API allows you to list, create, modify, and delete segments programmatically.
Get a list of all user segments in the given project.
Segment collection response
Invalid access token
Invalid resource identifier
curl -i -X GET \ 'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}' \ -H 'Authorization: YOUR_API_KEY_HERE'
{- "items": [
- {
- "name": "string",
- "description": "string",
- "tags": [
- "string"
], - "creationDate": 0,
- "key": "string",
- "included": [
- "string"
], - "excluded": [
- "string"
], - "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "rules": [
- {
- "_id": "string",
- "clauses": [
- {
- "_id": "string",
- "attribute": "string",
- "op": "string",
- "values": [
- null
], - "negate": true
}
], - "weight": 0,
- "bucketBy": "string"
}
], - "version": 0,
- "deleted": true,
- "_access": {
- "denied": [
- {
- "action": "string",
- "reason": {
- "resources": [
- null
], - "notResources": [
- null
], - "actions": [
- null
], - "notActions": [
- null
], - "effect": "string",
- "role_name": "string"
}
}
], - "allowed": [
- {
- "action": "string",
- "reason": {
- "resources": [
- null
], - "notResources": [
- null
], - "actions": [
- null
], - "notActions": [
- null
], - "effect": "string",
- "role_name": "string"
}
}
]
}, - "_flags": [
- {
- "name": "string",
- "key": "string",
- "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "_site": {
- "href": "string",
- "type": "string"
}
}
], - "unbounded": true,
- "generation": 0,
- "_unboundedMetadata": {
- "envId": "string",
- "segmentId": "string",
- "version": 0,
- "includedCount": 0,
- "excludedCount": 0,
- "deleted": true
}, - "_external": "string",
- "_externalLink": "string",
- "_importInProgress": true
}
], - "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}
}
Create a new user segment.
Segment response
Invalid request
Invalid access token
Forbidden
Invalid resource identifier
Rate limited
{- "name": "string",
- "key": "string",
- "description": "string",
- "tags": [
- "ops"
], - "unbounded": true
}
{- "name": "string",
- "description": "string",
- "tags": [
- "string"
], - "creationDate": 0,
- "key": "string",
- "included": [
- "string"
], - "excluded": [
- "string"
], - "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "rules": [
- {
- "_id": "string",
- "clauses": [
- {
- "_id": "string",
- "attribute": "string",
- "op": "string",
- "values": [
- null
], - "negate": true
}
], - "weight": 0,
- "bucketBy": "string"
}
], - "version": 0,
- "deleted": true,
- "_access": {
- "denied": [
- {
- "action": "string",
- "reason": {
- "resources": [
- "string"
], - "notResources": [
- "string"
], - "actions": [
- "string"
], - "notActions": [
- "string"
], - "effect": "string",
- "role_name": "string"
}
}
], - "allowed": [
- {
- "action": "string",
- "reason": {
- "resources": [
- "string"
], - "notResources": [
- "string"
], - "actions": [
- "string"
], - "notActions": [
- "string"
], - "effect": "string",
- "role_name": "string"
}
}
]
}, - "_flags": [
- {
- "name": "string",
- "key": "string",
- "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "_site": {
- "href": "string",
- "type": "string"
}
}
], - "unbounded": true,
- "generation": 0,
- "_unboundedMetadata": {
- "envId": "string",
- "segmentId": "string",
- "version": 0,
- "includedCount": 0,
- "excludedCount": 0,
- "deleted": true
}, - "_external": "string",
- "_externalLink": "string",
- "_importInProgress": true
}
Get a single user segment by key.
Segment response
Invalid access token
Invalid resource identifier
Rate limited
curl -i -X GET \ 'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}' \ -H 'Authorization: YOUR_API_KEY_HERE'
{- "name": "string",
- "description": "string",
- "tags": [
- "string"
], - "creationDate": 0,
- "key": "string",
- "included": [
- "string"
], - "excluded": [
- "string"
], - "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "rules": [
- {
- "_id": "string",
- "clauses": [
- {
- "_id": "string",
- "attribute": "string",
- "op": "string",
- "values": [
- null
], - "negate": true
}
], - "weight": 0,
- "bucketBy": "string"
}
], - "version": 0,
- "deleted": true,
- "_access": {
- "denied": [
- {
- "action": "string",
- "reason": {
- "resources": [
- "string"
], - "notResources": [
- "string"
], - "actions": [
- "string"
], - "notActions": [
- "string"
], - "effect": "string",
- "role_name": "string"
}
}
], - "allowed": [
- {
- "action": "string",
- "reason": {
- "resources": [
- "string"
], - "notResources": [
- "string"
], - "actions": [
- "string"
], - "notActions": [
- "string"
], - "effect": "string",
- "role_name": "string"
}
}
]
}, - "_flags": [
- {
- "name": "string",
- "key": "string",
- "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "_site": {
- "href": "string",
- "type": "string"
}
}
], - "unbounded": true,
- "generation": 0,
- "_unboundedMetadata": {
- "envId": "string",
- "segmentId": "string",
- "version": 0,
- "includedCount": 0,
- "excludedCount": 0,
- "deleted": true
}, - "_external": "string",
- "_externalLink": "string",
- "_importInProgress": true
}
Update a user segment. The request body must be a valid semantic patch, JSON patch, or JSON merge patch.
To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch
to your Content-Type
header. To learn more, read Updates using semantic patch.
The body of a semantic patch request for updating segments requires an environmentKey
in addition to instructions
and an optional comment
. The body of the request takes the following properties:
comment
(string): (Optional) A description of the update.environmentKey
(string): (Required) The key of the LaunchDarkly environment.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 action requires parameters, you must include those parameters as additional fields in the object.Semantic patch requests support the following kind
instructions for updating segments.
Adds user keys to the individual user targets included in the segment. Returns an error if this causes the same user key to be both included and excluded.
values
: List of user keys.Adds user keys to the individual user targets excluded from the segment. Returns an error if this causes the same user key to be both included and excluded.
values
: List of user keys.Removes user keys from the individual user targets included in the segment.
values
: List of user keys.Removes user keys from the individual user targets excluded from the segment.
values
: List of user keys.Updates the name of the segment.
value
: Name of the segment.You can also use JSON patch. To learn more, read Updates using JSON patches.
For example, to update the description for a segment, use the following request body:
{
"patch": [
{
"op": "replace",
"path": "/description",
"value": "new description"
}
]
}
To update fields in the segment that are arrays, set the path
to the name of the field and then append /<array index>
. Using /0
adds the new entry to the beginning of the array.
For example, to add a rule to a segment, use the following request body:
{
"patch":[
{
"op": "add",
"path": "/rules/0",
"value": {
"clauses": [{ "attribute": "email", "op": "endsWith", "values": [".edu"], "negate": false }]
}
}
]
}
To add or remove users from segments, we recommend using semantic patch. Semantic patch for segments includes specific instructions
for adding and removing both included and excluded users.
Segment response
Invalid request
Invalid access token
Forbidden
Invalid resource identifier
Status conflict
Rate limited
{- "patch": [
- {
- "op": "replace",
- "path": "/description",
- "value": "New description for this segment"
}, - {
- "op": "add",
- "path": "/tags/0",
- "value": "example"
}
]
}
{- "name": "string",
- "description": "string",
- "tags": [
- "string"
], - "creationDate": 0,
- "key": "string",
- "included": [
- "string"
], - "excluded": [
- "string"
], - "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "rules": [
- {
- "_id": "string",
- "clauses": [
- {
- "_id": "string",
- "attribute": "string",
- "op": "string",
- "values": [
- null
], - "negate": true
}
], - "weight": 0,
- "bucketBy": "string"
}
], - "version": 0,
- "deleted": true,
- "_access": {
- "denied": [
- {
- "action": "string",
- "reason": {
- "resources": [
- "string"
], - "notResources": [
- "string"
], - "actions": [
- "string"
], - "notActions": [
- "string"
], - "effect": "string",
- "role_name": "string"
}
}
], - "allowed": [
- {
- "action": "string",
- "reason": {
- "resources": [
- "string"
], - "notResources": [
- "string"
], - "actions": [
- "string"
], - "notActions": [
- "string"
], - "effect": "string",
- "role_name": "string"
}
}
]
}, - "_flags": [
- {
- "name": "string",
- "key": "string",
- "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "_site": {
- "href": "string",
- "type": "string"
}
}
], - "unbounded": true,
- "generation": 0,
- "_unboundedMetadata": {
- "envId": "string",
- "segmentId": "string",
- "version": 0,
- "includedCount": 0,
- "excludedCount": 0,
- "deleted": true
}, - "_external": "string",
- "_externalLink": "string",
- "_importInProgress": true
}
Delete a user segment.
Action succeeded
Invalid access token
Forbidden
Invalid resource identifier
Status conflict
Rate limited
curl -i -X DELETE \ 'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}' \ -H 'Authorization: YOUR_API_KEY_HERE'
{- "code": "unauthorized",
- "message": "invalid key"
}
Update targets included or excluded in a Big Segment.
Action succeeded
Invalid request
Invalid access token
Invalid resource identifier
Rate limited
{- "included": {
- "add": [
- "string"
], - "remove": [
- "string"
]
}, - "excluded": {
- "add": [
- "string"
], - "remove": [
- "string"
]
}
}
{- "code": "invalid_request",
- "message": "invalid request body"
}
Get the membership status (included/excluded) for a given user in this Big Segment. This operation does not support standard segments.
Segment membership for user response
Invalid request
Invalid access token
Invalid resource identifier
Rate limited
curl -i -X GET \ 'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}/users/{userKey}' \ -H 'Authorization: YOUR_API_KEY_HERE'
{- "userKey": "string",
- "included": true,
- "excluded": true
}
Get a list of a segment's user targets that are scheduled for removal.
Expiring user target response
Invalid access token
Invalid resource identifier
Rate limited
curl -i -X GET \ 'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{segmentKey}/expiring-user-targets/{environmentKey}' \ -H 'Authorization: YOUR_API_KEY_HERE'
{- "items": [
- {
- "_id": "string",
- "_version": 0,
- "expirationDate": 0,
- "userKey": "string",
- "targetType": "string",
- "variationId": "string",
- "_resourceId": {
- "kind": "string",
- "projectKey": "string",
- "environmentKey": "string",
- "flagKey": "string",
- "key": "string"
}
}
], - "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}
}
Update expiring user targets for a segment. Updating a user target expiration uses the semantic patch format.
To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch
to your Content-Type
header. To learn more, read Updates using semantic patch.
If the request is well-formed but any of its instructions failed to process, this operation returns status code 200
. In this case, the response errors
array will be non-empty.
Semantic patch requests support the following kind
instructions for updating user targets.
Schedules a date and time when LaunchDarkly will remove a user from segment targeting.
targetType
: A segment's target type, must be either included
or excluded
.userKey
: The user key.value
: The date when the user should expire from the segment targeting, in Unix milliseconds.Updates the date and time when LaunchDarkly will remove a user from segment targeting.
targetType
: A segment's target type, must be either included
or excluded
.userKey
: The user key.value
: The new date when the user should expire from the segment targeting, in Unix milliseconds.version
: The segment version.Removes the scheduled expiration for the user in the segment.
targetType
: A segment's target type, must be either included
or excluded
.userKey
: The user key.Expiring user target response.
Invalid request
Invalid access token
Forbidden
Invalid resource identifier
Status conflict
Rate limited
{- "comment": "string",
- "instructions": [
- {
- "kind": "updateExpireUserTargetDate",
- "targetType": "included",
- "userKey": "userKey",
- "value": 1587582000000,
- "version": 0
}
]
}
{- "items": [
- {
- "_id": "string",
- "_version": 0,
- "expirationDate": 0,
- "userKey": "string",
- "targetType": "string",
- "variationId": "string",
- "_resourceId": {
- "kind": "string",
- "projectKey": "string",
- "environmentKey": "string",
- "flagKey": "string",
- "key": "string"
}
}
], - "_links": {
- "property1": {
- "href": "string",
- "type": "string"
}, - "property2": {
- "href": "string",
- "type": "string"
}
}, - "totalInstructions": 0,
- "successfulInstructions": 0,
- "failedInstructions": 0,
- "errors": [
- {
- "instructionIndex": 0,
- "message": "string"
}
]
}