Utilities and agent helpers

Symlinks, linting, peek and section reads, timeline and feeds, clipping, extended graph APIs, rules, space settings, audit logs, and public share URLs.

These endpoints share the usual prefix http://localhost:3333/api/kiwi and authentication rules from API overview.

Read symlink target

GET /readlink?path=link/to/page.md

Returns plain text target path. 404 if the path is missing; 400 if the path is not a symlink.

Lint markdown

POST /lint
Content-Type: application/json

Lint an existing file:

{ "path": "concepts/auth.md" }

Or inline content:

{ "content": "# Title\n\nBody..." }

Response: { "issues": [ /* structured lint records */ ] } (always an array, possibly empty).

Peek summary

GET /peek?path=concepts/auth.md

Returns JSON with title, snippet, frontmatter, links_out, links_in, headings, word_count, and other lightweight fields without returning the full body.

Read one section

GET /section?path=concepts/auth.md&heading=OAuth2%20flow

or

GET /section?path=concepts/auth.md&index=2

Returns { "path", "heading", "level", "content", "line_start", "line_end" }.

Activity timeline

GET /timeline?limit=50&offset=0&actor=agent:bot&type=write&path_prefix=runbooks/

• type filter: write, delete, or omit for both.
• limit defaults to 50, max 500.

Response: { "events": [...], "total": <number> } — total is a hint for pagination (see server implementation).

Feeds

GET /feed.xml
GET /feed.json

Atom and JSON Feed built from recent timeline events (titles include updated vs deleted paths).

Clip a web page

POST /clip
Content-Type: application/json

{
  "url": "https://example.com/article",
  "title": "Optional override",
  "tags": ["research", "web"],
  "folder": "clips/"
}

Fetches the article, converts to markdown, writes through the pipeline using X-Actor (default clipper), and returns { "path", "title", "excerpt" }.

Extended graph APIs

All of the following return 503 when link indexing is unavailable.

Centrality

GET /graph/centrality?limit=50

Returns { "pages": [ { "path", "pagerank", "betweenness", ... } ] } (truncated to limit).

Communities

GET /graph/communities

Louvain communities over wiki-link edges: { "communities": ... }.

Shortest path

GET /graph/path?from=concepts/a.md&to=runbooks/b.md

Returns { "path": ["concepts/a.md", "..."] }. 404 when no path exists.

Local neighborhood

GET /graph/walk?path=concepts/a.md&include_siblings=true

Returns outbound wiki links, backlinks, and optional same-directory neighbors.

Page templates

Slash-command templates in .kiwi/templates/:

GET /templates
GET /template?name=meeting-notes

GET /templates lists available template names. GET /template returns the template body for insertion into new pages.

Search evaluation

Benchmark search quality against expected paths:

POST /eval
Content-Type: application/json

{
  "queries": [
    {
      "question": "authentication flow",
      "expected_paths": ["pages/auth.md", "concepts/oauth.md"]
    }
  ]
}

Returns per-query FTS and semantic ranks plus aggregate hit_rate, mrr, and precision_at_5. MCP: kiwi_eval.

Backup status

When [backup] is configured:

GET /backup/status
GET /sync/status

Returns last push time, remote URL, and error state for the background backup goroutine.

Rules file

GET /rules
GET /rules?format=cursor
PUT /rules

• Without format, returns raw .kiwi/rules.md (empty string when missing).
• format may be cursor, claude, agents, or openclaw to wrap user rules for a specific harness.
• PUT accepts raw markdown (max 256 KiB) and commits .kiwi/rules.md when git versioning is enabled.

Space metadata

GET /space/info

{ "visibility": "private", "root": "/data/knowledge" }

PUT /space/visibility
Content-Type: application/json

{ "visibility": "public" }

Allowed values: private, unlisted, public. Persists into .kiwi/config.toml and updates the live config.

Audit log

GET /audit?since=2026-05-01T00:00:00Z&limit=100

Returns JSON array entries { "ts", "method", "path", "space", "actor", "token_hash", "ip", "status", "duration_ms" }.

501 when audit logging was not enabled for this server. Default since is the last 24 hours; limit defaults to 100 (max 10000).

Public routes

Share tokens

Create links with POST /share. Readers call without API authentication:

GET /api/kiwi/public/:token

Optional password: query password or header X-Share-Password. Wrong or missing passwords return 401 with a WWW-Authenticate challenge when the link is password protected.

Public visibility browsing

These endpoints expose only markdown that declares visibility: public in frontmatter:

GET /api/kiwi/public/file?path=concepts/open.md
GET /api/kiwi/public/tree?path=

Non-public pages return 404 as “not found” to avoid leaking existence.

Raw files

GET /raw/*

Serves raw bytes for static assets and markdown outside the JSON APIs (used by the web UI). Not a substitute for GET /file when you need ETag semantics.

UI configuration

GET /ui-config

Returns JSON consumed by the embedded web UI (feature flags, layout hints).

MCP parity

Many of these flows have MCP tools (kiwi_lint, kiwi_peek, kiwi_section, kiwi_timeline, kiwi_feed, kiwi_clip, kiwi_graph_*, and more). See MCP.