API overview - KiwiFS — Markdown filesystem for agents and teams

The KiwiFS REST API gives you full read/write access to your markdown filesystem over HTTP. Every operation available in the web UI and MCP interface is also available as a REST endpoint.

Base URL

http://localhost:3333/api/kiwi

All endpoints are prefixed with /api/kiwi/. In multi-space mode, endpoints include the space name:

/api/kiwi/{space}/file?path=concepts/auth.md

You can also keep the path /api/kiwi/... (no {space} segment) and send the header X-Kiwi-Space: engineering so reverse proxies or the FUSE client can dispatch to a configured space without changing URL shapes. Space administration (GET/POST/DELETE /api/spaces) is documented in Spaces API. See Multi-space.

Authentication

Configure the auth type in .kiwi/config.toml under [auth] type.

none (default)
apikey
perspace
oidc

No authentication required. Suitable for local development and trusted networks.

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

Pass a global API key via the Authorization: Bearer header.

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

Each space has its own API key. Use the same header format as apikey mode.

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

OpenID Connect authentication. Pass a JWT Bearer token issued by your identity provider.

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

Common headers

Header	Purpose	Example
`X-Actor`	Attribution for the git commit author	`agent:my-agent`
`X-Provenance`	Lineage tracking for audit trails	`run:run-249`
`If-Match`	Optimistic locking using ETag (git blob SHA)	`a1b2c3d4e5f6`
`Content-Type`	Body format	`text/markdown` or `application/json`
`X-Kiwi-Space`	Target space when using the shared `/api/kiwi/...` prefix	`engineering`
`X-Space`	Recorded on audit log entries when present	`engineering`

Always set X-Actor on write operations. KiwiFS uses this value as the git commit author, making it easy to trace which agent or user made each change.

Error handling

All errors return a JSON body with a single error field and a standard HTTP status code.

{"error": "file not found: concepts/missing.md"}

Status code	Meaning
`400`	Bad request (malformed query, missing required field)
`401`	Unauthorized (missing or invalid credentials)
`404`	Resource not found
`409`	Conflict (ETag mismatch on optimistic lock, or draft merge failure)
`422`	Unprocessable entity (validation error)
`501`	Not implemented (optional subsystem disabled, for example drafts)
`503`	Service unavailable (claims, vector search, Dataview executor, and similar optional services)
`500`	Internal server error

Health endpoints

Use these endpoints for liveness and readiness probes in container orchestrators.

curl http://localhost:3333/health

All three return JSON. /health and /healthz always respond with 200 when the process is up:

{"status": "ok"}

/readyz checks storage and optional protocol health (NFS, S3, WebDAV). When storage is unreachable or an enabled protocol is unhealthy, it returns 503:

{
  "status": "ok",
  "protocols": {
    "nfs": { "enabled": true, "healthy": true, "port": 2049 },
    "s3": { "enabled": false },
    "webdav": { "enabled": true, "healthy": false, "error": "listen tcp :3335: bind: address already in use" }
  }
}

Use /readyz for Kubernetes readiness probes when optional protocols are enabled.

Prometheus metrics

curl http://localhost:3333/metrics

Exposes Prometheus-formatted metrics including request counts, latencies, and active connections. Use this to wire KiwiFS into your monitoring stack (Grafana, Datadog, etc.).

Rate limiting

When [server.rate_limit] in .kiwi/config.toml sets requests_per_minute greater than zero, KiwiFS applies a token-bucket limiter keyed by Bearer token hash (or client IP when anonymous). Health, readiness, and metrics routes skip the limiter. If requests_per_minute is not configured, no built-in HTTP rate limit is applied — use a reverse proxy (nginx, Caddy, Envoy) for strict quotas or geographic rules.

Machine-readable references

KiwiFS provides machine-readable documentation for agents and integrations:

Resource	URL
llms.txt	docs.kiwifs.com/llms.txt
llms-full.txt	docs.kiwifs.com/llms-full.txt
OpenAPI spec	`GET /api/openapi.json` on any KiwiFS instance
Swagger UI	`GET /api/docs` on any KiwiFS instance

Point your agent at llms-full.txt for a single-file reference of every REST endpoint, MCP tool, and CLI command. The OpenAPI spec at /api/openapi.json is machine-parseable for code generation.

Next steps

File operations

Read, write, and delete files.

Search

Full-text and vector search.

Versioning

Git history, diff, and blame.

Metadata

Structured queries and knowledge graph.

Drafts

Staging branches for agents.

Views

Saved DQL bases.

Utilities

Lint, timeline, graph helpers, rules, audit.

​Base URL

​Authentication

​Common headers

​Error handling

​Health endpoints

​Prometheus metrics

​Rate limiting

​Machine-readable references

​Next steps

File operations

Search

Versioning

Metadata

Drafts

Views

Utilities

Base URL

Authentication

Common headers

Error handling

Health endpoints

Prometheus metrics

Rate limiting

Machine-readable references

Next steps