Spaces admin

When KiwiFS runs with a space manager, space administration lives at /api/spaces (not under /api/kiwi/).

Per-space file APIs remain at /api/kiwi/... or /api/kiwi/{space}/.... See Multi-space for routing rules.

List spaces

GET /api/spaces

curl -s 'http://localhost:3333/api/spaces'

Response

{
  "spaces": [
    {
      "name": "engineering",
      "root": "/data/eng-wiki",
      "fileCount": 1420,
      "sizeBytes": 45000000,
      "lastModified": "2026-05-02T10:00:00Z"
    }
  ]
}

string

Unique space identifier.

string

Filesystem path for this space.

integer

Number of markdown files.

integer

Total size on disk.

string

Most recent file modification.

Get one space

GET /api/spaces/:name

curl -s 'http://localhost:3333/api/spaces/engineering'

Returns 404 if the name is unknown.

List init templates

GET /api/init-templates

curl -s 'http://localhost:3333/api/init-templates'

Response

[
  {"id": "knowledge", "name": "Knowledge Base", "description": "LLM-maintained KB with schema, episodes, playbook"},
  {"id": "wiki", "name": "Wiki", "description": "Team wiki with decisions, processes, reference docs"},
  {"id": "runbook", "name": "Runbook", "description": "Ops procedures, incidents, postmortems"},
  {"id": "research", "name": "Research", "description": "Notes, experiments, literature"},
  {"id": "tasks", "name": "Tasks", "description": "Task tracking with workflow schema"},
  {"id": "blank", "name": "Blank", "description": "Config only, no starter files"}
]

Use the template id when creating a space with POST /api/spaces.

Create a space

POST /api/spaces
Content-Type: application/json

string

required

Unique identifier for the new space.

string

required

Filesystem path for the space’s knowledge root.

string

Init template to scaffold the space with (e.g. knowledge, wiki, tasks). Use GET /api/init-templates to list available templates.

curl -X POST 'http://localhost:3333/api/spaces' \
  -H 'Content-Type: application/json' \
  -d '{"name":"research","root":"/data/research-wiki","template":"research"}'

Returns 201 with space metadata. Returns 409 if the name already exists.

KiwiFS creates the root directory, initializes git and indexes, and persists the entry to .kiwi/spaces.json.

Delete a space

DELETE /api/spaces/:name

curl -X DELETE 'http://localhost:3333/api/spaces/research'

Response

{ "deleted": "research" }

Removes the space from the manager but does not delete files on disk. Clean up the root directory separately if needed.

Auth

Protect /api/spaces in production. Creation and deletion are administrative operations. Per-space API keys (auth.type = perspace) apply to /api/kiwi routes after routing.

Multi-space

Routing and configuration.

Configuration

[[spaces]] config syntax.

REST API

CLI

List spaces

Get one space

List init templates

Create a space

Delete a space

Auth

Multi-space

Configuration

​List spaces

​Get one space

​List init templates

​Create a space

​Delete a space

​Auth

​Related documentation

Multi-space

Configuration

List spaces

Get one space

List init templates

Create a space

Delete a space

Auth

Related documentation