Skip to main content
POST
/
agents
/
folders
cURL
curl -X POST "https://api.cartesia.ai/agents/folders" \
  -H "X-API-Key: your-api-key" \
  -H "Cartesia-Version: 2025-04-16" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Docs", "parent_id": null}'
{
  "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"

Body

application/json
name
string
required

A human-readable name for the folder. Must be unique among siblings.

Minimum string length: 1
parent_id
string | null

ID of the parent folder. Omit or pass null to create a top-level folder. Folders can be nested at most three levels deep.

Response

Folder created.

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.