Updating Flags (Experimental)

These experimental endpoints let you update feature flag values and segment overrides via the Admin API. They're meant as a simpler alternative to the current endpoints, which were designed with our dashboard user experience in mind:

Convenient to use in automation via CLI
Need no prior feature ID lookup — accepts name
Work the same regardless of Feature Versioning

caution

These endpoints are experimental and may change without notice. They cannot be used when change requests are enabled.

We're evaluating two approaches for updating flags — Option A (one change per request) and Option B (everything in one request). Each scenario below shows both. Try them and let us know which works better for you.

Common details:

Identify features by name or id (pick one, not both).
All endpoints return 204 No Content on success.
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"}`

Toggle a flag on or off

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

Option A — POST /api/experiments/environments/{environment_key}/update-flag-v1/

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

Option B — POST /api/experiments/environments/{environment_key}/update-flag-v2/

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

Update a feature value

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

Option A

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

Option B

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
  -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.

Option A

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

Option B — single request:

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
  -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"}
      }
    ]
  }'

The priority field on segment overrides is optional. Omit it to add at the lowest priority. Priority 1 is highest.

Configure multiple segment overrides

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

Option A — one request per segment override plus one for the default:

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

# Enterprise segment (highest priority)
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "pricing_tier"},
    "segment": {"id": 101, "priority": 1},
    "enabled": true,
    "value": {"type": "string", "value": "enterprise"}
  }'

# Premium segment
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "pricing_tier"},
    "segment": {"id": 202, "priority": 2},
    "enabled": true,
    "value": {"type": "string", "value": "premium"}
  }'

Option B — single request:

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
  -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": 1,
        "enabled": true,
        "value": {"type": "string", "value": "enterprise"}
      },
      {
        "segment_id": 202,
        "priority": 2,
        "enabled": true,
        "value": {"type": "string", "value": "premium"}
      }
    ]
  }'

Configure A/B/n experiments (multivariate flags)

Set up multivariate flags and customise weights per segment.

The multivariate_options list is absolute: omitting an option means deleting it.
Segment overrides can only re-weight options configured in the environment.
Deleting a multivariate option also deletes it in every segment override.
Segments already overriding multivariate options do not gain new variants added to the environment automatically.

Option A

# First, configure multivariate flags in the environment
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_payment_gateway_experiment"},
    "enabled": true,
    "value": {"type": "string", "value": "default"},
    "multivariate_options": [
      {"percentage_allocation": 20, "value": {"type": "string", "value": "sharp_payments"}},
      {"percentage_allocation": 10, "value": {"type": "string", "value": "gemstone_express"}}
    ]
  }'

# Multivariate option `id`s can be fetched via the admin API
curl -X GET '/api/v1/projects/{project_id}/features/{feature_id}/mv-options/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json'

# You can update (add, delete, re-weight) multivariate options in the environment
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_payment_gateway_experiment"},
    "multivariate_options": [
      {"id": 991, "percentage_allocation": 20, "value": {"type": "string", "value": "sharp_payments"}},
      {"percentage_allocation": 5, "value": {"type": "string", "value": "e-z-pay"}}
    ]
  }'

# Segment overrides can re-weight multivariate options (but can't add, delete, or update values)
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_payment_gateway_experiment"},
    "segment": {"id": 101, "priority": 1},
    "multivariate_options": [
      {"id": 991, "percentage_allocation": 0},
      {"id": 993, "percentage_allocation": 100}
    ]
  }'

Option B

# Configure the environment default and its multivariate options
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
  -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"},
      "multivariate_options": [
        {"percentage_allocation": 20, "value": {"type": "string", "value": "sharp_payments"}},
        {"percentage_allocation": 10, "value": {"type": "string", "value": "gemstone_express"}}
      ]
    }
  }'

# Multivariate option `id`s can be fetched via the admin API
curl -X GET '/api/v1/projects/{project_id}/features/{feature_id}/mv-options/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json'

# Re-weight the environment default and segment overrides in a single request
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_payment_gateway_experiment"},
    "environment_default": {
      "multivariate_options": [
        {
          "id": 991,
          "percentage_allocation": 30,
          "value": {"type": "string", "value": "sharp_payments"}
        },
        {
          "id": 992,
          "percentage_allocation": 5,
          "value": {"type": "string", "value": "gemstone_express"}
        }
      ]
    },
    "segment_overrides": [
      {
        "segment_id": 101,
        "priority": 1,
        "multivariate_options": [
          {"id": 991, "percentage_allocation": 100},
          {"id": 992, "percentage_allocation": 0}
        ]
      },
      {
        "segment_id": 202,
        "priority": 2,
        "multivariate_options": [
          {"id": 991, "percentage_allocation": 0},
          {"id": 992, "percentage_allocation": 100}
        ]
      }
    ]
  }'

# Segment overrides can re-weight multivariate options (but can't add, delete, or update values)
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "new_payment_gateway_experiment"},
    "segment_overrides": [
      {
        "segment_id": 101,
        "multivariate_options": [
          {"id": 991, "percentage_allocation": 50},
          {"id": 992, "percentage_allocation": 50}
        ]
      }
    ]
  }'

Remove a segment override

A separate endpoint for removing a segment override from a feature:

POST /api/experiments/environments/{environment_key}/delete-segment-override/

curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/delete-segment-override/' \
  -H 'Authorization: Api-Key <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "feature": {"name": "pricing_tier"},
    "segment": {"id": 202}
  }'

Quick reference

Aspect	Details
Feature ID	`name` or `id` — use one, not both
Value types	`string`, `integer`, `boolean`
Segment priority	Optional — omit to add at lowest priority; `1` is highest
Feature Versioning	Works the same whether enabled or not
Success response	`204 No Content`
Limitations	Incompatible with change requests
Full API schema	Swagger Explorer

Toggle a flag on or off​

Update a feature value​

Roll out a feature to a segment​

Configure multiple segment overrides​

Configure A/B/n experiments (multivariate flags)​

Remove a segment override​

Quick reference​

Toggle a flag on or off

Update a feature value

Roll out a feature to a segment

Configure multiple segment overrides

Configure A/B/n experiments (multivariate flags)

Remove a segment override

Quick reference