> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Folders

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

## List Folders

<ParamField query="GET" path="/api/folders" type="endpoint">
  Retrieve all folders for the authenticated user
</ParamField>

### Authorization

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

### Response

<ResponseField name="id" type="string" required>
  Unique identifier for the folder
</ResponseField>

<ResponseField name="name" type="string" required>
  Name of the folder
</ResponseField>

<ResponseField name="parent_id" type="string" optional>
  ID of the parent folder (null for root folders)
</ResponseField>

<ResponseField name="is_expanded" type="boolean">
  Whether the folder is expanded in the UI
</ResponseField>

<ResponseField name="data" type="object" optional>
  Additional folder data including files and collections
</ResponseField>

### Example Request

```bash cURL theme={null}
curl -X GET "https://your-domain.com/api/folders" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

```json 200 theme={null}
[
  {
    "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

<ParamField query="POST" path="/api/folders" type="endpoint">
  Create a new folder
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  Name of the folder to create
</ParamField>

<ParamField body="parent_id" type="string" optional>
  ID of the parent folder (omit for root folder)
</ParamField>

### Example Request

```bash cURL theme={null}
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

```json 200 theme={null}
{
  "id": "folder_789",
  "user_id": "user_123",
  "name": "New Project",
  "parent_id": "folder_123",
  "is_expanded": false,
  "data": {},
  "created_at": 1709395200,
  "updated_at": 1709395200
}
```

```json 400 Bad Request theme={null}
{
  "detail": "Folder already exists"
}
```

***

## Get Folder by ID

<ParamField query="GET" path="/api/folders/{id}" type="endpoint">
  Retrieve a specific folder by ID
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier of the folder
</ParamField>

### Example Request

```bash cURL theme={null}
curl -X GET "https://your-domain.com/api/folders/folder_123" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

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

```json 404 Not Found theme={null}
{
  "detail": "Not Found"
}
```

***

## Update Folder

<ParamField query="POST" path="/api/folders/{id}/update" type="endpoint">
  Update folder name or data
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier of the folder to update
</ParamField>

### Request Body

<ParamField body="name" type="string" optional>
  Updated name for the folder
</ParamField>

<ParamField body="data" type="object" optional>
  Updated folder data
</ParamField>

### Example Request

```bash cURL theme={null}
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

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

```json 400 Bad Request theme={null}
{
  "detail": "Folder already exists"
}
```

***

## Update Folder Parent

<ParamField query="POST" path="/api/folders/{id}/update/parent" type="endpoint">
  Move folder to a different parent folder
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier of the folder to move
</ParamField>

### Request Body

<ParamField body="parent_id" type="string" optional>
  ID of the new parent folder (null to move to root)
</ParamField>

### Example Request

```bash cURL theme={null}
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

```json 200 theme={null}
{
  "id": "folder_456",
  "user_id": "user_123",
  "name": "Client A",
  "parent_id": "folder_789",
  "is_expanded": false,
  "data": {},
  "created_at": 1709308800,
  "updated_at": 1709395600
}
```

```json 400 Bad Request theme={null}
{
  "detail": "Folder already exists"
}
```

***

## Update Folder Expanded State

<ParamField query="POST" path="/api/folders/{id}/update/expanded" type="endpoint">
  Update whether the folder is expanded in the UI
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier of the folder
</ParamField>

### Request Body

<ParamField body="is_expanded" type="boolean" required>
  Whether the folder should be expanded
</ParamField>

### Example Request

```bash cURL theme={null}
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

```json 200 theme={null}
{
  "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

<ParamField query="DELETE" path="/api/folders/{id}" type="endpoint">
  Delete a folder and optionally its contents
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier of the folder to delete
</ParamField>

### Query Parameters

<ParamField query="delete_contents" type="boolean" optional>
  Whether to delete chats in the folder (default: true). If false, chats are moved to root.
</ParamField>

### Authorization

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

### Example Request

```bash cURL theme={null}
curl -X DELETE "https://your-domain.com/api/folders/folder_123?delete_contents=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

```json 200 theme={null}
true
```

```json 403 Forbidden theme={null}
{
  "detail": "Access prohibited"
}
```

```json 404 Not Found theme={null}
{
  "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