Rollouts and history
Change what a flag does in one environment, check what a person would see, and go back to an earlier version.
Concepts#
One configuration per environment#
A flag holds a separate configuration for each environment, and every save bumps that environment's version by one. A configuration answers the question “who gets this flag on?” in a fixed order, and the first thing that applies wins: the emergency stop (everyone off), then enabled (off means off, even for targeted people), then named targeting, then segments, then attribute rules, then prerequisite flags (a blocked prerequisite stops the percentage rollout, but not people already matched above), and finally the rolloutPercentage. The reason an evaluation gave is one of KILL_SWITCH, DISABLED, TARGETED_USER, SEGMENT_MATCH, RULE_MATCH, DEPENDENCY_BLOCKED, FULL_ROLLOUT, ROLLOUT_IN, ROLLOUT_OUT or NO_IDENTIFIER, which is what the inspector returns.
Versions make every change reversible#
Each toggle, edit, variant change, emergency stop and rollback is saved as a version with who made it and when. A rollback re-applies an older configuration as a new version, so history is never rewritten and a rollback can itself be rolled back.
Rules that apply to every change here#
- You need a role that may change that environment. In a production environment developers are read-only for rollouts, targeting, toggling and rollback, and get
403. - In an environment that requires approval, direct changes are refused with
403; propose a release instead. Rollbacks and the emergency stop are never held up by approval. - Archived flags, and flags in archived projects, cannot be changed (
400). - The percentage and the variant weights are decided per person with a stable hash, so raising 10% to 25% keeps the first 10% in.
Examples use $FLAGSWIFT_URL for your server and $SESSION for the value of the auth_session cookie; see Dashboard API.
Environment configuration#
Update an environment's configuration#
/api/flags/{id}/environments/{environment}Send only what you want to change; everything else is kept. Each save becomes a new version. enabled is not settable here: use toggle. Sending nothing that changes anything returns the flag unchanged and saves no version. The response is the whole flag.
Authorization
flags.update, plus rollouts.update and targeting.update for what you change
Path parameters
idstring (uuid)RequiredThe flag id (not its key).environmentstringRequiredThe environment name, such as production (not its id).
Body (send any of these)
rolloutPercentageinteger0 to 100. How much of the audience gets the flag on.bucketByuser | account | deviceWhat the percentage is counted over, so everyone sharing that identifier gets the same outcome. Default user.targetingobject{ enabled, users, accounts?, devices? };enabledandusersare required (use[]). Up to 1,000 of each; blanks and duplicates are removed. Named people are on regardless of the percentage whileenabledis true. Replaces the previous targeting.rulesarrayAttribute rules, each{ id, conditions[] }with at least one condition. All conditions in a rule must match, any rule grants on. Same limits as segment rules. Replaces the list.segmentsstring[]Segment keys whose members are targeted, up to 20. Each must exist in the organization (segments are shared by every project). Replaces the list.dependenciesstring[]Prerequisite flag keys that must be on for the person before the percentage rollout applies. Up to 10, each an active flag in the same project and environment; no loops, and chains no deeper than 5. Replaces the list.allocationobjectVariant key to weight for a multivariate flag, such as{ "classic": 60, "compact": 40 }. Weights are 0 to 100, must add up to exactly 100, and a variant you leave out gets 0.offVariantstringThe variant served when the flag is off. Must be one of the flag's variants.
Errors
- 400Malformed JSON (
Invalid JSON body), validation failed (Rollout cannot exceed 100,Rollout must be a whole number,Bucket by user, account or device,Allocation must map variant keys to weights); orAllocation must add up to 100%,Allocation weights must be between 0 and 100,At most 20 rules,Unknown variant “x” in allocation,This flag has no variants;Unknown segment: vip; a bad prerequisite (A flag cannot depend on itself,Flags cannot depend on each other in a loop (a → b → a),Not an active flag in this project and environment: x); a rule problem (Rule 1, condition 1: …); or the flag or its project is archived. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.update,rollouts.updateortargeting.updatefor what you sent, cannot change production (Your role cannot make this change in a production environment), or the environment requires approval (Production requires approval. Propose a release instead of changing it directly., with the environment's display name first). 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 PATCH "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/environments/production" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{
"rolloutPercentage": 25,
"bucketBy": "account",
"allocation": { "classic": 60, "compact": 40 }
}'{
"status": "success",
"message": "Environment updated 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": true,
"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": true,
"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": 25,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 60,
"compact": 40
},
"version": 3,
"lastModified": "2026-10-02T09:30:00.000Z",
"modifiedBy": "dana@example.com",
"bucketBy": "account"
}
},
"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
}
}Check what someone would see#
/api/flags/{id}/environments/{environment}/inspectRuns the real evaluation for a person without changing or recording anything and returns the result with its reason. Send at least one of the three identifiers. It works on archived flags too.
enabled,reasonand, for a flag with variants,variantandvalueare the answer an SDK would give.bucketis the person's position from 0 to 9,999 andcutoffis where the rollout stops (percentage times 100).inRolloutis true when the bucket is below the cutoff, and null when no identifier could be used (bucketis then null).targeted,ruleMatchedandmatchedSegmentsay which route granted access;variantBucketis what picked the variant.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).environmentstringRequiredThe environment name, such as production (not its id).
Body
identifierstringThe user. Up to 255 characters.accountstringThe organization or tenant.devicestringThe install.attributesobjectValues that rules can match.
Errors
- 400Malformed JSON (
Invalid JSON body),Enter a user, account or device to check, an identifier over 255 characters, orAttributes must be an object. - 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). - 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/environments/production/inspect" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "identifier": "user-123", "account": "acme", "attributes": { "plan": "pro" } }'{
"status": "success",
"message": "OK",
"data": {
"enabled": true,
"reason": "ROLLOUT_IN",
"variant": "compact",
"value": "compact",
"bucket": 2310,
"bucketBy": "account",
"matchedSegment": null,
"cutoff": 2500,
"rolloutPercentage": 25,
"inRollout": true,
"targeted": false,
"ruleMatched": false,
"variantBucket": 6120
}
}Versions and history#
Saved versions of an environment#
/api/flags/{id}/versions?environment=…environment is required. page and limit (default 20, up to 100). Newest first. current is the version the environment is at now. action is baseline, toggle, update, variants, kill_switch or rollback; a rollback version has restoredFrom and the reason you gave. config is the snapshot of that version.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Query parameters
environmentstringRequiredThe environment name.pageintegerFrom 1. Default 1.limitinteger1 to 100. Default 20.
Errors
- 400
Environment is required, orlimitoutside 1 to 100. - 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). - 404
Flag not found, orEnvironment “qa” is not configured for this flag.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/versions?environment=production&limit=20"{
"status": "success",
"message": "OK",
"data": {
"items": [
{
"id": "5b6c7d8e-9f01-4a2b-8c3d-4e5f60718293",
"version": 3,
"action": "update",
"config": {
"enabled": true,
"rolloutPercentage": 25,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"bucketBy": "account",
"offVariant": "classic",
"allocation": {
"classic": 60,
"compact": 40
}
},
"restoredFrom": null,
"reason": null,
"actorEmail": "dana@example.com",
"createdAt": "2026-10-03T08:30:00.000Z"
},
{
"id": "1a2b3c4d-5e6f-4789-a0b1-c2d3e4f50617",
"version": 2,
"action": "toggle",
"config": {
"enabled": true,
"rolloutPercentage": 100,
"targeting": {
"enabled": false,
"users": []
},
"killSwitchActive": false,
"offVariant": "classic",
"allocation": {
"classic": 100
}
},
"restoredFrom": null,
"reason": null,
"actorEmail": "dana@example.com",
"createdAt": "2026-10-03T08:10:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 3,
"totalPages": 1,
"hasNext": false,
"hasPrev": false
},
"current": 3
}
}Change history#
/api/flags/{id}/historyEvery change to the flag, across environments, with who made it, newest first. page and limit (default 20, up to 100). action is one of create, toggle, rollout, rollback, update_targeting, move, kill_switch, archive, restore, update_variants and allocation. previousValue and newValue hold whatever changed, so their shape depends on the action.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Query parameters
pageintegerFrom 1. Default 1.limitinteger1 to 100. Default 20.
Errors
- 400
limitoutside 1 to 100 orpagebelow 1. - 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). - 404
Flag not found.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/history?page=1&limit=20"{
"status": "success",
"message": "OK",
"data": {
"items": [
{
"id": "c4d5e6f7-0819-4a2b-93c4-d5e6f7081920",
"action": "rollout",
"environment": "production",
"previousValue": 100,
"newValue": 25,
"userEmail": "dana@example.com",
"createdAt": "2026-10-03T08:30:00.000Z"
},
{
"id": "d5e6f708-1920-4b3c-a4d5-e6f708192031",
"action": "toggle",
"environment": "production",
"previousValue": false,
"newValue": true,
"userEmail": "dana@example.com",
"createdAt": "2026-10-03T08:10:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 2,
"totalPages": 1,
"hasNext": false,
"hasPrev": false
}
}
}Export the history#
/api/flags/{id}/history/export?format=csvformat is csv (the default) or json. It comes back as a download named like flag-history-checkout-layout-2026-10-03.json, newest first, and is not wrapped in the usual envelope. At most 10,000 rows are included; when the history is longer the response header X-Export-Truncated is true (and truncated is true in the JSON). CSV cells that start with a formula character are prefixed with an apostrophe.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Query parameters
formatcsv | jsonDefault csv.
Errors
- 400
Format must be csv or json. - 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). - 404
Flag not found.
curl -s -b "auth_session=$SESSION" -OJ \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/history/export?format=json"{
"exportedAt": "2026-10-03T09:00:00.000Z",
"flag": {
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"key": "checkout-layout",
"name": "Checkout layout",
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71"
},
"count": 1,
"truncated": false,
"entries": [
{
"timestamp": "2026-10-03T08:10:00.000Z",
"flagKey": "checkout-layout",
"flagName": "Checkout layout",
"action": "toggle",
"environmentKey": "production",
"environmentName": "Production",
"previousValue": false,
"newValue": true,
"changedByEmail": "dana@example.com",
"changedById": "u_01"
}
]
}Roll back#
/api/flags/{id}/rollbackversion is optional; without it the environment returns to the most recent earlier version that serves differently (looking back through up to 50 versions). reason is up to 300 characters and is kept with the version. The rollback is saved as a new version (here version 4, restoring version 2), so it can be undone. It never restores the emergency stop. Segments deleted since are dropped from the restored configuration. Services that cannot use a session can do the same with an admin key; see the Evaluation API. Approval does not apply to rollbacks.
Authorization
rollouts.rollback
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Body
environmentstringRequiredThe environment name to roll back.versionintegerA saved version number, 1 or higher. Default: the most recent earlier version that serves differently.reasonstringTrimmed, up to 300 characters. Kept with the new version.
Errors
- 400Malformed JSON (
Invalid JSON body),Environment is required,Version must be 1 or higher,Reason must be 300 characters or less;The flag is already at this version;There is no earlier version to roll back to(no version given); a version recorded under an emergency stop, or one that predates the flag's variants or uses variants that changed since (Pick a later version.); a prerequisite that no longer exists; or an archived flag or project. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
rollouts.rollback, cannot change production, or the emergency stop is active (Cannot roll back while the kill switch is active). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found,Environment “qa” is not configured for this flag, orThat version does not exist.
curl -s -X POST "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/rollback" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "environment": "production", "version": 2, "reason": "error rate spike" }'{
"status": "success",
"message": "Flag rolled back 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": true,
"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": true,
"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": 4,
"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:30:00.000Z",
"pinned": false
}
}Emergency stop#
Stop or restore#
/api/flags/kill-switchServes the off result to everyone for the chosen flags and environments until it is lifted, whatever the targeting says. Only active (not archived) flags are touched.
The result counts what happened: flagsAffected flags, changed flag-and-environment pairs, wasEnabled that were serving traffic until now, restored (restore only) turned back on, and skipped pairs that were already in the target state or not configured. Repeating a request is safe.
Authorization
kill_switch.execute (restore: kill_switch.restore)
Body
modeactivate | restoreRequiredStop the flags, or lift the stop.environmentsstring[]RequiredEnvironment names, 1 to 50.flagIdsstring[]1 to 500 flags. Leave it out to cover every active flag in the organization, or give projectId to narrow it to one project.projectIdstringUsed when flagIds is not given.reasonstringUp to 300 characters, kept in the audit log and on each version.
Errors
- 400Malformed JSON (
Invalid JSON body),Mode must be activate or restore,Choose at least one environment,Choose at least one flag(an emptyflagIds),Too many flags in one request(over 500), orReason must be 300 characters or less. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
kill_switch.execute(orkill_switch.restorefor restore) for one of the environments. Developers are withdrawn from it in production. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Unknown environment: qa, orNo matching flags foundwhen none of the flagIds exist or are active.
curl -s -X POST "$FLAGSWIFT_URL/api/flags/kill-switch" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{
"mode": "activate",
"environments": ["production"],
"flagIds": ["7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13"],
"reason": "checkout errors"
}'{
"status": "success",
"message": "Kill switch activated",
"data": {
"mode": "activate",
"flagsAffected": 1,
"changed": 1,
"wasEnabled": 1,
"restored": 0,
"skipped": 0
}
}Production
- The stop is an evaluation reason,
KILL_SWITCH, so SDKs and the inspector show why a flag is off. - Lifting it puts each flag back to whether it was on or off when the stop began. A stop recorded before snapshots existed is lifted and left off.
- While a flag is stopped in an environment, toggling and rollback there are refused with
403.
Common patterns#
Ramp a rollout, with a way back#
# 1. Turn the flag on in production (rollout is 100% by default, so set the percentage first).
curl -s -X PATCH "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/environments/production" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "rolloutPercentage": 5 }'
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" }'
# 2. Widen it as confidence grows. Anyone already in stays in.
curl -s -X PATCH "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/environments/production" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "rolloutPercentage": 25 }'
# 3. Something is wrong: see the saved versions, then go back.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/versions?environment=production"
curl -s -X POST "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/rollback" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "environment": "production", "reason": "error rate spike" }'Check before you ship#
After changing targeting, call inspect for a person you expect in and one you expect out. The reason tells you which rule applied, so a surprising result points straight at the cause: DISABLED means the flag is off, DEPENDENCY_BLOCKED means a prerequisite is off for that person, ROLLOUT_OUT means their bucket is at or above cutoff.
Incident: stop everything, then bring it back#
# Stop one project's flags in production.
curl -s -X POST "$FLAGSWIFT_URL/api/flags/kill-switch" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "mode": "activate", "environments": ["production"], "projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71", "reason": "payment provider outage" }'
# When it is safe: flags that were on come back on, flags that were off stay off.
curl -s -X POST "$FLAGSWIFT_URL/api/flags/kill-switch" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "mode": "restore", "environments": ["production"], "projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71" }'