Feature flags

Get the status for a particular feature flag across environments.

Get a list of statuses for all feature flags. The status includes the last time the feature flag was requested, as well as a state, which is one of the following:

• new: the feature flag was created within the last seven days, and has not been requested yet
• active: the feature flag was requested by your servers or clients within the last seven days
• inactive: the feature flag was created more than seven days ago, and hasn't been requested by your servers or clients within the past seven days
• launched: one variation of the feature flag has been rolled out to all your users for at least 7 days

Get the status for a particular feature flag.

Get a list of all features in the given project. By default, each feature includes configurations for each environment. You can filter environments with the env query parameter. For example, setting env=production restricts the returned configurations to just your production environment. You can also filter feature flags by tag with the tag query parameter.

We support the following fields for filters:

• query is a string that matches against the flags' keys and names. It is not case sensitive.
• archived is a boolean to filter the list to archived flags. When this is absent, only unarchived flags are returned.
• type is a string allowing filtering to temporary or permanent flags.
• status is a string allowing filtering to new, inactive, active, or launched flags in the specified environment. This filter also requires a filterEnv field to be set to a valid environment. For example: filter=status:active,filterEnv:production.
• tags is a + separated list of tags. It filters the list to members who have all of the tags in the list.
• hasExperiment is a boolean with values of true or false and returns any flags that have an attached metric.
• hasDataExport is a boolean with values of true or false and returns any flags that are currently exporting data in the specified environment. This includes flags that are exporting data via Experimentation. This filter also requires a filterEnv field to be set to a valid environment key. e.g. filter=hasExperiment:true,filterEnv:production
• evaluated is an object that contains a key of after and a value in Unix time in milliseconds. This returns all flags that have been evaluated since the time you specify in the environment provided. This filter also requires a filterEnv field to be set to a valid environment. For example: filter=evaluated:{"after": 1590768455282},filterEnv:production.
• filterEnv is a string with the key of a valid environment. The filterEnv field is used for filters that are environment specific. If there are multiple environment specific filters you should only declare this parameter once. For example: filter=evaluated:{"after": 1590768455282},filterEnv:production,status:active.

An example filter is query:abc,tags:foo+bar. This matches flags with the string abc in their key or name, ignoring case, which also have the tags foo and bar.

By default, this returns all flags. You can page through the list with the limit parameter and by following the first, prev, next, and last links in the returned _links field. These links will not be present if the pages they refer to don't exist. For example, the first and prev links will be missing from the response on the first page.

Create a feature flag with the given name, key, and variations.

Get a single feature flag by key. By default, this returns the configurations for all environments. You can filter environments with the env query parameter. For example, setting env=production restricts the returned configurations to just the production environment.

Perform a partial update to a feature flag. The request body must be a valid semantic patch or JSON patch.

Using semantic patches on a feature flag

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 feature flags 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 feature flags.

turnFlagOn

Sets the flag's targeting state to On.

For example, to turn a flag on, use this request body:

{
  "environmentKey": "example-environment-key",
  "instructions": [ { "kind": "turnFlagOn" } ]
}

turnFlagOff

Sets the flag's targeting state to Off.

For example, to turn a flag off, use this request body:

{
  "environmentKey": "example-environment-key",
  "instructions": [ { "kind": "turnFlagOff" } ]
}

addUserTargets

Adds user keys to the individual user targets for the variation that variationId specifies. Returns an error if this causes the flag to target the same user key in multiple variations.

Parameters

• values: List of user keys.
• variationId: ID of a variation on the flag.

removeUserTargets

Removes user keys from the individual user targets for the variation that variationId specifies. Does nothing if the flag does not target the user keys.

Parameters

• values: List of user keys.
• variationId: ID of a variation on the flag.

replaceUserTargets

Removes all existing user targeting and replaces it with the list of targets you provide.

Parameters

• targets: A list of user targeting. Each item in the list must include a variationId and a list of values.

For example, to replace user targets, use this request body:

{
  "environmentKey": "example-environment-key",
  "instructions": [
    {
      "kind": "replaceUserTargets",
      "targets": [
        {
          "variationId": "variation-1",
          "values": ["blah", "foo", "bar"]
        },
        {
          "variationId": "variation-2",
          "values": ["abc", "def"]
        }
      ]
    }    
  ]
}

clearUserTargets

Removes all individual user targets from the variation that variationId specifies.

Parameters

• variationId: ID of a variation on the flag.

addPrerequisite

Adds the flag indicated by key with variation variationId as a prerequisite to the flag in the path parameter.

