Create a feature flag

POST

/api/v2/flags/:projectKey

POST

/api/v2/flags/:projectKey

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

1 {
2   "name": "My Flag",
3   "kind": "boolean",
4   "key": "flag-key-123abc",
5   "_version": 1,
6   "creationDate": 1494437420312,
7   "variations": [
8     {
9       "value": null,
10       "_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
11     },
12     {
13       "value": null,
14       "_id": "a00bf58d-d252-476c-b915-15a74becacb4"
15     }
16   ],
17   "temporary": true,
18   "tags": [
19     "example-tag"
20   ],
21   "_links": {
22     "parent": {
23       "href": "/api/v2/flags/my-project",
24       "type": "application/json"
25     },
26     "self": {
27       "href": "/api/v2/flags/my-project/my-flag",
28       "type": "application/json"
29     }
30   },
31   "experiments": {
32     "baselineIdx": 1,
33     "items": [
34       {
35         "metricKey": "my-metric",
36         "_metric": {
37           "_id": "5902deadbeef667524a01290",
38           "_versionId": "version-id-123abc",
39           "key": "metric-key-123abc",
40           "name": "My metric",
41           "kind": "custom",
42           "_links": {
43             "parent": {
44               "href": "/api/v2/metrics/my-project",
45               "type": "application/json"
46             },
47             "self": {
48               "href": "/api/v2/metrics/my-project/my-metric",
49               "type": "application/json"
50             }
51           },
52           "tags": [],
53           "_creationDate": 1628192791148,
54           "dataSource": {
55             "key": "string",
56             "environmentKey": "string",
57             "_name": "string",
58             "_integrationKey": "string"
59           },
60           "experimentCount": 0,
61           "metricGroupCount": 0,
62           "activeExperimentCount": 2,
63           "activeGuardedRolloutCount": 1,
64           "_version": 1,
65           "_attachedFlagCount": 0,
66           "_site": {},
67           "_access": {
68             "denied": [
69               {
70                 "action": "string",
71                 "reason": {
72                   "effect": "allow",
73                   "resources": [
74                     "proj/*:env/*;qa_*:/flag/*"
75                   ],
76                   "notResources": [
77                     "string"
78                   ],
79                   "actions": [
80                     "*"
81                   ],
82                   "notActions": [
83                     "string"
84                   ],
85                   "role_name": "string"
86                 }
87               }
88             ],
89             "allowed": [
90               {
91                 "action": "string",
92                 "reason": {
93                   "effect": "allow",
94                   "resources": [
95                     "proj/*:env/*;qa_*:/flag/*"
96                   ],
97                   "notResources": [
98                     "string"
99                   ],
100                   "actions": [
101                     "*"
102                   ],
103                   "notActions": [
104                     "string"
105                   ],
106                   "role_name": "string"
107                 }
108               }
109             ]
110           },
111           "lastModified": {
112             "date": "2021-08-05T19:46:31.148082Z"
113           },
114           "maintainerId": "569fdeadbeef1644facecafe",
115           "_maintainer": {
116             "_links": {
117               "self": {
118                 "href": "/api/v2/members/569f183514f4432160000007",
119                 "type": "application/json"
120               }
121             },
122             "_id": "569f183514f4432160000007",
123             "role": "admin",
124             "email": "ariel@acme.com"
125           },
126           "description": "string",
127           "category": "Error monitoring",
128           "isNumeric": true,
129           "successCriteria": "HigherThanBaseline",
130           "unit": "string",
131           "eventKey": "Order placed",
132           "analysisUnits": [
133             "user"
134           ],
135           "filters": {
136             "type": "contextAttribute",
137             "op": "in",
138             "values": [
139               "JP"
140             ],
141             "negate": false
142           },
143           "unitAggregationType": "average",
144           "analysisType": "mean",
145           "percentileValue": 95,
146           "eventDefault": {
147             "disabled": true,
148             "value": 0
149           },
150           "lastSeen": 1,
151           "archived": true,
152           "archivedAt": 1609459200000,
153           "selector": "string",
154           "urls": [
155             "[{\"kind\":\"exact\",\"url\":\"https://www.example.com/page1\"}]"
156           ],
157           "windowStartOffset": 1,
158           "windowEndOffset": 1,
159           "traceQuery": "service.name = \"checkout\"",
160           "traceValueLocation": "duration",
161           "randomizationUnits": [
162             "user"
163           ]
164         },
165         "environments": [
166           "production",
167           "test",
168           "my-environment"
169         ],
170         "_environmentSettings": {}
171       }
172     ]
173   },
174   "customProperties": "{\"jira.issues\":{\"name\":\"Jira issues\",\"value\":[\"is-123\",\"is-456\"]}}",
175   "archived": false,
176   "description": "This flag controls the example widgets",
177   "clientSideAvailability": {},
178   "maintainerId": "569f183514f4432160000007",
179   "_maintainer": {
180     "_links": {
181       "self": {
182         "href": "/api/v2/members/569f183514f4432160000007",
183         "type": "application/json"
184       }
185     },
186     "_id": "569f183514f4432160000007",
187     "role": "admin",
188     "email": "ariel@acme.com",
189     "firstName": "Ariel",
190     "lastName": "Flores"
191   },
192   "maintainerTeamKey": "team-1",
193   "_maintainerTeam": {
194     "key": "team-key-123abc",
195     "name": "Example team",
196     "_links": {
197       "parent": {
198         "href": "/api/v2/teams",
199         "type": "application/json"
200       },
201       "roles": {
202         "href": "/api/v2/teams/example-team/roles",
203         "type": "application/json"
204       },
205       "self": {
206         "href": "/api/v2/teams/example-team",
207         "type": "application/json"
208       }
209     }
210   },
211   "archivedDate": 1494437420312,
212   "deprecated": false,
213   "deprecatedDate": 1494437420312,
214   "defaults": {
215     "onVariation": 0,
216     "offVariation": 1
217   },
218   "_purpose": "string",
219   "migrationSettings": {
220     "contextKind": "device",
221     "stageCount": 6
222   },
223   "environments": {
224     "my-environment": {
225       "on": false,
226       "archived": false,
227       "salt": "61eddeadbeef4da1facecafe3a60a397",
228       "sel": "810edeadbeef4844facecafe438f2999492",
229       "lastModified": 1627071171347,
230       "version": 1,
231       "_site": {
232         "href": "/default/my-environment/features/client-side-flag",
233         "type": "text/html"
234       },
235       "_environmentName": "My Environment",
236       "trackEvents": false,
237       "trackEventsFallthrough": false,
238       "targets": [
239         {
240           "values": [
241             "user-key-123abc"
242           ],
243           "variation": 0,
244           "contextKind": "user"
245         }
246       ],
247       "contextTargets": [
248         {
249           "values": [
250             "device-key-123abc"
251           ],
252           "variation": 0,
253           "contextKind": "device"
254         }
255       ],
256       "rules": [],
257       "fallthrough": {
258         "variation": 0
259       },
260       "offVariation": 1,
261       "prerequisites": [],
262       "_summary": {
263         "variations": {
264           "0": {
265             "rules": 0,
266             "nullRules": 0,
267             "targets": 1,
268             "contextTargets": 1,
269             "isFallthrough": true
270           },
271           "1": {
272             "rules": 0,
273             "nullRules": 0,
274             "targets": 0,
275             "isOff": true
276           }
277         },
278         "prerequisites": 0
279       }
280     }
281   },
282   "includeInSnippet": true,
283   "goalIds": []
284 }

