> ## 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.

# Spaces admin

> List, inspect, create, and remove knowledge spaces on a running KiwiFS server.

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](https://docs.kiwifs.com/concepts/multi-space.md) for routing.

> [!WARNING]
>
> 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`**

```bash theme={null}
curl -s 'http://localhost:3333/api/spaces'
```

**spaces** `object[]`

**space**

**name** `string`

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

**root** `string`

Folder on disk.

**fileCount** `integer`

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

**sizeBytes** `integer`

Total size of those files.

**lastModified** `string`

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

```json Response theme={null}
{
  "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`**

**name** `string` *required*

Space name.

```bash theme={null}
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`**

```bash theme={null}
curl -s 'http://localhost:3333/api/init-templates'
```

**templates** `object[]`

**template**

**id** `string`

Value to pass as `template`.

**label** `string`

Display name.

**description** `string`

One-line summary.

```json Response theme={null}
{
  "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`**

**name** `string` *required*

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

**root** `string`

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

**template** `string` (default: blank)

Init template ID from [`GET /api/init-templates`](#list-init-templates).

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

```json 201 Created theme={null}
{
  "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`**

**name** `string` *required*

Space name.

```bash theme={null}
curl -X DELETE 'http://localhost:3333/api/spaces/research'
```

```json Response theme={null}
{"deleted": "research"}
```

Returns `404` if the name is unknown.

> [!NOTE]
>
> 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.

## Related

> [card] [Multi-space](https://docs.kiwifs.com/concepts/multi-space.md)
>
> Routing, space selection, and per-space keys.

> [card] [Configuration](https://docs.kiwifs.com/configuration.md#multi-space)
>
> Declare spaces with `[[spaces]]`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.