Organise documents in folders

A collection can hold thousands of documents. Folders let you keep them in a tree — Policies/HR, Contracts/2026 — then list, filter and move whole branches at once.

You need a key with the editor role to move things; reading the tree needs only read access.

export KOVAC_API_KEY="the-key-you-created"
export KOVAC_BASE="https://your-platform-host"
export COLLECTION_ID="the-collection"

In the console

Open a collection and go to its Documents tab.

• Folder tree. A column beside the table lists All documents, No folder, then your folders with the number of documents in each. Selecting a folder filters the table to it. Include subfolders is a toggle. A breadcrumb above the table shows where you are, and the selection is in the page address, so a link opens the same view. On a narrow screen the tree becomes a folder picker.
• Rename or move a folder. Use Rename or Move… on a folder’s menu. The dialog shows how many documents and chunks will move before you confirm. Nothing is re-processed and it costs nothing in model fees.
• Move documents. Select documents in the table and choose Move to folder….
• Upload into a folder. The upload dialog has a Folder field, prefilled with the folder you have selected. A folder you drop in is created under it, and an archive keeps its own folders.
• A document’s folder. A document’s page shows its folder as a breadcrumb; each part links back to the Documents tab filtered to it.

The rest of this page shows the same things through the API.

What a folder is

A document’s folder is its path metadata, for example Policies/HR. There is no separate folder object: a folder exists while at least one document is in it, and disappears when the last one leaves. A document with no path sits at the root.

The platform also derives a reserved folders key holding every ancestor of the path (["Policies", "Policies/HR"]) on the document and on its chunks. You cannot set it; a value you send for folders is ignored.

Setting a folder

• Upload. Pass path as a form field or in the metadata JSON.
• Bulk import. An archive’s folders become each file’s path. See Bulk import.
• Sidecar files. A path in a sidecar is kept.
• S3 sources. The folders below the source’s own prefix become its path.
• Workflows. The ingest step takes a path.

curl -s -X POST "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/documents" \
  -H "Authorization: Bearer $KOVAC_API_KEY" \
  -F "file=@leave-policy.pdf" \
  -F 'metadata={"path": "Policies/HR"}'

Browsing and filtering

List the tree:

curl -s "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/folders" \
  -H "Authorization: Bearer $KOVAC_API_KEY"

{
  "folders": [
    {"path": "Policies", "name": "Policies", "depth": 1, "direct_count": 2, "total_count": 9},
    {"path": "Policies/HR", "name": "HR", "depth": 2, "direct_count": 7, "total_count": 7}
  ],
  "root_count": 4
}

direct_count is the documents in that folder alone; total_count includes subfolders. Counts cover the documents you can see, active and archived.

Filter the document list with folder:

curl -s "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/documents?folder=Policies&recursive=true" \
  -H "Authorization: Bearer $KOVAC_API_KEY"

recursive defaults to true (the folder and its subfolders). With recursive=false you get only that folder’s own documents, and folder= (empty) with recursive=false lists the root. The filters parameter may not also name folders or path.

Moving and renaming

Renaming a folder is moving it. Move Policies/HR to People/HR:

curl -s -X POST "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/folders:move" \
  -H "Authorization: Bearer $KOVAC_API_KEY" -H "Content-Type: application/json" \
  -d '{"from": "Policies/HR", "to": "People/HR", "dry_run": true}'

With dry_run the response is {"documents": 7, "chunks": 212, "dry_run": true} and nothing changes. Send "dry_run": false to do it. Notes:

• to set to "" moves the folder’s contents to the root.
• Moving a folder into itself is refused with 409.
• Every version of every document you can read moves with its folder, superseded versions included. Restricted documents you cannot read are not moved.
• A 503 means the move did not finish (for example the folder was busy). Repeat the same request to finish it.
• A 409 is also returned when the collection declares its own path metadata field as something other than plain text (an enum, or a field with fixed options), because there path is not a folder.
• Moves are recorded in the audit log.

To move chosen documents instead, use the bulk endpoint with the move action:

curl -s -X POST "$KOVAC_BASE/api/manage/collections/$COLLECTION_ID/documents:bulk" \
  -H "Authorization: Bearer $KOVAC_API_KEY" -H "Content-Type: application/json" \
  -d '{"action": "move", "path": "Archive/2025", "document_ids": ["..."]}'

Cost

A move rewrites metadata on each chunk. Nothing is re-parsed or re-embedded, so it makes no model calls and costs no model fees. A very large move is still real database work, so run a dry run first and move big branches outside busy hours.

Searching a folder from an agent

An agent can be limited to a folder with collection_filters. See Limit an agent to part of a collection.

Limits

• At most 20 levels deep.
• At most 200 characters per folder name, 1024 for the whole path.
• / is the separator. Leading, trailing and repeated slashes and surrounding spaces are dropped.
• Backslashes, control characters, and . or .. segments are refused.