Skip to content
FlagSwiftDocs

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 403 and 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.

Fields you set when creating a flag
FieldTypeDescription
name*stringThe 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*stringThe readable name shown in the console.
projectId*stringThe 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.
descriptionstringUp to 500 characters. Default empty.
owner, expectedRemovalAt, expiresAt, permanentoptionalLifecycle fields; see Lifecycle. owner defaults to you. These can also be sent when editing.
variantsarrayUp 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.
Fields on every flag in a response
FieldTypeDescription
idstringUse this in paths such as /api/flags/{id}.
environmentsobjectOne entry per environment name: enabled, rolloutPercentage, targeting, killSwitchActive, version, lastModified, modifiedBy and, where set, rules, segments, bucketBy, dependencies, offVariant and allocation.
archivedAtISO date | nullSet while the flag is archived.
createdBy, owneremail | nullowner falls back to the creator.
pinnedbooleanWhether you pinned it. Only meaningful where the response is per person (the list and pin calls).
createdAt, updatedAtISO dateTimestamps.

Create and find#

Create a flag#

POST/api/flags

Returns 201 with the flag. The flag appears in every environment of the organization, off.

Authorization

flags.create

Body

  • namestringRequired

    The key your code uses. Trimmed and lower-cased; letters, numbers, hyphens and underscores. Unique within the project, and it cannot be changed.
  • displayNamestringRequired

    The readable name shown in the console. Trimmed, cannot be blank.
  • projectIdstringRequired

    The project the flag lives in. It must exist and must not be archived.
  • typeboolean | string | number | json

    Default boolean. Anything other than boolean needs 2 to 20 variants; boolean flags take none.
  • descriptionstring

    Trimmed, 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 | null

    Up to 254 characters, must be an email address. Defaults to you on create; null clears it.
  • expectedRemovalAtISO date | null

    When the flag should be cleaned up. Any date string that parses; null clears it.
  • expiresAtISO date | null

    When the flag expires. Same format; null clears it.
  • permanentboolean

    Marks the flag as long-lived. A permanent flag cannot have either date.

Errors

  • 400Malformed JSON (Invalid JSON body), or validation failed, for example Key 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, or This project is archived. Restore it to make changes.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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).
  • 404Project 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.).
Request
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" }
    ]
  }'
201Created
{
  "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#

GET/api/flags

Newest first, always; there is no sort parameter. Returns { items, pagination }, where pagination is { page, limit, total, totalPages, hasNext, hasPrev }.

Authorization

flags.read

Query parameters

  • projectIdstring

    Only this project's flags, archived project included. Without it you get every project's flags except those in archived projects.
  • searchstring

    Matches key and display name. Up to 100 characters.
  • environmentstring

    With status, the environment the status refers to. Ignored on its own.
  • statusenabled | disabled

    Flags that are on or off in the chosen environment. Ignored without environment.
  • typeboolean | string | number | json

    Only flags of this type.
  • archivedactive | archived | all

    Default active.
  • markpinned

    Only flags you pinned. The other filters still apply.
  • pageinteger

    From 1. Default 1.
  • limitinteger

    1 to 100. Default 10.

Errors

  • 400A parameter is invalid, for example limit above 100 or archived that is not one of the three values.
  • 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).
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags?projectId=b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71&status=enabled&environment=production&limit=20"
200OK
{
  "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#

GET/api/flags/{id}

Works for archived flags too, so you can inspect one before restoring it.

Authorization

flags.read

Path parameters

  • idstring (uuid)Required

    The flag id (not its key).

Errors

  • 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).
  • 404No flag with that id in your organization (Flag not found).
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13"
200OK
{
  "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#

GET/api/flags/{id}/dependents

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

    The flag id (not its key).

Errors

  • 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).
  • 404No flag with that id in your organization (Flag not found).
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/dependents"
200OK
{
  "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#

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

    The flag id (not its key).

Body (send any of these)

  • displayNamestring

    Trimmed, cannot be empty.
  • descriptionstring

    Trimmed, up to 500 characters.
  • projectIdstring

    Moves the flag to another project of the same organization. This also needs flags.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 | null

    Up to 254 characters, must be an email address. Defaults to you on create; null clears it.
  • expectedRemovalAtISO date | null

    When the flag should be cleaned up. Any date string that parses; null clears it.
  • expiresAtISO date | null

    When the flag expires. Same format; null clears it.
  • permanentboolean

    Marks 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_session cookie.
  • 403Your role lacks flags.update, or you tried to move the flag without flags.move. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Flag not found, or for a move Project not found.
  • 409A move was refused because the key already exists in the target project, or another flag uses this one as a prerequisite.
Request
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" }'
200OK
{
  "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#

PUT/api/flags/{id}/variants

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

    The flag id (not its key).

Body

  • variantsVariant[]Required

    The 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), or Variants 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_session cookie.
  • 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.
Request
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" }
    ]
  }'
200OK
{
  "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#

POST/api/flags/{id}/archive

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

    The flag id (not its key).

Errors

  • 400This flag is already archived.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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.
Request
curl -s -X POST -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/archive"
200OK
{
  "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#

POST/api/flags/{id}/restore

Authorization

flags.update

Path parameters

  • idstring (uuid)Required

    The flag id (not its key).

Errors

  • 400This flag is not archived.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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).
Request
curl -s -X POST -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/restore"
200OK
{
  "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#

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

    The flag id (not its key).

Query parameters

  • forceboolean

    Default 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 send force=true.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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).
Request
curl -s -X DELETE -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13?force=true"
200OK
{
  "status": "success",
  "message": "Flag deleted successfully",
  "data": null
}

Pin or unpin for yourself#

PUT/api/flags/{id}/marks

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

    The flag id (not its key).

Body

  • kind"pin"Required

    The only kind there is.
  • valuebooleanRequired

    true 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_session cookie.
  • 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).
Request
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 }'
200OK
{
  "status": "success",
  "message": "Saved",
  "data": {
    "pinned": true
  }
}

Switch on and off#

Toggle in one environment#

POST/api/flags/{id}/toggle

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

    The flag id (not its key).

Body

  • environmentstringRequired

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

Errors

  • 400Malformed JSON (Invalid JSON body), or Environment is required, or the flag or its project is archived.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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).
  • 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/toggle" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "production" }'
200OK
{
  "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#

GET/api/flags/{id}/analytics?environment=production&days=14

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

    The flag id (not its key).

Query parameters

  • environmentstringRequired

    The environment name to report on.
  • daysinteger

    1 to 90. Default 14.

Errors

  • 400Environment is required, or days outside 1 to 90.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks metrics.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Flag not found, or Environment “qa” does not exist for this flag.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/analytics?environment=production&days=14"

Versions

Every change to an environment's configuration saves a new version, so any toggle can be rolled back later.
  • 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.

Check, archive, delete
# 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#

Page through every enabled flag in a project
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.