Files

Read, write, patch, append, rename, upload, and serve files through the KiwiFS REST API.

File endpoints are the core of the API. Every write goes through the write pipeline: it lands on disk, becomes a git commit, updates the search index, and is broadcast to SSE subscribers.

All paths below are relative to http://localhost:3333/api/kiwi unless they start with /raw. File paths in ?path= are relative to the knowledge root; paths that escape the root or point into hidden directories return 400.

Get the directory tree

Returns the folder hierarchy as a nested object, up to 20 levels deep.

GET /tree

path · string · default: "/"

Folder to start from.

curl 'http://localhost:3333/api/kiwi/tree?path=concepts'

path · string

Path relative to the root.

name · string

File or folder name.

isDir · boolean

true for folders.

size · integer

File size in bytes. Omitted for folders.

permalink · string

Public URL for the file. Present only for files when a public URL is configured.

children · object[]

Nested entries with the same shape. Omitted when empty.

Response

{
  "path": "concepts",
  "name": "concepts",
  "isDir": true,
  "children": [
    {
      "path": "concepts/auth.md",
      "name": "auth.md",
      "isDir": false,
      "size": 1420,
      "permalink": "https://wiki.example.com/page/concepts/auth.md"
    }
  ]
}

Returns 404 if the folder does not exist.

Read a file

Returns the raw file bytes with an ETag you can use for conditional writes.

GET /file

path · string · required

File path.

metadata_only · boolean · default: "false"

Return only the parsed frontmatter as a JSON object.

resolve_links · boolean · default: "false"

Rewrite wiki links to absolute URLs. Requires a configured public URL.

source · string · default: "api"

Label stored with the page view in analytics. Also accepted as the X-Kiwi-Source header.

If-None-Match · string

ETag from an earlier read. Returns 304 when it still matches.

If-Modified-Since · string

HTTP date. Returns 304 when the file has not changed since.

Content

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

Response

HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
ETag: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
Last-Modified: Sun, 19 Oct 2026 09:30:00 GMT
Cache-Control: no-cache
X-Permalink: https://wiki.example.com/page/concepts/auth.md

---
title: Authentication
status: verified
---
# Authentication

OAuth2 + JWT based authentication system.

Response headers:

Header	Meaning
ETag	Quoted git blob hash of the content
Last-Modified	File modification time
X-Permalink	Public URL, when a public URL is configured
X-File-Type	symlink when the path is a symbolic link

Returns 404 if the file does not exist.

Write a file

Creates or replaces a file. The request body is the full file content, up to 32 MB.

PUT /file

path · string · required

File path. Parent folders are created as needed.

If-Match · string

ETag the file must still have. Returns 409 on mismatch.

X-Actor · string · default: "anonymous"

Commit author.

X-Provenance · string

type:id pair appended to the page’s derived-from frontmatter list, for example run:run-249.

Content-Type · string

Send application/x-symlink to create a symbolic link whose target is the body.

Create or replace

curl -X PUT 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
  -H "Content-Type: text/markdown" \
  -H "X-Actor: agent:docs-writer" \
  --data-binary @auth.md

path · string

Path written.

etag · string

New ETag (also in the ETag header).

Response

{"path": "concepts/auth.md", "etag": "c3d4e5f6a7b8c3d4e5f6a7b8c3d4e5f6a7b8c3d4"}

A symlink write returns {"path": "latest.md", "type": "symlink"}.

Status	When
409	If-Match mismatch, denied workflow transition, rejected by a write hook, or the file is append-only
413	Body over 32 MB
422	Content fails the schema for its type

Patch frontmatter

Merges fields into a page’s YAML frontmatter and leaves the body byte-for-byte unchanged. Two equivalent routes exist.

PATCH /file/frontmatter

The body wraps the fields in a fields object.

curl -X PATCH 'http://localhost:3333/api/kiwi/file/frontmatter?path=decisions/adr-12.md' \
  -H "Content-Type: application/json" \
  -H "X-Field-Manager: agent:reviewer" \
  -d '{"fields": {"reviewed_by": "alice", "status": "accepted"}}'

PATCH /file?merge=frontmatter

The body is the field map itself. merge=frontmatter is required; other values return 400.

curl -X PATCH 'http://localhost:3333/api/kiwi/file?path=runbooks/high-cpu.md&merge=frontmatter' \
  -H "Content-Type: application/json" \
  -H 'If-Match: "abc123..."' \
  -d '{"last_executed": "2026-10-19", "execution_count": 5}'

path · string · required

Markdown file to update. Must already exist.

force · boolean · default: "false"

Take over keys that another field manager owns.

If-Match · string

ETag the file must still have.

X-Field-Manager · string

Name that owns the keys you set. Another manager changing an owned key gets 409 unless it sends force=true.

X-Actor · string · default: "anonymous"

Commit author.

Response

