Analytics and health

These endpoints answer two questions: what are people and agents reading and failing to find, and which pages need attention. Analytics and health endpoints need the default SQLite search backend and return 501 when KiwiFS runs with search.engine = "grep". KiwiFS records a page view on every GET /api/kiwi/file for a markdown page, except from known bots. Tag views with ?source= or the X-Kiwi-Source header (default api) to break them down by client.

Health dashboard

Return page counts, health issues, link coverage, recent updates, and engagement in one call. The web UI’s analytics panel uses this.

GET /api/kiwi/analytics

string

Path prefix. Only pages under it are counted.

integer

default:"30"

Days used for the stale check. See Stale pages.

curl 'http://localhost:3333/api/kiwi/analytics?scope=concepts/'

integer

Indexed pages.

integer

Sum of word counts.

object

Issue groups. Each has count and paths. Orphans, broken links, and empty pages come from the latest janitor scan.

Show properties

object

Pages past review. See Stale pages.

object

Pages no other page links to.

object

Pages containing a wiki link that doesn’t resolve.

object

Pages with no body.

object

Pages without frontmatter. paths is always empty.

object

Show properties

integer

Pages with at least one outgoing link.

integer

Pages with none.

number

Mean outgoing links per page.

object[]

The 10 most recently updated pages, each with path and updated_at.

object

Show properties

integer

All recorded page views.

object[]

Most viewed pages. Same shape as page views.

object[]

Most frequent searches with no results. Same shape as failed searches.

{
  "total_pages": 142,
  "total_words": 58210,
  "health": {
    "stale": { "count": 2, "paths": ["concepts/legacy-auth.md", "concepts/sso.md"] },
    "orphans": { "count": 1, "paths": ["concepts/caching.md"] },
    "broken_links": { "count": 1, "paths": ["concepts/billing.md"] },
    "empty": { "count": 0, "paths": [] },
    "no_frontmatter": { "count": 12, "paths": [] }
  },
  "coverage": { "pages_with_links": 120, "pages_without_links": 22, "avg_links_per_page": 3.4 },
  "top_updated": [
    { "path": "concepts/auth.md", "updated_at": "2026-10-18T14:30:00Z" }
  ],
  "engagement": {
    "total_views": 3120,
    "top_viewed": [
      { "path": "concepts/auth.md", "count": 412, "first_seen": 1758000000, "last_seen": 1760880000 }
    ],
    "failed_searches": [
      { "query": "oauth refresh token", "search_type": "search", "count": 7, "first_seen": 1759000000, "last_seen": 1760870000 }
    ]
  }
}

Analytics overview

Return headline numbers for a period, each compared with the period before it.

GET /api/kiwi/analytics/overview

string

default:"7d"

Number of days followed by d, such as 7d, 30d, or 90d. Invalid values fall back to 7d.

curl 'http://localhost:3333/api/kiwi/analytics/overview?period=30d'

string

Period used.

integer

Page views in the period.

number

Change in views versus the previous period, in percent.

integer

Searches in the period.

number

Change in searches, in percent.

number

Share of searches that returned results.

number

Change in success rate, in percentage points.

integer

Distinct pages viewed.

number

Change in distinct pages viewed, in percent.

{
  "period": "30d",
  "total_views": 3120,
  "views_delta_percent": 12.5,
  "total_searches": 860,
  "searches_delta_percent": -3.1,
  "search_success_rate": 0.91,
  "success_rate_delta_pp": 2.0,
  "unique_pages_viewed": 97,
  "unique_pages_delta_percent": 4.3
}

Page views

Return the most viewed pages, optionally for one page or since a point in time.

GET /api/kiwi/analytics/views

integer

default:"20"

Maximum rows, up to 200.

string

Only return views of this page.

string

Unix timestamp or RFC 3339 time. Returns 400 if it is neither.

curl 'http://localhost:3333/api/kiwi/analytics/views?top=5&since=2026-10-01T00:00:00Z'

integer

Row limit used.

string

Path filter, if given.

integer

Start time as a Unix timestamp, if given.

object[]

Show properties

string

Page path.

integer

Views.

integer

First view, Unix seconds.

integer

Latest view, Unix seconds.

{
  "top": 5,
  "since": 1759276800,
  "results": [
    { "path": "concepts/auth.md", "count": 212, "first_seen": 1759280000, "last_seen": 1760880000 }
  ]
}

Page view time series

Return page views bucketed over time, plus the top 20 pages for the period. Buckets are hourly for periods up to 7 days and daily beyond that.

GET /api/kiwi/analytics/views/v2

string

default:"30d"

Number of days followed by d.

string

Limit the time series to one page. top_pages always covers every page.

curl 'http://localhost:3333/api/kiwi/analytics/views/v2?period=7d&path=concepts/auth.md'

string

Period used.

string

Path filter, if given.

object[]

Buckets, each with timestamp (Unix seconds, bucket start) and count.

object[]

Up to 20 pages, same shape as page views results.

