Create a feature flag — LaunchDarkly

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:

1 {
2   "key": "flag-key-123",
3   "purpose": "migration",
4   "migrationSettings": {
5     "stageCount": 6,
6     "contextKind": "account"
7   }
8 }

To learn more, read Migration Flags.

Path parameters

projectKeystringRequired

The project key

Query parameters

clonestringOptional

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.

Request

This endpoint expects an object.

namestringRequired

A human-friendly name for the feature flag

keystringRequired

A unique key used to reference the flag in your code

descriptionstringOptional

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

clientSideAvailabilityobjectOptional

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

variationslist of objectsOptional

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.

temporarybooleanOptional

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

tagslist of stringsOptional

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

customPropertiesmap from strings to objectsOptional

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.

defaultsobjectOptional

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.

purposeenumOptional

Allowed values: migrationholdout

Purpose of the flag

migrationSettingsobjectOptional

Settings relevant to flags where purpose is migration

maintainerIdstringOptional

The ID of the member who maintains this feature flag

maintainerTeamKeystringOptional

The key of the team that maintains this feature flag

initialPrerequisiteslist of objectsOptional

Initial set of prerequisite flags for all environments

includeInSnippetbooleanOptionalDeprecated

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

Response

Global flag response

namestring

A human-friendly name for the feature flag

kindenum

Allowed values: booleanmultivariate

Kind of feature flag

keystring

A unique key used to reference the flag in your code

_versioninteger

Version of the feature flag

creationDatelong

Timestamp of flag creation date

variationslist of objects

An array of possible variations for the flag

temporaryboolean

Whether the flag is a temporary flag

tagslist of strings

Tags for the feature flag

_linksmap from strings to objects

The location and content type of related resources

experimentsobject

Experimentation data for the feature flag

customPropertiesmap from strings to objects

archivedboolean

Boolean indicating if the feature flag is archived

environmentsmap from strings to objects

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

descriptionstringOptional

Description of the feature flag

clientSideAvailabilityobjectOptional

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

maintainerIdstringOptional

Associated maintainerId for the feature flag

_maintainerobjectOptional

Associated maintainer member info for the feature flag

maintainerTeamKeystringOptional

The key of the associated team that maintains this feature flag

_maintainerTeamobjectOptional

Associated maintainer team info for the feature flag

archivedDatelongOptional

If archived is true, date of archive

deprecatedbooleanOptional

Boolean indicating if the feature flag is deprecated

deprecatedDatelongOptional

If deprecated is true, date of deprecation

defaultsobjectOptional

_purposestringOptional

migrationSettingsobjectOptional

Migration-related settings for the flag

includeInSnippetbooleanOptionalDeprecated

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

goalIdslist of stringsOptionalDeprecated

Deprecated, use experiments instead

Errors

1 curl -X POST https://app.launchdarkly.com/api/v2/flags/projectKey \ 2 -H "Authorization: <apiKey>" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "name": "My Flag", 6 "key": "flag-key-123abc", 7 "clientSideAvailability": { 8 "usingEnvironmentId": true, 9 "usingMobileKey": true 10 } 11 }'

