Skip to main content
PATCH
/
agents
/
folders
/
{id}
Attach to agents
curl -X PATCH "https://api.cartesia.ai/agents/folders/folder_abc" \
  -H "X-API-Key: your-api-key" \
  -H "Cartesia-Version: 2025-04-16" \
  -H "Content-Type: application/json" \
  -d '{"agents": [{"id": "agent_abc"}, {"id": "agent_def"}]}'
{
  "id": "<string>",
  "parent_id": "<string>",
  "name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "agents": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "documents": [
    {
      "id": "<string>",
      "name": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

Authorization
string
header
required

Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.

Headers

Cartesia-Version
enum<string>
required

API version header.

Available options:
2026-03-01
Example:

"2026-03-01"

Path Parameters

id
string
required

The ID of the folder.

Body

application/json

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.

Minimum string length: 1
parent_id
string | null

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.

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.

Response

Folder updated.

id
string
required

The ID of the folder.

parent_id
string | null
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 · object[]
required

Agents that have access to this folder.

documents
FolderDocumentSummary · object[]
required

Documents inside this folder.