> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit log

> Record every HTTP request to a space as JSON lines for access reviews and debugging.

The audit log records one entry for each HTTP request a space serves: who made it, what they called, and how it went. Use it to review access, trace what an agent did, or find slow calls. It is off by default.

The audit log covers requests. To see what changed inside a file, use [versioning](https://docs.kiwifs.com/concepts/versioning.md): every write is a git commit with its actor.

## Turn it on

```toml .kiwi/config.toml theme={null}
[audit]
enabled = true
```

Restart the server. While the log is off, `GET /api/kiwi/audit` returns `501`.

## File format

Entries are appended to one JSON Lines file per UTC day:

**.kiwi**

**audit**

**2026-10-18.jsonl**

**2026-10-19.jsonl**

```json .kiwi/audit/2026-10-19.jsonl theme={null}
{"ts":"2026-10-19T09:12:03.481Z","method":"PUT","path":"/api/kiwi/file","actor":"agent:docs-writer","token_hash":"9f2c41ab","ip":"10.0.0.5","status":200,"duration_ms":42}
{"ts":"2026-10-19T09:12:05.022Z","method":"GET","path":"/api/kiwi/search","actor":"anonymous","ip":"10.0.0.7","status":401,"duration_ms":0}
```

| Field | Description |
| - | - |
| `ts` | Request start time, RFC 3339 with nanoseconds. |
| `method` | HTTP method. |
| `path` | URL path without the query string, so `?path=...` values are not recorded. In multi-space mode the space prefix is already stripped. |
| `space` | Value of the `X-Space` request header, when present. |
| `actor` | Value of `X-Actor` after authentication, or `anonymous`. |
| `token_hash` | First 8 hex characters of the SHA-256 of the bearer token. Lets you tell keys apart without storing them. |
| `ip` | Client IP, honoring `X-Forwarded-For` and `X-Real-IP`. |
| `status` | HTTP status code, including auth failures. |
| `duration_ms` | Time spent handling the request. |

Every route is logged, including the web UI and static assets, except `/health`, `/healthz`, `/readyz`, and `/metrics`. Each space writes to its own `.kiwi/audit/` folder.

> [!NOTE]
>
> Audit files are plain JSON Lines, not signed or hash-chained. Ship them to write-once storage if you need tamper evidence. KiwiFS does not rotate or delete them, so prune old days yourself.

## Query the log

```bash Terminal theme={null}
curl 'http://localhost:3333/api/kiwi/audit?since=2026-10-19T00:00:00Z&limit=500' \
  -H 'Authorization: Bearer kiwi_sk_...'
```

**since** `string`

RFC 3339 timestamp. Defaults to 24 hours ago.

**limit** `integer` (default: 100)

Maximum entries, from 1 to 10000. Values outside that range fall back to 100.

The response is a JSON array of entries in the same shape as the file, oldest first. To narrow by actor or status, filter the result yourself or read the files directly:

```bash Terminal theme={null}
jq -c 'select(.actor == "agent:docs-writer" and .method != "GET")' .kiwi/audit/2026-10-19.jsonl
```

## Use cases

> [accordion] Access reviews
>
> Group entries by `actor` and `token_hash` to see which keys are in use and what each one touched. Look for `401` and `403` statuses to spot misconfigured or probing clients.

> [accordion] Debugging agent behavior
>
> Filter by the agent's actor and a time window to reconstruct its sequence of calls. Pair it with `GET /api/kiwi/versions` to see the exact content each write produced.

> [accordion] Performance
>
> Sort by `duration_ms` to find slow routes. For dashboards, scrape the Prometheus metrics at `/metrics` instead.

## Related

> [card] [Audit log API](https://docs.kiwifs.com/api/utilities.md#audit-log)
>
> Endpoint reference.

> [card] [Configuration](https://docs.kiwifs.com/configuration.md#audit)
>
> The `[audit]` section.

> [card] [Versioning](https://docs.kiwifs.com/concepts/versioning.md)
>
> Content history for every write.

> [card] [Authentication](https://docs.kiwifs.com/guides/auth-tokens.md)
>
> How actors and tokens are assigned.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.