Tutorial

Flags

A flag, the audience its rules point at, and the audit trail behind both

Checked 2026-09-28

A config flag is one typed value of an environment, decided per request instead of at deploy time: a default, targeting rules and percentage rollouts, and an answer for whoever asks. Three collections make it up — the flag, the audience its rules point at, and the record of what changed.

#The three collections

ConfigFlag

One typed configuration value or feature flag of an environment: a default, targeting rules and percentage rollouts.

ConfigSegment

A reusable audience of an environment: subjects listed by id, and conditions over the evaluation context.

ConfigChange

One committed change to a flag or segment: the audit trail, kept after the flag or segment is deleted.

#A flag is one typed value

Every value of a flag has the same type, and there is always a default to fall back on. The rest of the spec is how an evaluation departs from that default.

The flag's id is the key evaluators ask for, so it is worth choosing rather than accepting the one the server assigns. enabled is what makes a rollout reversible in one call: with the flag off, every evaluation returns the default and the rules are not read at all.

#A segment is an audience you reuse

A ConfigSegment is a reusable audience of an environment. Flag rules refer to it with IN_SEGMENT, so one change to the audience reaches every flag that names it. That is the reason to have segments rather than the same conditions copied into twenty flags: "our beta testers" becomes one object with one meaning.

A segment that a flag names cannot be deleted — the delete is refused — which is what keeps a live rule from pointing at nothing. Segments covers building one and changing it.

#A change is the audit trail

A ConfigChange is one committed change to a flag or segment of an environment. It records the target, the action, the target's generation after the change, the target's spec as it stood at that moment, and who made it. The trail outlives the flag: a deleted flag leaves its changes behind.

Change history covers what each record holds and how to read the trail back.

#Names and ids

Flag

orgs/{org}/projects/{project}/envs/{env}/config_flags/{config_flag}

Flag id

cfg_<cell><ulid>

Segment

orgs/{org}/projects/{project}/envs/{env}/config_segments/{config_segment}

Segment id

seg_<cell><ulid>

Change

orgs/{org}/projects/{project}/envs/{env}/config_changes/{config_change}

Change id

chg_<cell><ulid>

All three live in one environment, and a name is a path, so the same path works in the API, the CLI and the console.

#The scopes

• config:read — flags, segments, changes and the snapshot.
• config:write — creating, changing and deleting a flag or a segment.
• config:evaluate — reading values for one evaluation context, never the rules behind them. A publishable key may hold this scope, which is how a browser or a mobile app evaluates flags without holding a secret. Keys and scopes covers the two kinds of key.