> ## 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.
# API overview
> Base URL, authentication, common headers, and error handling for the KiwiFS REST API.
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](/api/spaces). See [Multi-space](/concepts/multi-space).
## Authentication
Configure the auth type in `.kiwi/config.toml` under `[auth] type`.
No authentication required. Suitable for local development and trusted networks.
```bash theme={null}
curl http://localhost:3333/api/kiwi/tree
```
Pass a global API key via the `Authorization: Bearer` header.
```bash theme={null}
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.
```bash theme={null}
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.
```bash theme={null}
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.
```json theme={null}
{"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.
```bash Health theme={null}
curl http://localhost:3333/health
```
```bash Liveness theme={null}
curl http://localhost:3333/healthz
```
```bash Readiness theme={null}
curl http://localhost:3333/readyz
```
All three return JSON. **`/health`** and **`/healthz`** always respond with **`200`** when the process is up:
```json theme={null}
{"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`**:
```json theme={null}
{
"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
```bash theme={null}
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](https://docs.kiwifs.com/llms.txt) |
| **llms-full.txt** | [docs.kiwifs.com/llms-full.txt](https://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
Read, write, and delete files.
Full-text and vector search.
Git history, diff, and blame.
Structured queries and knowledge graph.
Staging branches for agents.
Saved DQL bases.
Lint, timeline, graph helpers, rules, audit.