Skip to main content

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 it in our own dashboard and CLI, and eventually make it canonical.

caution

This endpoint is experimental and may change without notice. Mind some limitations:

  • It cannot be used when change requests are enabled.
  • It does 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. Use PUT with caution, as it overwrites all configuration this endpoint supports in the environment.

Values are

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"}
      }
    ]
  }'

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.

Roll back a feature from a segment​

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/new_payment_gateway_experiment/' \
  -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/new_payment_gateway_experiment/' \
  -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.