{"path": "decisions/adr-12.md", "etag": "d4e5f6a7..."}

When a key belongs to another manager, nothing is written and the response lists the conflicts:

409 Conflict

{
  "error": "decisions/adr-12.md: status (managed by agent:triage); force to take them over",
  "conflicts": [{"key": "status", "manager": "agent:triage"}]
}

Returns 400 for a non-markdown file or an empty field map, and 404 if the file does not exist.

Append to a file

Adds content to the end of a file without a read-modify-write cycle. Creates the file if it does not exist.

POST /file/append

path · string · required

File path.

separator · string · default: "\\n"

Inserted between the existing content and the new content.

X-Actor · string · default: "anonymous"

Commit author.

curl -X POST 'http://localhost:3333/api/kiwi/file/append?path=log/agent.md' \
  -H "X-Actor: agent:logger" \
  --data-binary $'## Entry 42\n\nNew finding from run 249.'

Response

{"path": "log/agent.md", "etag": "b2c3d4e5..."}

Use append for agent logs, episodic memory, and append-only files. The body limit is 32 MB.

Delete a file

Deletes a file and records the deletion as a commit.

DELETE /file

path · string · required

File path.

X-Actor · string · default: "anonymous"

Commit author.

curl -X DELETE 'http://localhost:3333/api/kiwi/file?path=concepts/old.md' \
  -H "X-Actor: agent:cleanup"

Response

{"deleted": "concepts/old.md"}

Returns 404 if the file does not exist.

Bulk write

Writes several files in one git commit. If any file fails a check, nothing is written.

POST /bulk

files · object[] · required

Files to write.

Show file

path · string · required

File path.

content · string · required

Full file content.

if_match · string

ETag this file must still have. One mismatch fails the whole batch with 409.

actor · string

Commit author. Falls back to X-Actor.

message · string

Commit message.

X-Provenance · string

type:id pair added to every file’s derived-from list.

curl -X POST 'http://localhost:3333/api/kiwi/bulk' \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "agent:importer",
    "message": "Import billing concepts",
    "files": [
      {"path": "concepts/billing.md", "content": "# Billing\n\nStripe integration."},
      {"path": "concepts/users.md", "content": "# Users\n\nUser management."}
    ]
  }'

count · integer

Number of files written.

files · object[]

path and new etag for each file.

Response

{
  "count": 2,
  "files": [
    {"path": "concepts/billing.md", "etag": "e5f6a7b8..."},
    {"path": "concepts/users.md", "etag": "f6a7b8c9..."}
  ]
}

Rename a file

Moves a file and rewrites every wiki link and markdown link that points to it, in one commit.

POST /rename

from · string · required

Current path.

to · string · required

New path. Must not exist unless overwrite=true.

update_links · boolean · default: "true"

Set false to move the file and leave references as written.

overwrite · boolean · default: "false"

Replace an existing destination, like rename(2). Meant for protocol clients that save by writing a temp file and renaming it over the original.

X-Actor · string · default: "anonymous"

Commit author.

curl -X POST 'http://localhost:3333/api/kiwi/rename' \
  -H "Content-Type: application/json" \
  -d '{"from": "concepts/auth.md", "to": "concepts/authentication.md"}'

from · string

Original path.

to · string

New path.

etag · string

ETag of the moved file.

updated_links · string[]

Other pages whose links were rewritten. Omitted when none changed.

Response

{
  "from": "concepts/auth.md",
  "to": "concepts/authentication.md",
  "etag": "c3d4e5f6...",
  "updated_links": ["concepts/users.md", "runbooks/login-outage.md"]
}

Returns 404 if the source does not exist and 409 if the destination exists or a link could not be kept pointing at the file.

Rename a folder

Moves a folder, rewrites links into it from elsewhere, and fixes relative links inside it, in one commit.

POST /rename-dir

from · string · required

Current folder.

to · string · required

New folder. No destination file may exist.

update_links · boolean · default: "true"

Set false to leave references as written.

curl -X POST 'http://localhost:3333/api/kiwi/rename-dir' \
  -H "Content-Type: application/json" \
  -d '{"from": "concepts", "to": "docs/concepts"}'

Response

{
  "from": "concepts",
  "to": "docs/concepts",
  "renamed": 15,
  "updated_links": ["index.md", "runbooks/onboarding.md"]
}

renamed is the number of files moved. For multi-file moves and merges with a review step, see Refactor.

Upload an asset

Uploads an image, video, audio file, or PDF as multipart form data and returns a ready-to-paste markdown link.

POST /assets

path · string

Folder to store the file in, for example assets/diagrams. Defaults to the root.

file · file · required

The file (multipart field name file). Hidden names starting with . are rejected.

X-Actor · string · default: "anonymous"

Commit author.

curl -X POST 'http://localhost:3333/api/kiwi/assets?path=assets' \
  -H "X-Actor: agent:uploader" \
  -F "file=@diagram.png"

