Segments

Get a list of all segments in the given project.

Create a new segment.

Get a single segment by key.

Update a segment. The request body must be a valid semantic patch, JSON patch, or JSON merge patch.

Using semantic patches on a segment

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.

Instructions

Semantic patch requests support the following kind instructions for updating segments.

addIncludedTargets

Adds context keys to the individual context targets included in the segment for the specified contextKind. Returns an error if this causes the same context key to be both included and excluded.

Parameters

• contextKind: The context kind the targets should be added to.
• values: List of keys.

addIncludedUsers

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. If you are working with contexts, use addIncludedTargets instead of this instruction.

Parameters

• values: List of user keys.

addExcludedTargets

Adds context keys to the individual context targets excluded in the segment for the specified contextKind. Returns an error if this causes the same context key to be both included and excluded.

Parameters

• contextKind: The context kind the targets should be added to.
• values: List of keys.

addExcludedUsers

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. If you are working with contexts, use addExcludedTargets instead of this instruction.

Parameters

• values: List of user keys.

removeIncludedTargets

Removes context keys from the individual context targets included in the segment for the specified contextKind.

Parameters

• contextKind: The context kind the targets should be removed from.
• values: List of keys.

removeIncludedUsers

Removes user keys from the individual user targets included in the segment. If you are working with contexts, use removeIncludedTargets instead of this instruction.

Parameters

• values: List of user keys.

removeExcludedTargets

Removes context keys from the individual context targets excluded from the segment for the specified contextKind.

Parameters

• contextKind: The context kind the targets should be removed from.
• values: List of keys.

removeExcludedUsers

Removes user keys from the individual user targets excluded from the segment. If you are working with contexts, use removeExcludedTargets instead of this instruction.

Parameters

• values: List of user keys.

updateName

Updates the name of the segment.

Parameters

• value: Name of the segment.

Using JSON patches on a 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": [{ "contextKind": "user", "attribute": "email", "op": "endsWith", "values": [".edu"], "negate": false }]
      }
    }
  ]
}

To add or remove targets from segments, we recommend using semantic patch. Semantic patch for segments includes specific instructions for adding and removing both included and excluded targets.

Delete a segment.

Update context targets included or excluded in a Big Segment.

Get the membership status (included/excluded) for a given context in this Big Segment. This operation does not support standard segments.

Update user context targets included or excluded in a Big Segment.

Contexts are now available

After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use Get expiring targets for segment instead of this endpoint. To learn more, read Contexts.

Get the membership status (included/excluded) for a given user in this Big Segment. This operation does not support standard segments.

Get a list of a segment's context targets that are scheduled for removal.

Update expiring context targets for a segment. Updating a context 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.

Instructions

Semantic patch requests support the following kind instructions for updating context targets.

addExpiringTarget

Schedules a date and time when LaunchDarkly will remove a context from segment targeting.

Parameters

• targetType: A segment's target type, must be either included or excluded.
• contextKey: The context key.
• contextKind: The kind of context being targeted.
• value: The date when the context should expire from the segment targeting, in Unix milliseconds.

updateExpiringTarget

Updates the date and time when LaunchDarkly will remove a context from segment targeting.

Parameters

• targetType: A segment's target type, must be either included or excluded.
• contextKey: The context key.
• contextKind: The kind of context being targeted.
• value: The new date when the context should expire from the segment targeting, in Unix milliseconds.
• version: The segment version.

removeExpiringTarget

Removes the scheduled expiration for the context in the segment.

Parameters

• targetType: A segment's target type, must be either included or excluded.
• contextKey: The context key.
• contextKind: The kind of context being targeted.

Contexts are now available

After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use Get expiring targets for segment instead of this endpoint. To learn more, read Contexts.

Get a list of a segment's user targets that are scheduled for removal.

Contexts are now available

After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use Update expiring targets for segment instead of this endpoint. To learn more, read Contexts.

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.

Instructions

Semantic patch requests support the following kind instructions for updating user targets.

addExpireUserTargetDate

Schedules a date and time when LaunchDarkly will remove a user from segment targeting.

Parameters

• 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.

updateExpireUserTargetDate

Updates the date and time when LaunchDarkly will remove a user from segment targeting.

Parameters

• 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.

removeExpireUserTargetDate

Removes the scheduled expiration for the user in the segment.

Parameters

• targetType: A segment's target type, must be either included or excluded.
• userKey: The user key.