Create a feature flag with the given name, key, and variations. <details> <summary>Click to expand instructions for <strong>creating a migration flag</strong></summary> ### 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: ```json { "key": "flag-key-123", "purpose": "migration", "migrationSettings": { "stageCount": 6, "contextKind": "account" } } ``` To learn more, read [Migration Flags](https://launchdarkly.com/docs/home/flags/migration). </details>

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

{
  "name": "My Flag",
  "kind": "boolean",
  "key": "flag-key-123abc",
  "_version": 1,
  "creationDate": 1494437420312,
  "variations": [
    {
      "value": null,
      "_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
    },
    {
      "value": null,
      "_id": "a00bf58d-d252-476c-b915-15a74becacb4"
    }
  ],
  "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": 1,
    "items": [
      {
        "metricKey": "my-metric",
        "_metric": {
          "_id": "5902deadbeef667524a01290",
          "_versionId": "version-id-123abc",
          "key": "metric-key-123abc",
          "name": "My metric",
          "kind": "custom",
          "_links": {
            "parent": {
              "href": "/api/v2/metrics/my-project",
              "type": "application/json"
            },
            "self": {
              "href": "/api/v2/metrics/my-project/my-metric",
              "type": "application/json"
            }
          },
          "tags": [],
          "_creationDate": 1628192791148,
          "dataSource": {
            "key": "string",
            "environmentKey": "string",
            "_name": "string",
            "_integrationKey": "string"
          },
          "experimentCount": 0,
          "metricGroupCount": 0,
          "activeExperimentCount": 2,
          "activeGuardedRolloutCount": 1,
          "_version": 1,
          "_attachedFlagCount": 0,
          "_site": {},
          "_access": {
            "denied": [
              {
                "action": "string",
                "reason": {
                  "effect": "allow",
                  "resources": [
                    "proj/*:env/*;qa_*:/flag/*"
                  ],
                  "notResources": [
                    "string"
                  ],
                  "actions": [
                    "*"
                  ],
                  "notActions": [
                    "string"
                  ],
                  "role_name": "string"
                }
              }
            ],
            "allowed": [
              {
                "action": "string",
                "reason": {
                  "effect": "allow",
                  "resources": [
                    "proj/*:env/*;qa_*:/flag/*"
                  ],
                  "notResources": [
                    "string"
                  ],
                  "actions": [
                    "*"
                  ],
                  "notActions": [
                    "string"
                  ],
                  "role_name": "string"
                }
              }
            ]
          },
          "lastModified": {
            "date": "2021-08-05T19:46:31.148082Z"
          },
          "maintainerId": "569fdeadbeef1644facecafe",
          "_maintainer": {
            "_links": {
              "self": {
                "href": "/api/v2/members/569f183514f4432160000007",
                "type": "application/json"
              }
            },
            "_id": "569f183514f4432160000007",
            "role": "admin",
            "email": "ariel@acme.com"
          },
          "description": "string",
          "category": "Error monitoring",
          "isNumeric": true,
          "successCriteria": "HigherThanBaseline",
          "unit": "string",
          "eventKey": "Order placed",
          "analysisUnits": [
            "user"
          ],
          "filters": {
            "type": "contextAttribute",
            "op": "in",
            "values": [
              "JP"
            ],
            "negate": false
          },
          "unitAggregationType": "average",
          "analysisType": "mean",
          "percentileValue": 95,
          "eventDefault": {
            "disabled": true,
            "value": 0
          },
          "lastSeen": 1,
          "archived": true,
          "archivedAt": 1609459200000,
          "selector": "string",
          "urls": [
            "[{\"kind\":\"exact\",\"url\":\"https://www.example.com/page1\"}]"
          ],
          "windowStartOffset": 1,
          "windowEndOffset": 1,
          "traceQuery": "service.name = \"checkout\"",
          "traceValueLocation": "duration",
          "randomizationUnits": [
            "user"
          ]
        },
        "environments": [
          "production",
          "test",
          "my-environment"
        ],
        "_environmentSettings": {}
      }
    ]
  },
  "customProperties": "{\"jira.issues\":{\"name\":\"Jira issues\",\"value\":[\"is-123\",\"is-456\"]}}",
  "archived": false,
  "description": "This flag controls the example widgets",
  "clientSideAvailability": {},
  "maintainerId": "569f183514f4432160000007",
  "_maintainer": {
    "_links": {
      "self": {
        "href": "/api/v2/members/569f183514f4432160000007",
        "type": "application/json"
      }
    },
    "_id": "569f183514f4432160000007",
    "role": "admin",
    "email": "ariel@acme.com",
    "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"
      }
    }
  },
  "archivedDate": 1494437420312,
  "deprecated": false,
  "deprecatedDate": 1494437420312,
  "defaults": {
    "onVariation": 0,
    "offVariation": 1
  },
  "_purpose": "string",
  "migrationSettings": {
    "contextKind": "device",
    "stageCount": 6
  },
  "environments": {
    "my-environment": {
      "on": false,
      "archived": false,
      "salt": "61eddeadbeef4da1facecafe3a60a397",
      "sel": "810edeadbeef4844facecafe438f2999492",
      "lastModified": 1627071171347,
      "version": 1,
      "_site": {
        "href": "/default/my-environment/features/client-side-flag",
        "type": "text/html"
      },
      "_environmentName": "My Environment",
      "trackEvents": false,
      "trackEventsFallthrough": false,
      "targets": [
        {
          "values": [
            "user-key-123abc"
          ],
          "variation": 0,
          "contextKind": "user"
        }
      ],
      "contextTargets": [
        {
          "values": [
            "device-key-123abc"
          ],
          "variation": 0,
          "contextKind": "device"
        }
      ],
      "rules": [],
      "fallthrough": {
        "variation": 0
      },
      "offVariation": 1,
      "prerequisites": [],
      "_summary": {
        "variations": {
          "0": {
            "rules": 0,
            "nullRules": 0,
            "targets": 1,
            "contextTargets": 1,
            "isFallthrough": true
          },
          "1": {
            "rules": 0,
            "nullRules": 0,
            "targets": 0,
            "isOff": true
          }
        },
        "prerequisites": 0
      }
    }
  },
  "includeInSnippet": true,
  "goalIds": []
}

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

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.

