> ## 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.

# Folders

> Organize chats, files, and resources with hierarchical folder structures

## Overview

Folders in Open WebUI provide hierarchical organization for chats, files, and knowledge collections. Create nested folder structures to keep your workspace organized and efficient.

<Note>
  Folder functionality requires `ENABLE_FOLDERS` configuration and the `features.folders` permission for non-admin users.
</Note>

## Creating Folders

Create folders to organize your workspace:

```python theme={null}
# API endpoint: POST /api/v1/folders/
{
  "name": "Q1 Projects",
  "meta": {
    "icon": "📁"
  },
  "data": {
    "files": [],
    "description": "First quarter project chats"
  }
}
```

<Steps>
  <Step title="Choose a Name">
    Select a descriptive folder name. Names are case-insensitive and unique per user at each level.
  </Step>

  <Step title="Add Metadata (Optional)">
    Include custom icons or other metadata:

    ```json theme={null}
    {"meta": {"icon": "🚀"}}
    ```
  </Step>

  <Step title="Store Additional Data">
    Use the `data` field for custom attributes like descriptions or file references
  </Step>
</Steps>

<Warning>
  Folder names must be unique within the same parent folder. Attempting to create a duplicate folder will return an error.
</Warning>

## Folder Hierarchy

### Creating Nested Folders

Build hierarchical structures:

```python theme={null}
# Create parent folder
POST /api/v1/folders/
{"name": "Work"}
# Returns: {"id": "folder-123", ...}

# Create child folder
POST /api/v1/folders/
{
  "name": "Projects",
  "parent_id": "folder-123"  # Links to parent
}
```

### Moving Folders

Reorganize by changing parent:

```python theme={null}
# API endpoint: POST /api/v1/folders/{id}/update/parent
{
  "parent_id": "new-parent-id"  # null for root level
}
```

<Tabs>
  <Tab title="Move to Root">
    ```json theme={null}
    {"parent_id": null}
    ```

    Moves folder to top level
  </Tab>

  <Tab title="Move to Subfolder">
    ```json theme={null}
    {"parent_id": "folder-456"}
    ```

    Creates nested structure
  </Tab>

  <Tab title="Validation">
    System prevents:

    * Duplicate names in destination
    * Circular references
    * Moving to non-existent parents
  </Tab>
</Tabs>

## Folder Management

### Listing Folders

Retrieve your folder structure:

```bash theme={null}
# API endpoint: GET /api/v1/folders/
```

Returns:

```json theme={null}
[
  {
    "id": "folder-123",
    "name": "Work Projects",
    "parent_id": null,
    "meta": {"icon": "💼"},
    "is_expanded": true,
    "created_at": 1234567890,
    "updated_at": 1234567900
  },
  {
    "id": "folder-456",
    "name": "Personal",
    "parent_id": null,
    "meta": {"icon": "🏠"},
    "is_expanded": false,
    "created_at": 1234567890,
    "updated_at": 1234567900
  }
]
```

<Tip>
  The list endpoint automatically validates folder integrity and fixes broken parent references.
</Tip>

### Get Folder Details

Retrieve a specific folder:

```bash theme={null}
# API endpoint: GET /api/v1/folders/{id}
```

Includes:

* Full folder metadata
* Custom data fields
* Parent relationship
* Expansion state
* Timestamps

### Updating Folders

Modify folder properties:

```python theme={null}
# API endpoint: POST /api/v1/folders/{id}/update
{
  "name": "Updated Name",
  "meta": {"icon": "✨"},
  "data": {
    "description": "Updated description",
    "color": "blue"
  }
}
```

<Note>
  `data` and `meta` fields are merged with existing values, not replaced.
</Note>

### Expansion State

Control folder visibility in UI:

```python theme={null}
# API endpoint: POST /api/v1/folders/{id}/update/expanded
{
  "is_expanded": true  # or false
}
```

Use cases:

* **Remember UI State**: Persist folder open/closed state
* **Auto-Collapse**: Close inactive folders
* **Default Open**: Expand important folders by default

## Folder Contents

### Storing References

Folders can reference various content types:

```json theme={null}
{
  "data": {
    "files": [
      {"id": "file-123", "type": "file"},
      {"id": "col-456", "type": "collection"},
      {"id": "custom-789", "type": "custom"}
    ]
  }
}
```

<CardGroup cols={3}>
  <Card title="Files" icon="file">
    References to uploaded files tracked in the files system
  </Card>

  <Card title="Collections" icon="layer-group">
    Knowledge base collections for RAG
  </Card>

  <Card title="Custom Types" icon="puzzle-piece">
    Application-specific content references
  </Card>
</CardGroup>

### Automatic Validation

Folder list endpoint validates content:

