Create a feature flag

For the complete documentation index, see llms.txt. For the full documentation snapshot, see llms-full.txt.

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

Click to expand instructions for creating a migration flag

Creating a migration flag

When you create a migration flag, the variations are pre-determined based on the number of stages in the migration.

To create a migration flag, omit the variations and defaults information. Instead, provide a purpose of migration, and migrationSettings. If you create a migration flag with six stages, contextKind is required. Otherwise, it should be omitted.

Here’s an example:

{
  "key": "flag-key-123",
  "purpose": "migration",
  "migrationSettings": {
    "stageCount": 6,
    "contextKind": "account"
  }
}

To learn more, read Migration Flags.

POST /api/v2/flags/{projectKey}

Create a feature flag

cURL

curl --request POST \
  --url https://app.launchdarkly.com/api/v2/flags/{projectKey} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientSideAvailability": {
    "usingEnvironmentId": true,
    "usingMobileKey": true
  },
  "key": "flag-key-123abc",
  "name": "My Flag"
}
'

201

{
  "name": "My Flag",
  "kind": "boolean",
  "key": "flag-key-123abc",
  "_version": 1,
  "creationDate": "1494437420312",
  "variations": [
    {
      "_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05",
      "value": true
    },
    {
      "_id": "a00bf58d-d252-476c-b915-15a74becacb4",
      "value": false
    }
  ],
  "temporary": true,
  "tags": [
    "example-tag"
  ],
  "_links": {
    "parent": {
      "href": "/api/v2/flags/my-project",
      "type": "application/json"
    },
    "self": {
      "href": "/api/v2/flags/my-project/my-flag",
      "type": "application/json"
    }
  },
  "experiments": "{\"baselineIdx\": 0,\"items\": []}",
  "customProperties": "{\"jira.issues\":{\"name\":\"Jira issues\",\"value\":[\"is-123\",\"is-456\"]}}",
  "archived": false,
  "description": "This flag controls the example widgets",
  "includeInSnippet": true,
  "clientSideAvailability": "{\"usingMobileKey\":true,\"usingEnvironmentId\":false}",
  "maintainerId": "569f183514f4432160000007",
  "_maintainer": {
    "_links": {
      "self": {
        "href": "/api/v2/members/569f183514f4432160000007",
        "type": "application/json"
      }
    },
    "_id": "569f183514f4432160000007",
    "role": "admin",
    "email": "[e-mail]",
    "firstName": "Ariel",
    "lastName": "Flores"
  },
  "maintainerTeamKey": "team-1",
  "_maintainerTeam": {
    "key": "team-key-123abc",
    "name": "Example team",
    "_links": {
      "parent": {
        "href": "/api/v2/teams",
        "type": "application/json"
      },
      "roles": {
        "href": "/api/v2/teams/example-team/roles",
        "type": "application/json"
      },
      "self": {
        "href": "/api/v2/teams/example-team",
        "type": "application/json"
      }
    }
  },
  "goalIds": [],
  "archivedDate": "1494437420312",
  "deprecated": false,
  "deprecatedDate": "1494437420312",
  "defaults": "{\"onVariation\":0,\"offVariation\":1}",
  "_purpose": "<string>",
  "migrationSettings": {
    "contextKind": "device",
    "stageCount": 6
  },
  "environments": {
    "my-environment": {
      "_environmentName": "My Environment",
      "_site": {
        "href": "/default/my-environment/features/client-side-flag",
        "type": "text/html"
      },
      "_summary": {
        "prerequisites": 0,
        "variations": {
          "0": {
            "contextTargets": 1,
            "isFallthrough": true,
            "nullRules": 0,
            "rules": 0,
            "targets": 1
          },
          "1": {
            "isOff": true,
            "nullRules": 0,
            "rules": 0,
            "targets": 0
          }
        }
      },
      "archived": false,
      "contextTargets": [
        {
          "contextKind": "device",
          "values": [
            "device-key-123abc"
          ],
          "variation": 0
        }
      ],
      "fallthrough": {
        "variation": 0
      },
      "lastModified": 1627071171347,
      "offVariation": 1,
      "on": false,
      "prerequisites": [],
      "rules": [],
      "salt": "61eddeadbeef4da1facecafe3a60a397",
      "sel": "810edeadbeef4844facecafe438f2999492",
      "targets": [
        {
          "contextKind": "user",
          "values": [
            "user-key-123abc"
          ],
          "variation": 0
        }
      ],
      "trackEvents": false,
      "trackEventsFallthrough": false,
      "version": 1
    }
  }
}

