The KiwiFS REST API gives you full read/write access to your knowledge base over HTTP. Every operation available in the web UI and MCP interface is also available as a REST endpoint.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.
Base URL
/api/kiwi/. In multi-space mode, endpoints include the space name:
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.
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 |
Error handling
All errors return a JSON body with a singleerror field and a standard HTTP status code.
| 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) |
422 | Unprocessable entity (validation error) |
500 | Internal server error |
Health endpoints
Use these endpoints for liveness and readiness probes in container orchestrators.Rate limiting
KiwiFS enforces a built-in rate limit of 100 requests/second per IP with a burst allowance of 200. Health and metrics endpoints are exempt. If you need stricter or more advanced rate limiting, place a reverse proxy (nginx, Caddy, Envoy) in front of the server.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.