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

# 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](/api/overview).

## Read symlink target

```http theme={null}
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

```http theme={null}
POST /lint
Content-Type: application/json
```

Lint an existing file:

```json theme={null}
{ "path": "concepts/auth.md" }
```

Or inline content:

```json theme={null}
{ "content": "# Title\n\nBody..." }
```

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

## Peek summary

```http theme={null}
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

```http theme={null}
GET /section?path=concepts/auth.md&heading=OAuth2%20flow
```

or

```http theme={null}
GET /section?path=concepts/auth.md&index=2
```

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

## Activity timeline

```http theme={null}
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

```http theme={null}
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

```http theme={null}
POST /clip
Content-Type: application/json
```

```json theme={null}
{
  "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

```http theme={null}
GET /graph/centrality?limit=50
```

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

### Communities

```http theme={null}
GET /graph/communities
```

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

### Shortest path

```http theme={null}
GET /graph/path?from=concepts/a.md&to=runbooks/b.md
```

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

### Local neighborhood

```http theme={null}
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/`:

```http theme={null}
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:

```http theme={null}
POST /eval
Content-Type: application/json
```

```json theme={null}
{
  "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:

```http theme={null}
GET /backup/status
GET /sync/status
```

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

## Rules file

```http theme={null}
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

```http theme={null}
GET /space/info
```

```json theme={null}
{ "visibility": "private", "root": "/data/knowledge" }
```

```http theme={null}
PUT /space/visibility
Content-Type: application/json
```

```json theme={null}
{ "visibility": "public" }
```

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

## Audit log

```http theme={null}
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`](/api/analytics#sharing). Readers call **without** API authentication:

```http theme={null}
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:

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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](/concepts/mcp).