GET /api/v1/change-history
Returns a paginated feed of all changes made within a tenant. Every create, update, delete, publish, rollback, approve, reject, archive, and restore action is recorded in the audit log and surfaced through this endpoint. Use it to answer “who changed what, when?” for compliance, debugging, and operational visibility.
Authentication
Requires a valid tenant and one of the following roles: admin or editor.
| Header | Required | Description |
|---|
X-Tenant-Id | Yes | Tenant identifier |
Authorization | Yes | Bearer token or API key |
Query Parameters
All parameters are optional. When no filters are provided, the endpoint returns the most recent changes across all entity types.
| Parameter | Type | Default | Description |
|---|
entityType | string | — | Filter by entity type (e.g., decision_flow, offer, creative, category, channel, qualification_rule, contact_policy, connector, pipeline, schema, customer) |
entityId | string | — | Filter to changes for a specific entity by its ID |
action | string | — | Filter by action type: create, update, delete, publish, rollback, approve, reject, soft_delete, restore |
since | string | — | ISO 8601 timestamp. Only return changes at or after this time |
limit | integer | 50 | Number of results per page (max 200) |
page | integer | 1 | Page number for pagination |
Example Request
Fetch all decision flow changes in the last 7 days:
curl -X GET "https://playground.kaireonai.com/api/v1/change-history?entityType=decision_flow&since=2026-03-25T00:00:00Z&limit=20" \
-H "X-Tenant-Id: my-tenant" \
-H "Authorization: Bearer sk_live_abc123"
Example Response
{
"changes": [
{
"id": "audit_f7a2b1c3",
"action": "rollback",
"entityType": "decision_flow",
"entityId": "flow_abc123",
"entityName": "Default Recommendation Flow",
"summary": "Rolled back Decision Flow \"Default Recommendation Flow\"",
"user": {
"id": "user_001",
"name": "jane.smith@example.com"
},
"timestamp": "2026-04-01T10:30:00.000Z",
"changes": {
"action": "rollback",
"fromVersion": 5,
"toVersion": 3,
"newVersion": 6,
"notes": "Rollback to v3: Reverting due to scoring regression in v5"
}
},
{
"id": "audit_e3d4c5b6",
"action": "publish",
"entityType": "decision_flow",
"entityId": "flow_abc123",
"entityName": "Default Recommendation Flow",
"summary": "Published Decision Flow \"Default Recommendation Flow\"",
"user": {
"id": "user_002",
"name": "john.doe@example.com"
},
"timestamp": "2026-03-25T16:45:00.000Z",
"changes": {
"version": 5,
"notes": "Experimental propensity model"
}
},
{
"id": "audit_a1b2c3d4",
"action": "update",
"entityType": "decision_flow",
"entityId": "flow_abc123",
"entityName": "Default Recommendation Flow",
"summary": "Updated Decision Flow \"Default Recommendation Flow\"",
"user": {
"id": "user_002",
"name": "john.doe@example.com"
},
"timestamp": "2026-03-25T15:00:00.000Z",
"changes": {}
}
],
"total": 3,
"page": 1,
"limit": 20
}
Response Fields
| Field | Type | Description |
|---|
changes | array | List of audit log entries matching the query |
changes[].id | string | Unique audit log entry ID |
changes[].action | string | The action performed (see table below) |
changes[].entityType | string | The type of entity that was changed |
changes[].entityId | string | The ID of the changed entity |
changes[].entityName | string or null | Human-readable name of the entity, if available |
changes[].summary | string | Auto-generated one-line summary (e.g., "Published Decision Flow \"Default Flow\"") |
changes[].user.id | string or null | The ID of the user who made the change |
changes[].user.name | string | The name or email of the user, or "system" for automated changes |
changes[].timestamp | string | ISO 8601 timestamp of when the change occurred |
changes[].changes | object | Action-specific change details (varies by action type) |
total | integer | Total number of matching records (for pagination) |
page | integer | Current page number |
limit | integer | Results per page |
Action Types
| Action | Description |
|---|
create | Entity was created |
update | Entity was modified |
delete | Entity was permanently deleted |
publish | Decision flow or other entity was published to production |
rollback | Decision flow was rolled back to a previous version |
approve | Governance approval was granted |
reject | Governance approval was rejected |
soft_delete | Entity was archived (soft-deleted) |
restore | Previously archived entity was restored |
gdpr_erasure | Customer data was erased for GDPR compliance |
Error Responses
| Status | Cause |
|---|
401 | Missing or invalid authentication credentials |
403 | Insufficient role (requires admin or editor) |
500 | Internal server error |
Combine entityId with no other filters to see the complete lifecycle of a single entity — from creation through every update, publish, and rollback.
The summary field is auto-generated from the action and entity type, formatted for display in a UI timeline (e.g., “Created Offer”, “Published Decision Flow”). Use it directly in activity feeds without additional formatting.
