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.
Budget allocations define spending and impression limits per time period. Budgets can be scoped globally or to a specific category, offer, or channel.
GET /api/v1/budgets
List budget allocations for the tenant.
Query Parameters
| Parameter | Type | Required | Description |
|---|
periodKey | string | No | Filter by period (e.g., 2026-03-18) |
scope | string | No | Filter by scope: global, category, offer, channel |
Response
{
"budgets": [
{
"id": "clx...",
"name": "Q1 Email Budget",
"scope": "channel",
"scopeId": "ch_email",
"periodType": "monthly",
"periodKey": "2026-03",
"maxImpressions": 50000,
"maxSpend": 10000.00,
"maxConversions": null,
"tenantId": "my-tenant",
"createdAt": "2026-03-01T00:00:00.000Z"
}
],
"count": 1
}
POST /api/v1/budgets
Create a budget allocation. At least one limit (maxImpressions, maxSpend, or maxConversions) is required. Editor or Admin.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Budget name (max 255 chars) |
scope | string | No | Scope level: global, category, offer, channel (default: global) |
scopeId | string | No | ID of the scoped entity (required if scope is not global) |
periodType | string | No | Period granularity: daily, weekly, monthly, quarterly (default: daily) |
periodKey | string | Yes | Period identifier (e.g., 2026-03-18, 2026-Q1) |
maxImpressions | integer | No | Maximum impressions allowed |
maxSpend | number | No | Maximum spend amount |
maxConversions | integer | No | Maximum conversions allowed |
Example
curl -X POST https://playground.kaireonai.com/api/v1/budgets \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-d '{
"name": "March Premium Card Budget",
"scope": "offer",
"scopeId": "offer_premium_card",
"periodType": "monthly",
"periodKey": "2026-03",
"maxImpressions": 10000,
"maxSpend": 5000
}'
Response (201)
Returns the created budget allocation object.
PUT /api/v1/budgets
Update a budget allocation. Editor or Admin.
Request Body
| Field | Type | Required | Description |
|---|
id | string | Yes | Budget allocation ID |
name | string | No | Updated name |
scope | string | No | Updated scope |
scopeId | string | No | Updated scope entity ID |
periodType | string | No | Updated period type |
periodKey | string | No | Updated period key |
maxImpressions | integer | No | Updated max impressions |
maxSpend | number | No | Updated max spend |
maxConversions | integer | No | Updated max conversions |
DELETE /api/v1/budgets?id=
Delete a budget allocation. Admin only.
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Budget allocation ID |
Response
