Star
Build

Segments

A segment is a named list of context keys, like "beta testers" or "enterprise accounts", that any rule can target. Import millions of members; every check still answers from memory.

Create one and add members

ENV=https://flags.acme.com/v1/admin/projects/acme/environments/production
      
      curl -X POST $ENV/segments -H "Authorization: Bearer $FEATUREKIT_TOKEN" -H "Content-Type: application/json" \
        -d '{ "key": "beta-testers", "name": "Beta testers" }'
      
      curl -X POST $ENV/segments/beta-testers/members -H "Authorization: Bearer $FEATUREKIT_TOKEN" -H "Content-Type: application/json" \
        -d '{ "add": [{ "contextKey": "u-ana" }, { "contextKey": "u-ben" }], "remove": [{ "contextKey": "u-cy" }] }'

Segments belong to one environment. A member is a context kind and a key together (kind defaults to user), so a user and an organization that share a key are different members.

Target it from a rule

"rules": [{
        "clauses": [{ "attribute": "key", "op": "segmentMatch", "values": ["beta-testers"] }],
        "variation": 1
      }]

Several segment keys in values means "a member of any of them". Add "negate": true for "everyone except", like "everyone but enterprise accounts".

Importing large lists

Each request adds up to 50,000 and removes up to 50,000 members, in its own transaction. A 10-million-member list is 200 requests, and a failed page is retried on its own instead of restarting the import.

const env = "https://flags.acme.com/v1/admin/projects/acme/environments/production";
      
      for (let i = 0; i < keys.length; i += 50_000) {
        await fetch(`${env}/segments/enterprise/members`, {
          method: "POST",
          headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "idempotency-key": `enterprise-import-${i}` },
          body: JSON.stringify({ add: keys.slice(i, i + 50_000).map((contextKey) => ({ contextKey })) }),
        });
      }

Mark lists synced from another system "external": true when you create them, so nobody edits them by hand. Add a member with "excluded": true to keep them out whatever else says: excluded always wins.

How it stays fast

Every SDK gets the segment inside its snapshot, encoded to fit:

EncodingUsed when500,000 membersExact?
Inline listUp to 50,000 members (SEGMENT_INLINE_MAX)-Yes
Roaring bitmapEvery key is an integer, all of one kind117 bytes for sequential idsYes
Cuckoo filterAnything else: UUIDs, emailsAbout 4 MBOne false positive in about 500 million checks

No encoding makes a network call, so a segment check costs about 185ns. A compile reads at most 2,000,000 members per segment (SEGMENT_MEMBER_CEILING); past that it fails loudly and the previous snapshot keeps serving, rather than building a partial list.

An unreadable segment never grants access

If an SDK can't read a segment, every rule using it fails, including negated ones. Treating it as "not a member" would turn "everyone except enterprise" into "everyone". See negation.

Deleting one

A segment still named by a rule can't be deleted: the API answers 409 SEGMENT_IN_USE and lists the flags. Remove it from their rules first.

Every endpoint is in the segments reference.