API overview

Base URL, authentication, headers, concurrency, errors, and health endpoints for the KiwiFS REST API.

The KiwiFS REST API gives you read and write access to a markdown filesystem over HTTP. Everything the web UI does goes through these endpoints, and most MCP tools have a REST equivalent.

Base URL

http://localhost:3333/api/kiwi

Every knowledge endpoint lives under /api/kiwi/. Health, metrics, OpenAPI, raw files, llms.txt, and MCP sit at the server root.

Selecting a space

A server can host several spaces. Pick one in either of two ways:

Path segment

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

The header takes precedence over the path. An unknown name in X-Kiwi-Space returns 404 instead of falling back to another space. Requests with neither go to the primary space. Space administration (/api/spaces) is covered in Spaces admin.

Authentication

Set the mode with [auth] type in .kiwi/config.toml. Every mode except none expects an Authorization: Bearer <token> header on /api/kiwi/* requests.

none (default)

No credentials. Use this for local development and trusted networks.

curl http://localhost:3333/api/kiwi/tree

apikey

One shared key from auth.api_key. Values like ${KIWI_API_KEY} are expanded from the environment.

.kiwi/config.toml

[auth]
type = "apikey"
api_key = "${KIWI_API_KEY}"

curl http://localhost:3333/api/kiwi/tree \
  -H "Authorization: Bearer $KIWI_API_KEY"

perspace

A list of keys, each bound to an actor and optionally to a space, a scope, and a path prefix.

.kiwi/config.toml

[auth]
type = "perspace"

[[auth.api_keys]]
key = "${ENG_KEY}"
space = "engineering"
actor = "agent:eng-bot"
scope = "write"        # read | write | admin (default admin)
prefix = "runbooks/"   # optional path restriction

curl http://localhost:3333/api/kiwi/engineering/tree \
  -H "Authorization: Bearer $ENG_KEY"

A read key can only send GET and HEAD. A key with space or prefix gets 403 for any ?path= (or /bulk file path) outside that scope. The key’s actor replaces whatever X-Actor the client sends.

oidc

A JWT from your identity provider, verified against auth.oidc.issuer and auth.oidc.client_id. The token’s email claim (or sub) becomes the actor.

curl http://localhost:3333/api/kiwi/tree \
  -H "Authorization: Bearer eyJhbGciOi..."

Send SIGHUP to the server process to reload [auth] from disk without a restart. See Auth tokens for key management.

What auth covers

Route	When auth is on
/api/kiwi/*	Requires a valid bearer token.
GET /api/kiwi/* with [space] visibility = "public"	Open to anonymous reads. Writes still need a token.
GET /file, /peek, /section with visibility = "unlisted"	Open when ?path= is set. Listing, tree, and search still need a token.
/raw/*	Needs a bearer token, a signed URL from GET /raw-sign, or a target that is already public.
/llms.txt, /llms-full.txt	Stay reachable without a token, but only list pages marked public or published (unless the space is public).
/api/kiwi/public/*, /p/*	Always anonymous. See Publish.
/health, /healthz, /readyz, /metrics, /api/docs, /api/openapi.json	Always anonymous.
/api/spaces, /api/init-templates	Not checked by KiwiFS. Protect them at your proxy.

/mcp only checks credentials in apikey mode, using the same key. With perspace or oidc, put /mcp behind your proxy’s auth or disable it.

Request headers

Header	Purpose	Example
Authorization	Bearer token for any auth mode other than none	Bearer kiwi_sk_abc123
X-Actor	Commit author for writes. Ignored when perspace or oidc auth sets the actor. Defaults to anonymous.	agent:my-agent
X-Provenance	Adds a derived-from entry (type, id, date, actor) to the page’s frontmatter on PUT /file and POST /bulk. Format is type:id.	run:run-249
If-Match	ETag the file must still have for the write to succeed	"a1b2c3d4..."
If-None-Match / If-Modified-Since	Conditional read on GET /file; returns 304 when unchanged	"a1b2c3d4..."
X-Field-Manager	Names the owner of frontmatter keys set by a frontmatter patch	agent:triage
X-Kiwi-Space	Target space on the shared /api/kiwi/... prefix	engineering
X-Kiwi-Source	Source label recorded with page-view analytics on GET /file	slack-bot

Set X-Actor on every write when you use none or apikey auth. It becomes the git commit author, so you can trace which agent changed what with blame.

Optimistic concurrency

Every file read returns an ETag header: the quoted git blob hash of the content. Writes return the new ETag in both the ETag header and the JSON etag field.

Send that value back in If-Match to make a write conditional. If someone else changed the file since your read, the write is rejected with 409 and nothing is written.

# 1. Read and capture the ETag
ETAG=$(curl -sI 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
  | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r')

# 2. Write only if the file is unchanged
curl -X PUT 'http://localhost:3333/api/kiwi/file?path=concepts/auth.md' \
  -H "X-Actor: agent:updater" \
  -H "If-Match: $ETAG" \
  --data-binary @auth.md

409 Conflict

{"error": "file modified since last read — re-fetch and retry"}

If-Match works on PUT /file, PATCH /file, and PATCH /file/frontmatter. For POST /bulk, set if_match per file; one mismatch fails the whole batch. Quotes around the ETag are optional.

Errors

Errors return a JSON body with a single error field. Server-side failures (5xx) return a generic message; details go to the server log.

{"error": "path is required"}

Status	Meaning
400	Missing or invalid parameter, malformed JSON, or a path outside the knowledge root
401	Missing or invalid credentials
403	Token scope does not allow this method or path, or an invalid /raw signature
404	File, version, draft, view, or space not found
409	ETag mismatch, workflow transition denied, append-only file, frontmatter field owned by another manager, rename target exists, or draft merge conflict
413	Body too large (32 MB per file write, 110 MB per request)
415	Uploaded asset type is not in the allowlist
422	Write failed schema validation
429	Rate limit exceeded. Includes Retry-After: 60.
501	Optional feature is off (for example drafts) or unsupported by the versioning backend (blame, word diff)
503	Optional service unavailable (Dataview executor, vector search, claims, SSE subscriber cap)
500	Internal error

Pagination

There is no global pagination envelope. Endpoints that return long lists take their own parameters:

Style	Endpoints	Parameters
Offset	GET /search, GET /query, GET /views/:name/execute, GET /timeline	limit, offset; DQL results include total and has_more
Cursor	GET /changes	since (a commit hash) and limit; pass the returned last_seq as the next since

Rate limiting

Rate limiting is off unless you set requests_per_minute above zero:

.kiwi/config.toml

[server.rate_limit]
requests_per_minute = 300
burst_size = 50   # default 50

KiwiFS then applies a token bucket per bearer token (hashed) or per client IP for anonymous requests. /health, /healthz, /readyz, and /metrics are never limited. Over the limit, requests get 429 with Retry-After: 60.

Health and metrics

Use these unauthenticated endpoints for container probes and monitoring.

Liveness

curl http://localhost:3333/healthz

GET /health always returns {"status": "ok"}. GET /healthz adds uptime and version:

{"status": "ok", "uptime": "3h12m5s", "version": "0.19.78"}

GET /readyz checks storage and any enabled protocol servers (NFS, S3, WebDAV). It returns 200 with status: "ready", or 503 with status set to storage-unreachable or protocol-unhealthy.

503 Service Unavailable

{
  "status": "protocol-unhealthy",
  "protocols": {
    "nfs": {"enabled": true, "healthy": true, "port": 2049, "endpoint": "0.0.0.0:2049"},
    "webdav": {"enabled": true, "port": 3335, "endpoint": "0.0.0.0:3335", "error": "dial tcp 0.0.0.0:3335: connect: connection refused"}
  }
}

GET /metrics returns Prometheus text with kiwi_build_info, kiwi_uptime_seconds, kiwi_sse_subscribers, and kiwi_janitor_issues (after the first janitor scan). It does not export per-request counters; collect those at your proxy.

Machine-readable references

Resource	Where
OpenAPI spec	GET /api/openapi.json on any KiwiFS server
Swagger UI	GET /api/docs on any KiwiFS server
Workspace llms.txt	GET /llms.txt: every page, grouped by folder, with links and summaries
Workspace llms-full.txt	GET /llms-full.txt: every page’s markdown concatenated, capped at 5 MiB with a truncation notice
These docs	docs.kiwifs.com/llms.txt and llms-full.txt

Next steps

Files

Read, write, rename, and upload.

Search

Full-text, hybrid, and semantic search.

Versioning

History, diff, blame, and the change feed.

Metadata and graph

DQL queries and the link graph.

Drafts

Staging branches for agents.

Utilities

Lint, timeline, rules, audit.