Flags
Create, find, edit, archive and switch flags, and manage their variants.
Concepts#
What a flag is#
A flag is a named switch that belongs to one project. Its name is the key your code asks for, and it is the same in every environment. What differs per environment is the configuration under environments: on or off, rollout percentage, targeting, segments, prerequisites and a version number that goes up on every change. The Rollouts page covers that configuration.
Types and variants#
A flag is a boolean (the default, with no variants) or one of string, number and json, which need between 2 and 20 variants. The type is fixed when the flag is created. A new flag starts off at 100% in every environment the organization has; a flag with variants starts serving its first variant.
Rules worth knowing#
- A flag is never archived and deleted in one step. Archive hides it and makes it read-only; delete works only on an archived flag.
- Archiving, and moving a flag to another project, are refused while another flag lists it as a prerequisite.
- Archived flags, and flags in an archived project, cannot be edited, toggled or rolled back until restored.
- In an environment that requires approval, direct changes are refused with
403and you propose a release instead.
Examples use $FLAGSWIFT_URL for your server and $SESSION for the value of the auth_session cookie you got when you signed in; see Dashboard API. Every response uses the same envelope: { "status", "message", "data" } on success and { "status": "error", "message" } on failure. A validation failure lists every problem in one message, joined with commas.
The flag object#
A flag belongs to a project and has the same key in every environment. Each environment holds its own on or off state, rollout, targeting and version, which the Rollouts page covers.
| Field | Type | Description |
|---|---|---|
| name* | string | The key your code uses. Lower case letters, numbers, hyphens and underscores; it is trimmed and lower-cased for you. Unique within the project, and it cannot be changed. |
| displayName* | string | The readable name shown in the console. |
| projectId* | string | The project the flag lives in. It must exist and must not be archived. |
| type | boolean | string | number | json | Default boolean. Anything other than boolean needs 2 to 20 variants; boolean flags take none. |
| description | string | Up to 500 characters. Default empty. |
| owner, expectedRemovalAt, expiresAt, permanent | optional | Lifecycle fields; see Lifecycle. owner defaults to you. These can also be sent when editing. |
| variants | array | Up to 20 of { key, value, name? }. The key (lower case, letters, numbers, - and _ with no doubled or edge separators, up to 50) and the value are both required, and keys must be unique. name is a label of up to 80 characters. The value must suit the flag's type: a string, a finite number, or a JSON object or array, each up to 16,384 characters. |
| Field | Type | Description |
|---|---|---|
| id | string | Use this in paths such as /api/flags/{id}. |
| environments | object | One entry per environment name: enabled, rolloutPercentage, targeting, killSwitchActive, version, lastModified, modifiedBy and, where set, rules, segments, bucketBy, dependencies, offVariant and allocation. |
| archivedAt | ISO date | null | Set while the flag is archived. |
| createdBy, owner | email | null | owner falls back to the creator. |
| pinned | boolean | Whether you pinned it. Only meaningful where the response is per person (the list and pin calls). |
| createdAt, updatedAt | ISO date | Timestamps. |
Create and find#
Create a flag#
/api/flagsReturns 201 with the flag. The flag appears in every environment of the organization, off.
Authorization
flags.create
Body
namestringRequiredThe key your code uses. Trimmed and lower-cased; letters, numbers, hyphens and underscores. Unique within the project, and it cannot be changed.displayNamestringRequiredThe readable name shown in the console. Trimmed, cannot be blank.projectIdstringRequiredThe project the flag lives in. It must exist and must not be archived.typeboolean | string | number | jsonDefault boolean. Anything other than boolean needs 2 to 20 variants; boolean flags take none.descriptionstringTrimmed, up to 500 characters. Default empty.variantsVariant[]Required for non-boolean types, 2 to 20 of{ key, value, name? }.key: required, lower-cased, up to 50 characters, letters, numbers,-and_with no doubled or edge separators, unique in the flag.value: required, and must suit the type: a string, a finite number, or a JSON object or array, each up to 16,384 characters when serialised.name: optional label, up to 80 characters.owneremail | nullUp to 254 characters, must be an email address. Defaults to you on create; null clears it.expectedRemovalAtISO date | nullWhen the flag should be cleaned up. Any date string that parses; null clears it.expiresAtISO date | nullWhen the flag expires. Same format; null clears it.permanentbooleanMarks the flag as long-lived. A permanent flag cannot have either date.
Errors
- 400Malformed JSON (
Invalid JSON body), or validation failed, for exampleKey may only contain lowercase letters, numbers, hyphens and underscores,Project is required,A string flag needs at least 2 variants,Boolean flags do not have variants,Variant key “compact” is used twice, orThis project is archived. Restore it to make changes. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.create(You do not have permission to do this). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Project not found: the project does not exist or belongs to another organization. - 409The key is taken in this project (
A flag with this key already exists in this project), or an archived flag holds it (An archived flag with this key exists in this project. Restore it instead.).
curl -s -X POST "$FLAGSWIFT_URL/api/flags" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{
"name": "checkout-layout",
"displayName": "Checkout layout",
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"type": "string",
"variants": [
{ "key": "classic", "value": "classic" },
{ "key": "compact", "value": "compact" }
]
}'{
"status": "success",
"message": "Flag created successfully",
"data": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"value": "compact"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": null,
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-02T09:30:00.000Z",
"pinned": false
}
}List flags#
/api/flagsNewest first, always; there is no sort parameter. Returns { items, pagination }, where pagination is { page, limit, total, totalPages, hasNext, hasPrev }.
Authorization
flags.read
Query parameters
projectIdstringOnly this project's flags, archived project included. Without it you get every project's flags except those in archived projects.searchstringMatches key and display name. Up to 100 characters.environmentstringWith status, the environment the status refers to. Ignored on its own.statusenabled | disabledFlags that are on or off in the chosen environment. Ignored without environment.typeboolean | string | number | jsonOnly flags of this type.archivedactive | archived | allDefault active.markpinnedOnly flags you pinned. The other filters still apply.pageintegerFrom 1. Default 1.limitinteger1 to 100. Default 10.
Errors
- 400A parameter is invalid, for example
limitabove 100 orarchivedthat is not one of the three values. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags?projectId=b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71&status=enabled&environment=production&limit=20"{
"status": "success",
"message": "Flags fetched successfully",
"data": {
"items": [
{
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"value": "compact"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": true,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 2,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": null,
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-02T09:30:00.000Z",
"pinned": true
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1,
"hasNext": false,
"hasPrev": false
}
}
}Get a flag#
/api/flags/{id}Works for archived flags too, so you can inspect one before restoring it.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No flag with that id in your organization (
Flag not found).
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13"{
"status": "success",
"message": "OK",
"data": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"value": "compact"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": null,
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-02T09:30:00.000Z",
"pinned": false
}
}Flags that depend on this one#
/api/flags/{id}/dependentsLists flags that use this one as a prerequisite, one entry per environment where they do. An empty items means nothing depends on it. Archiving or moving the flag is refused while any exist.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No flag with that id in your organization (
Flag not found).
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/dependents"{
"status": "success",
"message": "OK",
"data": {
"items": [
{
"flagId": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
"flagKey": "express-checkout",
"flagName": "Express checkout",
"environment": "production"
}
]
}
}Edit, move and archive#
Edit details or move#
/api/flags/{id}The key (name), the type and the variants are not editable here; unknown fields are ignored.
Authorization
flags.update
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Body (send any of these)
displayNamestringTrimmed, cannot be empty.descriptionstringTrimmed, up to 500 characters.projectIdstringMoves the flag to another project of the same organization. This also needsflags.move, which only admins hold. The target must not be archived or already hold the key, and the flag must have no prerequisites and be nobody's prerequisite.owneremail | nullUp to 254 characters, must be an email address. Defaults to you on create; null clears it.expectedRemovalAtISO date | nullWhen the flag should be cleaned up. Any date string that parses; null clears it.expiresAtISO date | nullWhen the flag expires. Same format; null clears it.permanentbooleanMarks the flag as long-lived. A permanent flag cannot have either date.
Errors
- 400Malformed JSON (
Invalid JSON body), or validation failed (Name cannot be empty,Description must be 500 characters or less,Owner must be an email address), the flag is archived (This flag is archived. Restore it to make changes.), its project is archived, a permanent flag was given dates, or a move was blocked because the flag has prerequisites of its own. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.update, or you tried to move the flag withoutflags.move. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found, or for a moveProject not found. - 409A move was refused because the key already exists in the target project, or another flag uses this one as a prerequisite.
curl -s -X PATCH "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "displayName": "Checkout layout (2026)", "description": "Compact layout experiment" }'{
"status": "success",
"message": "Flag updated successfully",
"data": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout (2026)",
"description": "Compact layout experiment",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"value": "compact"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": null,
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-03T08:15:00.000Z",
"pinned": false
}
}Replace variants#
/api/flags/{id}/variantsSends the whole list; whatever you leave out is removed. Same rules as at creation: 2 to 20, key and value required on each. Only variants no environment serves can be removed, either through its allocation or as its off variant.
Authorization
flags.update
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Body
variantsVariant[]RequiredThe complete list, 2 to 20 of{ key, value, name? }with the same rules as on create. Anything left out is removed.
Errors
- 400Malformed JSON (
Invalid JSON body), orVariants are required, a boolean flag (Boolean flags do not have variants), fewer than 2 or more than 20 variants, a bad or duplicate key, a value that does not suit the type (Variant “wizard” needs a valid string value), or an archived flag or project. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.update. Removing a variant or changing a live value also needs write access in production environments. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No flag with that id in your organization (
Flag not found). - 409A variant you left out is still served somewhere (
Variant “wizard” is still served in production. Move its traffic to another variant first.). Change the allocation or off variant first.
curl -s -X PUT "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/variants" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{
"variants": [
{ "key": "classic", "value": "classic" },
{ "key": "compact", "value": "compact", "name": "Compact" },
{ "key": "wizard", "value": "wizard" }
]
}'{
"status": "success",
"message": "Variants updated",
"data": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"name": "Compact",
"value": "compact"
},
{
"key": "wizard",
"value": "wizard"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": null,
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-02T09:30:00.000Z",
"pinned": false
}
}Archive#
/api/flags/{id}/archiveHides the flag and makes it read-only; its configuration and history are kept. It disappears from the default list (archived=active) and can be restored.
Authorization
flags.archive (developers, release managers and admins)
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Errors
- 400
This flag is already archived. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.archive. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No flag with that id in your organization (
Flag not found). - 409Another flag uses it as a prerequisite (
Cannot archive “Checkout layout”: it is a prerequisite of Upsell banner (production). Remove the dependency first.). Check/dependents.
curl -s -X POST -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/archive"{
"status": "success",
"message": "Flag archived",
"data": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"value": "compact"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": "2026-10-03T08:20:00.000Z",
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-03T08:20:00.000Z",
"pinned": false
}
}Restore#
/api/flags/{id}/restoreAuthorization
flags.update
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Errors
- 400
This flag is not archived. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.update. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No flag with that id in your organization (
Flag not found).
curl -s -X POST -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/restore"{
"status": "success",
"message": "Flag restored",
"data": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"value": "compact"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": null,
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-02T09:30:00.000Z",
"pinned": false
}
}Delete#
/api/flags/{id}Permanent: the flag, its history and its saved versions go, and only the audit trail stays. It works on archived flags only, so archive first. A flag that code still references is refused unless you add ?force=true.
Authorization
flags.delete
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Query parameters
forcebooleanDefault false. true deletes the flag even though code references still mention it.
Errors
- 400The flag is not archived (
Archive the flag before deleting it permanently), or code still references it (This flag is still used in 3 places in code. Remove those first, or delete it anyway.) and you did not sendforce=true. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.delete. Admins hold it by default. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No flag with that id in your organization (
Flag not found).
curl -s -X DELETE -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13?force=true"{
"status": "success",
"message": "Flag deleted successfully",
"data": null
}Pin or unpin for yourself#
/api/flags/{id}/marksPins belong to you and are not visible to others. You can pin at most 3 flags. Repeating a request changes nothing. Send "value": false to unpin.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Body
kind"pin"RequiredThe only kind there is.valuebooleanRequiredtrue to pin, false to unpin.
Errors
- 400Invalid body (
Kind is required,Kind must be pin,Value is required), or you already pin 3 flags (You can pin at most 3 flags. Remove one first.). - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No flag with that id in your organization (
Flag not found).
curl -s -X PUT "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/marks" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "kind": "pin", "value": true }'{
"status": "success",
"message": "Saved",
"data": {
"pinned": true
}
}Switch on and off#
Toggle in one environment#
/api/flags/{id}/toggleFlips the flag in that environment and returns the whole flag; look at environments.production.enabled for the result. Every toggle saves a new version, so it can be rolled back.
Authorization
flags.toggle
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Body
environmentstringRequiredThe environment name, such as production (not its id).
Errors
- 400Malformed JSON (
Invalid JSON body), orEnvironment is required, or the flag or its project is archived. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.toggle;Your role cannot make this change in a production environment(developers); the environment requires approval (Production requires approval. Propose a release instead of changing it directly.); or the emergency stop is active (Cannot toggle flag while the kill switch is active for this environment). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found, orEnvironment “qa” is not configured for this flag.
curl -s -X POST "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/toggle" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "environment": "production" }'{
"status": "success",
"message": "Flag toggled successfully",
"data": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-layout",
"displayName": "Checkout layout",
"description": "",
"type": "string",
"variants": [
{
"key": "classic",
"value": "classic"
},
{
"key": "compact",
"value": "compact"
}
],
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"environments": {
"development": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"staging": {
"enabled": false,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 1,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com"
},
"production": {
"enabled": true,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
},
"version": 2,
"lastModified": "2026-10-03T08:30:00.000Z",
"modifiedBy": "dana@example.com"
}
},
"archivedAt": null,
"createdBy": "dana@example.com",
"owner": "dana@example.com",
"expectedRemovalAt": null,
"expiresAt": null,
"permanent": false,
"createdAt": "2026-10-02T09:30:00.000Z",
"updatedAt": "2026-10-03T08:30:00.000Z",
"pinned": false
}
}Outcome analytics#
/api/flags/{id}/analytics?environment=production&days=14How each variant of the flag did on each outcome in one environment: people exposed, people who converted, conversion rate, summed value and, for each variant against the first, a two-proportion z-test. environment is required; days is 1 to 90 (default 14). Empty until analytics is turned on with ANALYTICS_ENABLED=true and SDKs report exposures. See Outcome analytics.
Authorization
metrics.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Query parameters
environmentstringRequiredThe environment name to report on.daysinteger1 to 90. Default 14.
Errors
- 400
Environment is required, ordaysoutside 1 to 90. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
metrics.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found, orEnvironment “qa” does not exist for this flag.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/analytics?environment=production&days=14"Versions
- The emergency stop is a separate call, on the Rollouts page.
- Changing several flags at a set time is a release, not a toggle. See Releases.
Common patterns#
Retire a flag: archive, then delete#
Archiving is the safe step and can be undone; deleting is permanent. The usual path is to check that nothing needs the flag, archive it, and delete it later once code no longer mentions it.
# 1. Is it a prerequisite of another flag? An empty items list means no.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/dependents"
# 2. Archive it. It is now hidden and read-only; POST .../restore brings it back.
curl -s -X POST -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/archive"
# 3. Later, once the code is clean (see /api/flags/{id}/code-references), delete it.
# Without force, a flag that code still references is refused with 400.
curl -s -X DELETE -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13"Find what is on in production#
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags?projectId=b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71&environment=production&status=enabled&page=1&limit=100"
# Keep requesting page=2, 3 ... while data.pagination.hasNext is true.Add a variant, then send traffic to it#
Variants and their traffic are separate. First add the variant with PUT /variants (include every existing one), then give it weight with the allocation field of PATCH /api/flags/{id}/environments/{environment} on the Rollouts page. To remove a variant, do it in the other order: move its traffic away first, then replace the list without it.