Admin - KaireonAI

POST /api/v1/admin/cache

Emergency cache flush. Invalidates cached offers, decisioning gates, and/or contact policies. Admin only.

Request Body

Field	Type	Required	Description
`scope`	string	No	`"all"`, `"offers"`, `"qualificationRule"`, or `"contactPolicy"`. Default: `"all"`

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

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

The alert field summarizes queue pressure so operators can decide whether to retry, purge, or page a human. The thresholds are:

Value	Condition
`"OK"`	10 or fewer events
`"WARNING"`	11-100 events
`"CRITICAL"`	More than 100 events

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

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"`, `"audit"`, `"attachments"`, or `"system_health"`
`retentionDays`	integer	Yes	Retention period in days (1-36500)
`legalHold`	boolean	No	When `true`, this data class is exempt from automatic cleanup regardless of `retentionDays`. There is no separate “legal hold” dataClass — set this flag on the real class row. See Retention & Archival.

The request body is validated server-side; invalid dataClass values, out-of-range retentionDays, and missing required fields return 400 Bad Request.

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
  }'

Response: 200 OK with the upserted retention configuration object (same shape as the items returned by the list endpoint).

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 count of tables in the platform’s curated tenant-scoped table list. missingRLS lists tables that either have RLS disabled OR are missing the tenant_isolation policy. Use this report to confirm tenant-isolation coverage across every multi-tenant table before a release.

POST /api/v1/admin/rls

Idempotent enable. Turns on ENABLE ROW LEVEL SECURITY + FORCE ROW LEVEL SECURITY on every table in the configured RLS table list 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 is empty. Any table that could not be enabled is listed in failed with the underlying error message and the call still returns 200 OK so operators can re-run after fixing the offending table.

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
}

The response includes the full CycloneDX document, a deterministic SHA-256 digest of that document, and the component count. The same digest is mirrored in the X-SBOM-Digest response header so operators can pin against it without re-parsing the body, and the response carries Cache-Control: no-store. The release pipeline still publishes the SBOM as a release artifact at build time; 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

​POST /api/v1/admin/cache

​Request Body

​Response

​GET /api/v1/admin/dlq

​Query Parameters

​Response

​Alert Levels

​POST /api/v1/admin/dlq

​Request Body

​Response (retry)

​Response (purge)

​GET /api/v1/admin/retention-configs

​Response

​POST /api/v1/admin/retention-configs

​Request Body

​Example

​GET /api/v1/admin/rls

​Response

​POST /api/v1/admin/rls

​Response

​GET /api/v1/admin/sbom

​Response

​POST /api/v1/cleanup

​Response

​GET /api/v1/metrics/summary

​Response

​POST /api/v1/tenant/reset

​Request Body

​Response

​Roles

POST /api/v1/admin/cache

Request Body

Response

GET /api/v1/admin/dlq

Query Parameters

Response

Alert Levels

POST /api/v1/admin/dlq

Request Body

Response (retry)

Response (purge)

GET /api/v1/admin/retention-configs

Response

POST /api/v1/admin/retention-configs

Request Body

Example

GET /api/v1/admin/rls

Response

POST /api/v1/admin/rls

Response

GET /api/v1/admin/sbom

Response

POST /api/v1/cleanup

Response

GET /api/v1/metrics/summary

Response

POST /api/v1/tenant/reset

Request Body

Response

Roles