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.
GET /api/v1/audit-logs
Query audit log entries. Admin only. Logs are immutable — no DELETE, PUT, or PATCH operations are permitted.
Query Parameters
| Parameter | Type | Default | Description |
|---|
entityType | string | — | Filter by entity type (e.g., "connector", "offer", "decision_flow", "category", "sub_category", "channel", "creative", "outcome_type") |
page | integer | 1 | Page number |
limit | integer | 50 | Results per page (max 100) |
Response
{
"logs": [
{
"id": "log_001",
"action": "create",
"entityType": "offer",
"entityId": "offer_001",
"entityName": "Platinum Card",
"changes": {},
"before": null,
"after": {
"id": "offer_001",
"name": "Platinum Card",
"status": "draft",
"priority": 75,
"version": 1
},
"entityVersion": 1,
"userId": "user_001",
"userName": "John Doe",
"tenantId": "tenant_001",
"requestId": "req_abc123",
"integrityHash": "a1b2c3d4e5f6...",
"prevHash": "x9y8z7w6v5u4...",
"timestamp": "2026-03-16T14:30:00.000Z"
}
],
"total": 5420,
"page": 1,
"limit": 50
}
Audit log fields
| Field | Type | Description |
|---|
action | string | One of create, update, soft_delete, restore, delete, mandatory_override. |
entityType | string | The entity type (e.g., offer, category, channel, creative, sub_category, outcome_type, decision_flow, qualification_rule, contact_policy, placement, trigger_rule, guardrail_rule, arbitration_profile, summary_definition, flow_route). |
entityId | string | The ID of the affected entity. |
entityName | string | The name of the entity at the time of the action. |
before | object | null | Full entity snapshot before the change. null for create actions. |
after | object | null | Full entity snapshot after the change. |
entityVersion | integer | null | The entity’s version at the time of the action. |
changes | object | Additional metadata (e.g., cascade reason for soft-delete). |
integrityHash | string | SHA-256 hash of the log entry for tamper detection. |
prevHash | string | null | The integrityHash of the previous log entry, forming the integrity chain. |
Audit logs are append-only. DELETE, PUT, and PATCH requests return 405 Method Not Allowed with a clear message that audit logs are immutable.
Cascade audit entries
When a parent entity is soft-deleted with cascade (e.g., deleting a category cascades to sub-categories and offers), a separate audit log entry is created for each cascaded child. These entries include a changes.reason field indicating the cascade source:
{
"action": "soft_delete",
"entityType": "sub_category",
"entityId": "sub_01",
"changes": { "reason": "Cascade from category cat_01" },
"entityVersion": 2
}
GET /api/v1/audit-logs/verify
Verify the integrity of the audit log chain using SHA-256 hash verification. Admin only.
Query Parameters
| Parameter | Type | Description |
|---|
limit | integer | Only verify the last N entries (quick check mode). Omit to verify entire chain |
Response
{
"intact": true,
"verified": 5420,
"total": 5420,
"scanned": 5420
}
Broken Chain Response
{
"intact": false,
"verified": 3210,
"total": 5420,
"scanned": 5420,
"brokenAtId": "log_3211",
"brokenReason": "hash_mismatch"
}
Broken Reasons
| Reason | Description |
|---|
hash_mismatch | Recomputed SHA-256 hash does not match the stored hash |
chain_link_mismatch | Entry’s prevHash does not match the previous entry’s integrityHash |
GET /api/v1/audit-export
Export audit logs for SOC 2 compliance. Supports JSON, CSV, and SOC 2 formatted output. Rate limited to 10 requests per 60 seconds. Admin only.
Query Parameters
| Parameter | Type | Default | Description |
|---|
format | string | "json" | Output format: "json", "csv", "soc2" |
startDate | string | — | ISO date string for range start |
endDate | string | — | ISO date string for range end |
entityType | string | — | Filter by entity type |
action | string | — | Filter by action ("create", "update", "delete") |
limit | integer | 10000 | Max records (max 10000) |
offset | integer | 0 | Pagination offset |
Example
curl "https://playground.kaireonai.com/api/v1/audit-export?format=csv&startDate=2026-03-01&endDate=2026-03-16" \
-H "X-Tenant-Id: my-tenant" \
-H "Authorization: Bearer sk_live_abc123" \
-o audit-export.csv
Content-Disposition: attachment.
POST /api/v1/audit-export
Verify audit integrity chain via the export endpoint.
Request Body
| Field | Type | Required | Description |
|---|
action | string | Yes | Must be "verify_integrity" |
startDate | string | No | ISO start date for range verification |
endDate | string | No | ISO end date for range verification |
Roles
| Endpoint | Allowed Roles |
|---|
GET /audit-logs | admin |
GET /audit-logs/verify | admin |
GET /audit-export | admin |
POST /audit-export | admin |