path · string

Stored path.

markdown · string

Embed (![]()) for images, video, and audio; a link for other types.

contentType · string

Detected MIME type.

size · integer

Size in bytes.

etag · string

ETag of the stored file.

Response

{
  "path": "assets/diagram.png",
  "markdown": "![diagram](/raw/assets/diagram.png)",
  "contentType": "image/png",
  "size": 48213,
  "etag": "0a1b2c3d..."
}

The default limit is 100 MiB and the default allowlist covers common image, video, and audio types plus PDF. Override both with [assets] max_file_size and allowed_types. Too large returns 413; a type outside the allowlist returns 415.

Serve a raw file

Serves file bytes at a stable URL for <img>, <video>, and <iframe> tags. The web UI uses it for every embedded asset.

GET /raw/{path} (also GET /api/kiwi/raw/{path} and GET /api/kiwi/{space}/raw/{path} for non-primary spaces)

path · string · required

File path, URL-escaped per segment.

exp · string

Expiry from GET /raw-sign.

sig · string

Signature from GET /raw-sign.

curl -O 'http://localhost:3333/raw/assets/diagram.png' \
  -H "Authorization: Bearer $KIWI_API_KEY"

When auth is on, a request needs one of:

• An Authorization header that passes normal auth (key scopes apply to the file path).
• A valid exp and sig pair. An invalid or expired signature returns 403.
• A target that is already public: a branding logo or favicon, a page with visibility: public or that is published, or an asset next to such a page.

Spaces with visibility = "public" or "unlisted" serve raw files without credentials. Responses include X-Content-Type-Options: nosniff, and SVGs get a restrictive Content-Security-Policy. Use GET /file instead when you need an ETag.

Sign a raw file URL

Returns a short-lived /raw/ URL that works without an Authorization header, for clients that can’t send one.

GET /raw-sign

path · string · required

File path.

curl 'http://localhost:3333/api/kiwi/raw-sign?path=assets/diagram.png' \
  -H "Authorization: Bearer $KIWI_API_KEY"

path · string

Normalized path.

url · string

Signed URL, relative to the server root.

expires · string

Expiry time (RFC 3339).

Response

{
  "path": "assets/diagram.png",
  "url": "/raw/assets/diagram.png?exp=1792400400&sig=Zk3x...",
  "expires": "2026-10-19T10:00:00Z"
}

A signed URL stays valid for 30 to 60 minutes. Signatures are per space and do not survive a server restart.

Get a table of contents

Returns a page’s headings with anchor slugs.

GET /toc

path · string · required

Markdown file.

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

Response

{
  "path": "concepts/auth.md",
  "headings": [
    {"level": 1, "text": "Authentication", "slug": "authentication"},
    {"level": 2, "text": "OAuth2 flow", "slug": "oauth2-flow"},
    {"level": 2, "text": "JWT tokens", "slug": "jwt-tokens"}
  ]
}

Resolve wiki links

Rewrites [[wiki links]] in a markdown string to absolute URLs, for rendering content outside KiwiFS.

POST /resolve-links

content · string · required

Markdown to rewrite.

curl -X POST 'http://localhost:3333/api/kiwi/resolve-links' \
  -H "Content-Type: application/json" \
  -d '{"content": "See [[auth]] and [[billing]]."}'

Response

{"content": "See [auth](https://wiki.example.com/page/concepts/auth.md) and [billing](https://wiki.example.com/page/concepts/billing.md)."}

Without a configured public URL, the content comes back unchanged. To resolve links while reading a file, use GET /file?resolve_links=true.

List page templates

Returns the markdown templates in .kiwi/templates/, sorted by name.

GET /templates

curl 'http://localhost:3333/api/kiwi/templates'

Response

{
  "templates": [
    {"name": "decision", "path": ".kiwi/templates/decision.md"},
    {"name": "runbook", "path": ".kiwi/templates/runbook.md"}
  ]
}

Returns an empty templates array when the folder does not exist. See Templates.

Read a page template

Returns one template’s content.

GET /template

name · string · required

Template name without .md.

curl 'http://localhost:3333/api/kiwi/template?name=runbook'

Response

{"name": "runbook", "content": "---\ntype: runbook\nstatus: draft\n---\n\n# Title\n\n## Steps\n\n1. ..."}

Returns 404 if the template does not exist and 400 for a name containing /, \, or ...

Read a symlink target

Returns the target of a symbolic link as plain text, without following it.

GET /readlink

path · string · required

Symlink path.

curl 'http://localhost:3333/api/kiwi/readlink?path=latest.md'

Response

reports/2026-10.md

Returns 404 if the path does not exist and 400 if it is not a symlink.

Related

Versioning

History, diff, and blame for any file.

Utilities

Peek, sections, lint, and more.

Drafts

Stage file changes on a branch before merging.

Wiki links

How links resolve and get rewritten on rename.