Skip to main content
When audit logging is enabled, KiwiFS records every API request as a structured entry. Use audit logs for compliance, debugging, and understanding how agents and users interact with your knowledge base.

​
Enabling audit logging

.kiwi/config.toml
[audit]
enabled = true
Without this setting, the audit endpoint returns 501 Not Implemented.

​
Querying the audit log

GET /api/kiwi/audit?since=2026-05-01T00:00:00Z&limit=100
​
since
string
ISO 8601 timestamp. Defaults to the last 24 hours.
​
limit
integer
default:"100"
Maximum entries to return (max 10,000).
[
  {
    "ts": "2026-05-02T14:30:00Z",
    "method": "PUT",
    "path": "/api/kiwi/file?path=concepts/auth.md",
    "space": "default",
    "actor": "agent:docs-writer",
    "token_hash": "a1b2c3...",
    "ip": "10.0.0.5",
    "status": 200,
    "duration_ms": 42
  }
]

​
Entry fields

FieldDescription
tsTimestamp of the request
methodHTTP method (GET, PUT, POST, DELETE)
pathFull request path including query parameters
spaceSpace name (from URL segment or X-Kiwi-Space header)
actorValue of X-Actor header, if present
token_hashHash of the Bearer token used for authentication
ipClient IP address
statusHTTP response status code
duration_msRequest processing time in milliseconds

​
Use cases

Audit logs provide a tamper-evident record of who accessed or modified knowledge. Filter by actor or token_hash to trace activity by a specific agent or user.
When an agent writes unexpected content, query the audit log by time range and actor to reconstruct the sequence of API calls.
Use duration_ms to identify slow requests. Combine with Prometheus metrics for dashboards.
The X-Space header is also recorded when present, allowing you to trace cross-space operations in multi-space deployments.

Configuration

Enable audit logging in config.toml.

Optional features

Feature matrix — audit requires explicit opt-in.

Utilities API

REST endpoint details.
Last modified on May 31, 2026