Create a feature flag

Create a feature flag

Creating a migration flag

Authentication

Path parameters

Query parameters

Request

Response

Errors

Creating a migration flag

Authentication

Path parameters

Query parameters

Request

Response

Errors

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

1	{
2	"name": "My Flag",
3	"kind": "boolean",
4	"key": "flag-key-123abc",
5	"_version": 1,
6	"creationDate": 1494437420312,
7	"variations": [
8	{
9	"value": null,
10	"_id": "e432f62b-55f6-49dd-a02f-eb24acf39d05"
11	},
12	{
13	"value": null,
14	"_id": "a00bf58d-d252-476c-b915-15a74becacb4"
15	}
16	],
17	"temporary": true,
18	"tags": [
19	"example-tag"
20	],
21	"_links": {
22	"parent": {
23	"href": "/api/v2/flags/my-project",
24	"type": "application/json"
25	},
26	"self": {
27	"href": "/api/v2/flags/my-project/my-flag",
28	"type": "application/json"
29	}
30	},
31	"experiments": {
32	"baselineIdx": 1,
33	"items": [
34	{
35	"metricKey": "my-metric",
36	"_metric": {
37	"_id": "5902deadbeef667524a01290",
38	"_versionId": "version-id-123abc",
39	"key": "metric-key-123abc",
40	"name": "My metric",
41	"kind": "custom",
42	"_links": {
43	"parent": {
44	"href": "/api/v2/metrics/my-project",
45	"type": "application/json"
46	},
47	"self": {
48	"href": "/api/v2/metrics/my-project/my-metric",
49	"type": "application/json"
50	}
51	},
52	"tags": [],
53	"_creationDate": 1628192791148,
54	"dataSource": {
55	"key": "string",
56	"environmentKey": "string",
57	"_name": "string",
58	"_integrationKey": "string"
59	},
60	"experimentCount": 0,
61	"metricGroupCount": 0,
62	"activeExperimentCount": 2,
63	"activeGuardedRolloutCount": 1,
64	"_version": 1,
65	"_attachedFlagCount": 0,
66	"_site": {},
67	"_access": {
68	"denied": [
69	{
70	"action": "string",
71	"reason": {
72	"effect": "allow",
73	"resources": [
74	"proj/:env/;qa_:/flag/"
75	],
76	"notResources": [
77	"string"
78	],
79	"actions": [
80	"*"
81	],
82	"notActions": [
83	"string"
84	],
85	"role_name": "string"
86	}
87	}
88	],
89	"allowed": [
90	{
91	"action": "string",
92	"reason": {
93	"effect": "allow",
94	"resources": [
95	"proj/:env/;qa_:/flag/"
96	],
97	"notResources": [
98	"string"
99	],
100	"actions": [
101	"*"
102	],
103	"notActions": [
104	"string"
105	],
106	"role_name": "string"
107	}
108	}
109	]
110	},
111	"lastModified": {
112	"date": "2021-08-05T19:46:31.148082Z"
113	},
114	"maintainerId": "569fdeadbeef1644facecafe",
115	"_maintainer": {
116	"_links": {
117	"self": {
118	"href": "/api/v2/members/569f183514f4432160000007",
119	"type": "application/json"
120	}
121	},
122	"_id": "569f183514f4432160000007",
123	"role": "admin",
124	"email": "ariel@acme.com"
125	},
126	"description": "string",
127	"category": "Error monitoring",
128	"isNumeric": true,
129	"successCriteria": "HigherThanBaseline",
130	"unit": "string",
131	"eventKey": "Order placed",
132	"analysisUnits": [
133	"user"
134	],
135	"filters": {
136	"type": "contextAttribute",
137	"op": "in",
138	"values": [
139	"JP"
140	],
141	"negate": false
142	},
143	"unitAggregationType": "average",
144	"analysisType": "mean",
145	"percentileValue": 95,
146	"eventDefault": {
147	"disabled": true,
148	"value": 0
149	},
150	"lastSeen": 1,
151	"archived": true,
152	"archivedAt": 1609459200000,
153	"selector": "string",
154	"urls": [
155	"[{\"kind\":\"exact\",\"url\":\"https://www.example.com/page1\"}]"
156	],
157	"windowStartOffset": 1,
158	"windowEndOffset": 1,
159	"traceQuery": "service.name = \"checkout\"",
160	"traceValueLocation": "duration",
161	"randomizationUnits": [
162	"user"
163	]
164	},
165	"environments": [
166	"production",
167	"test",
168	"my-environment"
169	],
170	"_environmentSettings": {}
171	}
172	]
173	},
174	"customProperties": "{\"jira.issues\":{\"name\":\"Jira issues\",\"value\":[\"is-123\",\"is-456\"]}}",
175	"archived": false,
176	"description": "This flag controls the example widgets",
177	"clientSideAvailability": {},
178	"maintainerId": "569f183514f4432160000007",
179	"_maintainer": {
180	"_links": {
181	"self": {
182	"href": "/api/v2/members/569f183514f4432160000007",
183	"type": "application/json"
184	}
185	},
186	"_id": "569f183514f4432160000007",
187	"role": "admin",
188	"email": "ariel@acme.com",
189	"firstName": "Ariel",
190	"lastName": "Flores"
191	},
192	"maintainerTeamKey": "team-1",
193	"_maintainerTeam": {
194	"key": "team-key-123abc",
195	"name": "Example team",
196	"_links": {
197	"parent": {
198	"href": "/api/v2/teams",
199	"type": "application/json"
200	},
201	"roles": {
202	"href": "/api/v2/teams/example-team/roles",
203	"type": "application/json"
204	},
205	"self": {
206	"href": "/api/v2/teams/example-team",
207	"type": "application/json"
208	}
209	}
210	},
211	"archivedDate": 1494437420312,
212	"deprecated": false,
213	"deprecatedDate": 1494437420312,
214	"defaults": {
215	"onVariation": 0,
216	"offVariation": 1
217	},
218	"_purpose": "string",
219	"migrationSettings": {
220	"contextKind": "device",
221	"stageCount": 6
222	},
223	"environments": {
224	"my-environment": {
225	"on": false,
226	"archived": false,
227	"salt": "61eddeadbeef4da1facecafe3a60a397",
228	"sel": "810edeadbeef4844facecafe438f2999492",
229	"lastModified": 1627071171347,
230	"version": 1,
231	"_site": {
232	"href": "/default/my-environment/features/client-side-flag",
233	"type": "text/html"
234	},
235	"_environmentName": "My Environment",
236	"trackEvents": false,
237	"trackEventsFallthrough": false,
238	"targets": [
239	{
240	"values": [
241	"user-key-123abc"
242	],
243	"variation": 0,
244	"contextKind": "user"
245	}
246	],
247	"contextTargets": [
248	{
249	"values": [
250	"device-key-123abc"
251	],
252	"variation": 0,
253	"contextKind": "device"
254	}
255	],
256	"rules": [],
257	"fallthrough": {
258	"variation": 0
259	},
260	"offVariation": 1,
261	"prerequisites": [],
262	"_summary": {
263	"variations": {
264	"0": {
265	"rules": 0,
266	"nullRules": 0,
267	"targets": 1,
268	"contextTargets": 1,
269	"isFallthrough": true
270	},
271	"1": {
272	"rules": 0,
273	"nullRules": 0,
274	"targets": 0,
275	"isOff": true
276	}
277	},
278	"prerequisites": 0
279	}
280	}
281	},
282	"includeInSnippet": true,
283	"goalIds": []
284	}

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