Change History

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.

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

GET /api/v1/change-history

Authentication

Query Parameters

Example Request

Example Response

Response Fields

Action Types

Error Responses

​GET /api/v1/change-history

​Authentication

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Action Types

​Error Responses

GET /api/v1/change-history

Authentication

Query Parameters

Example Request

Example Response

Response Fields

Action Types

Error Responses