1 { 2 "name": "My Flag", 3 "kind": "boolean", 4 "key": "flag-key-123abc", 5 "_version": 1, 6 "creationDate": 1000000, 7 "variations": [ 8 { 9 "value": true, 10 "_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05", 11 "description": "description", 12 "name": "name" 13 }, 14 { 15 "value": false, 16 "_id": "a00bf58d-d252-476c-b915-15a74becacb4", 17 "description": "description", 18 "name": "name" 19 } 20 ], 21 "temporary": true, 22 "tags": [ 23 "example-tag" 24 ], 25 "_links": { 26 "parent": { 27 "href": "/api/v2/flags/my-project", 28 "type": "application/json" 29 }, 30 "self": { 31 "href": "/api/v2/flags/my-project/my-flag", 32 "type": "application/json" 33 } 34 }, 35 "experiments": { 36 "baselineIdx": 1, 37 "items": [ 38 { 39 "metricKey": "my-metric", 40 "_metric": { 41 "_id": "5902deadbeef667524a01290", 42 "_versionId": "version-id-123abc", 43 "key": "metric-key-123abc", 44 "name": "My metric", 45 "kind": "pageview", 46 "_links": { 47 "parent": { 48 "href": "/api/v2/metrics/my-project", 49 "type": "application/json" 50 }, 51 "self": { 52 "href": "/api/v2/metrics/my-project/my-metric", 53 "type": "application/json" 54 } 55 }, 56 "tags": [ 57 "tags" 58 ], 59 "_creationDate": 1000000, 60 "experimentCount": 0, 61 "metricGroupCount": 0, 62 "_attachedFlagCount": 0, 63 "maintainerId": "569fdeadbeef1644facecafe", 64 "_maintainer": { 65 "_links": { 66 "self": { 67 "href": "/api/v2/members/569f183514f4432160000007", 68 "type": "application/json" 69 } 70 }, 71 "_id": "569f183514f4432160000007", 72 "role": "admin", 73 "email": "ariel@acme.com", 74 "firstName": "Ariel", 75 "lastName": "Flores" 76 }, 77 "category": "Error monitoring", 78 "isNumeric": true, 79 "percentileValue": 95 80 } 81 } 82 ] 83 }, 84 "customProperties": { 85 "key": { 86 "name": "Jira issues", 87 "value": [ 88 "is-123", 89 "is-456" 90 ] 91 } 92 }, 93 "archived": false, 94 "environments": { 95 "my-environment": { 96 "on": false, 97 "archived": false, 98 "salt": "61eddeadbeef4da1facecafe3a60a397", 99 "sel": "810edeadbeef4844facecafe438f2999492", 100 "lastModified": 1627071171347, 101 "version": 1, 102 "_site": { 103 "href": "/default/my-environment/features/client-side-flag", 104 "type": "text/html" 105 }, 106 "_environmentName": "My Environment", 107 "trackEvents": false, 108 "trackEventsFallthrough": false, 109 "targets": [ 110 { 111 "values": [ 112 "user-key-123abc" 113 ], 114 "variation": 0, 115 "contextKind": "user" 116 } 117 ], 118 "contextTargets": [ 119 { 120 "values": [ 121 "device-key-123abc" 122 ], 123 "variation": 0, 124 "contextKind": "device" 125 } 126 ], 127 "rules": [ 128 { 129 "clauses": [ 130 { 131 "attribute": "attribute", 132 "op": "op", 133 "values": [], 134 "negate": true 135 } 136 ], 137 "trackEvents": true 138 } 139 ], 140 "fallthrough": { 141 "variation": 0 142 }, 143 "offVariation": 1, 144 "prerequisites": [ 145 { 146 "key": "key", 147 "variation": 1 148 } 149 ], 150 "_access": { 151 "denied": [ 152 { 153 "action": "action", 154 "reason": { 155 "effect": "allow" 156 } 157 } 158 ], 159 "allowed": [ 160 { 161 "action": "action", 162 "reason": { 163 "effect": "allow" 164 } 165 } 166 ] 167 }, 168 "_debugEventsUntilDate": 1000000, 169 "_summary": { 170 "variations": { 171 "0": { 172 "rules": 0, 173 "nullRules": 0, 174 "targets": 1, 175 "contextTargets": 1, 176 "isFallthrough": true 177 }, 178 "1": { 179 "rules": 0, 180 "nullRules": 0, 181 "targets": 0, 182 "contextTargets": 1, 183 "isOff": true 184 } 185 }, 186 "prerequisites": 0 187 } 188 } 189 }, 190 "description": "This flag controls the example widgets", 191 "clientSideAvailability": { 192 "usingMobileKey": true, 193 "usingEnvironmentId": true 194 }, 195 "maintainerId": "569f183514f4432160000007", 196 "_maintainer": { 197 "_links": { 198 "self": { 199 "href": "/api/v2/members/569f183514f4432160000007", 200 "type": "application/json" 201 } 202 }, 203 "_id": "569f183514f4432160000007", 204 "role": "admin", 205 "email": "ariel@acme.com", 206 "firstName": "Ariel", 207 "lastName": "Flores" 208 }, 209 "maintainerTeamKey": "team-1", 210 "_maintainerTeam": { 211 "key": "team-key-123abc", 212 "name": "Example team", 213 "_links": { 214 "parent": { 215 "href": "/api/v2/teams", 216 "type": "application/json" 217 }, 218 "roles": { 219 "href": "/api/v2/teams/example-team/roles", 220 "type": "application/json" 221 }, 222 "self": { 223 "href": "/api/v2/teams/example-team", 224 "type": "application/json" 225 } 226 } 227 }, 228 "archivedDate": 1000000, 229 "deprecated": false, 230 "deprecatedDate": 1000000, 231 "defaults": { 232 "onVariation": 0, 233 "offVariation": 1 234 }, 235 "_purpose": "_purpose", 236 "migrationSettings": { 237 "contextKind": "device", 238 "stageCount": 6 239 }, 240 "includeInSnippet": true, 241 "goalIds": [ 242 "goalIds" 243 ] 244 }

