Folders and tags

Folders and tags work as they do in the app. People and records have separate folder trees. Tags are shared by both.

Folders

List them, optionally only one kind:

curl "https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/folders?kind=people" \
  -H "Authorization: Bearer kb_live_YOUR_KEY"

The list is flat. Build the tree from each folder's parent_id (null at the top level).

Create one:

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/folders \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: create-folder-1" \
  -H "Content-Type: application/json" \
  -d '{"kind": "people", "name": "Novak line", "parent_id": null}'

• Names are 1 to 100 characters and unique among siblings, ignoring case. A clash is 409 conflict.
• Folders nest up to 10 levels, and a workspace has at most 500.
• PATCH .../folders/{folder_id} renames a folder or moves it (parent_id: null moves it to the top level).
• DELETE .../folders/{folder_id} deletes only the folder. Its subfolders and items move up into its parent.

Move items into a folder

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/folders/FOLDER_ID/items \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: file-people-1" \
  -H "Content-Type: application/json" \
  -d '{"kind": "people", "ids": ["PERSON_ID_1", "PERSON_ID_2"]}'

An item is in at most one folder, so it leaves its current one. To take items out of every folder (the app's Top level), send the same body to POST .../folders/unfile.

Tags

• GET .../tags lists them by name, with how many people and records carry each.
• POST .../tags creates one: {"name": "Emigrated", "color": "#4f46e5"}. Names are 1 to 50 characters and unique in the workspace, ignoring case. A workspace has at most 200 tags.
• PATCH .../tags/{tag_id} renames or recolours a tag. DELETE removes it from everything that had it.

Add or remove tags on many items at once:

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/tags/apply \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: tag-people-1" \
  -H "Content-Type: application/json" \
  -d '{"kind": "people", "ids": ["PERSON_ID"], "add": ["TAG_ID"]}'

Up to 100 items and 50 tags in each of add and remove. Adding a tag an item already has changes nothing.

Moving items and applying tags are all or nothing: if any item or tag is not in the workspace, or an item is in the Trash, you get 404 and nothing changes. See Trash and bulk actions.

Filter lists

GET .../people and GET .../records take ?folder_id= and ?tag_id=, and every person and record carries folder_id and tag_ids.