---
title: "Update Folder"
method: PATCH
path: "/agents/folders/{id}"
tags: ["Folders"]
---

# Update Folder

`PATCH /agents/folders/{id}`

Update a [knowledge base](/line/knowledge-base) folder's name, parent, documents, or agents

## Path parameters

- `id` string, required

## Headers

- `Cartesia-Version` '2026-03-01', date, required

## Request body

- UpdateFolderBody — Fields to update on a folder. All fields are optional. Passing `documents` or `agents` replaces the full set — send an empty array to detach all documents or agents.
  - `name` string — A new name for the folder. Must be unique among siblings.
  - `parent_id` string, nullable — Move the folder under a new parent, or `null` to move it to the top level. Cannot create a circular reference.
  - `documents` object[] — The complete set of documents that should be in this folder. Documents not in the list are deleted. Pass an empty array to delete all documents in the folder.
    - `id` string, required
  - `agents` object[] — The complete set of agents that have access to this folder. Agents not in the list have their access revoked. Pass an empty array to revoke access for all agents.
    - `id` string, required

## Response `200`

Folder updated.

- FolderResponse
  - `id` string, required — The ID of the folder.
  - `parent_id` string, nullable, required — The ID of the parent folder, or `null` for top-level folders.
  - `name` string, required — The folder's name.
  - `created_at` string, date-time, required — When the folder was created.
  - `agents` FolderAgentSummary[], required — Agents that have access to this folder.
    - `id` string, required — The ID of the agent.
    - `name` string, required — The name of the agent.
  - `documents` FolderDocumentSummary[], required — Documents inside this folder.
    - `id` string, required — The ID of the document.
    - `name` string, nullable, required — The document's display name, or `null` if unnamed.
    - `created_at` string, date-time, required — When the document was uploaded.
    - `metadata` object, required — User-defined string-keyed metadata.

## Other responses

- `400` — Bad request. Possible reasons: a folder with the same name already exists in the target location (`error_code: kb_folder_duplicate_name`); nesting would exceed the three-level limit (`error_code: kb_folder_max_depth`); attempting to move a folder under itself or one of its descendants (`error_code: kb_folder_circular_reference`); one or more `documents[].id` values do not exist or are not owned by you (`error_code: kb_document_not_owned`); or one or more `agents[].id` values do not exist or are not owned by you (`error_code: kb_agent_not_found`).
- `404` — Folder not found (`error_code: kb_folder_not_found`) or parent folder not found (`error_code: kb_folder_parent_not_found`).

---

[API](https://skmtc.net/cartesia/apis/cartesia-api.md) · [All operations](https://skmtc.net/cartesia/apis/cartesia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cartesia/cartesia-api/versions/8910812440d3/schema)