Skip to content
FlagSwiftDocs

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#

PATCH/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)Required

    The flag id (not its key).
  • environmentstringRequired

    The environment name, such as production (not its id).

Body (send any of these)

  • rolloutPercentageinteger

    0 to 100. How much of the audience gets the flag on.
  • bucketByuser | account | device

    What the percentage is counted over, so everyone sharing that identifier gets the same outcome. Default user.
  • targetingobject

    { enabled, users, accounts?, devices? }; enabled and users are required (use []). Up to 1,000 of each; blanks and duplicates are removed. Named people are on regardless of the percentage while enabled is true. Replaces the previous targeting.
  • rulesarray

    Attribute 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.
  • allocationobject

    Variant 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.
  • offVariantstring

    The 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); or Allocation 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_session cookie.
  • 403Your role lacks flags.update, rollouts.update or targeting.update for 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).
  • 404Flag not found, or Environment “qa” is not configured for this flag.
Request
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 }
  }'
200OK
{
  "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#

POST/api/flags/{id}/environments/{environment}/inspect

Runs 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, reason and, for a flag with variants, variant and value are the answer an SDK would give.
  • bucket is the person's position from 0 to 9,999 and cutoff is where the rollout stops (percentage times 100). inRollout is true when the bucket is below the cutoff, and null when no identifier could be used (bucket is then null).
  • targeted, ruleMatched and matchedSegment say which route granted access; variantBucket is what picked the variant.

Authorization

flags.read

Path parameters

  • idstring (uuid)Required

    The flag id (not its key).
  • environmentstringRequired

    The environment name, such as production (not its id).

Body

  • identifierstring

    The user. Up to 255 characters.
  • accountstring

    The organization or tenant.
  • devicestring

    The install.
  • attributesobject

    Values that rules can match.

Errors

  • 400Malformed JSON (Invalid JSON body), Enter a user, account or device to check, an identifier over 255 characters, or Attributes must be an object.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Flag not found, or Environment “qa” is not configured for this flag.
Request
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" } }'
200OK
{
  "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#

GET/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)Required

    The flag id (not its key).

Query parameters

  • environmentstringRequired

    The environment name.
  • pageinteger

    From 1. Default 1.
  • limitinteger

    1 to 100. Default 20.

Errors

  • 400Environment is required, or limit outside 1 to 100.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Flag not found, or Environment “qa” is not configured for this flag.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/versions?environment=production&limit=20"
200OK
{
  "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#

GET/api/flags/{id}/history

Every 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)Required

    The flag id (not its key).

Query parameters

  • pageinteger

    From 1. Default 1.
  • limitinteger

    1 to 100. Default 20.

Errors

  • 400limit outside 1 to 100 or page below 1.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Flag not found.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/history?page=1&limit=20"
200OK
{
  "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#

GET/api/flags/{id}/history/export?format=csv

format 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)Required

    The flag id (not its key).

Query parameters

  • formatcsv | json

    Default csv.

Errors

  • 400Format must be csv or json.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Flag not found.
Request
curl -s -b "auth_session=$SESSION" -OJ \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/history/export?format=json"
200OKResponse · 200 OK (format=json, saved as a file)
{
  "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#

POST/api/flags/{id}/rollback

version 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)Required

    The flag id (not its key).

Body

  • environmentstringRequired

    The environment name to roll back.
  • versioninteger

    A saved version number, 1 or higher. Default: the most recent earlier version that serves differently.
  • reasonstring

    Trimmed, 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_session cookie.
  • 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).
  • 404Flag not found, Environment “qa” is not configured for this flag, or That version does not exist.
Request
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" }'
200OK
{
  "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#

POST/api/flags/kill-switch

Serves 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 | restoreRequired

    Stop the flags, or lift the stop.
  • environmentsstring[]Required

    Environment 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.
  • projectIdstring

    Used when flagIds is not given.
  • reasonstring

    Up 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 empty flagIds), Too many flags in one request (over 500), or Reason must be 300 characters or less.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks kill_switch.execute (or kill_switch.restore for 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).
  • 404Unknown environment: qa, or No matching flags found when none of the flagIds exist or are active.
Request
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"
  }'
200OK
{
  "status": "success",
  "message": "Kill switch activated",
  "data": {
    "mode": "activate",
    "flagsAffected": 1,
    "changed": 1,
    "wasEnabled": 1,
    "restored": 0,
    "skipped": 0
  }
}

Production

Developers are withdrawn from the kill switch in production. Release managers and admins keep it, so someone can always stop a flag in an incident.
  • 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#

Turn on, ramp, and undo
# 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#

Activate, later restore
# 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" }'