Skip to main content
POST /api/v1/projects/{project_id}/rules Requires rules.write permission. Rules are evaluated in priority order (lowest number first) during flag evaluation. Rule types:
  • boolean — Always matches. Returns return_value unconditionally.
  • attribute — Matches when a context attribute satisfies the operator condition.
  • percentage — Deterministic rollout based on a hash of the bucket_by context field.
Operators (for attribute rules): eq, neq, in, not_in, contains, starts_with, ends_with value_json encoding: Use a JSON string (e.g. "\"TR\"") for eq/neq/contains/starts_with/ends_with; use a JSON array of strings (e.g. "[\"TR\",\"DE\"]") for in/not_in.

​
Path parameters

​
project_id
string
required
UUID of the project.

​
Request body

​
flag_id
string
required
UUID of the flag this rule belongs to.
​
priority
integer
required
Evaluation order. Lower numbers are evaluated first.
​
rule_type
string
required
One of boolean, attribute, or percentage.
​
return_value
boolean
required
Value returned when this rule matches.
​
attribute
string | null
Context key to evaluate. Required for attribute rules.
​
operator
string | null
Comparison operator for attribute rules. One of eq, neq, in, not_in, contains, starts_with, ends_with.
​
value_json
string | null
JSON-encoded target value. String for scalar operators; array of strings for in/not_in.
​
rollout_percentage
integer | null
Percentage of traffic to include (0–100). Required for percentage rules.
​
bucket_by
string
default:"user_id"
Context field used to deterministically assign users to buckets.
​
is_active
boolean
default:"true"
Whether this rule participates in evaluation immediately.

​
Response

​
rule
object
required
The newly created rule.

​
Errors

StatusWhen
400Request body is invalid or missing required fields
403Caller lacks rules.write permission
404Flag not found

​
Examples

curl -X POST http://localhost:8080/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/rules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "flag_id": "550e8400-e29b-41d4-a716-446655440000",
    "priority": 1,
    "rule_type": "percentage",
    "rollout_percentage": 50,
    "bucket_by": "user_id",
    "return_value": true
  }'

{
  "rule": {
    "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "flag_id": "550e8400-e29b-41d4-a716-446655440000",
    "priority": 1,
    "rule_type": "percentage",
    "attribute": null,
    "operator": null,
    "value_json": null,
    "rollout_percentage": 50,
    "bucket_by": "user_id",
    "return_value": true,
    "is_active": true,
    "created_at": "2026-03-21T10:00:00Z",
    "updated_at": "2026-03-21T10:00:00Z"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us