# Folders endpoints Folders for people and records: list, create, rename, move and delete them, and move items into one. Paths are relative to https://kleiobase.com/api/v1. Request and response schemas are in the OpenAPI document at https://kleiobase.com/api/v1/openapi.json. ## List folders `GET /workspaces/{workspace_id}/folders` A flat list; build the tree from parent_id. People and records have separate folder trees. Not paginated: next_cursor is always null. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `kind` (query, optional): Only folders of people or of records. Responses: - `200`: Folders. - `401`: Missing, malformed, unknown or revoked API key. - `403`: The account has no paid plan. - `404`: The workspace does not exist or is not visible to this key's owner. - `422`: Invalid kind. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Create a folder `POST /workspaces/{workspace_id}/folders` Folders nest up to 10 levels; a workspace has at most 500. Names are unique among siblings, ignoring case. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409. Takes a request body; see the OpenAPI document for its schema. Responses: - `201`: The created folder. - `401`: Missing, malformed, unknown or revoked API key. - `403`: The account has no paid plan, or the key is read-only (a read_write key is required). - `404`: The workspace does not exist or is not visible to this key's owner. Also: parent_id is not a folder in this workspace. - `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: a sibling folder already has this name. - `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid name, a parent of the other kind, too deep, or the folder limit is reached. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Rename or move a folder `PATCH /workspaces/{workspace_id}/folders/{folder_id}` parent_id null moves it to the top level. The counts in the response are 0; GET folders has them. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `folder_id` (path, required): The folder id. - `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409. Takes a request body; see the OpenAPI document for its schema. Responses: - `200`: The folder. - `401`: Missing, malformed, unknown or revoked API key. - `403`: The account has no paid plan, or the key is read-only (a read_write key is required). - `404`: The workspace does not exist or is not visible to this key's owner. Also: The folder or parent_id is not a folder in this workspace. - `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: a sibling folder already has this name. - `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, a parent of the other kind, too deep, or a move into the folder itself or one of its own subfolders. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Delete a folder `DELETE /workspaces/{workspace_id}/folders/{folder_id}` Only the folder is deleted: its subfolders and items move up into its parent (or to the top level). Replays of an Idempotency-Key return the original body and request_id; headers are not replayed. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `folder_id` (path, required): The folder id. - `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409. Responses: - `200`: Deleted. - `401`: Missing, malformed, unknown or revoked API key. - `403`: The account has no paid plan, or the key is read-only (a read_write key is required). - `404`: The workspace does not exist or is not visible to this key's owner. Also: The folder is not in this workspace. - `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. - `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Move items into a folder `POST /workspaces/{workspace_id}/folders/{folder_id}/items` 1 to 100 ids of kind. An item is in at most one folder, so it leaves its current folder. All or nothing: every id must be a person or record of that kind in this workspace and not in Trash. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `folder_id` (path, required): The folder id. - `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409. Takes a request body; see the OpenAPI document for its schema. Responses: - `200`: Moved. - `401`: Missing, malformed, unknown or revoked API key. - `403`: The account has no paid plan, or the key is read-only (a read_write key is required). - `404`: The workspace does not exist or is not visible to this key's owner. Also: The folder, or one of the items, is not in this workspace (or the item is in Trash). - `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. - `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, or kind does not match the folder. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. ## Move items to the top level `POST /workspaces/{workspace_id}/folders/unfile` Takes 1 to 100 people or records out of their folder, as Top level in the app's Move to folder. An item already at the top level stays there. All or nothing: every id must be a person or record of that kind in this workspace and not in Trash. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed. Parameters: - `workspace_id` (path, required): The workspace (project) id. - `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409. Takes a request body; see the OpenAPI document for its schema. Responses: - `200`: Moved. - `401`: Missing, malformed, unknown or revoked API key. - `403`: The account has no paid plan, or the key is read-only (a read_write key is required). - `404`: The workspace does not exist or is not visible to this key's owner. Also: One of the items is not in this workspace (or is in Trash). - `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. - `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body. - `429`: Rate limit exceeded. Wait the number of seconds in Retry-After. - `500`: Unexpected error. Retry later and quote request_id if it persists. Canonical: https://kleiobase.com/developers/docs/reference/folders