Skip to main content

​
What is a flag?

A flag is a named boolean switch that lives within an environment. It has a key used to identify it at evaluation time, an enabled toggle that controls whether the flag is active, and a default_value that is returned when no targeting rule matches.

​
The key field

The key is a short, stable identifier you define when creating a flag — for example, new-dashboard or checkout-v2. You pass this value as flag_key in evaluation requests: 
{
  "flag_key": "new-dashboard",
  "environment_key": "production",
  "context": {
    "user_id": "user-123"
  }
}

​
Enabled state

The enabled field controls whether the flag participates in rule evaluation.
  • When enabled is false, the evaluation engine skips all rules and immediately returns default_value with reason "disabled".
  • When enabled is true, rules are evaluated in priority order.
This makes enabled a master switch — useful for disabling a flag entirely without deleting its rules.

​
Default value

The default_value is returned in two situations:
  1. The flag is disabled (enabled: false) — reason: "disabled"
  2. The flag is enabled but no rule matches the evaluation context — reason: "default"
default_value is a boolean and defaults to false when creating a new flag.

​
Salt

The salt field is an auto-generated string used as an input to the hashing function for percentage-based rules. It ensures that percentage rollouts for different flags produce independent, uncorrelated bucketing even when the same bucket_by field value (e.g., the same user_id) is used across flags. You do not set the salt manually — it is generated by the API at flag creation time.

​
Evaluation order

When POST /api/v1/evaluate is called, the engine follows this sequence:
  1. Disabled check — If enabled is false, return default_value with reason disabled.
  2. Rule evaluation — Active rules are checked in ascending priority order (lowest number first). The first matching rule determines the result with reason rule_match.
  3. Default fallback — If no rule matches, return default_value with reason default.

​
Flag schema

FieldTypeDescription
idUUIDUnique flag identifier
environment_idUUIDThe environment this flag belongs to
keystringIdentifier used in evaluation requests
namestringDisplay name
descriptionstringOptional description (nullable)
enabledbooleanWhether the flag participates in rule evaluation
default_valuebooleanValue returned when no rule matches or flag is disabled
saltstringAuto-generated; used for deterministic percentage bucketing
created_atdatetimeISO 8601 creation timestamp
updated_atdatetimeISO 8601 last-updated timestamp

​
Endpoints

MethodEndpointPermissionDescription
GET/api/v1/projects/{project_id}/flagsflags.readList all flags in a project
POST/api/v1/projects/{project_id}/flagsflags.writeCreate a new flag
GET/api/v1/projects/{project_id}/flags/{id}flags.readGet a flag and its rules
PATCH/api/v1/projects/{project_id}/flags/{id}flags.writeUpdate flag name, description, enabled, or default_value
DELETE/api/v1/projects/{project_id}/flags/{id}flags.deleteDelete a flag and its rules

​
Required permissions

  • flags.read — Read flags and their rules
  • flags.write — Create and update flags
  • flags.delete — Delete flags (cascades to rules)

Build docs developers (and LLMs) love

Get started for freeTalk to us