Parameters

• key: Flag key of the prerequisite flag.
• variationId: ID of a variation of the prerequisite flag.

removePrerequisite

Removes the prerequisite flag indicated by key. Does nothing if this prerequisite does not exist.

Parameters

• key: Flag key of an existing prerequisite flag.

updatePrerequisite

Changes the prerequisite flag that key indicates to use the variation that variationId indicates. Returns an error if this prerequisite does not exist.

Parameters

• key: Flag key of an existing prerequisite flag.
• variationId: ID of a variation of the prerequisite flag.

replacePrerequisites

Removes all existing prerequisites and replaces them with the list you provide.

Parameters

• prerequisites: A list of prerequisites. Each item in the list must include a flag key and variationId.

For example, to replace prerequisites, use this request body:

{
  "environmentKey": "example-environment-key",
  "instructions": [
    {
      "kind": "replacePrerequisites",
      "prerequisites": [
        {
          "key": "prereq-flag-key",
          "variationId": "variation-1"
        },
        {
          "key": "another-prereq-flag-key",
          "variationId": "variation-2"
        }
      ]
    }
  ]
}

addRule

Adds a new targeting rule to the flag. The rule may contain clauses and serve the variation that variationId indicates, or serve a percent rollout that rolloutWeights and rolloutBucketBy indicate.

If beforeRuleId is set, adds the new rule before the indicated rule. Otherwise, adds the new rule to the end of the list.

Parameters

• clauses: Array of clause objects, with attribute (string), op (string), and values (array of strings, numbers, or dates) properties.
• beforeRuleId: Optional ID of a rule in the flag.
• variationId: ID of a variation of the flag.
• rolloutWeights: Map of variationId to weight, in thousandths of a percent (0-100000).
• rolloutBucketBy: Optional user attribute.

removeRule

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

Parameters

• ruleId: ID of a rule in the flag.

replaceRules

Removes all targeting rules for the flag and replaces them with the list you provide.

Parameters

• rules: A list of rules.

For example, to replace rules, use this request body:

{
  "environmentKey": "example-environment-key",
  "instructions": [
    {
      "kind": "replaceRules",
      "rules": [
        {
          "variationId": "variation-1",
          "description": "myRule",
          "clauses": [
            {
              "attribute": "segmentMatch",
              "op": "segmentMatch",
              "values": ["test"]
            }
          ],
          "trackEvents": true
        }
      ]
    }
  ]
}

addClauses

Adds the given clauses to the rule indicated by ruleId.

Parameters

• ruleId: ID of a rule in the flag.
• clauses: Array of clause objects, with attribute (string), op (string), and values (array of strings, numbers, or dates) properties.

removeClauses

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

Parameters

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

updateClause

Replaces the clause indicated by ruleId and clauseId with clause.

Parameters

• ruleId: ID of a rule in the flag.
• clauseId: ID of a clause in that rule.
• clause: New clause object, with attribute (string), op (string), and values (array of strings, numbers, or dates) properties.

addValuesToClause

Adds values to the values of the clause that ruleId and clauseId indicate.

Parameters

• ruleId: ID of a rule in the flag.
• clauseId: ID of a clause in that rule.
• values: Array of strings.

removeValuesFromClause

Removes values from the values of the clause indicated by ruleId and clauseId.

Parameters

ruleId: ID of a rule in the flag. clauseId: ID of a clause in that rule. values: Array of strings.

reorderRules

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

Parameters

• ruleIds: Array of IDs of all rules in the flag.

updateRuleVariationOrRollout

Updates what ruleId serves when its clauses evaluate to true. The rule can serve either the variation that variationId indicates, or a percent rollout that rolloutWeights and rolloutBucketBy indicate.

Parameters

• ruleId: ID of a rule in the flag.
• variationId: ID of a variation of the flag. or
• rolloutWeights: Map of variationId to weight, in thousandths of a percent (0-100000).
• rolloutBucketBy: Optional user attribute.

updateFallthroughVariationOrRollout

Updates the default or "fallthrough" rule for the flag, which the flag serves when a user matches none of the targeting rules. The rule can serve either the variation that variationId indicates, or a percent rollout that rolloutWeights and rolloutBucketBy indicate.

Parameters

variationId: ID of a variation of the flag. or rolloutWeights: Map of variationId to weight, in thousandths of a percent (0-100000). rolloutBucketBy: Optional user attribute.

updateOffVariation

Updates the default off variation to variationId. The flag serves the default off variation when the flag's targeting is Off.

Parameters

