Experimental: Updating Flags

We're experimenting with a set of new endpoints for updating feature flags. They should provide better ergonomics for the most common use cases, while keeping operations agnostic to Feature Versioning. We plan to dogfood them in our own dashboard and CLI, and eventually make them canonical.

caution

These endpoints are experimental and may change without notice. Note these limitations:

• They cannot be used when change requests are enabled.
• They do not support identity overrides.

These may be lifted in the future.

Learn more in the [API specification](link TODO).

Updating a flag

We support both PATCH and PUT methods for updating a flag. Attributes omitted from a PATCH payload are left unchanged. Use PUT with caution, as it overwrites every attribute this endpoint accepts for the environment.

Values are passed as a value object with a type and a value 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:

curl -X PATCH 'https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/' \
  -H 'Authorization: Api-Key {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "environment_default": {"enabled": true}
  }'

Update a feature value

Change a feature's default value in an environment:

curl -X PATCH 'https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/' \
  -H 'Authorization: Api-Key {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "environment_default": {
      "value": {"type": "integer", "value": "1000"}
    }
  }'

Roll out a feature to a segment

Enable a flag for one or more segments, while keeping it off for everyone else:

curl -X PATCH 'https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/' \
  -H 'Authorization: Api-Key {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "environment_default": {
      "enabled": false
    },
    "segment_overrides": [
      {
        "segment": {"id": 101},
        "enabled": true,
        "priority": 10
      },
      {
        "segment": {"id": 202},
        "enabled": true,
        "priority": 20
      }
    ]
  }'

Segments can also override the feature's value for the environment:

curl -X PATCH 'https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/' \
  -H 'Authorization: Api-Key {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "segment_overrides": [
      {
        "segment": {"id": 101},
        "value": {"type": "string", "value": "enterprise"}
      }
    ]
  }'

Overrides listed in a PATCH payload are added or updated by segment; overrides not listed are left unchanged. When adding a new segment override, if priority is omitted, it defaults to the override's position in the segment_overrides list. The lowest number has the highest priority.

Remove a segment override

A full representation of all segment overrides for a feature must be passed to /segment-overrides/:

curl -X PUT 'https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/segment-overrides/' \
  -H 'Authorization: Api-Key {api_key}' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "segment": {"id": 101},
      "priority": 10,
      "value": {"type": "string", "value": "enterprise"}
    }
  ]'

Any overrides omitted from the list are deleted.

Re-weight variants (A/B/n)

On previously configured multivariate features (e.g. experiments), the weight of each variant can be adjusted in the environment and per segment with the variants property.

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

Re-weight the variants for a feature in the environment:

curl -X PATCH 'https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/' \
  -H 'Authorization: Api-Key {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "environment_default": {
      "variants": [
        {"key": "variant_a", "weight": 10},
        {"key": "variant_b", "weight": 10.5}
      ]
    }
  }'

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

curl -X PATCH 'https://api.flagsmith.com/api/__future__/environments/{environment_key}/features/{feature_id}/' \
  -H 'Authorization: Api-Key {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "segment_overrides": [
      {
        "segment": {"id": 101},
        "variants": [
          {"key": "variant_a", "weight": 25},
          {"key": "variant_b", "weight": 25}
        ]
      }
    ]
  }'

In both environment_default and segment_overrides, the variants list must include all variants for the feature, even if their weight is zero.