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

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

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

```json Response theme={null}
{
  "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](https://docs.kiwifs.com/api/overview.md#optimistic-concurrency).

**`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](https://docs.kiwifs.com/api/analytics.md). 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.

```bash Content theme={null}
curl -i 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md'
```

```bash Frontmatter only theme={null}
curl 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md&metadata_only=true'
```

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

```bash Create or replace theme={null}
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
```

```bash Conditional write theme={null}
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"' \
  --data-binary @auth.md
```

```bash Create a symlink theme={null}
curl -X PUT 'http://localhost:3333/api/kiwi/file?path=latest.md' \
  -H "Content-Type: application/x-symlink" \
  -d 'reports/2026-10.md'
```

**path** `string`

Path written.

**etag** `string`

New ETag (also in the `ETag` header).

```json Response theme={null}
{"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](https://docs.kiwifs.com/api/schemas.md) 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.

> [tab] PATCH /file/frontmatter
>
> The body wraps the fields in a `fields` object.
>
> ```bash theme={null}
> 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"}}'
> ```

> [tab] PATCH /file?merge=frontmatter
>
> The body is the field map itself. `merge=frontmatter` is required; other values return `400`.
>
> ```bash theme={null}
> 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.

```json Response theme={null}
{"path": "decisions/adr-12.md", "etag": "d4e5f6a7..."}
```

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

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

```bash theme={null}
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.'
```

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

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

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

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

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

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

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

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

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

```json Response theme={null}
{
  "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](https://docs.kiwifs.com/api/refactor.md).

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

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

```json Response theme={null}
{
  "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`](#sign-a-raw-file-url).

**sig** `string`

Signature from [`GET /raw-sign`](#sign-a-raw-file-url).

```bash theme={null}
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`](#read-a-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.

```bash theme={null}
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).

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

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/toc?path=concepts/auth.md'
```

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

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

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

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/templates'
```

```json Response theme={null}
{
  "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](https://docs.kiwifs.com/guides/templates.md).

## Read a page template

Returns one template's content.

**`GET /template`**

**name** `string` *required*

Template name without `.md`.

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/template?name=runbook'
```

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

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/readlink?path=latest.md'
```

```text Response theme={null}
reports/2026-10.md
```

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

## Related

> [card] [Versioning](https://docs.kiwifs.com/api/versioning.md)
>
> History, diff, and blame for any file.

> [card] [Utilities](https://docs.kiwifs.com/api/utilities.md)
>
> Peek, sections, lint, and more.

> [card] [Drafts](https://docs.kiwifs.com/api/drafts.md)
>
> Stage file changes on a branch before merging.

> [card] [Wiki links](https://docs.kiwifs.com/concepts/wiki-links.md)
>
> How links resolve and get rewritten on rename.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.