> ## 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.

# Analytics and health

> Knowledge health dashboard, per-page health checks, comments, sharing, and real-time events.

## Health dashboard

Get an overview of your knowledge base health.

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/analytics'
```

```json theme={null}
{
  "total_pages": 142,
  "stale_pages": 8,
  "orphan_pages": 5,
  "broken_links": 3,
  "empty_pages": 1,
  "pages_without_frontmatter": 12,
  "link_coverage_pct": 96.5,
  "recently_updated": [
    {"path": "concepts/auth.md", "updated": "2026-04-25T14:30:00Z"},
    {"path": "concepts/billing.md", "updated": "2026-04-24T09:15:00Z"}
  ]
}
```

<ResponseField name="total_pages" type="integer">Total number of pages.</ResponseField>
<ResponseField name="stale_pages" type="integer">Pages past their `review-by` date in frontmatter.</ResponseField>
<ResponseField name="orphan_pages" type="integer">Pages with no incoming backlinks.</ResponseField>
<ResponseField name="broken_links" type="integer">Wiki links pointing to nonexistent pages.</ResponseField>
<ResponseField name="empty_pages" type="integer">Pages with no content beyond frontmatter.</ResponseField>
<ResponseField name="pages_without_frontmatter" type="integer">Pages missing YAML frontmatter.</ResponseField>
<ResponseField name="link_coverage_pct" type="number">Percentage of wiki links that resolve to existing pages.</ResponseField>
<ResponseField name="recently_updated" type="array">Most recently modified pages.</ResponseField>

## Analytics overview

Compact dashboard for the web UI engagement panel:

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/analytics/overview'
```

## Page views

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/analytics/views'
curl 'http://localhost:3333/api/kiwi/analytics/views/v2?path=concepts/auth.md'
```

`views/v2` returns richer per-page engagement when tracking is enabled.

## Search analytics

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/analytics/searches'
curl 'http://localhost:3333/api/kiwi/analytics/failed-searches'
```

Failed searches help identify content gaps agents could not answer.

## Trends and content gaps

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/analytics/trends'
curl 'http://localhost:3333/api/kiwi/analytics/content-gaps'
```

Dismiss a content gap suggestion:

```bash theme={null}
curl -X POST 'http://localhost:3333/api/kiwi/analytics/content-gaps/dismiss' \
  -H 'Content-Type: application/json' \
  -d '{"query": "oauth refresh token"}'
```

## Import sources analytics

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/analytics/sources'
```

Summarizes pages by `_source` frontmatter from imports.

## Per-page health check

Analyze the health of a single page.

<ParamField query="path" type="string" required>
  File path to check.
</ParamField>

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/health-check?path=concepts/auth.md'
```

```json theme={null}
{
  "path": "concepts/auth.md",
  "word_count": 342,
  "link_count": 5,
  "backlink_count": 8,
  "days_since_update": 2,
  "issues": []
}
```

When issues are detected, they appear in the `issues` array:

```json theme={null}
{
  "issues": [
    {"type": "stale", "message": "Page is 45 days past its review date"},
    {"type": "broken_link", "message": "Link [[payments-v1]] does not resolve"}
  ]
}
```

## Stale pages

List pages that are past their review date.

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/stale'
```

```json theme={null}
[
  {
    "path": "concepts/legacy-auth.md",
    "title": "Legacy Authentication",
    "review_by": "2026-03-01",
    "days_overdue": 55
  }
]
```

## Contradictions

Detect pages with potentially conflicting claims.

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/contradictions'
```

```json theme={null}
[
  {
    "pages": ["concepts/auth.md", "runbooks/login-flow.md"],
    "claim": "session timeout duration",
    "details": "auth.md says 30 minutes, login-flow.md says 1 hour"
  }
]
```

## Janitor scan

Run a full knowledge health scan across the entire knowledge base.

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/janitor'
```

```json theme={null}
{
  "stale": 8,
  "orphans": 5,
  "broken_links": 3,
  "empty": 1,
  "missing_frontmatter": 12,
  "recommendations": [
    "Link orphan page concepts/caching.md from a parent topic",
    "Update stale page runbooks/deploy-v1.md (90 days overdue)",
    "Fix broken link [[payments-v1]] in concepts/billing.md"
  ]
}
```

***

## Memory report

Get an overview of your episodic memory structure — useful for agents that use the episode/merge pattern.

```http theme={null}
GET /api/kiwi/memory/report
```

<ParamField query="episodes_prefix" type="string">
  Path prefix for episodes directory. Uses the configured default if omitted.
