Create, edit and organize flags
Create a flag with a clear key, keep its details tidy, and move, archive, restore or delete it when its job changes.
- Time
- About 10 min
- Who can do it
- Developer, Release manager or Admin to create and edit. Admin for the Advanced tab: move, archive from the flag, delete.
- Where
- Feature Flags in the console, then the flag's Overview and Advanced tabs
- You finish with
- A flag with a stable key, found and managed from one list
What and why#
What a flag is#
A flag has a key your code reads, a readable name for the console, a type and a separate on or off state in every environment. The key and the type are fixed at creation. Everything else can change.
Why the shape matters#
A flag outlives the code that first reads it, so a clear key, a description of what it controls and a tidy exit (archive, then delete) keep a project readable as flags pile up. Archiving is reversible and keeps history, which makes it the safe default for retiring a flag.
Before you start#
- A project that is not archived. Flags in an archived project are read-only.
- Permissions:
flags.createandflags.updateto create and edit, held by Product managers, Developers, Release managers and Admins.flags.archiveto archive (Developers, Release managers and Admins),flags.moveto move andflags.deleteto delete (Admins only). The Advanced tab is offered only to people who holdflags.move, so non-Admins archive from the Flag lifecycle list or the API. - The flag type, if it is not a plain on or off. See Choose a flag type and variants, because the type cannot change later.
Walk through it#
Create the flag
Open Flags and choose New Flag. In the Create Flag form, pick a Project (the field is hidden when you opened the list from a project), then fill in Name (required), Key (required), Type and an optional Description. Choose Create Flag.
Create Flag fields Field Rule Description Name required The readable name shown in the console, for example New checkout flow. You can change it later. Key required Lower case letters, numbers, hyphens and underscores, for example new-checkout-flow. Unique in the project and fixed after creation. SDKs use it.Type Boolean Boolean, String, Number or JSON. Anything other than Boolean shows a Variants section. Description up to 500 What the flag controls and when it should be on. Shown on the Overview tab. The Create Flag dialog with a String flag. Choosing a type other than Boolean adds the Variants section, starting with the rows control and treatment. Typing the Name suggests a Key until you edit the Key yourself. The button stays disabled until the form is valid and, for non-Boolean types, until every variant row is valid.
You should see. The flag opens in the list with one switch per environment, all off. The form told you so before you saved: it is created disabled in all your environments.Edit the details
Open the flag. On the Overview tab, change the Display name (required) or the Description and choose Save changes. Discard puts the saved values back. The key and the type cannot change.
You should see. The new name shows in the list. The change is recorded in the audit log.Find and pin flags
The list has a search box (Search by name or key) and filters for Environment, Status (Enabled or Disabled, available once you choose an environment), Type and Archived flags (Active, Archived, or Active and archived). Pin the flags you check often. Pins are yours alone, and you can pin up to 3 flags; a fourth asks you to unpin one first.
Move a flag to another project
Admins only. On the Advanced tab, choose a Target project under Move to another project, choose Move flag and confirm. Every environment setting and the full history come with it.
A move is refused when the key already exists in the target project, when the target project is archived, when other flags use this one as a prerequisite, or when this flag has prerequisites of its own. Remove those dependencies first.
Archive, restore or delete
On the Advanced tab, Archive flag hides the flag and makes it read-only. Its configuration and history are kept, SDKs stop serving it and checks fall back to their default. Restore flag brings back the configuration it had. Delete permanently appears only for archived flags and needs an Admin: you type the flag key (case-sensitive) to confirm.
The Advanced tab of an active flag. Archived flags show Restore flag and Delete permanently instead. The dialog that opens from Archive flag, and the same dialog while the request runs. You should see. An archived flag leaves the default list and shows under the Archived filter. The Overview, Variants, Targeting & rollout, Releases and Lifecycle tabs become read-only, and the Advanced tab offers Restore and Delete.
Check before you archive or delete
Do it with the API#
These Dashboard API calls use your signed-in session cookie (see Calling the Dashboard API in the APIs section). Responses are wrapped as { status, message, data }.
Create a flag with variants
Needs flags.create. The response is trimmed here: it also carries every environment's configuration.
curl -X POST "https://flags.example.com/api/flags" \
-b jar.txt -H "Content-Type: application/json" \
-d '{
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "Which checkout page layout customers see",
"projectId": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"type": "string",
"variants": [
{ "key": "classic", "value": "classic" },
{ "key": "compact", "value": "compact" }
]
}'{
"status": "success",
"message": "Flag created successfully",
"data": {
"id": "b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05",
"name": "checkout-layout",
"displayName": "Checkout layout",
"type": "string",
"variants": [
{ "key": "classic", "value": "classic" },
{ "key": "compact", "value": "compact" }
],
"projectId": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"archivedAt": null,
"owner": "you@example.com",
"permanent": false
}
}Edit, archive and restore
Send projectId in the PATCH body to move a flag (it also needs flags.move). Delete with DELETE /api/flags/FLAG_ID, and add ?force=true only when you accept that code still using the flag falls back to its default.
# Rename (flags.update)
curl -X PATCH "https://flags.example.com/api/flags/FLAG_ID" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"displayName":"Checkout page layout"}'
# Archive (flags.archive), then restore (flags.update)
curl -X POST "https://flags.example.com/api/flags/FLAG_ID/archive" -b jar.txt
curl -X POST "https://flags.example.com/api/flags/FLAG_ID/restore" -b jar.txt{
"status": "success",
"message": "Flag archived",
"data": { "id": "b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05", "name": "checkout-layout", "archivedAt": "2026-10-03T10:41:00.000Z" }
}List and search with GET /api/flags?projectId=...&search=checkout&archived=all. See the Flags API for every query parameter.
What to check#
- The new flag is off in every environment.
- An archived flag shows under the Archived filter and is read-only.
- Archive, restore and move appear in the audit log and in the flag's History tab.
Good to know#
Name the key like a variable
new-checkout-flow over test2, and put the “why” in the description.Can I reuse the key of an archived flag?
What happens to the flag in my app when I archive it?
false). Remove the code first, or confirm nothing reads the flag, before you archive.Why can I not see the Advanced tab?
Who is the owner of a new flag?
If something goes wrong#
A flag with this key already exists in this project
Why: Keys are unique per project. An archived flag counts.
Fix: Pick another key. If the message says an archived flag has it, restore that flag from the Advanced tab instead.
Key may only contain lowercase letters, numbers, hyphens and underscores
Why: The key has a space, a capital letter or another character.
Fix: Use a form like new-checkout-flow.
Cannot archive: it is a prerequisite of another flag
Why: Another flag lists this one under Prerequisites in some environment (FLAG_IS_PREREQUISITE).
Fix: Open the flag named in the message, remove the prerequisite on its Targeting & rollout tab, then archive again.
This project is archived. Restore it to make changes
Why: Flags in an archived project are read-only (PROJECT_ARCHIVED).
Fix: Restore the project from Manage projects first.
This flag is still used in N places in code
Why: Deleting is blocked while a code scan reports references (HAS_CODE_REFERENCES).
Fix: Remove the references and let the next scan run, or switch on Delete it anyway if you accept the fallback.