Flags
Create, change and delete feature flags from an agent.
A flag lives in one environment. Paths start with /api/agent/organizations/{organizationId}/{environment}/flags. Reading needs any role; creating, changing and deleting need editor or higher.
Create a flag
curl -X POST https://improve.obelism.studio/api/agent/organizations/$ORG/staging/flags \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "New checkout",
"options": [
{ "name": "Off", "split": 100 },
{ "name": "On", "split": 0 }
]
}'{
"flag": {
"flagId": "feat_01H8XYZ",
"name": "New checkout",
"slug": "new-checkout",
"icon": "⛳️",
"state": "draft",
"audienceId": null,
"options": [
{ "id": 1, "name": "Off", "slug": "off", "value": "", "split": 100 },
{ "id": 2, "name": "On", "slug": "on", "value": "", "split": 0 }
],
"createdAt": "2026-10-08T12:00:00.000Z",
"updatedAt": "2026-10-08T12:00:00.000Z"
}
}| Field | Default |
|---|---|
name | Required |
slug | The slugified name. The SDK looks flags up by it |
icon | A random emoji |
state | draft. Only active flags are served |
audienceId | null, everyone. Or an audience id |
options | Original (split 100) and Alteration (split 0) |
Each option has a name, an optional slug, an optional value your code can read, and a split: its relative weight, from 0 to 100.
Change a flag
PATCH .../flags/{flagId} changes the fields you send. To turn a flag on, set its state:
curl -X PATCH https://improve.obelism.studio/api/agent/organizations/$ORG/staging/flags/$FLAG \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"state":"active"}'options is always the full new list. An option with an id updates that option, one without an id is added, and options you leave out are deleted.
Other operations
| Method | Path | Does |
|---|---|---|
GET | /flags | List the flags, without their options |
GET | /flags/{flagId} | Get one flag with its options |
DELETE | /flags/{flagId} | Delete the flag (204) |
A flag change reaches SDKs within about 30 seconds, when the edge cache of the datafile expires.