Audit Logs

Viewing history in the app

Settings → Change History (/settings/change-history) reads this API back. It leads with chain integrity, because a log you cannot trust is worse than no log, and shows a field-level before/after diff for the selected change rather than the raw row snapshots. Filter by entity type, action, or the user who made the change. Selecting an entry shows who, when, the request id, and each field that moved.

Attribution. Entries written before 2026-08-15 record the actor as system with no user id — the helpers accepted one and almost no caller passed it. The screen flags those in amber as “no actor recorded” rather than implying the platform made the change. Entries written since name the person.

Snapshot coverage is partial. Whole-row before/after snapshots are recorded for configuration entities — offers, creatives, contact policies, decisioning gates, decision flows — and not for high-volume records such as interactions. Where no snapshot exists the screen says no field-level detail was recorded, rather than showing an empty diff that would imply nothing changed.

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`, `ranking_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

CSV exports are returned as downloadable files with 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

See also: Compliance | Operations Dashboard

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Viewing history in the app

GET /api/v1/audit-logs

Query Parameters

Response

Audit log fields

Cascade audit entries

GET /api/v1/audit-logs/verify

Query Parameters

Response

Broken Chain Response

Broken Reasons

GET /api/v1/audit-export

Query Parameters

Example

POST /api/v1/audit-export

Request Body

Roles

​Viewing history in the app

​GET /api/v1/audit-logs

​Query Parameters

​Response

​Audit log fields

​Cascade audit entries

​GET /api/v1/audit-logs/verify

​Query Parameters

​Response

​Broken Chain Response

​Broken Reasons

​GET /api/v1/audit-export

​Query Parameters

​Example

​POST /api/v1/audit-export

​Request Body

​Roles

Viewing history in the app

GET /api/v1/audit-logs

Query Parameters

Response

Audit log fields

Cascade audit entries

GET /api/v1/audit-logs/verify

Query Parameters

Response

Broken Chain Response

Broken Reasons

GET /api/v1/audit-export

Query Parameters

Example

POST /api/v1/audit-export

Request Body

Roles