<Steps>
  <Step title="Check File Access">
    Verifies you have read access to referenced files
  </Step>

  <Step title="Check Collection Access">
    Validates knowledge collection permissions
  </Step>

  <Step title="Remove Invalid References">
    Automatically cleans up inaccessible items
  </Step>

  <Step title="Update Folder">
    Saves cleaned references back to database
  </Step>
</Steps>

### Chats in Folders

Chats can be organized in folders:

```python theme={null}
# Associate chat with folder
POST /api/v1/chats/{chat_id}/folder
{
  "folder_id": "folder-123"  # or null to remove
}

# Count chats in folder
# Automatically checked before deletion
chats_count = Chats.count_chats_by_folder_id_and_user_id(
    folder_id, user_id
)
```

<Tip>
  Folders support hierarchical chat organization. Retrieving folder contents can include subfolders automatically.
</Tip>

## Deleting Folders

Remove folders and handle contents:

```bash theme={null}
# API endpoint: DELETE /api/v1/folders/{id}?delete_contents=true
```

### Deletion Options

<Tabs>
  <Tab title="Delete Contents (Default)">
    ```bash theme={null}
    DELETE /api/v1/folders/{id}?delete_contents=true
    ```

    Behavior:

    * Deletes all chats in folder
    * Recursively deletes subfolders
    * Removes all folder contents
    * Permanent deletion
  </Tab>

  <Tab title="Preserve Contents">
    ```bash theme={null}
    DELETE /api/v1/folders/{id}?delete_contents=false
    ```

    Behavior:

    * Moves chats to root level
    * Preserves all chat data
    * Deletes only folder structure
    * Safe option for reorganization
  </Tab>
</Tabs>

### Recursive Deletion

Folder deletion handles the entire hierarchy:

<Steps>
  <Step title="Identify Children">
    Finds all subfolders recursively
  </Step>

  <Step title="Process Chats">
    For each folder, either deletes or moves chats
  </Step>

  <Step title="Delete Subfolders">
    Removes child folders from deepest level up
  </Step>

  <Step title="Delete Parent">
    Finally removes the requested folder
  </Step>
</Steps>

<Warning>
  Deleting a folder with `delete_contents=true` permanently removes all chats in that folder and its subfolders. This action cannot be undone.
</Warning>

### Permission Requirements

Folder deletion checks:

```python theme={null}
# If folder contains chats, requires chat.delete permission
if Chats.count_chats_by_folder_id(folder_id, user_id):
    if not has_permission(user_id, "chat.delete", USER_PERMISSIONS):
        raise HTTPException(403, "Cannot delete folder with chats")
```

## Search & Discovery

### Search by Name

Find folders matching specific names:

```python theme={null}
# Exact match search (normalized)
folders = Folders.search_folders_by_names(
    user_id,
    queries=["work", "personal", "projects"]
)

# Returns matching folders + all their children
```

### Partial Search

Find folders containing text:

```python theme={null}
# Substring search
folders = Folders.search_folders_by_name_contains(
    user_id,
    query="proj"  # Matches "Projects", "Project Alpha", etc.
)
```

### Name Normalization

Search intelligently handles variations:

<CardGroup cols={2}>
  <Card title="Space Handling" icon="space-awesome">
    "Work Projects" = "work\_projects" = "work projects"
  </Card>

  <Card title="Case Insensitive" icon="a">
    "PROJECTS" = "projects" = "Projects"
  </Card>

  <Card title="Punctuation" icon="dash">
    Underscores and spaces treated identically
  </Card>

  <Card title="Whitespace" icon="compress">
    Multiple spaces collapsed to single space
  </Card>
</CardGroup>

## Folder Integrity

### Automatic Validation

The folder list endpoint ensures data integrity:

```python theme={null}
# Automatic checks on GET /api/v1/folders/
for folder in folders:
    # Fix broken parent references
    if folder.parent_id and not parent_exists(folder.parent_id):
        folder.parent_id = None
        update_folder(folder)
    
    # Validate file references
    if folder.data and "files" in folder.data:
        valid_files = validate_file_access(folder.data["files"])
        folder.data["files"] = valid_files
        update_folder(folder)
```

Benefits:

* **Self-Healing**: Automatically fixes broken references
* **Access Control**: Removes inaccessible items
* **Consistent State**: Ensures valid folder hierarchy

### Preventing Duplicate Names

System enforces unique names:

```python theme={null}
# Creating folder
if existing_folder_with_name_exists(parent_id, user_id, name):
    raise HTTPException(400, "Folder already exists")

# Renaming folder
if different_folder_has_name(parent_id, user_id, new_name):
    raise HTTPException(400, "Folder already exists")
```

## Best Practices

### Folder Organization

