Skip to content
FlagSwiftDocs

Segments

A segment is a named group of people that many flags can target at once.

Concepts#

One group, many flags#

Define who is in a group once, then point any number of flags at it by key in each environment's segments list (see Rollouts). Editing the segment changes every flag that uses it, in every environment, as soon as SDKs refresh.

Who is a member#

A person is in a segment when any of these holds: their user id is in users, their account in accounts, their device in devices; they match any one rule; or they are in any segment it includes. Within a rule, all conditions must match.

Rules to know#

  • The key is what flags refer to, so it is fixed at creation. Keys are unique within the organization.
  • A segment has a scope, chosen at creation and fixed afterwards. Without projectId it is organization-wide: flags in any project can use it. With a projectId it is scoped to that project: only that project's flags can use it, only that project's configuration carries it, and it is deleted with the project. Keys stay unique across the organization.
  • Includes follow the scope: an organization-wide segment can include only organization-wide segments; a project segment can include organization-wide segments and segments of the same project. A segment cannot include itself, and segments cannot include each other in a loop.
  • A flag can name organization-wide segments and segments scoped to its own project; a segment scoped to another project is refused on save, and a flag that uses a project-scoped segment cannot be moved to another project until it is removed.
  • Segments reach every environment, so a role that cannot change production targeting (developers) cannot edit or delete a segment that a production flag uses, directly or through an include.
  • Editing an organization-wide segment refreshes the configuration of every project whose flags use it; editing a scoped one refreshes only its project. Deleting is refused while a flag uses it (the message names the projects), and deleting a project deletes the segments scoped to it and keeps the organization-wide ones.

Examples use $FLAGSWIFT_URL for your server and $SESSION for the value of the auth_session cookie; see Dashboard API.

What a segment holds#

A segment belongs to the organization (optionally scoped to one project) and is identified by a key that flags refer to, which is why the key cannot change. It can name individual users, accounts and devices, hold attribute rules, and include other segments.

Limits
LimitDescription
Segments per organization500.
KeyLower case letters and numbers with single hyphens or underscores between them, up to 50 characters. Trimmed and lower-cased for you.
Members5,000 users, accounts and devices together; each identifier up to 255 characters. Duplicates and blanks are removed.
Rules20 per segment, 10 conditions each. A rule matches when all its conditions do; the segment matches when any rule does. Each rule has an id of up to 50 characters.
ConditionAn attribute (up to 100 characters: letters, numbers and . _ : -), an operator of equals, contains or in, and a value of up to 255 characters. For in the value is a list of 1 to 100.
IncludesUp to 10 other segments, by key.
Fields on a segment in a response
FieldTypeDescription
id, key, name, descriptionstringIdentity. Use id in paths.
users, accounts, devicesstring[]Named members.
rulesarrayEach { id, conditions[] }. Every rule must carry an id; if two rules share one, the later is renamed (r1 becomes r1-2). Duplicate conditions in a rule, and rules identical to an earlier one, are dropped.
includesstring[]Keys of included segments.
projectId, projectNamestring | nullThe project the segment is scoped to and its name; both null for an organization-wide segment. Fixed at creation.
usageobject{ flags, segments, projects }: how many flags (archived ones too, in every project) use it, how many other segments include it, and projects, the list of { id, key, name, flags } for each project whose flags use it. Any flag or including segment blocks deletion.
createdBy, createdAt, updatedAtWho made it and when.

Endpoints#

Create a segment#

POST/api/segments

Returns 201 with the segment and its usage.

Authorization

segments.create

Body

  • keystringRequired

    What flags will call it. Trimmed and lower-cased; 1 to 50 characters matching ^[a-z0-9]+([-_][a-z0-9]+)*$. Unique in the organization. Cannot change later.
  • namestringRequired

    Trimmed, up to 80 characters.
  • descriptionstring

    Trimmed, up to 500 characters. Default empty.
  • usersstring[]

    User ids. Each 1 to 255 characters. Default empty.
  • accountsstring[]

    Account ids, same limits as users. Default empty.
  • devicesstring[]

    Device ids, same limits as users. Default empty.
  • rulesRule[]

    Up to 20. Default empty. Each is { id, conditions[] }: id required (up to 50 characters), 1 to 10 conditions of { attribute, operator, value } where operator is equals, contains or in. See the limits above.
  • includesstring[]

    Keys of other segments in the organization, up to 10. Default empty. An organization-wide segment may include only organization-wide segments; a project segment may include organization-wide ones and its own project's.
  • projectIdstring | null

    Optional. Omit or send null for an organization-wide segment (the default); send a project id to scope the segment to that project. The project must belong to your organization and not be archived. Cannot be changed later.

