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.
Overview
Frequency caps limit how many recommendations or deliveries can occur within a time period. They operate at three scopes:
- Channel: Max emails/day, max push notifications/week
- Category: Max mandatory communications/week
- Offer: Max deliveries of a specific offer/month
List Frequency Caps
GET /api/v1/frequency-caps
Response
{
"data": [
{
"id": "fc_001",
"tenantId": "tenant_001",
"name": "Email Campaign Daily Cap 10K",
"scope": "channel",
"scopeId": "ch_email",
"maxVolume": 10000,
"period": "daily",
"enabled": true,
"currentCount": 3245,
"resetAt": "2026-03-31T00:00:00.000Z",
"createdAt": "2026-03-15T10:00:00.000Z",
"updatedAt": "2026-03-30T08:00:00.000Z"
}
],
"total": 3
}
Create Frequency Cap
POST /api/v1/frequency-caps
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Human-readable name |
scope | string | Yes | "offer", "category", or "channel" |
scopeId | string | Yes | ID of the scoped entity |
maxVolume | integer | Yes | Maximum count per period (minimum: 1) |
period | string | Yes | "daily", "weekly", or "monthly" |
enabled | boolean | No | Default: true |
Example
{
"name": "Email Campaign Daily Cap 10K",
"scope": "channel",
"scopeId": "ch_email",
"maxVolume": 10000,
"period": "daily",
"enabled": true
}
Response 201
Returns the created cap. The currentCount starts at 0 and resetAt is auto-computed based on the period.
{
"id": "fc_001",
"name": "Email Campaign Daily Cap 10K",
"scope": "channel",
"scopeId": "ch_email",
"maxVolume": 10000,
"period": "daily",
"enabled": true,
"currentCount": 0,
"resetAt": "2026-03-31T00:00:00.000Z"
}
Error codes
| Code | Reason |
|---|
400 | Validation error or duplicate cap (same scope, scopeId, and period). |
Update Frequency Cap
PUT /api/v1/frequency-caps
id in the body. Only provided fields are updated.
Request Body
| Field | Type | Required | Description |
|---|
id | string | Yes | Frequency cap ID |
name | string | No | Updated name |
scope | string | No | Updated scope |
scopeId | string | No | Updated scope ID |
maxVolume | integer | No | Updated max volume |
period | string | No | Updated period (resets currentCount to 0 and recomputes resetAt) |
enabled | boolean | No | Enable or disable |
Changing the period automatically resets the currentCount to 0 and recomputes the resetAt timestamp.
Response 200
Returns the updated cap.
Error codes
| Code | Reason |
|---|
400 | Validation error. |
404 | Frequency cap not found (wrong ID or different tenant). |
Delete Frequency Cap
DELETE /api/v1/frequency-caps?id={id}
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Frequency cap ID to delete |
Response 204
Empty body on success.
Error codes
| Code | Reason |
|---|
400 | Missing id parameter. |
404 | Frequency cap not found. |
How Frequency Caps Work
- When a batch run executes, each delivery increments the
currentCount for matching caps.
- If
currentCount >= maxVolume, further deliveries for that scope are blocked.
- Counters reset automatically at the start of each period:
- daily: Midnight UTC
- weekly: Monday midnight UTC
- monthly: First day of the month, midnight UTC
- Frequency caps are checked AFTER qualification and contact policy filtering.
Role requirements
| Method | Minimum role |
|---|
| GET | viewer |
| POST | editor |
| PUT | editor |
| DELETE | admin |
Example: Insurance Email Campaign
// Max 10,000 emails per day (budget control)
{
"name": "Email Daily Cap",
"scope": "channel",
"scopeId": "email-channel-id",
"maxVolume": 10000,
"period": "daily"
}
// Max 5,000 mandatory communications per week
{
"name": "Mandatory Weekly Cap",
"scope": "category",
"scopeId": "mandatory-category-id",
"maxVolume": 5000,
"period": "weekly"
}
// Max 2,000 Early Renewal offers per month
{
"name": "Early Renewal Monthly Cap",
"scope": "offer",
"scopeId": "early-renewal-offer-id",
"maxVolume": 2000,
"period": "monthly"
}
