> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeptar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders overview

> Organize knowledge documents into folders with stable IDs.

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

```json theme={null}
{
  "id": "knfldr_…",
  "name": "Marketing",
  "parent_folder_id": null,
  "folder_path": [{ "id": "knfldr_…" }],
  "knowledge_base_id": "knb_…",
  "organization_id": "org_…",
  "created_at": "2026-05-21T11:00:00.000Z",
  "updated_at": "2026-05-21T11:00:00.000Z"
}
```

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