Segments

addTags

Adds tags to the segment.

Parameters

• values: A list of tags to add.

Here's an example:

{
  "instructions": [{
    "kind": "addTags",
    "values": ["tag1", "tag2"]
  }]
}

removeTags

Removes tags from the segment.

Parameters

• values: A list of tags to remove.

Here's an example:

{
  "instructions": [{
    "kind": "removeTags",
    "values": ["tag1", "tag2"]
  }]
}

updateName

Updates the name of the segment.

Parameters

• value: Name of the segment.

Here's an example:

{
  "instructions": [{
    "kind": "updateName",
    "value": "Updated segment name"
  }]
}

addExcludedTargets

Adds context keys to the individual context targets excluded from 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.

Here's an example:

{
  "instructions": [{
    "kind": "addExcludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

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.

Here's an example:

{
  "instructions": [{
    "kind": "addExcludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

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.

Here's an example:

{
  "instructions": [{
    "kind": "addIncludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

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.

Here's an example:

{
  "instructions": [{
    "kind": "addIncludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

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.

Here's an example:

{
  "instructions": [{
    "kind": "removeExcludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

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.

Here's an example:

{
  "instructions": [{
    "kind": "removeExcludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

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.

Here's an example:

{
  "instructions": [{
    "kind": "removeIncludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

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.

Here's an example:

{
  "instructions": [{
    "kind": "removeIncludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

addClauses

Adds the given clauses to the rule indicated by ruleId.

Parameters

• clauses: Array of clause objects, with contextKind (string), attribute (string), op (string), negate (boolean), and values (array of strings, numbers, or dates) properties. The contextKind, if not provided, defaults to user. The contextKind, attribute, and values are case sensitive. The op must be lower-case.
• ruleId: ID of a rule in the segment.

Here's an example:

{
  "instructions": [{
    "kind": "addClauses",
    "clauses": [
      {
        "attribute": "email",
        "negate": false,
        "op": "contains",
        "values": ["value1"]
      }
    ],
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29",
  }]
}

addRule

Adds a new targeting rule to the segment. The rule may contain clauses.

Parameters

• clauses: Array of clause objects, with contextKind (string), attribute (string), op (string), negate (boolean), and values (array of strings, numbers, or dates) properties. The contextKind, if not provided, defaults to user. The contextKind, attribute, and values are case sensitive. The op must be lower-case.
• description: A description of the rule.

Here's an example:

{
  "instructions": [{
    "kind": "addRule",
    "clauses": [
      {
        "attribute": "email",
        "op": "contains",
        "negate": false,
        "values": ["@launchdarkly.com"]
      }
    ],
    "description": "Targeting rule for LaunchDarkly employees",
  }]
}

addValuesToClause

Adds values to the values of the clause that ruleId and clauseId indicate. Does not update the context kind, attribute, or operator.

Parameters

• ruleId: ID of a rule in the segment.
• clauseId: ID of a clause in that rule.
• values: Array of strings, case sensitive.

Here's an example:

{
  "instructions": [{
    "kind": "addValuesToClause",
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29",
    "clauseId": "10a58772-3121-400f-846b-b8a04e8944ed",
    "values": ["beta_testers"]
  }]
}

removeClauses

Removes the clauses specified by clauseIds from the rule indicated by ruleId.

Parameters

• ruleId: ID of a rule in the segment.
• clauseIds: Array of IDs of clauses in the rule.

Here's an example:

{
  "instructions": [{
    "kind": "removeClauses",
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29",
    "clauseIds": ["10a58772-3121-400f-846b-b8a04e8944ed", "36a461dc-235e-4b08-97b9-73ce9365873e"]
  }]
}

removeRule

Removes the targeting rule specified by ruleId. Does nothing if the rule does not exist.

Parameters

• ruleId: ID of a rule in the segment.

Here's an example:

{
  "instructions": [{
    "kind": "removeRule",
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29"
  }]
}

removeValuesFromClause

Removes values from the values of the clause indicated by ruleId and clauseId. Does not update the context kind, attribute, or operator.

Parameters

• ruleId: ID of a rule in the segment.
• clauseId: ID of a clause in that rule.
• values: Array of strings, case sensitive.

Here's an example:

{
  "instructions": [{
    "kind": "removeValuesFromClause",
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29",
    "clauseId": "10a58772-3121-400f-846b-b8a04e8944ed",
    "values": ["beta_testers"]
  }]
}

reorderRules

Rearranges the rules to match the order given in ruleIds. Returns an error if ruleIds does not match the current set of rules in the segment.

Parameters

• ruleIds: Array of IDs of all targeting rules in the segment.

Here's an example:

{
  "instructions": [{
    "kind": "reorderRules",
    "ruleIds": ["a902ef4a-2faf-4eaf-88e1-ecc356708a29", "63c238d1-835d-435e-8f21-c8d5e40b2a3d"]
  }]
}

updateClause

Replaces the clause indicated by ruleId and clauseId with clause.

Parameters

• ruleId: ID of a rule in the segment.
• clauseId: ID of a clause in that rule.
• clause: New clause object, with contextKind (string), attribute (string), op (string), negate (boolean), and values (array of strings, numbers, or dates) properties. The contextKind, if not provided, defaults to user. The contextKind, attribute, and values are case sensitive. The op must be lower-case.

Here's an example:

{
  "instructions": [{
    "kind": "updateClause",
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29",
    "clauseId": "10c7462a-2062-45ba-a8bb-dfb3de0f8af5",
    "clause": {
      "contextKind": "user",
      "attribute": "country",
      "op": "in",
      "negate": false,
      "values": ["Mexico", "Canada"]
    }
  }]
}

updateRuleDescription

Updates the description of the segment targeting rule.

Parameters

• description: The new human-readable description for this rule.
• ruleId: The ID of the rule. You can retrieve this by making a GET request for the segment.

Here's an example:

{
  "instructions": [{
    "kind": "updateRuleDescription",
    "description": "New rule description",
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29"
  }]
}

updateRuleRolloutAndContextKind

For a rule that includes a percentage of targets, updates the percentage and the context kind of the targets to include.

Parameters

• ruleId: The ID of a targeting rule in the segment that includes a percentage of targets.
• weight: The weight, in thousandths of a percent (0-100000).
• contextKind: The context kind.

Here's an example:

{
  "instructions": [{
    "kind": "reorderRules",
    "ruleId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29",
    "weight": "20000",
    "contextKind": "device"
  }]
}

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.

The following semantic patch instructions apply only to these larger list-based segments.

addBigSegmentExcludedTargets

For use with larger list-based segments ONLY. Adds context keys to the context targets excluded from the segment. Returns an error if this causes the same context key to be both included and excluded.

Parameters

• values: List of context keys.

Here's an example:

{
  "instructions": [{
    "kind": "addBigSegmentExcludedTargets",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

addBigSegmentIncludedTargets

For use with larger list-based segments ONLY. Adds context keys to the context targets included in the segment. Returns an error if this causes the same context key to be both included and excluded.

Parameters

• values: List of context keys.

Here's an example:

{
  "instructions": [{
    "kind": "addBigSegmentIncludedTargets",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

processBigSegmentImport

For use with larger list-based segments ONLY. Processes a segment import.

Parameters

• importId: The ID of the import. The import ID is returned in the Location header as part of the Create big segment import request.

Here's an example:

{
  "instructions": [{
    "kind": "processBigSegmentImport",
    "importId": "a902ef4a-2faf-4eaf-88e1-ecc356708a29"
  }]
}

removeBigSegmentExcludedTargets

For use with larger list-based segments ONLY. Removes context keys from the context targets excluded from the segment.

Parameters

• values: List of context keys.

Here's an example:

{
  "instructions": [{
    "kind": "removeBigSegmentExcludedTargets",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

removeBigSegmentIncludedTargets

For use with larger list-based segments ONLY. Removes context keys from the context targets included in the segment.

Parameters

• values: List of context keys.

Here's an example:

{
  "instructions": [{
    "kind": "removeBigSegmentIncludedTargets",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

addExpiringTarget

Schedules a date and time when LaunchDarkly will remove a context from segment targeting. The segment must already have the context as an individual target.

Parameters

• targetType: The type of individual target for this context. 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.

Here's an example:

{
  "instructions": [{
    "kind": "addExpiringTarget",
    "targetType": "included",
    "contextKey": "user-key-123abc",
    "contextKind": "user",
    "value": 1754092860000
  }]
}

updateExpiringTarget

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

Parameters

• targetType: The type of individual target for this context. 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: (Optional) The version of the expiring target to update. If included, update will fail if version doesn't match current version of the expiring target.

Here's an example:

{
  "instructions": [{
    "kind": "updateExpiringTarget",
    "targetType": "included",
    "contextKey": "user-key-123abc",
    "contextKind": "user",
    "value": 1754179260000
  }]
}

removeExpiringTarget

Removes the scheduled expiration for the context in the segment.

Parameters

• targetType: The type of individual target for this context. Must be either included or excluded.
• contextKey: The context key.
• contextKind: The kind of context being targeted.

Here's an example:

{
  "instructions": [{
    "kind": "removeExpiringTarget",
    "targetType": "included",
    "contextKey": "user-key-123abc",
    "contextKind": "user",
  }]
}

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.