variationId: ID of a variation of the flag.

Example

The body of a single semantic patch can contain many different instructions.

{
  "environmentKey": "production",
  "instructions": [
    {
      "kind": "turnFlagOn"
    },
    {
      "kind": "turnFlagOff"
    },
    {
      "kind": "addUserTargets",
      "variationId": "8bfb304e-d516-47e5-8727-e7f798e8992d",
      "values": ["userId", "userId2"]
    },
    {
      "kind": "removeUserTargets",
      "variationId": "8bfb304e-d516-47e5-8727-e7f798e8992d",
      "values": ["userId3", "userId4"]
    },
    {
      "kind": "updateFallthroughVariationOrRollout",
      "rolloutWeights": {
        "variationId": 50000,
        "variationId2": 50000
      },
      "rolloutBucketBy": null
    },
    {
      "kind": "addRule",
      "clauses": [
        {
          "attribute": "segmentMatch",
          "negate": false,
          "values": ["test-segment"]
        }
      ],
      "variationId": null,
      "rolloutWeights": {
        "variationId": 50000,
        "variationId2": 50000
      },
      "rolloutBucketBy": "key"
    },
    {
      "kind": "removeRule",
      "ruleId": "99f12464-a429-40fc-86cc-b27612188955"
    },
    {
      "kind": "reorderRules",
      "ruleIds": ["2f72974e-de68-4243-8dd3-739582147a1f", "8bfb304e-d516-47e5-8727-e7f798e8992d"]
    },
    {
      "kind": "addClauses",
      "ruleId": "1134",
      "clauses": [
        {
          "attribute": "email",
          "op": "in",
          "negate": false,
          "values": ["test@test.com"]
        }
      ]
    },
    {
      "kind": "removeClauses",
      "ruleId": "1242529",
      "clauseIds": ["8bfb304e-d516-47e5-8727-e7f798e8992d"]
    },
    {
      "kind": "updateClause",
      "ruleId": "2f72974e-de68-4243-8dd3-739582147a1f",
      "clauseId": "309845",
      "clause": {
        "attribute": "segmentMatch",
        "negate": false,
        "values": ["test-segment"]
      }
    },
    {
      "kind": "updateRuleVariationOrRollout",
      "ruleId": "2342",
      "rolloutWeights": null,
      "rolloutBucketBy": null
    },
    {
      "kind": "updateOffVariation",
      "variationId": "3242453"
    },
    {
      "kind": "addPrerequisite",
      "variationId": "234235",
      "key": "flagKey2"
    },
    {
      "kind": "updatePrerequisite",
      "variationId": "234235",
      "key": "flagKey2"
    },
    {
      "kind": "removePrerequisite",
      "key": "flagKey"
    }
  ]
}

Using JSON Patches on a feature flag

If you do not include the header described above, you can use JSON patch.

When using the update feature flag endpoint to add individual users to a specific variation, there are two different patch documents, depending on whether users are already being individually targeted for the variation.

If a flag variation already has users individually targeted, the path for the JSON Patch operation is:

{
  "op": "add",
  "path": "/environments/devint/targets/0/values/-",
  "value": "TestClient10"
}

If a flag variation does not already have users individually targeted, the path for the JSON Patch operation is:

[
  {
    "op": "add",
    "path": "/environments/devint/targets/-",
    "value": { "variation": 0, "values": ["TestClient10"] }
  }
]

Required approvals

If a request attempts to alter a flag configuration in an environment where approvals are required for the flag, the request will fail with a 405. Changes to the flag configuration in that environment will require creating an approval request or a workflow.

Conflicts

If a flag configuration change made through this endpoint would cause a pending scheduled change or approval request to fail, this endpoint will return a 400. You can ignore this check by adding an ignoreConflicts query parameter set to true.

Delete a feature flag in all environments. Use with caution: only delete feature flags your application no longer uses.

The includedActions and excludedActions define the parts of the flag configuration that are copied or not copied. By default, the entire flag configuration is copied.

You can have either includedActions or excludedActions but not both.

Valid includedActions and excludedActions include:

• updateOn
• updatePrerequisites
• updateTargets
• updateRules
• updateFallthrough
• updateOffVariation

The source and target must be JSON objects if using curl, specifying the environment key and (optional) current flag configuration version in that environment. For example:

{
  "key": "production",
  "currentVersion": 3
}

If target is specified as above, the API will test to ensure that the current flag version in the production environment is 3, and reject attempts to copy settings to production otherwise. You can use this to enforce optimistic locking on copy attempts.