</ParamField>

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/memory/report'
```

```json theme={null}
{
  "episodic_count": 23,
  "merged_from_refs": 15,
  "episodic_files": ["episodes/ep-001.md", "episodes/ep-002.md"],
  "unmerged": 8,
  "warnings": ["Episode ep-012.md has no merge target"]
}
```

## Context

Retrieve the knowledge base context files used by agents — the playbook, schema description, and index.

```http theme={null}
GET /api/kiwi/context
```

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/context'
```

```json theme={null}
{
  "playbook": "# Playbook\n\nRules for how agents should interact...",
  "schema": "# Schema\n\nFrontmatter fields and their meanings...",
  "index": "# Index\n\nTop-level knowledge structure..."
}
```

These map to `.kiwi/playbook.md`, `.kiwi/SCHEMA.md`, and `.kiwi/index.md`.

## Theme

Read or update the web UI theme.

### Get theme

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/theme'
```

### Set theme

```bash theme={null}
curl -X PUT 'http://localhost:3333/api/kiwi/theme' \
  -H "Content-Type: application/json" \
  -d '{"primary": "#6cbe45", "mode": "light"}'
```

Returns `403` if `ui.theme_locked = true` in configuration.

***

## Comments

Add, list, resolve, and delete inline comments on pages.

### List comments

<ParamField query="path" type="string" required>
  File path to list comments for.
</ParamField>

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/comments?path=concepts/auth.md'
```

```json theme={null}
[
  {
    "id": "cmt_01",
    "path": "concepts/auth.md",
    "line": 15,
    "author": "agent:reviewer",
    "body": "Should this mention refresh tokens?",
    "resolved": false,
    "created": "2026-04-25T10:00:00Z"
  }
]
```

### Add a comment

```bash theme={null}
curl -X POST 'http://localhost:3333/api/kiwi/comments?path=concepts/auth.md' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:reviewer" \
  -d '{"line": 15, "body": "Should this mention refresh tokens?"}'
```

### Resolve a comment

```bash theme={null}
curl -X PATCH 'http://localhost:3333/api/kiwi/comments/cmt_01' \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}'
```

### Delete a comment

```bash theme={null}
curl -X DELETE 'http://localhost:3333/api/kiwi/comments/cmt_01'
```

***

## Sharing

Create and manage share links for pages.

### Create a share link

```bash theme={null}
curl -X POST 'http://localhost:3333/api/kiwi/share' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:sharer" \
  -d '{"path": "concepts/auth.md", "expiresIn": "168h", "password": "optional-secret"}'
```

`expiresIn` is a Go duration string (`168h` for seven days). Omit it for links that never expire.

```json theme={null}
{
  "id": "a1b2c3d4",
  "path": "concepts/auth.md",
  "token": "<opaque-token>",
  "expiresAt": "2026-05-09T14:30:00Z",
  "createdBy": "agent:sharer",
  "createdAt": "2026-05-02T14:30:00Z",
  "viewCount": 0
}
```

Readers open `GET /api/kiwi/public/:token` (see [Utilities](/api/utilities#public-routes)).

### List share links

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/share?path=concepts/auth.md'
```

`path` is **required** — the handler returns every active link for that page.

### Revoke a share link

```bash theme={null}
curl -X DELETE 'http://localhost:3333/api/kiwi/share/a1b2c3d4'
```

Returns JSON `{ "revoked": "<id>" }` using the share **`id`** field (not the long `token`).

***

## Real-time events (SSE)

Subscribe to a Server-Sent Events stream that emits events on every write and delete. Use this for real-time UI updates or external integrations.

```bash theme={null}
curl -N 'http://localhost:3333/api/kiwi/events'
```

```
event: write
data: {"path":"concepts/auth.md","actor":"agent:docs-writer","timestamp":"2026-04-25T14:30:00Z"}

event: delete
data: {"path":"concepts/old-page.md","actor":"agent:cleanup","timestamp":"2026-04-25T14:31:00Z"}

event: write
data: {"path":"concepts/billing.md","actor":"agent:importer","timestamp":"2026-04-25T14:32:00Z"}
```

<Note>
  The SSE connection stays open indefinitely. Use `curl -N` (no-buffer) to see events as they arrive. In production, implement reconnection logic with the `Last-Event-ID` header.
</Note>

### Event types

| Event    | Trigger                       |
| -------- | ----------------------------- |
| `write`  | A file was created or updated |
| `delete` | A file was deleted            |
| `bulk`   | A bulk write completed        |
| `import` | An import completed           |