Manage Folders

The Folders API provides endpoints for organizing chats and other resources into a hierarchical folder structure.

List Folders

GET · endpoint

Retrieve all folders for the authenticated user

Authorization

Requires ENABLE_FOLDERS feature flag enabled and user permission features.folders or admin role.

Response

id · string · required

Unique identifier for the folder

name · string · required

Name of the folder

parent_id · string

ID of the parent folder (null for root folders)

is_expanded · boolean

Whether the folder is expanded in the UI

data · object

Additional folder data including files and collections

Example Request

cURL

curl -X GET "https://your-domain.com/api/folders" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

200

[
  {
    "id": "folder_123",
    "name": "Work Projects",
    "parent_id": null,
    "is_expanded": true,
    "data": {
      "files": []
    }
  },
  {
    "id": "folder_456",
    "name": "Client A",
    "parent_id": "folder_123",
    "is_expanded": false,
    "data": {}
  }
]

---

Create Folder

POST · endpoint

Create a new folder

Request Body

name · string · required

Name of the folder to create

parent_id · string

ID of the parent folder (omit for root folder)

Example Request

cURL

curl -X POST "https://your-domain.com/api/folders" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Project",
    "parent_id": "folder_123"
  }'

Example Response

200

{
  "id": "folder_789",
  "user_id": "user_123",
  "name": "New Project",
  "parent_id": "folder_123",
  "is_expanded": false,
  "data": {},
  "created_at": 1709395200,
  "updated_at": 1709395200
}

400 Bad Request

{
  "detail": "Folder already exists"
}

---

Get Folder by ID

GET · endpoint

Retrieve a specific folder by ID

Path Parameters

id · string · required

Unique identifier of the folder

Example Request

cURL

curl -X GET "https://your-domain.com/api/folders/folder_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

200

{
  "id": "folder_123",
  "user_id": "user_123",
  "name": "Work Projects",
  "parent_id": null,
  "is_expanded": true,
  "data": {
    "files": []
  },
  "created_at": 1709308800,
  "updated_at": 1709395200
}

404 Not Found

{
  "detail": "Not Found"
}

---

Update Folder

POST · endpoint

Update folder name or data

Path Parameters

id · string · required

Unique identifier of the folder to update

Request Body

name · string

Updated name for the folder

data · object

Updated folder data

Example Request

cURL

curl -X POST "https://your-domain.com/api/folders/folder_123/update" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work Projects (Updated)"
  }'

Example Response

200

{
  "id": "folder_123",
  "user_id": "user_123",
  "name": "Work Projects (Updated)",
  "parent_id": null,
  "is_expanded": true,
  "data": {},
  "created_at": 1709308800,
  "updated_at": 1709395500
}

400 Bad Request

{
  "detail": "Folder already exists"
}

---

Update Folder Parent

POST · endpoint

Move folder to a different parent folder

Path Parameters

id · string · required

Unique identifier of the folder to move

Request Body

parent_id · string

ID of the new parent folder (null to move to root)

Example Request

cURL

curl -X POST "https://your-domain.com/api/folders/folder_456/update/parent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "folder_789"
  }'

Example Response

200

{
  "id": "folder_456",
  "user_id": "user_123",
  "name": "Client A",
  "parent_id": "folder_789",
  "is_expanded": false,
  "data": {},
  "created_at": 1709308800,
  "updated_at": 1709395600
}

400 Bad Request

{
  "detail": "Folder already exists"
}

---

Update Folder Expanded State

POST · endpoint

Update whether the folder is expanded in the UI

Path Parameters

id · string · required

Unique identifier of the folder

Request Body

is_expanded · boolean · required

Whether the folder should be expanded

Example Request

cURL

curl -X POST "https://your-domain.com/api/folders/folder_123/update/expanded" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_expanded": true
  }'

Example Response

200

{
  "id": "folder_123",
  "user_id": "user_123",
  "name": "Work Projects",
  "parent_id": null,
  "is_expanded": true,
  "data": {},
  "created_at": 1709308800,
  "updated_at": 1709395700
}

---

Delete Folder

DELETE · endpoint

Delete a folder and optionally its contents

Path Parameters

id · string · required

Unique identifier of the folder to delete

Query Parameters

delete_contents · boolean

Whether to delete chats in the folder (default: true). If false, chats are moved to root.

Authorization

If the folder contains chats, requires chat.delete permission or admin role.

Example Request

cURL

curl -X DELETE "https://your-domain.com/api/folders/folder_123?delete_contents=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

200

true

403 Forbidden

{
  "detail": "Access prohibited"
}

404 Not Found

{
  "detail": "Not Found"
}

---

Access Control

Folders Feature

• Requires ENABLE_FOLDERS configuration flag to be enabled
• Users must have features.folders permission or admin role
• All folder operations are scoped to the authenticated user

Folder Integrity

• Automatically validates parent folder existence
• Orphaned folders are moved to root automatically
• Files and collections are validated for user access
• Invalid references are removed automatically

Nested Folders

• Folders support hierarchical parent-child relationships
• Deleting a parent folder recursively processes all subfolders
• Moving folders validates name uniqueness within the target parent

Chat Integration

• Folders can contain chats via folder_id association
• Deleting folders with chats requires chat.delete permission
• Chats can be moved to root or deleted based on delete_contents flag