From cdcac78927424741336eca607a0e583b0931f4c8 Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Tue, 31 Mar 2026 16:46:04 +0530 Subject: [PATCH 1/4] docs: add guide for experimental flag update endpoints Closes #6856 --- .../admin-api/updating-flags.md | 247 ++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md diff --git a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md new file mode 100644 index 000000000000..a4aeee0be4cf --- /dev/null +++ b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md @@ -0,0 +1,247 @@ +--- +title: Updating Flags +sidebar_label: Updating Flags +sidebar_position: 3 +--- + +These experimental endpoints let you update feature flag values and segment overrides via the Admin API. They're +purpose-built for automation and CI/CD — minimal payloads, no need to look up internal IDs, and they work the same +regardless of whether your environment uses v1 or v2 feature versioning. + +:::caution + +These endpoints are experimental and may change without notice. They do not support multivariate values and cannot be +used when [change requests](/administration-and-security/governance-and-compliance/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](https://github.com/Flagsmith/flagsmith/issues/6233). + +**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/`](https://api.flagsmith.com/api/v1/docs/#/experimental/api_experiments_environments_update_flag_v1_create) + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \ + -H 'Authorization: Api-Key ' \ + -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/`](https://api.flagsmith.com/api/v1/docs/#/experimental/api_experiments_environments_update_flag_v2_create) + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \ + -H 'Authorization: Api-Key ' \ + -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** + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \ + -H 'Authorization: Api-Key ' \ + -H 'Content-Type: application/json' \ + -d '{ + "feature": {"name": "api_rate_limit"}, + "enabled": true, + "value": {"type": "integer", "value": "1000"} + }' +``` + +**Option B** + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \ + -H 'Authorization: Api-Key ' \ + -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** + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \ + -H 'Authorization: Api-Key ' \ + -H 'Content-Type: application/json' \ + -d '{ + "feature": {"name": "new_checkout"}, + "segment": {"id": 456}, + "enabled": true, + "value": {"type": "boolean", "value": "true"} + }' +``` + +**Option B** — single request: + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \ + -H 'Authorization: Api-Key ' \ + -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: + +```bash +# Default +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \ + -H 'Authorization: Api-Key ' \ + -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 ' \ + -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 ' \ + -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: + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \ + -H 'Authorization: Api-Key ' \ + -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"} + } + ] + }' +``` + +--- + +## Remove a segment override + +Removes a segment override from a feature. + +[`POST /api/experiments/environments/{environment_key}/delete-segment-override/`](https://api.flagsmith.com/api/v1/docs/#/experimental/api_experiments_environments_delete_segment_override_create) + +```bash +curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/delete-segment-override/' \ + -H 'Authorization: Api-Key ' \ + -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 on v1 and v2 environments | +| Success response | `204 No Content` | +| Limitations | No multivariate support; incompatible with change requests | +| Full API schema | [Swagger Explorer](https://api.flagsmith.com/api/v1/docs/) | From 35ad49bf437f5e9536052b767f040db297ecd84b Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Thu, 2 Apr 2026 07:46:55 +0530 Subject: [PATCH 2/4] docs: reword feature versioning reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review comment — avoid unexplained v1/v2 terminology. --- .../flagsmith-api-overview/admin-api/updating-flags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md index a4aeee0be4cf..1c0e32117c9a 100644 --- a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md +++ b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md @@ -6,7 +6,7 @@ sidebar_position: 3 These experimental endpoints let you update feature flag values and segment overrides via the Admin API. They're purpose-built for automation and CI/CD — minimal payloads, no need to look up internal IDs, and they work the same -regardless of whether your environment uses v1 or v2 feature versioning. +regardless of whether your environment has Feature Versioning enabled. :::caution @@ -241,7 +241,7 @@ curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environmen | 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 on v1 and v2 environments | +| Feature Versioning | Works the same whether enabled or not | | Success response | `204 No Content` | | Limitations | No multivariate support; incompatible with change requests | | Full API schema | [Swagger Explorer](https://api.flagsmith.com/api/v1/docs/) | From b5b1126a9d4eb3b1d97754954bf1bf2a9c8dbc3b Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Thu, 2 Apr 2026 07:49:48 +0530 Subject: [PATCH 3/4] docs: add (Experimental) to title and sidebar label --- .../flagsmith-api-overview/admin-api/updating-flags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md index 1c0e32117c9a..3a1fbd417844 100644 --- a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md +++ b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md @@ -1,6 +1,6 @@ --- -title: Updating Flags -sidebar_label: Updating Flags +title: Updating Flags (Experimental) +sidebar_label: Updating Flags (Experimental) sidebar_position: 3 --- From f7597b50078f79676887aa0ad8f445e7423f1352 Mon Sep 17 00:00:00 2001 From: Gagan Trivedi Date: Thu, 2 Apr 2026 07:52:04 +0530 Subject: [PATCH 4/4] docs: clarify delete-segment-override is a separate endpoint --- .../flagsmith-api-overview/admin-api/updating-flags.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md index 3a1fbd417844..6a8ca75fbfb1 100644 --- a/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md +++ b/docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md @@ -218,7 +218,7 @@ curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environmen ## Remove a segment override -Removes a segment override from a feature. +A separate endpoint for removing a segment override from a feature: [`POST /api/experiments/environments/{environment_key}/delete-segment-override/`](https://api.flagsmith.com/api/v1/docs/#/experimental/api_experiments_environments_delete_segment_override_create)