Errors

  • 400Malformed JSON (Invalid JSON body), validation failed (Key is required, Name is required, Key may only contain lowercase letters, numbers, hyphens and underscores, At most 20 rules), a rule problem (Rule 1, condition 1: …), more than 5,000 members, an unknown, out-of-scope or looping include (Unknown segment: vip, A segment cannot include itself, An organization-wide segment can only include organization-wide segments), the organization already has 500 segments, or projectId names a project that is not found (PROJECT_NOT_FOUND) or archived (PROJECT_ARCHIVED).
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks segments.create. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 409A segment with this key already exists.
Request
curl -s -X POST "$FLAGSWIFT_URL/api/segments" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "beta-testers",
    "name": "Beta testers",
    "users": ["user-123"],
    "rules": [
      { "id": "r1", "conditions": [{ "attribute": "plan", "operator": "in", "value": ["pro", "team"] }] }
    ],
    "includes": []
  }'
201Created
{
  "status": "success",
  "message": "Segment created successfully",
  "data": {
    "id": "4d9e7a31-0c5b-4b8e-a2f6-91c3d5e7f802",
    "key": "beta-testers",
    "name": "Beta testers",
    "description": "",
    "users": [
      "user-123"
    ],
    "accounts": [],
    "devices": [],
    "rules": [
      {
        "id": "r1",
        "conditions": [
          {
            "attribute": "plan",
            "operator": "in",
            "value": [
              "pro",
              "team"
            ]
          }
        ]
      }
    ],
    "includes": [],
    "projectId": null,
    "projectName": null,
    "createdBy": "dana@example.com",
    "createdAt": "2026-10-02T09:30:00.000Z",
    "updatedAt": "2026-10-02T09:30:00.000Z",
    "usage": {
      "flags": 0,
      "segments": 0,
      "projects": []
    }
  }
}

List segments#

GET/api/segments

There is no paging: the response data is the plain array of the organization's segments (at most 500), sorted by key, each with its usage.

Authorization

segments.read

Query parameters

  • projectIdstring

    Optional. Keep only the segments usable in that project: organization-wide ones and ones scoped to it. Leave it out to list every segment of the organization, including those scoped to other projects (see projectId and projectName on each).

Errors

  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks segments.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Project not found, when projectId is given and is not in your organization.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/segments"
200OK
{
  "status": "success",
  "message": "OK",
  "data": [
    {
      "id": "4d9e7a31-0c5b-4b8e-a2f6-91c3d5e7f802",
      "key": "beta-testers",
      "name": "Beta testers",
      "description": "",
      "users": [
        "user-123"
      ],
      "accounts": [],
      "devices": [],
      "rules": [
        {
          "id": "r1",
          "conditions": [
            {
              "attribute": "plan",
              "operator": "in",
              "value": [
                "pro",
                "team"
              ]
            }
          ]
        }
      ],
      "includes": [],
      "projectId": null,
      "projectName": null,
      "createdBy": "dana@example.com",
      "createdAt": "2026-10-02T09:30:00.000Z",
      "updatedAt": "2026-10-02T09:30:00.000Z",
      "usage": {
        "flags": 2,
        "segments": 0,
        "projects": [
          {
            "id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
            "key": "web",
            "name": "Web",
            "flags": 2
          }
        ]
      }
    },
    {
      "id": "a8f1c2d3-e4b5-4697-8a0b-c1d2e3f4a5b6",
      "key": "internal",
      "name": "Internal staff",
      "description": "",
      "users": [],
      "accounts": [
        "acme"
      ],
      "devices": [],
      "rules": [],
      "includes": [],
      "projectId": null,
      "projectName": null,
      "createdBy": "dana@example.com",
      "createdAt": "2026-10-02T09:30:00.000Z",
      "updatedAt": "2026-10-02T09:30:00.000Z",
      "usage": {
        "flags": 0,
        "segments": 1,
        "projects": []
      }
    }
  ]
}

Get a segment#

GET/api/segments/{id}

Authorization

segments.read

Path parameters

  • idstring (uuid)Required

    The segment id (not its key).

Errors

  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks segments.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Segment not found: no segment with that id in your organization.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/segments/4d9e7a31-0c5b-4b8e-a2f6-91c3d5e7f802"
200OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "id": "4d9e7a31-0c5b-4b8e-a2f6-91c3d5e7f802",
    "key": "beta-testers",
    "name": "Beta testers",
    "description": "",
    "users": [
      "user-123"
    ],
    "accounts": [],
    "devices": [],
    "rules": [
      {
        "id": "r1",
        "conditions": [
          {
            "attribute": "plan",
            "operator": "in",
            "value": [
              "pro",
              "team"
            ]
          }
        ]
      }
    ],
    "includes": [],
    "projectId": null,
    "projectName": null,
    "createdBy": "dana@example.com",
    "createdAt": "2026-10-02T09:30:00.000Z",
    "updatedAt": "2026-10-02T09:30:00.000Z",
    "usage": {
      "flags": 2,
      "segments": 0,
      "projects": [
        {
          "id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
          "key": "web",
          "name": "Web",
          "flags": 2
        }
      ]
    }
  }
}

