Skip to content

Commit 0156837

Browse files
gagantrivedigagantrivedi
authored
docs: add guide for experimental flag update endpoints (#7083)
1 parent e8ce5ab commit 0156837

1 file changed

Lines changed: 247 additions & 0 deletions

File tree

  • docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api

‎docs/docs/integrating-with-flagsmith/flagsmith-api-overview/admin-api/updating-flags.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
title: Updating Flags (Experimental)
3+
sidebar_label: Updating Flags (Experimental)
4+
sidebar_position: 3
5+
---
6+
7+
These experimental endpoints let you update feature flag values and segment overrides via the Admin API. They're
8+
purpose-built for automation and CI/CD — minimal payloads, no need to look up internal IDs, and they work the same
9+
regardless of whether your environment has Feature Versioning enabled.
10+
11+
:::caution
12+
13+
These endpoints are experimental and may change without notice. They do not support multivariate values and cannot be
14+
used when [change requests](/administration-and-security/governance-and-compliance/change-requests) are enabled.
15+
16+
:::
17+
18+
We're evaluating two approaches for updating flags — **Option A** (one change per request) and **Option B** (everything
19+
in one request). Each scenario below shows both. Try them and
20+
[let us know which works better for you](https://github.com/Flagsmith/flagsmith/issues/6233).
21+
22+
**Common details:**
23+
24+
- Identify features by `name` or `id` (pick one, not both).
25+
- All endpoints return **204 No Content** on success.
26+
- Values are passed as a `value` object with `type` and `value` (always a string):
27+
28+
| Type | Example |
29+
| --------- | ------------------------------------------------ |
30+
| `string` | `{"type": "string", "value": "hello"}` |
31+
| `integer` | `{"type": "integer", "value": "42"}` |
32+
| `boolean` | `{"type": "boolean", "value": "true"}` |
33+
34+
---
35+
36+
## Toggle a flag on or off
37+
38+
The simplest case — flip a feature flag in an environment.
39+
40+
**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)
41+
42+
```bash
43+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
44+
-H 'Authorization: Api-Key <your_token>' \
45+
-H 'Content-Type: application/json' \
46+
-d '{
47+
"feature": {"name": "maintenance_mode"},
48+
"enabled": true,
49+
"value": {"type": "boolean", "value": "true"}
50+
}'
51+
```
52+
53+
**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)
54+
55+
```bash
56+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
57+
-H 'Authorization: Api-Key <your_token>' \
58+
-H 'Content-Type: application/json' \
59+
-d '{
60+
"feature": {"name": "maintenance_mode"},
61+
"environment_default": {
62+
"enabled": true,
63+
"value": {"type": "boolean", "value": "true"}
64+
}
65+
}'
66+
```
67+
68+
---
69+
70+
## Update a feature value
71+
72+
Change a feature's value — for example, setting a rate limit.
73+
74+
**Option A**
75+
76+
```bash
77+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
78+
-H 'Authorization: Api-Key <your_token>' \
79+
-H 'Content-Type: application/json' \
80+
-d '{
81+
"feature": {"name": "api_rate_limit"},
82+
"enabled": true,
83+
"value": {"type": "integer", "value": "1000"}
84+
}'
85+
```
86+
87+
**Option B**
88+
89+
```bash
90+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
91+
-H 'Authorization: Api-Key <your_token>' \
92+
-H 'Content-Type: application/json' \
93+
-d '{
94+
"feature": {"name": "api_rate_limit"},
95+
"environment_default": {
96+
"enabled": true,
97+
"value": {"type": "integer", "value": "1000"}
98+
}
99+
}'
100+
```
101+
102+
---
103+
104+
## Roll out a feature to a segment
105+
106+
Enable a feature for a specific segment (e.g. beta users) while keeping it off for everyone else.
107+
108+
**Option A**
109+
110+
```bash
111+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
112+
-H 'Authorization: Api-Key <your_token>' \
113+
-H 'Content-Type: application/json' \
114+
-d '{
115+
"feature": {"name": "new_checkout"},
116+
"segment": {"id": 456},
117+
"enabled": true,
118+
"value": {"type": "boolean", "value": "true"}
119+
}'
120+
```
121+
122+
**Option B** — single request:
123+
124+
```bash
125+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
126+
-H 'Authorization: Api-Key <your_token>' \
127+
-H 'Content-Type: application/json' \
128+
-d '{
129+
"feature": {"name": "new_checkout"},
130+
"environment_default": {
131+
"enabled": false,
132+
"value": {"type": "boolean", "value": "false"}
133+
},
134+
"segment_overrides": [
135+
{
136+
"segment_id": 456,
137+
"enabled": true,
138+
"value": {"type": "boolean", "value": "true"}
139+
}
140+
]
141+
}'
142+
```
143+
144+
The `priority` field on segment overrides is optional. Omit it to add at the lowest priority. Priority `1` is highest.
145+
146+
---
147+
148+
## Configure multiple segment overrides
149+
150+
Set different values per segment — for example, pricing tiers.
151+
152+
**Option A** — one request per segment override plus one for the default:
153+
154+
```bash
155+
# Default
156+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
157+
-H 'Authorization: Api-Key <your_token>' \
158+
-H 'Content-Type: application/json' \
159+
-d '{
160+
"feature": {"name": "pricing_tier"},
161+
"enabled": true,
162+
"value": {"type": "string", "value": "standard"}
163+
}'
164+
165+
# Enterprise segment (highest priority)
166+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
167+
-H 'Authorization: Api-Key <your_token>' \
168+
-H 'Content-Type: application/json' \
169+
-d '{
170+
"feature": {"name": "pricing_tier"},
171+
"segment": {"id": 101, "priority": 1},
172+
"enabled": true,
173+
"value": {"type": "string", "value": "enterprise"}
174+
}'
175+
176+
# Premium segment
177+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v1/' \
178+
-H 'Authorization: Api-Key <your_token>' \
179+
-H 'Content-Type: application/json' \
180+
-d '{
181+
"feature": {"name": "pricing_tier"},
182+
"segment": {"id": 202, "priority": 2},
183+
"enabled": true,
184+
"value": {"type": "string", "value": "premium"}
185+
}'
186+
```
187+
188+
**Option B** — single request:
189+
190+
```bash
191+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/update-flag-v2/' \
192+
-H 'Authorization: Api-Key <your_token>' \
193+
-H 'Content-Type: application/json' \
194+
-d '{
195+
"feature": {"name": "pricing_tier"},
196+
"environment_default": {
197+
"enabled": true,
198+
"value": {"type": "string", "value": "standard"}
199+
},
200+
"segment_overrides": [
201+
{
202+
"segment_id": 101,
203+
"priority": 1,
204+
"enabled": true,
205+
"value": {"type": "string", "value": "enterprise"}
206+
},
207+
{
208+
"segment_id": 202,
209+
"priority": 2,
210+
"enabled": true,
211+
"value": {"type": "string", "value": "premium"}
212+
}
213+
]
214+
}'
215+
```
216+
217+
---
218+
219+
## Remove a segment override
220+
221+
A separate endpoint for removing a segment override from a feature:
222+
223+
[`POST /api/experiments/environments/{environment_key}/delete-segment-override/`](https://api.flagsmith.com/api/v1/docs/#/experimental/api_experiments_environments_delete_segment_override_create)
224+
225+
```bash
226+
curl -X POST 'https://api.flagsmith.com/api/experiments/environments/{environment_key}/delete-segment-override/' \
227+
-H 'Authorization: Api-Key <your_token>' \
228+
-H 'Content-Type: application/json' \
229+
-d '{
230+
"feature": {"name": "pricing_tier"},
231+
"segment": {"id": 202}
232+
}'
233+
```
234+
235+
---
236+
237+
## Quick reference
238+
239+
| Aspect | Details |
240+
| -------------------- | ---------------------------------------------------------------------------- |
241+
| Feature ID | `name` or `id` — use one, not both |
242+
| Value types | `string`, `integer`, `boolean` |
243+
| Segment priority | Optional — omit to add at lowest priority; `1` is highest |
244+
| Feature Versioning | Works the same whether enabled or not |
245+
| Success response | `204 No Content` |
246+
| Limitations | No multivariate support; incompatible with change requests |
247+
| Full API schema | [Swagger Explorer](https://api.flagsmith.com/api/v1/docs/) |

0 commit comments

Comments
 (0)