> ## 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.

# Segments

> Create and manage customer segments backed by PostgreSQL views. Segments support cross-schema joins and filter conditions for dynamic audience definition.

## GET /api/v1/segments

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

### Query Parameters

| Parameter | Type    | Default | Description                    |
| --------- | ------- | ------- | ------------------------------ |
| `limit`   | integer | `50`    | Max results per page (max 100) |
| `cursor`  | string  | —       | Cursor for pagination          |

### Response

```json theme={null}
{
  "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

```bash theme={null}
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

| Field          | Type   | Required | Description                             |
| -------------- | ------ | -------- | --------------------------------------- |
| `id`           | string | Yes      | Segment ID or name                      |
| `name`         | string | No       | Updated name                            |
| `description`  | string | No       | Updated description                     |
| `status`       | string | No       | Updated status                          |
| `entityType`   | string | No       | Updated entity type                     |
| `baseSchemaId` | string | No       | Updated base schema                     |
| `joins`        | array  | No       | Updated joins (triggers view rebuild)   |
| `filters`      | array  | No       | Updated filters (triggers view rebuild) |

**Response:** `200 OK`

***

## DELETE /api/v1/segments

Delete a segment and drop its backing view.

| Parameter | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| `id`      | string | Yes      | Segment ID or name (query parameter) |

**Response:** `204 No Content`

A path variant `DELETE /api/v1/segments/{id}` is also available.

***

## GET /api/v1/segments/{id}

Get full segment details including base schema name.

**Response:** `200 OK` with the segment object.

***

## POST /api/v1/segments/{id}?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/{id}?action=preview

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

### Response

```json theme={null}
{
  "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         |

See also: [Data Platform](/data/overview)