Workspaces

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

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

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

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

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.

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