{
  "period": "7d",
  "path": "concepts/auth.md",
  "time_series": [
    { "timestamp": 1760839200, "count": 4 },
    { "timestamp": 1760842800, "count": 9 }
  ],
  "top_pages": [
    { "path": "concepts/auth.md", "count": 61, "first_seen": 1760300000, "last_seen": 1760880000 }
  ]
}

Search analytics

Return search volume over time, the success rate, and the 20 most frequent failed queries for a period.

GET /api/kiwi/analytics/searches

string

default:"30d"

Number of days followed by d.

curl 'http://localhost:3333/api/kiwi/analytics/searches?period=30d'

string

Period used.

number

Share of searches that returned results.

object[]

Buckets, each with timestamp and count.

object[]

Show properties

string

Query text.

string

Which search ran it, such as search or semantic.

integer

Times it was run.

integer

Times it returned results.

{
  "period": "30d",
  "search_success_rate": 0.91,
  "time_series": [{ "timestamp": 1758240000, "count": 31 }],
  "top_failed": [
    { "query": "oauth refresh token", "search_type": "search", "count": 7, "had_results": 0 }
  ]
}

Failed searches

Return the most frequent searches that returned no results.

GET /api/kiwi/analytics/failed-searches

integer

default:"20"

Maximum rows, up to 200.

string

Unix timestamp or RFC 3339 time. Returns 400 if it is neither.

curl 'http://localhost:3333/api/kiwi/analytics/failed-searches?top=10'

integer

Row limit used.

integer

Start time as a Unix timestamp, if given.

object[]

Show properties

string

Query text.

string

Which search ran it.

integer

Times it failed.

integer

First failure, Unix seconds.

integer

Latest failure, Unix seconds.

{
  "top": 10,
  "results": [
    { "query": "oauth refresh token", "search_type": "search", "count": 7, "first_seen": 1759000000, "last_seen": 1760870000 }
  ]
}

Trends

Return pages whose views rose or fell most compared with the previous period.

GET /api/kiwi/analytics/trends

string

default:"7d"

Number of days followed by d.

curl 'http://localhost:3333/api/kiwi/analytics/trends?period=7d'

string

Period used.

Pages with rising views.

object[]

Pages with falling views. Both arrays share this shape:

Show properties

string

Page path.

integer

Views in this period.

integer

Views in the previous period.

number

Change, in percent.

{
  "period": "7d",
  "trending": [{ "path": "runbooks/deploy.md", "current_views": 48, "previous_views": 12, "delta_percent": 300 }],
  "declining": [{ "path": "concepts/legacy-auth.md", "current_views": 2, "previous_views": 15, "delta_percent": -86.7 }]
}

Content gaps

Return failed queries that suggest missing pages. Dismissed queries are excluded.

GET /api/kiwi/analytics/content-gaps

integer

default:"20"

Maximum rows, up to 200.

curl 'http://localhost:3333/api/kiwi/analytics/content-gaps?limit=10'

object[]

Same shape as failed searches results.

{
  "results": [
    { "query": "oauth refresh token", "search_type": "search", "count": 7, "first_seen": 1759000000, "last_seen": 1760870000 }
  ]
}

Dismiss a content gap

Hide a query from the content gaps list, for example after writing the missing page.

POST /api/kiwi/analytics/content-gaps/dismiss

string

required

Query text, exactly as listed.

string

default:"search"

search_type from the content gap entry.

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

Returns 400 if query is missing.

{ "dismissed": "oauth refresh token" }

View sources

Return page views in a period grouped by source. The source is the source query parameter or X-Kiwi-Source header sent with the file read, or api when neither is set.

GET /api/kiwi/analytics/sources

string

default:"7d"

Number of days followed by d.

curl 'http://localhost:3333/api/kiwi/analytics/sources?period=30d'

string

Period used.

object

Map from source name to view count.

{ "period": "30d", "sources": { "ui": 2410, "api": 530, "mcp": 180 } }

Page health check

Return size, link, and freshness metrics and open issues for one page.

GET /api/kiwi/health-check

string

required

Page path.

curl 'http://localhost:3333/api/kiwi/health-check?path=concepts/auth.md'

Returns 400 if path is missing. A page that isn’t indexed returns 200 with the issue page not found in index.

string

Page path.

integer

Words in the page.

integer

Outgoing links.

integer

Incoming links.

number

Days since the page last changed.

number

Frontmatter quality_score, if set.

string[]

Issues from the latest janitor scan, formatted kind: message.

{
  "path": "concepts/billing.md",
  "word_count": 342,
  "link_count": 5,
  "backlink_count": 8,
  "days_since_update": 2.4,
  "issues": ["broken-link: link [[payments-v1]] does not resolve"]
}

Stale pages

List pages due for review. A page is stale when its next-review date has passed, or, if it has no next-review, when its reviewed date is older than days. Pages with status: deprecated or status: archived are skipped.

GET /api/kiwi/stale

integer

default:"30"

