Skip to main content

​
GET /api/v1/segments

List all segments with their base schema names. Supports cursor-based pagination.

​
Query Parameters

ParameterTypeDefaultDescription
limitinteger20Max results per page
cursorstring—Cursor for pagination

​
Response

{
  "data": [
    {
      "id": "seg_001",
      "name": "high_value_customers",
      "description": "Customers with lifetime value > $10,000",
      "status": "active",
      "entityType": "customer",
      "baseSchemaId": "schema_001",
      "baseSchemaName": "customers",
      "customerCount": 4521,
      "joins": [],
      "filters": [{ "field": "lifetime_value", "operator": ">", "value": 10000 }],
      "createdAt": "2026-02-01T10:00:00.000Z"
    }
  ],
  "total": 8,
  "hasMore": false
}

​
POST /api/v1/segments

Create a segment with optional join and filter definitions. A backing PostgreSQL view is automatically created and the initial row count is computed.

​
Request Body

FieldTypeRequiredDescription
namestringYesSegment name (max 255 chars)
baseSchemaIdstringYesBase schema to query
descriptionstringNoDescription
statusstringNo"draft", "active", "paused", "archived". Default: "draft"
entityTypestringNoDefault: "customer"
joinsarrayNoCross-schema join definitions
filtersarrayNoFilter conditions applied to the view

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/segments \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "name": "high_value_customers",
    "baseSchemaId": "schema_001",
    "description": "Customers with lifetime value > $10,000",
    "status": "active",
    "filters": [
      { "field": "lifetime_value", "operator": ">", "value": 10000 }
    ]
  }'
Response: 201 Created

​
PUT /api/v1/segments

Update a segment. When joins or filters change, the backing view is rebuilt and the customer count is recomputed.

​
Request Body

FieldTypeRequiredDescription
idstringYesSegment ID
namestringNoUpdated name
descriptionstringNoUpdated description
statusstringNoUpdated status
baseSchemaIdstringNoUpdated base schema
joinsarrayNoUpdated joins (triggers view rebuild)
filtersarrayNoUpdated filters (triggers view rebuild)
Response: 200 OK

​
DELETE /api/v1/segments

Delete a segment and drop its backing view.
ParameterTypeRequiredDescription
idstringYesSegment ID (query parameter)
Response: 204 No Content

​
GET /api/v1/segments/

Get full segment details including base schema name. Response: 200 OK with the segment object.

​
POST /api/v1/segments/?action=refresh

Recount the rows in the segment’s backing view and update customerCount and lastRefreshedAt. Response: 200 OK with the updated segment.

​
POST /api/v1/segments/?action=preview

Return a preview of the first 20 rows from the segment view.

​
Response

{
  "rows": [
    { "id": "CUST001", "email": "john@example.com", "lifetime_value": 15200.50 }
  ],
  "count": 20
}

​
Roles

EndpointAllowed Roles
GET /segmentsadmin, editor, viewer
POST /segmentsadmin, editor
PUT /segmentsadmin, editor
DELETE /segmentsadmin, editor
GET /segments/{id}any authenticated
POST /segments/{id} (refresh/preview)admin, editor
See also: Data Platform