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.
POST /api/v1/admin/cache
Emergency cache flush. Invalidates cached offers, qualification rules, and/or contact policies. Admin only.
Request Body
| Field | Type | Required | Description |
|---|
scope | string | No | "all", "offers", "qualificationRule", or "contactPolicy". Default: "all" |
src/app/api/v1/admin/cache/route.ts:23-30.
Response
{
"success": true,
"flushed": "all",
"tenantId": "tenant_001",
"timestamp": "2026-03-16T14:30:00.000Z"
}
GET /api/v1/admin/dlq
Get dead letter queue (DLQ) summary and events. Admin only.
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 50 | Max events to return (max 200) |
topic | string | — | Filter by topic |
src/app/api/v1/admin/dlq/route.ts:20-22.
Response
{
"totalEvents": 15,
"byTopic": {
"interaction_events": 10,
"pipeline_runs": 5
},
"events": [
{
"id": "dle_001",
"topic": "interaction_events",
"payload": { "customerId": "CUST001" },
"error": "Timeout after 30000ms",
"retryCount": 3,
"failedAt": "2026-03-16T12:00:00.000Z"
}
],
"alert": "WARNING"
}
Alert Levels
| Level | Condition |
|---|
OK | 10 or fewer events |
WARNING | 11-100 events |
CRITICAL | More than 100 events |
src/app/api/v1/admin/dlq/route.ts:46.
POST /api/v1/admin/dlq
Retry or purge DLQ events. Admin only.
Request Body
| Field | Type | Required | Description |
|---|
action | string | Yes | "retry" or "purge" |
eventIds | string[] | No | Specific event IDs to process |
topic | string | No | Process all events for a topic |
src/app/api/v1/admin/dlq/route.ts:70-113.
Response (retry)
{
"action": "retry",
"requeued": 10
}
Response (purge)
{
"action": "purge",
"deleted": 15
}
GET /api/v1/admin/retention-configs
List data retention configurations for the tenant. Admin only.
Response
[
{ "id": "rc_001", "dataClass": "interactions", "retentionDays": 365, "legalHold": false },
{ "id": "rc_002", "dataClass": "decisions", "retentionDays": 90, "legalHold": false },
{ "id": "rc_003", "dataClass": "audit", "retentionDays": 2555, "legalHold": true }
]
POST /api/v1/admin/retention-configs
Create or update a retention configuration (upsert). Admin only.
Request Body
| Field | Type | Required | Description |
|---|
dataClass | string | Yes | "interactions", "decisions", "metrics", or "audit" |
retentionDays | integer | Yes | Retention period in days (1-36500) |
legalHold | boolean | No | When true, data is exempt from automatic cleanup |
UpsertRetentionConfigSchema at src/app/api/v1/admin/retention-configs/route.ts:12-16.
Example
curl -X POST https://playground.kaireonai.com/api/v1/admin/retention-configs \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-d '{
"dataClass": "interactions",
"retentionDays": 365,
"legalHold": false
}'
200 OK with the upserted RetentionConfig row.
GET /api/v1/admin/rls
Report row-level security (RLS) posture for every tenant-scoped table. Admin only.
Response
{
"summary": {
"totalTables": 42,
"rlsEnabled": 42,
"rlsForced": 42,
"withPolicy": 42,
"missingRLS": []
},
"tables": [
{
"table": "Offer",
"rlsEnabled": true,
"rlsForced": true,
"policies": ["tenant_isolation"]
}
],
"timestamp": "2026-04-30T14:22:01.123Z"
}
totalTables is the length of RLS_TABLES declared at src/lib/db/rls.ts. missingRLS lists tables that either have RLS disabled OR are missing the tenant_isolation policy. Computed at src/app/api/v1/admin/rls/route.ts:27-37.
POST /api/v1/admin/rls
Idempotent enable. Turns on ENABLE ROW LEVEL SECURITY + FORCE ROW LEVEL SECURITY on every table in RLS_TABLES and creates the tenant_isolation policy where missing. Admin only. Logs an audit row with action update, entityType rls, entityId enable_all.
Response
{
"success": true,
"enabled": ["Offer", "Creative", "Channel", "Pipeline", "..."],
"failed": [],
"totalTables": 42,
"timestamp": "2026-04-30T14:22:01.123Z"
}
success is true only when failed.length === 0. Source: src/app/api/v1/admin/rls/route.ts:57-89.
GET /api/v1/admin/sbom
Returns the CycloneDX 1.5 software bill of materials for the running deployment, computed on demand from the deployment’s package-lock.json. Admin only. Shipped W4.5 (2026-04-28).
Response
{
"sbom": {
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"serialNumber": "urn:uuid:...",
"metadata": {
"timestamp": "2026-04-30T14:22:01.123Z",
"component": {
"type": "application",
"name": "kaireon-platform",
"version": "0.1.0"
}
},
"components": [
{ "type": "library", "name": "next", "version": "16.x.x", "purl": "pkg:npm/next@16.x.x" }
]
},
"digest": "sha256:abc123...",
"components": 1247
}
buildSbom() and sbomDigest() from src/lib/supply-chain/sbom. The same digest is also returned in the X-SBOM-Digest response header, and the response carries Cache-Control: no-store. Source: src/app/api/v1/admin/sbom/route.ts:30-69.
The release pipeline still publishes the SBOM as a release artifact via tools/scripts/generate-sbom.ts; this endpoint is the runtime-side counterpart for self-hosters who want to verify the components running in their cluster without rebuilding the image.
POST /api/v1/cleanup
Trigger data cleanup for expired variant assignments and old audit logs. Rate limited to 5 requests per 60 seconds. Admin only.
Response
{
"cleaned": {
"expiredVariantAssignments": 1200,
"oldAuditLogs": 5000
}
}
GET /api/v1/metrics/summary
Returns Prometheus kaireon_* metrics as JSON. Used by the operations dashboard. Admin only.
Response
{
"kaireon_recommend_requests_total": {
"name": "kaireon_recommend_requests_total",
"type": "counter",
"values": [{ "labels": {}, "value": 152000 }]
},
"kaireon_recommend_latency_seconds": {
"name": "kaireon_recommend_latency_seconds",
"type": "histogram",
"values": [{ "labels": { "le": "0.1" }, "value": 140000 }]
}
}
POST /api/v1/tenant/reset
Reset a playground workspace by deleting all tenant data. Only available for playground tenants. Admin only.
Request Body
| Field | Type | Required | Description |
|---|
confirm | boolean | Yes | Must be true to proceed |
Response
{
"message": "Workspace reset successfully. Decision counter is back to 0."
}
This permanently deletes ALL tenant data including Offers, Decision Flows, pipelines, interaction history, and all other records. This cannot be undone.
Roles
| Endpoint | Allowed Roles |
|---|
POST /admin/cache | admin |
GET /admin/dlq | admin |
POST /admin/dlq | admin |
GET /admin/retention-configs | admin |
POST /admin/retention-configs | admin |
GET /admin/rls | admin |
POST /admin/rls | admin |
GET /admin/sbom | admin |
POST /cleanup | admin |
GET /metrics/summary | admin |
POST /tenant/reset | admin |
