Audit API

Query the audit log. State-changing actions in Kanoniv are recorded with before/after state.

Overview

The audit log records changes to the identity graph. Audit events capture who performed an action, what changed, and the before/after state.

Method	Endpoint	Use Case
List events	GET /v1/audit	Get the 100 most recent audit events
Entity trail	GET /v1/audit/entity/:entity_id	Get all events for a specific entity

---

GET /v1/audit

List recent audit events for your tenant. Returns the 100 most recent events ordered by timestamp descending.

Request

Python

import httpx

resp = httpx.get("https://api.kanoniv.com/v1/audit",
    headers={"X-API-Key": "kn_..."})
events = resp.json()

for event in events:
    print(f"[{event['timestamp']}] {event['action']} by {event['actor_type']}:{event['actor_id']}")
    print(f"  Resource: {event['resource_type']}:{event['resource_id']}")

curl

curl "https://api.kanoniv.com/v1/audit" \
  -H "X-API-Key: kn_..."

Response

Returns an array of AuditEvent objects:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "t_abc123",
    "actor_id": "660e8400-e29b-41d4-a716-446655440001",
    "actor_type": "user",
    "action": "field_update",
    "resource_type": "canonical_entity",
    "resource_id": "770e8400-e29b-41d4-a716-446655440002",
    "before_state": {
      "email": "[email protected]"
    },
    "after_state": {
      "email": "[email protected]"
    },
    "reason": null,
    "timestamp": "2026-02-05T10:00:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "tenant_id": "t_abc123",
    "actor_id": "t_abc123",
    "actor_type": "system",
    "action": "reconciliation.health_alert",
    "resource_type": "batch_run",
    "resource_id": "880e8400-e29b-41d4-a716-446655440004",
    "before_state": null,
    "after_state": {
      "health_status": "warning",
      "merge_rate": 0.45
    },
    "reason": "Merge rate exceeded threshold",
    "timestamp": "2026-02-04T15:30:00Z"
  }
]

Response Fields

Field	Type	Description
id	UUID	Audit event ID
tenant_id	UUID	Tenant this event belongs to
actor_id	UUID	User or system ID that performed the action
actor_type	string	Actor type (e.g., "user", "worker", "system", "api_key")
action	string	What happened (e.g., "field_update", "merge", "revert", "reconciliation.health_alert")
resource_type	string	Type of resource affected (e.g., "canonical_entity", "batch_run")
resource_id	UUID	ID of the affected resource
before_state	object	State before the change (null for creation events)
after_state	object	State after the change
reason	string	Human-readable explanation (null if not provided)
timestamp	timestamp	When the event occurred

---

GET /v1/audit/entity/:entity_id

Get all audit events for a specific entity. Returns a complete timeline of how an entity was created, modified, merged, or reverted.

Path Parameters

Parameter	Type	Required	Description
entity_id	UUID	Yes	Canonical entity ID

Request

Python

import httpx

resp = httpx.get(
    "https://api.kanoniv.com/v1/audit/entity/770e8400-e29b-41d4-a716-446655440002",
    headers={"X-API-Key": "kn_..."})
trail = resp.json()

for event in trail:
    print(f"[{event['timestamp']}] {event['action']}")
    if event["before_state"]:
        print(f"  Before: {event['before_state']}")
    if event["after_state"]:
        print(f"  After:  {event['after_state']}")

curl

curl "https://api.kanoniv.com/v1/audit/entity/770e8400-e29b-41d4-a716-446655440002" \
  -H "X-API-Key: kn_..."

Response

Returns an array of AuditEvent objects (same schema as above) ordered by timestamp descending, filtered to events where resource_id matches the given entity ID.

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "tenant_id": "t_abc123",
    "actor_id": "660e8400-e29b-41d4-a716-446655440001",
    "actor_type": "user",
    "action": "field_update",
    "resource_type": "canonical_entity",
    "resource_id": "770e8400-e29b-41d4-a716-446655440002",
    "before_state": { "email": "[email protected]" },
    "after_state": { "email": "[email protected]" },
    "reason": null,
    "timestamp": "2026-02-01T09:00:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440011",
    "tenant_id": "t_abc123",
    "actor_id": "t_abc123",
    "actor_type": "worker",
    "action": "merge",
    "resource_type": "canonical_entity",
    "resource_id": "770e8400-e29b-41d4-a716-446655440002",
    "before_state": null,
    "after_state": { "email": "[email protected]", "name": "John Doe" },
    "reason": "Auto-merge: confidence 0.94",
    "timestamp": "2026-01-20T14:30:00Z"
  }
]