Updating Flags (Experimental)

The /api/experiments/environments/{environment_key}/update-flag/ endpoint lets you update feature flags, segment overrides, and variant allocations via the Admin API.

A successful response is always 204 No Content. The request body is a JSON object with the following fields:

• feature (required) — the feature to update, identified by name or id.
• environment_default (optional) — the default state of the feature in the environment.
• segment_overrides (optional) — a list of segment overrides for the feature.

Any attribute omitted in the payload will be left unchanged.

Values are passed as a value object with type and value (always a string):

Type	Example
string	{"type": "string", "value": "hello"}
integer	{"type": "integer", "value": "42"}
boolean	{"type": "boolean", "value": "true"}

Learn more in the API specification.

caution

This endpoint is experimental and may change without notice. It cannot be used when change requests are enabled.

Examples

Toggle a flag on or off

The simplest case — flip a feature flag in an environment.

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "maintenance_mode"},
    "environment_default": {"enabled": true}
  }'

Update a feature value

Change a feature's value — for example, setting a rate limit.

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "api_rate_limit"},
    "environment_default": {
      "enabled": true,
      "value": {"type": "integer", "value": "1000"}
    }
  }'

Roll out a feature to a segment

Enable a feature for a specific segment (e.g. beta users) while keeping it off for everyone else.

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_checkout"},
    "environment_default": {
      "enabled": false,
      "value": {"type": "boolean", "value": "false"}
    },
    "segment_overrides": [
      {
        "segment_id": 456,
        "enabled": true,
        "value": {"type": "boolean", "value": "true"}
      }
    ]
  }'

Configure multiple segment overrides

Set different values per segment — for example, pricing tiers.

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "pricing_tier"},
    "environment_default": {
      "enabled": true,
      "value": {"type": "string", "value": "standard"}
    },
    "segment_overrides": [
      {
        "segment_id": 101,
        "priority": 10,
        "enabled": true,
        "value": {"type": "string", "value": "enterprise"}
      },
      {
        "segment_id": 202,
        "priority": 20,
        "enabled": true,
        "value": {"type": "string", "value": "premium"}
      }
    ]
  }'

When adding a new segment override, and priority is omitted, priority is set to the position of the override in the segment_overrides list. The lowest number has the highest priority.

Configure A/B/n experiments (variants)

Set up features with weighted variants and customise weights per segment.

The variants list in environment_default defines the available variants for the feature, and their default weights in the environment. Each variant is identified by a key (slug format). Omitting a variant from the list deletes it in the environment, and in any segment overrides.

A weight is a fraction between 0 and 1. Any weight not allocated to variants serves the flag's default value.

The variants list in segment_overrides can only re-weight existing variants. Variants omitted from it keep their current weights for that segment.

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_payment_gateway_experiment"},
    "environment_default": {
      "enabled": true,
      "value": {"type": "string", "value": "default_gateway"},
      "variants": [
        {
          "key": "new_gateway_a",
          "weight": 0.1,
          "value": {"type": "string", "value": "sharp_payments"}
        },
        {
          "key": "new_gateway_b",
          "weight": 0.1,
          "value": {"type": "string", "value": "e_z_pay"}
        }
      ]
    }
  }'

Within the same request as above, or separately, you can also set different weights for a segment:

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_payment_gateway_experiment"},
    "segment_overrides": [
      {
        "segment_id": 101,
        "enabled": true,
        "value": {"type": "string", "value": "enterprise_gateway"},
        "variants": [
          {
            "key": "new_gateway_a",
            "weight": 0.25
          },
          {
            "key": "new_gateway_b",
            "weight": 0.25
          }
        ]
      }
    ]
  }'

Remove a segment override

A special delete attribute can be used to remove a segment override from a feature. It cannot be combined with other attributes besides segment_id.

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_checkout"},
    "segment_overrides": [
      {
        "segment_id": 456,
        "delete": true
      }
    ]
  }'