Segments

Create and manage reusable audience segments. Segments define groups of users based on conditions and can be referenced by targeting rules across multiple flags.

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

List Segments

Retrieve all segments for a project.

GET /flags/segments?project_id=...

Required scope: flags:read

Query Parameters

Parameter	Type	Required	Description
project_id	string	Yes	Project to list segments for.

Example Request

curl "https://app.krafter.dev/api/v1/flags/segments?project_id=a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5e",
      "name": "Pro Users",
      "description": "Users on the pro plan in North America",
      "rules": [
        {
          "key": "plan",
          "operator": "equals",
          "value": "pro"
        },
        {
          "key": "country",
          "operator": "in",
          "value": ["US", "CA"]
        }
      ],
      "match_type": "all",
      "created_at": "2025-03-10T11:00:00Z",
      "updated_at": "2025-03-10T11:00:00Z"
    },
    {
      "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6f",
      "name": "Beta Testers",
      "description": "Users who opted into the beta program",
      "rules": [
        {
          "key": "beta_optin",
          "operator": "equals",
          "value": true
        }
      ],
      "match_type": "all",
      "created_at": "2025-03-11T09:30:00Z",
      "updated_at": "2025-03-11T09:30:00Z"
    }
  ]
}

---

Create Segment

Create a new reusable segment.

POST /flags/segments

Required scope: flags:write

Request Body

Field	Type	Required	Description
project_id	string	Yes	Project this segment belongs to.
name	string	Yes	Display name for the segment.
description	string	No	Description of the audience this segment represents.
rules	array	Yes	Array of condition objects defining segment membership. See Rule Format.
match_type	string	Yes	How conditions are combined: "all" (AND) or "any" (OR).

Rule Format

Each rule is a condition object with three fields:

Field	Type	Description
key	string	The context attribute to evaluate (e.g., "plan", "country").
operator	string	Comparison operator: equals, not_equals, contains, not_contains, in, not_in, greater_than, less_than.
value	any	The value to compare against. For in and not_in, use an array.

Example Request

curl -X POST https://app.krafter.dev/api/v1/flags/segments \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Pro Users",
    "description": "Users on the pro plan in North America",
    "rules": [
      {
        "key": "plan",
        "operator": "equals",
        "value": "pro"
      },
      {
        "key": "country",
        "operator": "in",
        "value": ["US", "CA"]
      }
    ],
    "match_type": "all"
  }'

Example Response

// 201 Created
{
  "data": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5e",
    "name": "Pro Users",
    "description": "Users on the pro plan in North America",
    "rules": [
      {
        "key": "plan",
        "operator": "equals",
        "value": "pro"
      },
      {
        "key": "country",
        "operator": "in",
        "value": ["US", "CA"]
      }
    ],
    "match_type": "all",
    "created_at": "2025-03-10T11:00:00Z",
    "updated_at": "2025-03-10T11:00:00Z"
  }
}

---

Update Segment

Update an existing segment. Only provided fields are changed. Changes affect all rules that reference this segment.

PATCH /flags/segments/:segment_id

Required scope: flags:write

Request Body

Field	Type	Required	Description
name	string	No	Display name for the segment.
description	string	No	Description of the audience.
rules	array	No	Array of condition objects.
match_type	string	No	How conditions are combined: "all" or "any".

Example Request

curl -X PATCH https://app.krafter.dev/api/v1/flags/segments/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5e \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "key": "plan",
        "operator": "in",
        "value": ["pro", "enterprise"]
      },
      {
        "key": "country",
        "operator": "in",
        "value": ["US", "CA", "GB"]
      }
    ]
  }'

Example Response

{
  "data": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5e",
    "name": "Pro Users",
    "description": "Users on the pro plan in North America",
    "rules": [
      {
        "key": "plan",
        "operator": "in",
        "value": ["pro", "enterprise"]
      },
      {
        "key": "country",
        "operator": "in",
        "value": ["US", "CA", "GB"]
      }
    ],
    "match_type": "all",
    "created_at": "2025-03-10T11:00:00Z",
    "updated_at": "2025-03-16T16:00:00Z"
  }
}

---

Delete Segment

Permanently delete a segment. Any rules referencing this segment will have their segment_id cleared.

DELETE /flags/segments/:segment_id

Required scope: flags:write

Example Request

curl -X DELETE https://app.krafter.dev/api/v1/flags/segments/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5e \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

// 204 No Content