Edit a segment#

PATCH/api/segments/{id}

Any of name, description, users, accounts, devices, rules and includes. Lists replace the old list; they are not merged, so to add a user send the full list. Anything you leave out is kept. The key is ignored; the scope (projectId) cannot be changed.

Authorization

segments.update

Path parameters

  • idstring (uuid)Required

    The segment id (not its key).

Body

  • namestring

    Up to 80 characters; cannot be blank.
  • descriptionstring

    Up to 500 characters.
  • users, accounts, devicesstring[]

    Replaces the whole list. Each 1 to 255 characters; 5,000 members in total.
  • rulesRule[]

    Replaces the whole list. Up to 20 rules, same shape as on create.
  • includesstring[]

    Replaces the whole list. Up to 10 keys of other segments in the organization, within the scope rules above.
  • projectIdstring | null

    Not editable. Accepted only if it equals the current scope; any other value is refused with 400 (SEGMENT_SCOPE_IMMUTABLE).

Errors

  • 400Malformed JSON, validation failed (Name is required if you send an empty name, Description must be 500 characters or less), a rule or include problem as for create, or an attempt to change the scope (A segment's scope cannot be changed after it is created).
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks segments.update, or a production flag uses this segment and your role cannot change targeting in production (This segment is used by a flag in production, where your role cannot change targeting). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Segment not found: no segment with that id in your organization.
Request
curl -s -X PATCH "$FLAGSWIFT_URL/api/segments/4d9e7a31-0c5b-4b8e-a2f6-91c3d5e7f802" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "users": ["user-123", "user-456"], "description": "Opted in to the beta" }'
200OK
{
  "status": "success",
  "message": "Segment updated successfully",
  "data": {
    "id": "4d9e7a31-0c5b-4b8e-a2f6-91c3d5e7f802",
    "key": "beta-testers",
    "name": "Beta testers",
    "description": "Opted in to the beta",
    "users": [
      "user-123",
      "user-456"
    ],
    "accounts": [],
    "devices": [],
    "rules": [
      {
        "id": "r1",
        "conditions": [
          {
            "attribute": "plan",
            "operator": "in",
            "value": [
              "pro",
              "team"
            ]
          }
        ]
      }
    ],
    "includes": [],
    "projectId": null,
    "projectName": null,
    "createdBy": "dana@example.com",
    "createdAt": "2026-10-02T09:30:00.000Z",
    "updatedAt": "2026-10-03T08:00:00.000Z",
    "usage": {
      "flags": 2,
      "segments": 0,
      "projects": [
        {
          "id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
          "key": "web",
          "name": "Web",
          "flags": 2
        }
      ]
    }
  }
}

Delete a segment#

DELETE/api/segments/{id}

Authorization

segments.delete

Path parameters

  • idstring (uuid)Required

    The segment id (not its key).

Errors

  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks segments.delete (admins hold it), or a production flag uses the segment. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Segment not found: no segment with that id in your organization.
  • 409Still in use (This segment is used by 2 flags in “Web” (checkout, banner) and 1 other segment. Remove it there first.). Take it out of those flags' environment configuration, and out of other segments' includes, then retry.
Request
curl -s -X DELETE -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/segments/4d9e7a31-0c5b-4b8e-a2f6-91c3d5e7f802"
200OK
{
  "status": "success",
  "message": "Segment deleted successfully",
  "data": null
}
  • A segment used by a flag or included by another segment is protected from deletion, so removing one cannot quietly change what people see.
  • Segments ship to server SDKs inside the configuration payload, so they evaluate locally with the same engine.

Common patterns#

Create a segment and target it from a flag#

Two calls
# 1. Create the segment.
curl -s -X POST "$FLAGSWIFT_URL/api/segments" \
  -b "auth_session=$SESSION" -H "Content-Type: application/json" \
  -d '{ "key": "beta-testers", "name": "Beta testers", "accounts": ["acme"] }'

# 2. Make a flag serve ON to it in staging. Unknown keys, and segments scoped to another project, are refused with 400.
curl -s -X PATCH "$FLAGSWIFT_URL/api/flags/FLAG_ID/environments/staging" \
  -b "auth_session=$SESSION" -H "Content-Type: application/json" \
  -d '{ "segments": ["beta-testers"] }'

Add a person to an existing segment#

Updates replace lists, so read the segment first, add to users and send the whole list back. Two people doing this at once can overwrite each other; for a group that changes often, prefer an attribute rule such as { "attribute": "plan", "operator": "in", "value": ["pro"] } that your app already sends in the evaluation context.

Retire a segment#

Deleting is refused while anything uses it, which is the point. Check usage on the segment (it names every project that uses it), remove it from each flag's segments and from other segments' includes, then delete.