Age threshold for the reviewed fallback.

curl 'http://localhost:3333/api/kiwi/stale?days=60'

integer

Threshold used.

integer

Stale pages found.

object[]

Pages, each with path and frontmatter.

{
  "staleDays": 60,
  "count": 1,
  "results": [
    { "path": "concepts/legacy-auth.md", "frontmatter": { "title": "Legacy authentication", "next-review": "2026-08-01", "status": "active" } }
  ]
}

Contradictions

List pages that may conflict with a given page. A page is a candidate when it shares a tags or topics value with the given page and either has a different status, or both pages set source-of-truth: true.

GET /api/kiwi/contradictions

string

required

Page path.

curl 'http://localhost:3333/api/kiwi/contradictions?path=concepts/auth.md'

string

Page checked.

string[]

Paths of possibly conflicting pages.

{ "path": "concepts/auth.md", "contradictions": ["runbooks/login-flow.md"] }

Janitor scan

Return the results of a knowledge base health scan. The server runs scans on a schedule; this endpoint returns the cached result unless you ask for a fresh one or a non-default threshold.

GET /api/kiwi/janitor

integer

default:"90"

Days without changes before a page counts as stale. The default comes from the janitor configuration.

boolean

default:"false"

Run a new scan instead of returning the cached result.

curl 'http://localhost:3333/api/kiwi/janitor?fresh=true'

Cached responses include an X-Kiwi-Janitor-LastScan header with the scan time.

object[]

Show properties

string

stale, orphan, duplicate, contradiction, missing-owner, missing-status, empty-page, broken-link, no-review-date, decision-found, expired-memory, or execution-stale.

string

Affected page.

string

What’s wrong.

Other pages involved, such as the duplicate.

string

How to fix it.

string

error, warning, or info.

integer

Pages scanned.

integer

Pages with no issues.

string

When the scan ran.

{
  "issues": [
    {
      "kind": "orphan",
      "path": "concepts/caching.md",
      "message": "no other page links here",
      "suggestion": "link it from a parent topic",
      "severity": "warning"
    }
  ],
  "scanned": 142,
  "healthy": 131,
  "timestamp": "2026-10-19T06:00:00Z"
}

Memory report

Summarize episodic memory: how many episode files exist, how many have been merged into durable pages, and which haven’t. See Episodic memory.

GET /api/kiwi/memory/report

string

default:"episodes/"

Folder holding episode files. Defaults to [memory] episodes_path_prefix in config.

integer

Maximum entries in episodic_files and unmerged.

integer

Entries to skip in episodic_files and unmerged.

curl 'http://localhost:3333/api/kiwi/memory/report?limit=50'

Returns 400 for a negative or non-numeric limit or offset. Results are cached for 30 seconds.

integer

Episode files found.

integer

Episode files before pagination.

integer

Unmerged episodes before pagination.

integer

merged-from references across all pages.

number

Percentage of episodes referenced by a merged-from entry.

integer

Pages flagged as contradicting each other.

number

Mean age of active pages, in days.

integer

Pages whose expires_at has passed.

integer

Pages with memory_status: contested.

object

Map from frontmatter scope value to page count.

object[]

Episode files, each with path and optional episode_id and memory_kind.

object[]

Episodes not yet merged, same shape.

string[]

Problems found while scanning. Omitted when empty.

{
  "episodic_count": 23,
  "total_episodic": 23,
  "total_unmerged": 8,
  "contradictions": 0,
  "merged_from_refs": 15,
  "coverage_pct": 65.2,
  "avg_age_days": 41.7,
  "expired_count": 1,
  "contested_count": 0,
  "scope_counts": { "team": 18, "personal": 5 },
  "episodic_files": [{ "path": "episodes/ep-001.md", "episode_id": "ep-001" }],
  "unmerged": [{ "path": "episodes/ep-012.md", "episode_id": "ep-012" }]
}

MCP equivalents

kiwi_analytics (health dashboard), kiwi_health_check, and kiwi_memory_report.

Refactor

Find and fix broken links and orphan pages.

Web UI analytics

The analytics panel built on these endpoints.

REST API

CLI

Health dashboard

Analytics overview

Page views

Page view time series

Search analytics

Failed searches

Trends

Content gaps

Dismiss a content gap

View sources

Page health check

Stale pages

Contradictions

Janitor scan

Memory report

MCP equivalents

Refactor

Web UI analytics

​Health dashboard

​Analytics overview

​Page views

​Page view time series

​Search analytics

​Failed searches

​Trends

​Content gaps

​Dismiss a content gap

​View sources

​Page health check

​Stale pages

​Contradictions

​Janitor scan

​Memory report

​MCP equivalents

​Related

Refactor

Web UI analytics

Health dashboard

Analytics overview

Page views

Page view time series

Search analytics

Failed searches

Trends

Content gaps

Dismiss a content gap

View sources

Page health check

Stale pages

Contradictions

Janitor scan

Memory report

MCP equivalents

Related