Rules

What is a rule?

A rule is a conditional expression attached to a flag. When a flag is evaluated, its active rules are checked in priority order. The first rule whose condition matches the evaluation context determines the returned value. Each rule has:

A type that determines how the condition is evaluated
A priority that controls the order rules are checked
A return_value (boolean) that is returned when the rule matches
An is_active toggle that lets you disable individual rules without deleting them

Priority

The priority field is an integer where lower numbers are checked first. If two rules have priority 1 and 2, the rule with priority 1 is evaluated first. The first matching rule wins — subsequent rules are not evaluated. Set priorities intentionally. A broad rule with a low priority number can shadow more specific rules that have higher priority numbers.

is_active

When is_active is false, the rule is skipped entirely during evaluation. Inactive rules do not affect the result. Use this to temporarily disable a rule without deleting it.

Rule types

boolean
attribute
percentage

A boolean rule always matches, regardless of the evaluation context. It is the simplest rule type and is commonly used as a kill switch — when you need to force a flag to return a specific value for all users.Required fields: flag_id, priority, rule_type, return_valueExample: force a flag off for all users

{
  "flag_id": "550e8400-e29b-41d4-a716-446655440000",
  "priority": 1,
  "rule_type": "boolean",
  "bucket_by": "user_id",
  "return_value": false
}

Because this rule always matches, place it at the lowest priority number (highest precedence) only when you intend it to override all other rules. Give it a higher priority number (lower precedence) if you want other rules to be evaluated first.

An attribute rule matches when a specific field in the evaluation context satisfies a condition defined by an operator and target value.Required fields: flag_id, priority, rule_type, attribute, operator, value_json, return_valueOperators:

Operator	Match condition	`value_json` format
`eq`	Context value equals target	JSON string
`neq`	Context value does not equal target	JSON string
`contains`	Context value contains the substring	JSON string
`starts_with`	Context value starts with the substring	JSON string
`ends_with`	Context value ends with the substring	JSON string
`in`	Context value is in the target list	JSON array of strings
`not_in`	Context value is not in the target list	JSON array of strings

The value_json field is a JSON-encoded string. For scalar operators (eq, neq, contains, starts_with, ends_with), encode a JSON string. For list operators (in, not_in), encode a JSON array of strings.Example: enable for users in Turkey or Germany

{
  "flag_id": "550e8400-e29b-41d4-a716-446655440000",
  "priority": 1,
  "rule_type": "attribute",
  "attribute": "country",
  "operator": "in",
  "value_json": "[\"TR\",\"DE\"]",
  "bucket_by": "user_id",
  "return_value": true
}

The evaluation context for this rule would need to include a country field:

{
  "flag_key": "new-dashboard",
  "environment_key": "production",
  "context": {
    "user_id": "user-123",
    "country": "TR"
  }
}

A percentage rule enables deterministic gradual rollouts. It hashes the value of the bucket_by context field together with the flag’s salt to produce a stable bucket assignment. If the resulting bucket falls within the rollout_percentage, the rule matches.Because the hash is deterministic, the same user always lands in the same bucket — a user included in a 20% rollout remains included as the rollout expands to 50%.Required fields: flag_id, priority, rule_type, rollout_percentage, return_valueOptional fields: bucket_by (defaults to user_id)rollout_percentage accepts an integer between 0 and 100.Example: 50% rollout bucketed by user_id

{
  "flag_id": "550e8400-e29b-41d4-a716-446655440000",
  "priority": 1,
  "rule_type": "percentage",
  "rollout_percentage": 50,
  "bucket_by": "user_id",
  "return_value": true
}

To bucket by a different context field — for example, to roll out to 10% of organizations rather than users — set bucket_by to the relevant context key:

{
  "flag_id": "550e8400-e29b-41d4-a716-446655440000",
  "priority": 1,
  "rule_type": "percentage",
  "rollout_percentage": 10,
  "bucket_by": "organization_id",
  "return_value": true
}

Rule schema

Field	Type	Description
`id`	UUID	Unique rule identifier
`flag_id`	UUID	The flag this rule belongs to
`priority`	integer	Evaluation order — lower number is checked first
`rule_type`	string	`boolean`, `attribute`, or `percentage`
`attribute`	string	Context field to match against (attribute rules only; nullable)
`operator`	string	Comparison operator (attribute rules only; nullable)
`value_json`	string	JSON-encoded target value (attribute rules only; nullable)
`rollout_percentage`	integer	Inclusion threshold 0–100 (percentage rules only; nullable)
`bucket_by`	string	Context field used for hashing; defaults to `user_id`
`return_value`	boolean	Value returned when this rule matches
`is_active`	boolean	When `false`, this rule is skipped during evaluation
`created_at`	datetime	ISO 8601 creation timestamp
`updated_at`	datetime	ISO 8601 last-updated timestamp

Endpoints

Method	Endpoint	Permission	Description
`POST`	`/api/v1/projects/{project_id}/rules`	`rules.write`	Create a new rule
`PATCH`	`/api/v1/projects/{project_id}/rules/{id}`	`rules.write`	Update a rule
`DELETE`	`/api/v1/projects/{project_id}/rules/{id}`	`rules.delete`	Delete a rule

Required permissions

rules.read — Read rules (returned alongside flags via GET /api/v1/projects/{project_id}/flags/{id})
rules.write — Create and update rules
rules.delete — Delete rules

Get Started

Core Concepts

Guides

Account & Billing

What is a rule?

Priority

is_active

Rule types

Rule schema

Endpoints

Required permissions

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Account & Billing

​What is a rule?

​Priority

​is_active

​Rule types

​Rule schema

​Endpoints

​Required permissions

Build docs developers (and LLMs) love

What is a rule?

Priority

is_active

Rule types

Rule schema

Endpoints

Required permissions