Skip to main content

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.

​
Directory tree

Retrieve the directory tree as a JSON array.
​
path
string
default:"/"
Root path to list. Omit to list the entire knowledge base.
curl 'http://localhost:3333/api/kiwi/tree?path=concepts'
​
response
array
Array of tree nodes.
​
path
string
Full path relative to root.
​
name
string
File or directory name.
​
isDir
boolean
Whether this node is a directory.
​
size
integer
File size in bytes (0 for directories).
​
children
array
Nested tree nodes (directories only).
[
  {
    "path": "concepts",
    "name": "concepts",
    "isDir": true,
    "size": 0,
    "children": [
      {"path": "concepts/auth.md", "name": "auth.md", "isDir": false, "size": 1420, "children": null}
    ]
  }
]

​
Read a file

Retrieve raw markdown content. The response includes an ETag header containing the git blob SHA for optimistic locking.
​
path
string
required
File path relative to the knowledge root.
curl -i 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md'

HTTP/1.1 200 OK
Content-Type: text/markdown
ETag: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

# Authentication

OAuth2 + JWT based authentication system...

​
Write a file

Create or update a file. The request body is raw markdown. KiwiFS creates a git commit for each write.
​
path
string
required
File path relative to the knowledge root.
​
X-Actor
string
Git commit author attribution (e.g. agent:my-agent).
​
X-Provenance
string
Lineage tracking (e.g. run:run-249).
​
If-Match
string
ETag from a previous read. If the file has changed since your read, the server returns 409 Conflict.
curl -X PUT 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
  -H "Content-Type: text/markdown" \
  -H "X-Actor: agent:docs-writer" \
  -d '# Authentication

OAuth2 + JWT based authentication system.'
If you pass If-Match and the file has been modified since your read, the server returns 409 Conflict with an error message. Fetch the latest version, merge your changes, and retry.

​
Delete a file

Delete a file and create a git commit recording the deletion.
​
path
string
required
File path to delete.
curl -X DELETE 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
  -H "X-Actor: agent:cleanup"

​
Bulk write

Write multiple files in a single git commit. This is more efficient than individual writes and keeps your git history clean.
​
X-Actor
string
Git commit author attribution.
curl -X POST 'http://localhost:3333/api/kiwi/bulk' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:importer" \
  -d '{
    "files": [
      {"path": "concepts/auth.md", "content": "# Authentication\n\nOAuth2 flow."},
      {"path": "concepts/billing.md", "content": "# Billing\n\nStripe integration."},
      {"path": "concepts/users.md", "content": "# Users\n\nUser management."}
    ]
  }'
Use bulk writes when importing data or making batch updates. All files are committed atomically in a single git commit.

​
Upload assets

Upload binary files (images, PDFs, etc.) as multipart form data. 
curl -X POST 'http://localhost:3333/api/kiwi/assets' \
  -F "file=@diagram.png" \
  -H "X-Actor: agent:uploader"
The response returns the asset path you can reference in markdown: 
{"path": "assets/diagram.png"}

​
Table of contents

Get the heading outline for a file.
​
path
string
required
File path to extract headings from.
curl 'http://localhost:3333/api/kiwi/toc?path=concepts/auth.md'

[
  {"level": 1, "text": "Authentication", "slug": "authentication"},
  {"level": 2, "text": "OAuth2 flow", "slug": "oauth2-flow"},
  {"level": 2, "text": "JWT tokens", "slug": "jwt-tokens"}
]

​
Append to a file

Append content to an existing file without reading it first. 
POST /api/kiwi/file/append
​
path
string
required
File path to append to.
​
separator
string
default:"\\n"
String inserted between existing content and new content.
curl -X POST 'http://localhost:3333/api/kiwi/file/append?path=log/agent.md' \
  -H "X-Actor: agent:logger" \
  -d '## Entry 42

New finding from run 249.'

{"path": "log/agent.md", "etag": "b2c3d4e5f6..."}
Append is useful for agent logs, episodic memory, and audit trails where you want to add content without read-modify-write cycles.

​
Rename a file

Rename or move a file. Wiki links pointing to the old path are automatically updated. 
POST /api/kiwi/rename
​
from
string
required
Old file path.
​
to
string
required
New file path.
​
update_links
boolean
default:"true"
Rewrite wiki links in other files that point to the old path.
curl -X POST 'http://localhost:3333/api/kiwi/rename' \
  -H "Content-Type: application/json" \
  -d '{"from": "concepts/auth.md", "to": "concepts/authentication.md"}'

{
  "from": "concepts/auth.md",
  "to": "concepts/authentication.md",
  "etag": "c3d4e5f6...",
  "updated_links": 8
}

​
Rename a directory

Move an entire directory and update all internal links. 
POST /api/kiwi/rename-dir
​
from
string
required
Old directory path.
​
to
string
required
New directory path.
curl -X POST 'http://localhost:3333/api/kiwi/rename-dir' \
  -H "Content-Type: application/json" \
  -d '{"from": "concepts", "to": "docs/concepts"}'

{"from": "concepts", "to": "docs/concepts", "renamed": 15}

​
Templates

List and read page templates stored in .kiwi/templates/.

​
List templates

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

["runbook", "decision", "episode", "concept"]

​
Read a template

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

{"name": "runbook", "content": "---\ntype: runbook\ntitle: \nstatus: draft\n---\n\n# Title\n\n## Steps\n\n1. ..."}
Resolve [[wiki-links]] to their canonical file paths and permalinks. 
curl -X POST 'http://localhost:3333/api/kiwi/resolve-links' \
  -H "Content-Type: application/json" \
  -d '{"links": ["auth", "billing", "nonexistent"]}'

{
  "resolved": {
    "auth": {"path": "concepts/auth.md", "title": "Authentication"},
    "billing": {"path": "concepts/billing.md", "title": "Billing"}
  },
  "unresolved": ["nonexistent"]
}
Last modified on May 4, 2026