/launchdarkly-flag-targeting

Targeting Patterns

Reference for all targeting operations available through the LaunchDarkly API semantic patch system.

Toggle Flag On/Off

The simplest targeting change.

{"kind": "turnFlagOn"}

{"kind": "turnFlagOff"}

Notes:

• Turning a flag OFF makes it serve the offVariation to everyone, regardless of rules or targets.
• Turning a flag ON activates the full targeting evaluation (individual targets -> rules -> default rule).

Percentage Rollouts (Default Rule)

The default rule (fallthrough) is what applies when no individual targets or custom rules match.

Serve a single variation to everyone

{
  "kind": "updateFallthroughVariationOrRollout",
  "variationId": "<variation-id>"
}

Or by index:

{
  "kind": "updateFallthroughVariationOrRollout",
  "variationId": "<variation-id-of-index-0>"
}

Percentage rollout

{
  "kind": "updateFallthroughVariationOrRollout",
  "rolloutWeights": {
    "<variation-id-0>": 25000,
    "<variation-id-1>": 75000
  }
}

Note on weights: The API uses weights scaled by 1000. So:

• 25% = 25000
• 50% = 50000
• 75% = 75000
• 100% = 100000

Weights must sum to 100000.

Common rollout patterns

Custom Targeting Rules

Rules let you target specific segments of users based on context attributes.

Add a rule

{
  "kind": "addRule",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "email",
      "op": "endsWith",
      "values": ["@company.com"],
      "negate": false
    }
  ],
  "variationId": "<variation-id>",
  "description": "Internal users"
}

Rule clause operators

Multiple clauses (AND logic)

Clauses within a single rule are ANDed. All must match for the rule to apply:

{
  "kind": "addRule",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "plan",
      "op": "in",
      "values": ["enterprise"]
    },
    {
      "contextKind": "user",
      "attribute": "country",
      "op": "in",
      "values": ["US"]
    }
  ],
  "variationId": "<variation-id>",
  "description": "US enterprise users"
}

Rule with percentage rollout

Instead of serving a single variation, a rule can do a percentage rollout:

{
  "kind": "addRule",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "beta",
      "op": "in",
      "values": [true]
    }
  ],
  "rolloutWeights": {
    "<variation-id-0>": 50000,
    "<variation-id-1>": 50000
  },
  "description": "50/50 for beta users"
}

Remove a rule

{
  "kind": "removeRule",
  "ruleId": "<rule-id>"
}

The ruleId (also shown as _id) can be found in the flag's current configuration.

Reorder rules

{
  "kind": "reorderRules",
  "ruleIds": ["<rule-id-1>", "<rule-id-2>", "<rule-id-3>"]
}

Rule order matters: rules evaluate top to bottom, first match wins.

Update a rule's variation

{
  "kind": "updateRuleVariationOrRollout",
  "ruleId": "<rule-id>",
  "variationId": "<variation-id>"
}

Add/remove clauses on a rule

{
  "kind": "addClauses",
  "ruleId": "<rule-id>",
  "clauses": [
    {
      "contextKind": "user",
      "attribute": "country",
      "op": "in",
      "values": ["UK"]
    }
  ]
}

{
  "kind": "removeClauses",
  "ruleId": "<rule-id>",
  "clauseIds": ["<clause-id>"]
}

Individual Targets

Individual targets are the highest priority: they override all rules.

Add users to a variation

{
  "kind": "addTargets",
  "variationId": "<variation-id>",
  "values": ["user-key-1", "user-key-2"]
}

Remove users from a variation

{
  "kind": "removeTargets",
  "variationId": "<variation-id>",
  "values": ["user-key-1"]
}

Context-kind targets (non-user)

For custom context kinds (device, organization, etc.):

{
  "kind": "addContextTargets",
  "contextKind": "organization",
  "variationId": "<variation-id>",
  "values": ["org-123", "org-456"]
}

{
  "kind": "removeContextTargets",
  "contextKind": "organization",
  "variationId": "<variation-id>",
  "values": ["org-123"]
}

Replace all targets for a variation

{
  "kind": "replaceTargets",
  "variationId": "<variation-id>",
  "values": ["user-key-1", "user-key-2"]
}

Warning: This replaces ALL targets for the variation, not just adds to them.

Cross-Environment Config Copying

Copy targeting configuration from one environment to another.

This is a separate API call (not a semantic patch). Use the flag copy endpoint:

• Source: The environment to copy from
• Target: The environment to copy to
• Included actions: Selectively copy updateOn (toggle state), updateRules, updateFallthrough, updateOffVariation, updatePrerequisites, updateTargets

Common use case: promote staging to production

Copy the full targeting config from staging after testing:

source: "staging"
target: "production"
includedActions: ["updateOn", "updateRules", "updateFallthrough", "updateOffVariation", "updateTargets"]

Note: The target environment may have approval requirements. If so, the copy operation creates an approval request instead of applying immediately.

Batching Instructions

Multiple instructions can be batched. For example, turning on and setting a rollout in one call to toggle-flag and update-rollout, or sending multiple rule changes to update-targeting-rules:

{
  "environmentKey": "production",
  "instructions": [
    {"kind": "turnFlagOn"},
    {
      "kind": "updateFallthroughVariationOrRollout",
      "rolloutWeights": {
        "<variation-id-0>": 10000,
        "<variation-id-1>": 90000
      }
    }
  ],
  "comment": "Turning on with 10% rollout"
}

This is preferred over multiple separate calls: it's atomic (all changes apply together or none do).