Files

Directory tree

Retrieve the directory tree as a JSON array.

string

default:"/"

Root path to list. Omit to list the entire knowledge base.

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

array

Array of tree nodes.

string

Full path relative to root.

string

File or directory name.

boolean

Whether this node is a directory.

integer

File size in bytes (0 for directories).

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.

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

Read a symlink target

When a path in the knowledge root is a symbolic link, resolve its target without following into arbitrary filesystem paths outside the guard:

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

Returns plain text body with the symlink target. 404 when the path does not exist; 400 when the path exists but is not a symlink.

Write a file

Create or update a file. The request body is raw markdown. KiwiFS creates a git commit for each write.

string

required

File path relative to the knowledge root.

string

Git commit author attribution (e.g. agent:my-agent).

string

Lineage tracking (e.g. run:run-249).

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

curl -X PUT 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
  -H "Content-Type: text/markdown" \
  -H "X-Actor: agent:docs-writer" \
  -H "If-Match: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -d '# Authentication (updated)

Revised content here.'

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.

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.

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"}

Get the heading outline for a file.

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

string

required

File path to append to.

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

string

required

Old file path.

string

required

New file path.

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

string

required

Old directory path.

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

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"]
}

REST API

CLI

Directory tree

Read a file

Read a symlink target

Write a file

Delete a file

Bulk write

Upload assets

Table of contents

Append to a file

Rename a file

Rename a directory

Templates

List templates

Read a template

Resolve wiki links

​Directory tree

​Read a file

​Read a symlink target

​Write a file

​Delete a file

​Bulk write

​Upload assets

​Table of contents

​Append to a file

​Rename a file

​Rename a directory

​Templates

​List templates

​Read a template

​Resolve wiki links

Directory tree

Read a file

Read a symlink target

Write a file

Delete a file

Bulk write

Upload assets

Table of contents

Append to a file

Rename a file

Rename a directory

Templates

List templates

Read a template

Resolve wiki links