<Steps>
  <Step title="Use Clear Names">
    Choose descriptive, meaningful names:

    * ✅ "Client Projects"
    * ✅ "Personal Research"
    * ❌ "Folder1", "Misc", "Stuff"
  </Step>

  <Step title="Limit Nesting Depth">
    Keep hierarchies manageable:

    * 2-3 levels: Ideal for most use cases
    * 4-5 levels: Maximum recommended depth
    * Deeper nesting: Consider reorganization
  </Step>

  <Step title="Use Icons Consistently">
    Develop an icon system:

    * 📁 General folders
    * 💼 Work-related
    * 🏠 Personal
    * 🚀 Projects
    * 📚 Resources
  </Step>

  <Step title="Regular Maintenance">
    Keep folders relevant:

    * Archive old folders
    * Consolidate similar folders
    * Remove empty folders
    * Update folder names as needed
  </Step>
</Steps>

### Chat Organization

<Tip>
  Organize chats by:

  * **Project**: One folder per project
  * **Time Period**: Monthly or quarterly folders
  * **Topic**: Subject-based organization
  * **Client**: Client-specific conversations
</Tip>

### Metadata Usage

```json theme={null}
// Recommended metadata structure
{
  "meta": {
    "icon": "📁",
    "color": "blue",
    "priority": "high"
  },
  "data": {
    "description": "Detailed folder description",
    "tags": ["important", "active"],
    "created_by": "user-name",
    "purpose": "Client deliverables"
  }
}
```

## Performance Considerations

### Efficient Queries

<CardGroup cols={2}>
  <Card title="Batch Operations" icon="layer-group">
    Load all folders in one request instead of individual queries
  </Card>

  <Card title="Lazy Loading" icon="spinner">
    Load folder contents only when expanded in UI
  </Card>

  <Card title="Cache Folder List" icon="database">
    Cache folder structure for quick access
  </Card>

  <Card title="Optimize Depth" icon="layer-group">
    Limit folder nesting to reduce query complexity
  </Card>
</CardGroup>

### Large Folder Trees

Optimize for scale:

* **Pagination**: Consider pagination for large folder lists
* **Incremental Loading**: Load subfolders on demand
* **Search Indexing**: Use search for navigation instead of browsing
* **Flattening**: Periodically reorganize to reduce depth

## Integration with Other Features

### Chats

```python theme={null}
# Assign chat to folder
POST /api/v1/chats/{id}/folder
{"folder_id": "folder-123"}

# Query chats by folder
chats = Chats.get_chats_by_folder_id(folder_id, user_id)

# Count chats in folder
count = Chats.count_chats_by_folder_id_and_user_id(folder_id, user_id)

# Move chats to different folder
Chats.move_chats_by_user_id_and_folder_id(
    user_id, old_folder_id, new_folder_id
)
```

### Files & Collections

```python theme={null}
# Reference files in folder
"data": {
  "files": [
    {"id": "file-123", "type": "file"},
    {"id": "col-456", "type": "collection"}
  ]
}

# Automatic access validation
# GET /api/v1/folders/ validates:
# - Files: Files.check_access_by_user_id(file_id, user_id, "read")
# - Collections: Knowledges.check_access_by_user_id(col_id, user_id, "read")
```

### Custom Applications

Extend folders for your use case:

```json theme={null}
{
  "data": {
    "custom_field": "your_data",
    "app_metadata": {
      "workflow_stage": "review",
      "assigned_to": "user-123"
    }
  }
}
```

## API Reference

<CardGroup cols={2}>
  <Card title="List Folders" icon="list">
    ```
    GET /api/v1/folders/
    ```

    All folders with validation
  </Card>

  <Card title="Get Folder" icon="eye">
    ```
    GET /api/v1/folders/{id}
    ```

    Single folder details
  </Card>

  <Card title="Create Folder" icon="plus">
    ```
    POST /api/v1/folders/
    ```

    New folder at root or nested
  </Card>

  <Card title="Update Folder" icon="pen">
    ```
    POST /api/v1/folders/{id}/update
    ```

    Modify name, metadata, or data
  </Card>

  <Card title="Move Folder" icon="arrows">
    ```
    POST /api/v1/folders/{id}/update/parent
    ```

    Change parent (reorganize)
  </Card>

  <Card title="Toggle Expansion" icon="chevron-down">
    ```
    POST /api/v1/folders/{id}/update/expanded
    ```

    Update UI expansion state
  </Card>

  <Card title="Delete Folder" icon="trash">
    ```
    DELETE /api/v1/folders/{id}
    ```

    Remove folder ± contents
  </Card>
</CardGroup>

<Note>
  All endpoints require authentication and operate within user scope. Folders are private to each user.
</Note>