Authorizations

Authorization · string · header · required

Path Parameters

projectKey · string<string> · required

The project key

Query Parameters

clone · string<string>

The key of the feature flag to be cloned. The key identifies the flag in your code. For example, setting clone=flagKey copies the full targeting configuration for all environments, including on/off state, from the original flag to the new flag.

Body

application/json

name · string · required

A human-friendly name for the feature flag

Example:

"My flag"

key · string · required

A unique key used to reference the flag in your code

Example:

"flag-key-123abc"

description · string

Description of the feature flag. Defaults to an empty string.

Example:

"This flag controls the example widgets"

includeInSnippet · boolean · deprecated

Deprecated, use clientSideAvailability. Whether this flag should be made available to the client-side JavaScript SDK. Defaults to false.

clientSideAvailability · object

Which type of client-side SDKs the feature flag is available to

Show child attributes

Example:

"{\"usingMobileKey\":true,\"usingEnvironmentId\":false}"

variations · object[]

An array of possible variations for the flag. The variation values must be unique. If omitted, two boolean variations of true and false will be used.

Show child attributes

Example:

[{ "value": true }, { "value": false }]

temporary · boolean

Whether the flag is a temporary flag. Defaults to true.

Example:

false

tags · string[]

Tags for the feature flag. Defaults to an empty array.

Example:

["example-tag"]

customProperties · object

Metadata attached to the feature flag, in the form of the property key associated with a name and array of values for the metadata to associate with this flag. Typically used to store data related to an integration.

Show child attributes

Example:

"{ \"jira.issues\": {\"name\": \"Jira issues\", \"value\": [\"is-123\", \"is-456\"]} }"

defaults · object

The indices, from the array of variations, for the variations to serve by default when targeting is on and when targeting is off. These variations will be used for this flag in new environments. If omitted, the first and last variation will be used.

Show child attributes

Example:

"{\"onVariation\":0, \"offVariation\":1}"

purpose · enum<string>

Purpose of the flag

Available options: migration, holdout

Example:

"migration"

migrationSettings · object

Settings relevant to flags where purpose is migration

Show child attributes

maintainerId · string

The ID of the member who maintains this feature flag

Example:

"12ab3c45de678910fgh12345"

maintainerTeamKey · string

The key of the team that maintains this feature flag

Example:

"team-1"

initialPrerequisites · object[]

Initial set of prerequisite flags for all environments

Show child attributes

isFlagOn · boolean

Whether to automatically turn the flag on across all environments at creation. Defaults to false.

Response

201

application/json

Global flag response

name · string · required

A human-friendly name for the feature flag

Example:

"My Flag"

kind · enum<string> · required

Kind of feature flag

Available options: boolean, multivariate

Example:

"boolean"

key · string · required

A unique key used to reference the flag in your code

Example:

"flag-key-123abc"

_version · integer · required

Version of the feature flag

Example:

1

creationDate · integer<int64> · required

Timestamp of flag creation date

Example:

"1494437420312"

variations · object[] · required

An array of possible variations for the flag

Show child attributes

Example:

[
  {
    "_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05",
    "value": true
  },
  {
    "_id": "a00bf58d-d252-476c-b915-15a74becacb4",
    "value": false
  }
]

