Skip to main content
Folders give you a way to group knowledge documents — naming a tree of topics, brands, projects, or whatever taxonomy fits your team. Documents reference their folder by ID via folder_id; folders reference their parent the same way via parent_folder_id (null at the root).

​
Lifecycle

A folder is created empty. As you upload or create documents, set their folder_id to place them inside. Move documents between folders by PATCH /v1/knowledge-base/documents/:id with a new folder_id. Move sub-folders by PATCH /v1/knowledge-base/folders/:id with a new parent_folder_id. Renaming a folder is non-destructive — the folder’s id is stable. URLs to a folder (e.g. dashboard deep links) survive a rename. Moving a folder is also non-destructive: the folder keeps its id and all its contents.

​
Deleting a folder

A delete takes a mode query parameter:
  • mode=moveContentsToParent (default) — the folder’s children (sub-folders + direct documents) reparent to the deleted folder’s parent. Nothing is lost.
  • mode=deleteContentsRecursive — the entire subtree is removed, documents included. Every document whose folder_id is the deleted folder or any of its descendants is deleted along with its chunks and agent attachments; sub-folder rows cascade-delete.
This is destructive — pick moveContentsToParent from UIs unless the user explicitly confirms they want the contents removed; most file-manager UIs follow that default.

​
Cycle prevention

PATCH rejects moves that would create a cycle (moving a folder into its own subtree). The server returns 400 Bad Request.

​
Sibling-name uniqueness

Two folders can’t share a name under the same parent. Try to create or rename to a colliding name and you get 409 Conflict. The same name is allowed in different sub-trees (e.g. Drafts under both Marketing and Sales).

​
Response shape

folder_path is the root-first ancestor chain by ID (excludes self). A root folder’s folder_path is [].