Segments API

Auth: Clerk session.

List

GET /v1/segments?cursor=&limit=50 — paginated.

Get

GET /v1/segments/:id

{
  "data": {
    "id": "uuid", "tenant_id": "...", "project_id": "...",
    "name": "high_rollers",
    "description": "...",
    "definition": { ... },         // tree shape — see Segments feature page
    "compiled_query": "...",       // cached SQL fragment (non-event paths)
    "estimated_size": 2847,
    "last_computed_at": "...",
    "refresh_strategy": "realtime",
    "created_at": "...", "updated_at": "..."
  }
}

Create

POST /v1/segments

{
  "name": "high_rollers",
  "description": "Players with €1k+ lifetime deposit",
  "definition": {
    "operator": "AND",
    "conditions": [
      { "type": "trait", "field": "total_deposited", "op": ">", "value": 100000 }
    ]
  },
  "refresh_strategy": "realtime"
}

Validates definition against allowed trait fields + operators (see Segments feature page).

Update

PATCH /v1/segments/:id — partial. Definition changes recompile compiled_query.

Refresh

POST /v1/segments/:id/refresh — materialise membership.

{
  "data": {
    "matched": 2847,
    "added": 142,
    "removed": 18,
    "duration_ms": 387
  }
}

Walks player rows + UPDATEs segment_ids[] for affected players. Returns the diff vs. previous membership.

Sample

GET /v1/segments/:id/sample?limit=10 → 10 random matched player_ids for editor preview.

Delete

DELETE /v1/segments/:id → soft delete (sets deleted_at). Existing campaigns referencing the segment fall back to "no recipients" — admin should rebuild.