# Folders and tags

Organise people and records with folders and tags, and filter lists by them.


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:

```bash
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:

```bash
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

```bash
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:

```bash
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](/developers/docs/trash).

## Filter lists

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

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