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:
| Encoding | Used when | 500,000 members | Exact? |
|---|---|---|---|
| Inline list | Up to 50,000 members (SEGMENT_INLINE_MAX) | - | Yes |
| Roaring bitmap | Every key is an integer, all of one kind | 117 bytes for sequential ids | Yes |
| Cuckoo filter | Anything else: UUIDs, emails | About 4 MB | One 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.
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.