Flags and Variations

Flags and Variations

A FlagForge feature flag is a typed definition with one or more named variations. Use boolean flags for feature gates, or use string, number, and JSON flags to deliver remote configuration values. The flag definition is shared by the project, while its enabled state, defaults, and targeting rules are configured separately for each environment.

Flag management requires a server API key. Send it as a Bearer token to the management endpoints:

curl -H "Authorization: Bearer $SERVER_KEY" \
  "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/flags"

Flag types and variations

A flag has a stable key, a type, and a variations array. Every variation has a unique key and a value; an optional name can provide a human-friendly label. Variation keys, rather than array positions, are used by environment defaults and targeting rules.

Keep the variation values consistent with the flag's declared type. For example, represent an enabled state as true, not the string "true".

Example definitions

A boolean feature gate can expose on and off variations:

{
  "key": "new-checkout",
  "name": "New checkout",
  "description": "Controls the new checkout experience.",
  "type": "boolean",
  "variations": [
    { "key": "on", "name": "Enabled", "value": true },
    { "key": "off", "name": "Disabled", "value": false }
  ]
}

A JSON flag can deliver structured remote config without adding another deployment:

{
  "key": "checkout-limits",
  "name": "Checkout limits",
  "type": "json",
  "variations": [
    {
      "key": "standard",
      "name": "Standard limits",
      "value": { "maxItems": 10, "showExpress": false }
    },
    {
      "key": "expanded",
      "name": "Expanded limits",
      "value": { "maxItems": 50, "showExpress": true }
    }
  ]
}

Create a flag

Use POST /v1/projects/{projectId}/flags with a server key. The flag key must be unique within the project, and the request must contain at least one variation.

curl -X POST "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/flags" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-checkout",
    "name": "New checkout",
    "description": "Controls the new checkout experience.",
    "type": "boolean",
    "variations": [
      { "key": "on", "value": true },
      { "key": "off", "value": false }
    ]
  }'

The response contains the flag definition and a configs array. When a flag is created, FlagForge creates a disabled configuration in every environment that already exists in the project:

{
  "key": "new-checkout",
  "type": "boolean",
  "variations": [
    { "key": "on", "value": true },
    { "key": "off", "value": false }
  ],
  "configs": [
    {
      "environmentKey": "production",
      "enabled": false,
      "defaultVariationKey": "on",
      "offVariationKey": "off",
      "rules": []
    }
  ]
}

The first variation is initially selected as defaultVariationKey, and the last variation is initially selected as offVariationKey. Because the new configuration is disabled, evaluations initially serve the off variation.

Select defaults per environment

defaultVariationKey is the fallthrough variation: it is served when the flag is enabled and no targeting rule matches. offVariationKey is served whenever the flag is disabled. These selections belong to an environment, so production and development can use different defaults for the same flag.

Replace one environment's configuration with PUT /v1/projects/{projectId}/flags/{flagKey}/targeting:

curl -X PUT "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/flags/new-checkout/targeting" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "enabled": true,
    "defaultVariationKey": "on",
    "offVariationKey": "off",
    "rules": []
  }'

The endpoint replaces the targeting configuration for the specified environment. Include all of the environment's desired fields in the request, including an empty rules array when there are no rules. The referenced variation keys must belong to the flag.

For rule-based targeting or percentage rollouts, add targeting rules to the same request. See Targeting, Segments, and Rollouts for the condition and rollout fields.

Update and read definitions

Update flag metadata or its variation list with PATCH /v1/projects/{projectId}/flags/{flagKey}. Each property is optional, so send only the fields that need to change. Targeting and per-environment defaults are not changed by this endpoint.

curl -X PATCH "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/flags/new-checkout" \
  -H "Authorization: Bearer $SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout experiment",
    "variations": [
      { "key": "on", "name": "New experience", "value": true },
      { "key": "off", "name": "Existing experience", "value": false }
    ]
  }'

Read one flag with GET /v1/projects/{projectId}/flags/{flagKey}, or list all project flags with GET /v1/projects/{projectId}/flags. Both responses expose the flag's type, named variations, and every environment configuration, including enabled, defaultVariationKey, offVariationKey, and rules.

curl -H "Authorization: Bearer $SERVER_KEY" \
  "$FLAGFORGE_URL/v1/projects/$PROJECT_ID/flags/new-checkout"

After a client key bootstraps /v1/config, the SDK evaluates these definitions locally in the selected environment. Use typed getters such as isEnabled, getString, getNumber, and getJson; see the SDK Client Guide for application integration.