temporary · boolean · required

Whether the flag is a temporary flag

Example:

true

tags · string[] · required

Tags for the feature flag

Example:

["example-tag"]

_links · object · required

The location and content type of related resources

Show child attributes

Example:

{
  "parent": {
    "href": "/api/v2/flags/my-project",
    "type": "application/json"
  },
  "self": {
    "href": "/api/v2/flags/my-project/my-flag",
    "type": "application/json"
  }
}

experiments · object · required

Experimentation data for the feature flag

Show child attributes

Example:

"{\"baselineIdx\": 0,\"items\": []}"

customProperties · object · required

Metadata attached to the feature flag, in the form of the property key associated with a name and array of values for the metadata to associate with this flag. Typically used to store data related to an integration.

Show child attributes

Example:

"{\"jira.issues\":{\"name\":\"Jira issues\",\"value\":[\"is-123\",\"is-456\"]}}"

archived · boolean · required

Boolean indicating if the feature flag is archived

Example:

false

description · string

Description of the feature flag

Example:

"This flag controls the example widgets"

includeInSnippet · boolean · deprecated

Deprecated, use clientSideAvailability. Whether this flag should be made available to the client-side JavaScript SDK

Example:

true

clientSideAvailability · object

Which type of client-side SDKs the feature flag is available to

Show child attributes

Example:

"{\"usingMobileKey\":true,\"usingEnvironmentId\":false}"

maintainerId · string

Associated maintainerId for the feature flag

Example:

"569f183514f4432160000007"

_maintainer · object

Associated maintainer member info for the feature flag

Show child attributes

maintainerTeamKey · string

The key of the associated team that maintains this feature flag

Example:

"team-1"

_maintainerTeam · object

Associated maintainer team info for the feature flag

Show child attributes

goalIds · string[] · deprecated

Deprecated, use experiments instead

Example:

[]

archivedDate · integer<int64>

If archived is true, date of archive

Example:

"1494437420312"

deprecated · boolean

Boolean indicating if the feature flag is deprecated

Example:

false

deprecatedDate · integer<int64>

If deprecated is true, date of deprecation

Example:

"1494437420312"

defaults · object

The indices, from the array of variations, for the variations to serve by default when targeting is on and when targeting is off. These variations will be used for this flag in new environments. If omitted, the first and last variation will be used.

Show child attributes

Example:

"{\"onVariation\":0,\"offVariation\":1}"

_purpose · string

migrationSettings · object

Migration-related settings for the flag

Show child attributes

environments · object

Details on the environments for this flag. Only returned if the request is filtered by environment, using the filterEnv query parameter.

Show child attributes

Example:

{
  "my-environment": {
    "_environmentName": "My Environment",
    "_site": {
      "href": "/default/my-environment/features/client-side-flag",
      "type": "text/html"
    },
    "_summary": {
      "prerequisites": 0,
      "variations": {
        "0": {
          "contextTargets": 1,
          "isFallthrough": true,
          "nullRules": 0,
          "rules": 0,
          "targets": 1
        },
        "1": {
          "isOff": true,
          "nullRules": 0,
          "rules": 0,
          "targets": 0
        }
      }
    },
    "archived": false,
    "contextTargets": [
      {
        "contextKind": "device",
        "values": ["device-key-123abc"],
        "variation": 0
      }
    ],
    "fallthrough": { "variation": 0 },
    "lastModified": 1627071171347,
    "offVariation": 1,
    "on": false,
    "prerequisites": [],
    "rules": [],
    "salt": "61eddeadbeef4da1facecafe3a60a397",
    "sel": "810edeadbeef4844facecafe438f2999492",
    "targets": [
      {
        "contextKind": "user",
        "values": ["user-key-123abc"],
        "variation": 0
      }
    ],
    "trackEvents": false,
    "trackEventsFallthrough": false,
    "version": 1
  }
}