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
GET /api/v1/summary-definitions
Response
[
{
"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
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
{
"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
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 |
System summary definitions (created automatically during tenant setup) cannot have their dimensions changed. Attempting to change them returns a 400 error. You can update the name, description, aggregates, windows, and status.
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
DELETE /api/v1/summary-definitions?id={id}
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Summary definition ID to delete |
Response
Error codes
| Code | Reason |
|---|
400 | Missing id, or attempting to delete a system definition. |
404 | Summary definition not found. |
Deleting a summary definition stops new aggregation for that shape. Existing aggregated data is retained until the retention policy purges it.
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | admin |
| PUT | admin |
| DELETE | admin |
System definitions
Each tenant receives one system summary definition automatically during setup. System definitions:
- 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).
