Segments

Segments are dynamic audience groups computed from rules based on contact attributes, event history, channel availability, and consent state.

List Segments

`GET /api/workspaces/{workspaceId}/segments`

Returns all segments with their active member counts.

Auth: Session required

Response:


[
  {
    "id": "seg_abc123",
    "name": "Active Users",
    "description": "Users who visited in the last 7 days",
    "rules": { ... },
    "evaluation": "DYNAMIC",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "_count": { "memberships": 1234 }
  }
]

Create Segment

`POST /api/workspaces/{workspaceId}/segments`

Auth: Session required

Request Body:


{
  "name": "Active Users",
  "description": "Users who visited in the last 7 days",
  "rules": {
    "combinator": "and",
    "rules": [
      { "field": "events.page_view", "operator": "greater_than", "value": 0 }
    ]
  },
  "evaluation": "DYNAMIC"
}

Field	Type	Required	Description
`name`	string	Yes	Segment name
`description`	string	No	Human-readable description
`rules`	object	Yes	Rule definition (see below)
`evaluation`	string	No	`DYNAMIC` (default), `STATIC`, or `SNAPSHOT`

Rule Structure

Rules are a nested tree. A group node has a combinator (and / or) and a rules array; a leaf node has field, operator, and value. Groups can be nested inside groups.


{
  "combinator": "and",
  "rules": [
    { "field": "attributes.plan", "operator": "equals", "value": "pro" },
    { "field": "events.purchase", "operator": "greater_than", "value": 0 },
    {
      "combinator": "or",
      "rules": [
        { "field": "consent.email", "operator": "equals", "value": true },
        { "field": "tags", "operator": "contains", "value": "vip" }
      ]
    }
  ]
}

Operators:

Operator	Description
`equals` / `not_equals`	Exact match
`contains` / `not_contains`	Substring match, or array membership for `tags`
`starts_with` / `ends_with`	Prefix / suffix match
`greater_than` / `less_than`	Numeric or date comparison
`is_set` / `is_not_set`	Value present / absent (`value` ignored)
`in` / `not_in`	Value is (not) one of an array of values

Fields:

Field	Description
`email`, `firstName`, `lastName`, `phone`, `score`, `anonymous`, `createdAt`, `updatedAt`	Contact profile fields
`attributes.<name>`	Custom attribute (nested paths supported, e.g. `attributes.address.city`)
`tags` / `tags.<name>`	Contact tags (array) / whether a specific tag is present (boolean)
`events.<type>`	Number of events of that type recorded for the contact
`identity.<channel>`	Whether the contact has an identity for a channel (`email`, `push`, `telegram`, …)
`consent.<channel>`	Whether the contact has opted in to a channel

Get Segment (Preview)

`GET /api/workspaces/{workspaceId}/segments/{segmentId}`

Returns segment details with total member count and up to 10 sample contacts.

Response:


{
  "segment": { "id": "seg_abc123", "name": "Active Users" },
  "totalMembers": 1234,
  "sampleContacts": [
    { "id": "ct_1", "email": "jane@example.com", "firstName": "Jane" }
  ]
}

Recompute Segment

`POST /api/workspaces/{workspaceId}/segments/{segmentId}`

Triggers a full recomputation of segment memberships.

Auth: Session required

Response:


{
  "segmentId": "seg_abc123",
  "added": 15,
  "removed": 3,
  "unchanged": 1216
}