# Workspaces

Every resource lives under a workspace id. How to find yours, create, rename, archive and restore workspaces, and what archived workspaces allow.


A workspace is a separate knowledge base inside your account. People, families, records and everything else belong to exactly one workspace, so every resource path starts with `/workspaces/{workspace_id}`.

## List your workspaces

```bash
curl https://kleiobase.com/api/v1/workspaces \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

This returns the workspaces you own. The list is not paginated, so `next_cursor` is always `null`. Each entry has `id`, `name`, `is_default`, `archived` and `created_at`. There are no record or people counts.

## Use the id in the path

```bash
curl https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/records \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

The workspace you have open in the KleioBase app does not matter. The id in the path decides where a request reads and writes.

## Unknown workspaces return 404

If the id does not exist, or belongs to someone else, you get `404 not_found`. The two cases look identical on purpose.

## Create and rename a workspace

```bash
curl -X POST https://kleiobase.com/api/v1/workspaces \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: create-workspace-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Smith family"}'
```

You get `201` with the new workspace. Names are 1 to 80 characters after trimming spaces. Your plan limits how many active workspaces you can have. When you reach it, you get `403 forbidden` with `limit`, `used` and `plan` in `details`. Archived workspaces do not count.

To rename one, send `PATCH /workspaces/{workspace_id}` with `{"name": "..."}`. This also works on an archived workspace.

## Archive and restore

```bash
curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/archive \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: archive-workspace-1"
```

Archiving deletes nothing. It makes the workspace read-only and frees its place in your plan's workspace limit. The default workspace cannot be archived (`409 conflict`). If the workspace you archive is the one open in the app, the app switches to your default workspace, exactly as when you archive it there.

`POST /workspaces/{workspace_id}/restore` brings it back. Your plan's workspace limit is checked again, so a restore can return `403 forbidden`. Archiving an archived workspace, or restoring a live one, changes nothing and returns `200`.

Workspaces cannot be deleted through the API. Deleting one needs the email confirmation in the app. See the [Workspaces help article](/docs/workspaces).

## Archived workspaces are read-only

You can read an archived workspace, but any write to it returns `409 conflict`. Restore it with `POST .../restore` (or in the app, under **Settings > Workspaces**) to write again. Renaming, archiving, restoring and starting a [GEDCOM export](/developers/docs/gedcom) still work on an archived workspace.

## Limits are shared

Plan limits such as the number of people and monthly credits belong to your account, not to a workspace. They are shared across all your workspaces.

Canonical: https://kleiobase.com/developers/docs/workspaces