Admin

Platform administration endpoints for cache management, dead letter queue, retention policies, RLS posture, SBOM, data cleanup, metrics, and tenant reset.

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"

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", or "audit"
retentionDays	integer	Yes	Retention period in days (1-36500)
legalHold	boolean	No	When true, data is exempt from automatic cleanup

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

See also: Operations | Compliance