Skip to content
FlagSwiftDocs

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.create and flags.update to create and edit, held by Product managers, Developers, Release managers and Admins. flags.archive to archive (Developers, Release managers and Admins), flags.move to move and flags.delete to delete (Admins only). The Advanced tab is offered only to people who hold flags.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#

  1. 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
    FieldRuleDescription
    NamerequiredThe readable name shown in the console, for example New checkout flow. You can change it later.
    KeyrequiredLower case letters, numbers, hyphens and underscores, for example new-checkout-flow. Unique in the project and fixed after creation. SDKs use it.
    TypeBooleanBoolean, String, Number or JSON. Anything other than Boolean shows a Variants section.
    Descriptionup to 500What 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.
  2. 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.
  3. 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.

  4. 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.

  5. 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

Archiving is refused while another flag lists this one as a prerequisite, and the message names the flags that depend on it. If a code scan shows the flag is still used, deleting lists the files and asks you to switch on Delete it anyway. After that, those checks fall back to their default value.

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.

Request
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" }
    ]
  }'
Response
{
  "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.

Request
# 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
Archive response
{
  "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

The key lives in your code for as long as the flag does and cannot be renamed. Prefer something specific such as new-checkout-flow over test2, and put the “why” in the description.
Can I reuse the key of an archived flag?
No. An archived flag keeps its key, and creating a new flag with it is refused with a message telling you to restore the old one. Delete the archived flag first if you truly want the key back.
What happens to the flag in my app when I archive it?
Archived flags stop being served, so SDKs return your fallback (or false). Remove the code first, or confirm nothing reads the flag, before you archive.
Why can I not see the Advanced tab?
It is shown only to people who can move flags, which means Admins. Developers and Release managers can still archive a flag from the Flag lifecycle list or with the API.
Who is the owner of a new flag?
Whoever created it. Change it on the Lifecycle tab. See Give every flag an owner and an end date.

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.