Create and edit flags

A flag has shared fields that are the same in every environment, and an environment configuration that can differ per environment. Read Concepts for the full list.

Create a flag in the dashboardCopy Anchor Link

1. In your workspace, open Flags and select New flag.
2. Fill in Basics:
   • Name: a human-readable name that the dashboard shows.
   • Key (required): the identifier your code uses. The dashboard allows lowercase letters, digits, ., _, and -. You cannot change the key later.
   • Description (optional): what the flag controls. Use it to record the owner and a review date. See Flag lifecycle.
   • Tags (optional): labels for filtering the flag list.
3. Choose a Type. You cannot change the type later.
4. Define the Variants, then mark one as the default and, optionally, one as the off variant.
5. Under Environments, turn the flag on in the environments where it must serve values. New flags start off in every environment.
6. Select Create flag.

The SDK preview card shows the SDK call for the key and type that you chose.

Choose a typeCopy Anchor Link

Every variant value must match the type. Toggld rejects a flag whose variant has the wrong type.

The type is shared across environments, because your code reads the flag with a typed getter. If you need a different type, create a new flag.

Variants, default, and offCopy Anchor Link

• A variant is a named value. The dashboard requires at least two variants.
• In the New flag form, boolean flags have the variants true and false. You cannot rename or remove them. Flags from onboarding and from the API can use other names, such as on and off.
• The default variant is served when the flag is on and no targeting rule matches. Use set default to choose it.
• The off variant is served when the flag is off. Use set off to choose it. If you do not choose one, Toggld serves the default variant when the flag is off.

Edit a flagCopy Anchor Link

Open the flag from the Flags list. The page has one tab per environment, in the environment order. Each tab shows the environment's color and whether the flag is on. Production environments show a Live badge. Select a tab to edit that environment.

At the top of the page, Edit opens Edit details. There you change the Name, Description, and Tags, which every environment shares. Select Save details to save them. The key and the type cannot change.

In the selected environment you can:

• Turn the flag on or off with the environment's switch, at the top of Who gets what.
• Choose the off variant in If off, and the default variant in Everyone else (or Everyone when there are no rules).
• Add, reorder, duplicate, and delete rules. See Targeting rules.
• Edit the variants and their values in Values. The Served by column shows where each variant is served. You can remove a variant only when nothing serves it.
• Test a user with Test a user. The dialog evaluates the saved rules of this environment in your browser. It does not test your draft, and it does not prove that your application received the change.
• See the evaluation count and the served variants of the last 7 days in Evaluations. See Analytics.
• Compare every environment side by side with Compare.

Below the environments, these sections open when you select them:

• Activity: the flag's recent changes, with the environment of each change.
• Use in code: the SDK call for this flag.
• Details: the key, type, and creation date.
• Delete: delete the flag. See Delete a flag.

Save changesCopy Anchor Link

Edits to an environment stay in a draft until you save. The save bar shows Unsaved changes in environment.

• Save environment (for example, Save Production) saves the selected environment only.
• Toggld saves each environment separately. To change two environments, save each one.
• Discard removes the draft for the selected environment.
• Shared details save on their own, with Save details.

You can also turn a flag on or off from the Flags list, with the switch in the Serving column. The change saves at once, and the message has Undo. In a production environment, the switch asks you to confirm first.

Wait for the success message before you treat a change as live. After a save, SDKs receive the change through synchronization, which is not instant. See how fast changes arrive.

If someone else saved the flag after you opened it, the save fails with a conflict. Select Load latest, then apply your change again.

Tags and metadataCopy Anchor Link

Tags organize flags in the dashboard and in the Management API. Toggld trims tags, converts them to lowercase, and removes duplicates. A flag can have up to 50 tags of up to 64 characters each. Tags never reach SDKs and have no effect on evaluation.

Metadata is a set of key-value pairs with string, number, or boolean values, such as { "team": "growth" }. Metadata is shared across environments. Evaluation results include it as flagMetadata in the Node.js SDK and as metadata in OFREP responses.

Delete a flagCopy Anchor Link

Open the flag, open the Delete section at the bottom of the page, and select Delete flag, then Delete forever. Deletion removes the flag and its configuration from every environment. You cannot undo it.

After deletion, any code that still reads the key receives its fallback value with the error code FLAG_NOT_FOUND. Remove the flag from your code before you delete it. See Retire a flag.

Flag limit during the betaCopy Anchor Link

A workspace can hold up to ten flags during the beta. The limit counts all existing flags, whether they are on or off. When you reach it, the dashboard shows a banner, and the API returns HTTP 402 with the error FlagLimitExceeded. Existing flags keep working. Paid upgrades are not available yet.

Deleting a flag frees a place, but deletion can change your application's behavior. Remove the flag from your code first.

Create and update flags with the APICopy Anchor Link

Use a management key to manage flags from scripts and CI. The key's environment decides which environment configuration a request reads or writes.

Create a flagCopy Anchor Link

curl https://api.toggld.io/api/v1/flags \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-checkout",
    "name": "New checkout",
    "type": "boolean",
    "variants": { "on": true, "off": false },
    "defaultVariant": "on",
    "offVariant": "off",
    "enabled": false,
    "tags": ["checkout"]
  }'

The response is HTTP 201 with the flag. A create request does this:

• It copies the variants, default variant, and off variant to every environment.
• It applies enabled and targeting only to the key's environment. Other environments start off, with no rules.

If you omit enabled, the flag starts off, as it does in the dashboard. Send "enabled": true to turn it on in the key's environment right away.

Update part of a flagCopy Anchor Link

PATCH /api/v1/flags/{key} changes only the fields that you send. Variants, default variant, off variant, enabled state, and targeting change only in the key's environment. Name, description, tags, and metadata change in every environment.

To prevent lost updates, read the flag first and send its version as expectedVersion:

curl https://api.toggld.io/api/v1/flags/new-checkout \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY"

curl -X PATCH https://api.toggld.io/api/v1/flags/new-checkout \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expectedVersion": "VERSION_FROM_THE_GET_RESPONSE", "enabled": true }'

If another change was saved after your read, the API returns HTTP 409 with the error FlagConflict. Read the flag again before you retry.

Replace a flagCopy Anchor Link

PUT /api/v1/flags/{key} replaces the flag. Fields that you omit go back to their defaults: enabled becomes false, targeting becomes empty, and tags and metadata become empty. Prefer PATCH unless you send the complete flag.

ErrorsCopy Anchor Link

See Errors for the response format and the API reference for every field.