Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
GET /api/v1/segments
List all segments with their base schema names. Supports cursor-based pagination.
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 20 | Max results per page |
cursor | string | — | Cursor for pagination |
Response
{
"data": [
{
"id": "seg_001",
"tenantId": "tenant_001",
"name": "high_value_customers",
"description": "Customers with lifetime value > $10,000",
"status": "active",
"entityType": "customer",
"baseSchemaId": "schema_001",
"baseSchema": { "name": "customers" },
"baseSchemaName": "customers",
"customerCount": 4521,
"joins": [],
"filters": [{ "field": "lifetime_value", "operator": ">", "value": 10000 }],
"viewName": "seg_a1b2c3d4e5f6",
"lastRefreshedAt": null,
"createdAt": "2026-02-01T10:00:00.000Z",
"updatedAt": "2026-02-01T10:00:00.000Z"
}
],
"pagination": {
"total": 8,
"hasMore": false,
"limit": 50,
"cursor": null
}
}
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
| Field | Type | Required | Description |
|---|
name | string | Yes | Segment name (max 255 chars) |
baseSchemaId | string | Yes | Base schema to query |
description | string | No | Description |
status | string | No | "draft", "active", "paused", "archived". Default: "draft" |
entityType | string | No | Default: "customer" |
joins | array | No | Cross-schema join definitions |
filters | array | No | Filter 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 }
]
}'
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
| Field | Type | Required | Description |
|---|
id | string | Yes | Segment ID |
name | string | No | Updated name |
description | string | No | Updated description |
status | string | No | Updated status |
baseSchemaId | string | No | Updated base schema |
joins | array | No | Updated joins (triggers view rebuild) |
filters | array | No | Updated filters (triggers view rebuild) |
200 OK
DELETE /api/v1/segments
Delete a segment and drop its backing view.
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Segment ID (query parameter) |
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
| Endpoint | Allowed Roles |
|---|
GET /segments | admin, editor, viewer |
POST /segments | admin, editor |
PUT /segments | admin, editor |
DELETE /segments | admin, editor |
GET /segments/{id} | any authenticated |
POST /segments/{id} (refresh/preview) | admin, editor |