1	{
2	"key": "flag-key-123",
3	"purpose": "migration",
4	"migrationSettings": {
5	"stageCount": 6,
6	"contextKind": "account"
7	}
8	}

1	curl -X POST https://app.launchdarkly.com/api/v2/flags/projectKey \
2	-H "Authorization: <apiKey>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"name": "My Flag",
6	"key": "flag-key-123abc",
7	"clientSideAvailability": {
8	"usingEnvironmentId": true,
9	"usingMobileKey": true
10	}
11	}'

1	{
2	"name": "My Flag",
3	"kind": "boolean",
4	"key": "flag-key-123abc",
5	"_version": 1,
6	"creationDate": 1000000,
7	"variations": [
8	{
9	"value": true,
10	"_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05",
11	"description": "description",
12	"name": "name"
13	},
14	{
15	"value": false,
16	"_id": "a00bf58d-d252-476c-b915-15a74becacb4",
17	"description": "description",
18	"name": "name"
19	}
20	],
21	"temporary": true,
22	"tags": [
23	"example-tag"
24	],
25	"_links": {
26	"parent": {
27	"href": "/api/v2/flags/my-project",
28	"type": "application/json"
29	},
30	"self": {
31	"href": "/api/v2/flags/my-project/my-flag",
32	"type": "application/json"
33	}
34	},
35	"experiments": {
36	"baselineIdx": 1,
37	"items": [
38	{
39	"metricKey": "my-metric",
40	"_metric": {
41	"_id": "5902deadbeef667524a01290",
42	"_versionId": "version-id-123abc",
43	"key": "metric-key-123abc",
44	"name": "My metric",
45	"kind": "pageview",
46	"_links": {
47	"parent": {
48	"href": "/api/v2/metrics/my-project",
49	"type": "application/json"
50	},
51	"self": {
52	"href": "/api/v2/metrics/my-project/my-metric",
53	"type": "application/json"
54	}
55	},
56	"tags": [
57	"tags"
58	],
59	"_creationDate": 1000000,
60	"experimentCount": 0,
61	"metricGroupCount": 0,
62	"_attachedFlagCount": 0,
63	"maintainerId": "569fdeadbeef1644facecafe",
64	"_maintainer": {
65	"_links": {
66	"self": {
67	"href": "/api/v2/members/569f183514f4432160000007",
68	"type": "application/json"
69	}
70	},
71	"_id": "569f183514f4432160000007",
72	"role": "admin",
73	"email": "ariel@acme.com",
74	"firstName": "Ariel",
75	"lastName": "Flores"
76	},
77	"category": "Error monitoring",
78	"isNumeric": true,
79	"percentileValue": 95
80	}
81	}
82	]
83	},
84	"customProperties": {
85	"key": {
86	"name": "Jira issues",
87	"value": [
88	"is-123",
89	"is-456"
90	]
91	}
92	},
93	"archived": false,
94	"environments": {
95	"my-environment": {
96	"on": false,
97	"archived": false,
98	"salt": "61eddeadbeef4da1facecafe3a60a397",
99	"sel": "810edeadbeef4844facecafe438f2999492",
100	"lastModified": 1627071171347,
101	"version": 1,
102	"_site": {
103	"href": "/default/my-environment/features/client-side-flag",
104	"type": "text/html"
105	},
106	"_environmentName": "My Environment",
107	"trackEvents": false,
108	"trackEventsFallthrough": false,
109	"targets": [
110	{
111	"values": [
112	"user-key-123abc"
113	],
114	"variation": 0,
115	"contextKind": "user"
116	}
117	],
118	"contextTargets": [
119	{
120	"values": [
121	"device-key-123abc"
122	],
123	"variation": 0,
124	"contextKind": "device"
125	}
126	],
127	"rules": [
128	{
129	"clauses": [
130	{
131	"attribute": "attribute",
132	"op": "op",
133	"values": [],
134	"negate": true
135	}
136	],
137	"trackEvents": true
138	}
139	],
140	"fallthrough": {
141	"variation": 0
142	},
143	"offVariation": 1,
144	"prerequisites": [
145	{
146	"key": "key",
147	"variation": 1
148	}
149	],
150	"_access": {
151	"denied": [
152	{
153	"action": "action",
154	"reason": {
155	"effect": "allow"
156	}
157	}
158	],
159	"allowed": [
160	{
161	"action": "action",
162	"reason": {
163	"effect": "allow"
164	}
165	}
166	]
167	},
168	"_debugEventsUntilDate": 1000000,
169	"_summary": {
170	"variations": {
171	"0": {
172	"rules": 0,
173	"nullRules": 0,
174	"targets": 1,
175	"contextTargets": 1,
176	"isFallthrough": true
177	},
178	"1": {
179	"rules": 0,
180	"nullRules": 0,
181	"targets": 0,
182	"contextTargets": 1,
183	"isOff": true
184	}
185	},
186	"prerequisites": 0
187	}
188	}
189	},
190	"description": "This flag controls the example widgets",
191	"clientSideAvailability": {
192	"usingMobileKey": true,
193	"usingEnvironmentId": true
194	},
195	"maintainerId": "569f183514f4432160000007",
196	"_maintainer": {
197	"_links": {
198	"self": {
199	"href": "/api/v2/members/569f183514f4432160000007",
200	"type": "application/json"
201	}
202	},
203	"_id": "569f183514f4432160000007",
204	"role": "admin",
205	"email": "ariel@acme.com",
206	"firstName": "Ariel",
207	"lastName": "Flores"
208	},
209	"maintainerTeamKey": "team-1",
210	"_maintainerTeam": {
211	"key": "team-key-123abc",
212	"name": "Example team",
213	"_links": {
214	"parent": {
215	"href": "/api/v2/teams",
216	"type": "application/json"
217	},
218	"roles": {
219	"href": "/api/v2/teams/example-team/roles",
220	"type": "application/json"
221	},
222	"self": {
223	"href": "/api/v2/teams/example-team",
224	"type": "application/json"
225	}
226	}
227	},
228	"archivedDate": 1000000,
229	"deprecated": false,
230	"deprecatedDate": 1000000,
231	"defaults": {
232	"onVariation": 0,
233	"offVariation": 1
234	},
235	"_purpose": "_purpose",
236	"migrationSettings": {
237	"contextKind": "device",
238	"stageCount": 6
239	},
240	"includeInSnippet": true,
241	"goalIds": [
242	"goalIds"
243	]
244	}