> ## 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.
# Audit Logs
> Immutable audit trail with SHA-256 integrity chain. Query logs, verify chain integrity, and export for SOC 2 compliance.
## 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
```json theme={null}
{
"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:
```json theme={null}
{
"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
```json theme={null}
{
"intact": true,
"verified": 5420,
"total": 5420,
"scanned": 5420
}
```
### Broken Chain Response
```json theme={null}
{
"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
```bash theme={null}
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](/governance-security/compliance) | [Operations Dashboard](/self-host/architecture/operations)