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

# Summary Definitions

> CRUD endpoints for interaction summary aggregation shapes -- define how interaction data is bucketed and aggregated.

<Note>
  **See also**: [Summary Definitions concept and configuration](/studio/summary-definitions) for what this API powers, when to call it, and how it is configured.
</Note>

## Overview

Summary definitions control how raw interaction events are aggregated into daily/weekly/monthly buckets. Each definition specifies which dimensions to group by and which time windows to maintain.

***

## List Summary Definitions

```http theme={null}
GET /api/v1/summary-definitions
```

Returns all summary definitions for the current tenant, ordered by system definitions first, then alphabetically.

### Response

```json theme={null}
[
  {
    "id": "sd_001",
    "tenantId": "tenant_001",
    "name": "Offer Interactions",
    "description": "Track impressions and conversions by offer and channel",
    "dimensions": ["offer_id", "channel_id", "direction", "outcome_key"],
    "aggregates": ["count", "sum_value"],
    "windows": ["1d", "7d", "30d"],
    "status": "active",
    "isSystem": true,
    "createdAt": "2026-03-20T10:00:00.000Z",
    "updatedAt": "2026-03-20T10:00:00.000Z"
  }
]
```

***

## Create Summary Definition

```http theme={null}
POST /api/v1/summary-definitions
```

### Request Body

| Field         | Type      | Required | Description                                         |
| ------------- | --------- | -------- | --------------------------------------------------- |
| `name`        | string    | Yes      | Unique name for the definition                      |
| `description` | string    | No       | Human-readable description (defaults to `""`)       |
| `dimensions`  | string\[] | No       | Grouping dimensions (see allowed values below)      |
| `aggregates`  | string\[] | No       | Aggregation functions (see allowed values below)    |
| `windows`     | string\[] | No       | Time windows to maintain (see allowed values below) |
| `status`      | string    | No       | `active` (default) or `inactive`                    |

### Allowed Dimensions

| Dimension         | Description                         |
| ----------------- | ----------------------------------- |
| `offer_id`        | Group by offer                      |
| `creative_id`     | Group by creative/treatment         |
| `category_id`     | Group by business category          |
| `sub_category_id` | Group by sub-category               |
| `channel_id`      | Group by delivery channel           |
| `placement_type`  | Group by placement type             |
| `direction`       | Group by inbound/outbound direction |
| `outcome_key`     | Group by outcome type key           |

### Allowed Aggregates

| Aggregate         | Description               |
| ----------------- | ------------------------- |
| `count`           | Count of interactions     |
| `sum_value`       | Sum of interaction values |
| `last_contact`    | Timestamp of last contact |
| `distinct_offers` | Count of distinct offers  |

### Allowed Windows

| Window | Description       |
| ------ | ----------------- |
| `1d`   | Daily buckets     |
| `7d`   | Weekly buckets    |
| `14d`  | Bi-weekly buckets |
| `30d`  | Monthly buckets   |
| `90d`  | Quarterly buckets |

### Example

```json theme={null}
{
  "name": "Channel Performance Tracker",
  "description": "Track offer performance per channel with daily and weekly rollups",
  "dimensions": ["offer_id", "channel_id"],
  "aggregates": ["count", "sum_value"],
  "windows": ["1d", "7d"],
  "status": "active"
}
```

### Response `201`

Returns the created summary definition with `id`, `isSystem: false`, and timestamps.

### Error codes

| Code  | Reason                                                                  |
| ----- | ----------------------------------------------------------------------- |
| `400` | Missing name, invalid dimensions/aggregates/windows, or duplicate name. |

***

## Update Summary Definition

```http theme={null}
PUT /api/v1/summary-definitions
```

### Request Body

| Field         | Type      | Required | Description                                              |
| ------------- | --------- | -------- | -------------------------------------------------------- |
| `id`          | string    | Yes      | Summary definition ID                                    |
| `name`        | string    | No       | Updated name                                             |
| `description` | string    | No       | Updated description                                      |
| `dimensions`  | string\[] | No       | Updated dimensions (cannot change on system definitions) |
| `aggregates`  | string\[] | No       | Updated aggregates                                       |
| `windows`     | string\[] | No       | Updated windows                                          |
| `status`      | string    | No       | `active` or `inactive`                                   |

<Warning>
  System summary definitions (those flagged `isSystem: true`) cannot have their dimensions changed. Attempting to change them returns a `400` error. You can update the name, description, aggregates, windows, and status.
</Warning>

### Response `200`

Returns the updated summary definition.

### Error codes

| Code  | Reason                                                                                                                     |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| `400` | Missing `id`, invalid dimensions/aggregates/windows, duplicate name, or attempting to change system definition dimensions. |
| `404` | Summary definition not found.                                                                                              |

***

## Delete Summary Definition

```http theme={null}
DELETE /api/v1/summary-definitions?id={id}
```

Deletes a summary definition. System definitions cannot be deleted.

### Query Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `id`      | string | Yes      | Summary definition ID to delete |

### Response

```json theme={null}
{ "deleted": true }
```

### Error codes

| Code  | Reason                                                     |
| ----- | ---------------------------------------------------------- |
| `400` | Missing `id`, or attempting to delete a system definition. |
| `404` | Summary definition not found.                              |

<Warning>
  Deleting a summary definition stops new aggregation for that shape. Existing aggregated data is retained until the retention policy purges it.
</Warning>

***

## Role requirements

| Method | Minimum role |
| ------ | ------------ |
| GET    | `viewer`     |
| POST   | `admin`      |
| PUT    | `admin`      |
| DELETE | `admin`      |

***

## System definitions

Summary definitions flagged `isSystem: true` are treated as protected system definitions. They:

* Cannot have their `dimensions` changed (the API returns `400` if you try).
* Cannot be deleted (the API returns `400`).
* Can have their `name`, `description`, `aggregates`, `windows`, and `status` updated normally.
* Are listed first in GET responses (ordered by `isSystem` descending, then alphabetically by name).