Rules

Create and manage targeting rules for feature flags. Rules determine which users see which flag values based on conditions, percentages, and segments. Rules are scoped to a specific flag and environment.

Base URL: https://app.krafter.dev/api/v1

List Rules

Retrieve all rules for a flag in a given environment.

GET /flags/:flag_id/rules?environment=production

Required scope: flags:read

Query Parameters

Parameter	Type	Default	Description
environment	string	production	Environment to list rules for.

Example Request

curl "https://app.krafter.dev/api/v1/flags/c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f/rules?environment=production" \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": [
    {
      "id": "e5f6a7b8-9c0d-4e1f-9a2b-3c4d5e6f7a8b",
      "environment": "production",
      "position": 1,
      "conditions": [
        {
          "attribute": "plan",
          "operator": "equals",
          "value": "pro"
        }
      ],
      "value": true,
      "percentage": null,
      "enabled": true,
      "segment_id": null,
      "created_at": "2025-03-12T10:00:00Z",
      "updated_at": "2025-03-12T10:00:00Z"
    },
    {
      "id": "f6a7b8c9-0d1e-4f2a-9b3c-4d5e6f7a8b9c",
      "environment": "production",
      "position": 2,
      "conditions": [],
      "value": true,
      "percentage": 25,
      "enabled": true,
      "segment_id": null,
      "created_at": "2025-03-12T10:05:00Z",
      "updated_at": "2025-03-14T09:30:00Z"
    }
  ]
}

---

Create Rule

Create a new targeting rule for a flag. Rules are evaluated in order of position — the first matching rule determines the flag value.

POST /flags/:flag_id/rules

Required scope: flags:write

Request Body

Field	Type	Required	Description
environment	string	Yes	Environment this rule applies to (e.g., "production").
position	integer	No	Evaluation order. Lower positions are evaluated first. Auto-assigned if omitted.
conditions	array	Yes	Array of condition objects. See Condition Format below.
value	any	Yes	Value to return when this rule matches. Type must match the flag's flag_type.
percentage	integer	No	Percentage rollout (0-100). When set, the rule matches for this percentage of users.
enabled	boolean	No	Whether the rule is active. Defaults to true.
segment_id	string	No	Link this rule to a reusable segment instead of inline conditions.

Condition Format

Each condition is an object with three fields:

Field	Type	Description
attribute	string	The context attribute to evaluate (e.g., "plan", "country", "user_id").
operator	string	One of equals, not_equals, contains, not_contains, starts_with, ends_with, in, not_in, greater_than, less_than, regex, is_true, is_false, exists, not_exists. See Condition Operators for semantics, edge cases (missing attribute behaviour, unknown-operator fallback), and the regex safety limits (500-byte pattern cap, nested-quantifier ReDoS guard).
value	any	The value to compare against. For in and not_in, use an array or comma-separated string. For is_true / is_false / exists / not_exists, set to null.

Example Request

curl -X POST https://app.krafter.dev/api/v1/flags/c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f/rules \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "position": 1,
    "conditions": [
      {
        "attribute": "plan",
        "operator": "equals",
        "value": "pro"
      },
      {
        "attribute": "country",
        "operator": "in",
        "value": ["US", "CA", "GB"]
      }
    ],
    "value": true,
    "enabled": true
  }'

Example Response

// 201 Created
{
  "data": {
    "id": "e5f6a7b8-9c0d-4e1f-9a2b-3c4d5e6f7a8b",
    "environment": "production",
    "position": 1,
    "conditions": [
      {
        "attribute": "plan",
        "operator": "equals",
        "value": "pro"
      },
      {
        "attribute": "country",
        "operator": "in",
        "value": ["US", "CA", "GB"]
      }
    ],
    "value": true,
    "percentage": null,
    "enabled": true,
    "segment_id": null,
    "created_at": "2025-03-12T10:00:00Z",
    "updated_at": "2025-03-12T10:00:00Z"
  }
}

---

Update Rule

Update an existing rule. Only provided fields are changed.

PATCH /flags/:flag_id/rules/:rule_id

Required scope: flags:write

Request Body

Field	Type	Required	Description
position	integer	No	Evaluation order.
conditions	array	No	Array of condition objects.
value	any	No	Value to return when this rule matches.
percentage	integer	No	Percentage rollout (0-100). Set to null to remove.
enabled	boolean	No	Whether the rule is active.
segment_id	string	No	Link to a reusable segment. Set to null to remove.

Example Request

curl -X PATCH https://app.krafter.dev/api/v1/flags/c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f/rules/f6a7b8c9-0d1e-4f2a-9b3c-4d5e6f7a8b9c \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "percentage": 50,
    "enabled": true
  }'

Example Response

{
  "data": {
    "id": "f6a7b8c9-0d1e-4f2a-9b3c-4d5e6f7a8b9c",
    "environment": "production",
    "position": 2,
    "conditions": [],
    "value": true,
    "percentage": 50,
    "enabled": true,
    "segment_id": null,
    "created_at": "2025-03-12T10:05:00Z",
    "updated_at": "2025-03-16T15:00:00Z"
  }
}

---

Delete Rule

Permanently delete a targeting rule.

DELETE /flags/:flag_id/rules/:rule_id

Required scope: flags:write

Example Request

curl -X DELETE https://app.krafter.dev/api/v1/flags/c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f/rules/f6a7b8c9-0d1e-4f2a-9b3c-4d5e6f7a8b9c \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

// 204 No Content