Spaces admin

Every KiwiFS server runs a space manager, so these routes exist even when you serve a single folder. They live at /api/spaces and /api/init-templates, outside /api/kiwi/. Per-space file APIs stay at /api/kiwi/... or /api/kiwi/{space}/...; see Multi-space for routing.

KiwiFS does not apply [auth] to /api/spaces or /api/init-templates. Anyone who can reach the port can create and delete spaces. Block or authenticate these paths at your reverse proxy in production.

List spaces

Returns every registered space with file counts and size. GET /api/spaces

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

object[]

Show space

string

Space name used in /api/kiwi/{space}/... and X-Kiwi-Space.

string

Folder on disk.

integer

Files under the root, excluding dot-directories such as .kiwi and .git.

integer

Total size of those files.

string

Most recent file modification time. Omitted for an empty space.

Response

{
  "spaces": [
    {
      "name": "default",
      "root": "/data/knowledge",
      "fileCount": 1420,
      "lastModified": "2026-10-02T10:00:00Z",
      "sizeBytes": 45000000
    }
  ]
}

The primary space is named default unless [space] name is set in its config.

Get a space

Returns one space’s metadata. GET /api/spaces/:name

string

required

Space name.

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

Returns the same object as one entry of spaces above, or 404 if the name is unknown.

List init templates

Returns the scaffolds you can pass as template when creating a space. GET /api/init-templates

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

object[]

Show template

string

Value to pass as template.

string

Display name.

string

One-line summary.

Response

{
  "templates": [
    {"id": "adr", "label": "Architecture Decision Records", "description": "Architecture Decision Records with MADR format, status workflow, and JSON Schema"},
    {"id": "kb", "label": "Knowledge Base", "description": "Curated knowledge base with article types, verification workflow, and freshness enforcement"},
    {"id": "memory", "label": "Memory", "description": "Agent memory with episodic/semantic classification, consolidation, and retrieval"},
    {"id": "blank", "label": "Blank", "description": "Empty workspace with Kiwi config only"}
  ]
}

The full set is adr, cms, data, kb, log, memory, prompt, research, runbook, tasks, wiki, and blank, sorted by label with blank last.

Create a space

Scaffolds a folder from a template, builds its index and git repo, and registers it. POST /api/spaces

string

required

Unique space name. Cannot contain /, \, spaces, or dots.

string

Folder for the space. Defaults to .spaces/{name} inside the primary space’s root, which hides it from the primary space’s tree.

string

default:"blank"

Init template ID from GET /api/init-templates.

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

201 Created

{
  "name": "research",
  "root": "/data/knowledge/.spaces/research",
  "fileCount": 9,
  "lastModified": "2026-10-19T09:30:00Z",
  "sizeBytes": 18234
}

Returns 409 if the name already exists, and 400 for an invalid name or template. The space is saved to .kiwi/spaces.json in the primary space and restored on restart.

Delete a space

Unregisters a space and moves its folder aside. DELETE /api/spaces/:name

string

required

Space name.

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

Response

{"deleted": "research"}

Returns 404 if the name is unknown.

Deletion is a soft delete. KiwiFS renames the root to {root}.deleted-{timestamp} (for example research.deleted-20261019T093000), so you can recover the files or remove them yourself.

Multi-space

Routing, space selection, and per-space keys.

Configuration

Declare spaces with [[spaces]].

REST API

CLI

List spaces

Get a space

List init templates

Create a space

Delete a space

Multi-space

Configuration

​List spaces

​Get a space

​List init templates

​Create a space

​Delete a space

​Related

Multi-space

Configuration

List spaces

Get a space

List init templates

Create a space

Delete a space

Related