> ## 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, create, and remove knowledge spaces on a multi-space KiwiFS server.

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

<Info>
  Per-space file APIs remain at `/api/kiwi/...` or `/api/kiwi/{space}/...`. See [Multi-space](/concepts/multi-space) for routing rules.
</Info>

## List spaces

```http theme={null}
GET /api/spaces
```

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

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

<ResponseField name="spaces[].name" type="string">Unique space identifier.</ResponseField>
<ResponseField name="spaces[].root" type="string">Filesystem path for this space.</ResponseField>
<ResponseField name="spaces[].fileCount" type="integer">Number of markdown files.</ResponseField>
<ResponseField name="spaces[].sizeBytes" type="integer">Total size on disk.</ResponseField>
<ResponseField name="spaces[].lastModified" type="string">Most recent file modification.</ResponseField>

## Get one space

```http theme={null}
GET /api/spaces/:name
```

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

Returns `404` if the name is unknown.

## List init templates

```http theme={null}
GET /api/init-templates
```

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

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

```http theme={null}
POST /api/spaces
Content-Type: application/json
```

<ParamField body="name" type="string" required>
  Unique identifier for the new space.
</ParamField>

<ParamField body="root" type="string" required>
  Filesystem path for the space's knowledge root.
</ParamField>

<ParamField body="template" type="string">
  Init template to scaffold the space with (e.g. `knowledge`, `wiki`, `tasks`). Use `GET /api/init-templates` to list available templates.
</ParamField>

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

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

## Delete a space

```http theme={null}
DELETE /api/spaces/:name
```

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

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

<Warning>
  Removes the space from the manager but does **not** delete files on disk. Clean up the `root` directory separately if needed.
</Warning>

## Auth

<Tip>
  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.
</Tip>

## Related documentation

<CardGroup cols={2}>
  <Card title="Multi-space" icon="layer-group" href="/concepts/multi-space">
    Routing and configuration.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration#multi-space">
    `[[spaces]]` config syntax.
  </Card>
</CardGroup>