Summary Definitions

See also: Summary Definitions concept and configuration for what this API powers, when to call it, and how it is configured.

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

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

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

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}

Deletes a summary definition. System definitions cannot be deleted.

Query Parameters

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

Response

{ "deleted": true }

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

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

​Overview

​List Summary Definitions

​Response

​Create Summary Definition

​Request Body

​Allowed Dimensions

​Allowed Aggregates

​Allowed Windows

​Example

​Response 201

​Error codes

​Update Summary Definition

​Request Body

​Response 200

​Error codes

​Delete Summary Definition

​Query Parameters

​Response

​Error codes

​Role requirements

​System definitions

Overview

List Summary Definitions

Response

Create Summary Definition

Request Body

Allowed Dimensions

Allowed Aggregates

Allowed Windows

Example

Response `201`

Error codes

Update Summary Definition

Request Body

Response `200`

Error codes

Delete Summary Definition

Query Parameters

Response

Error codes

Role requirements

System definitions