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.

Folder functionality requires ENABLE_FOLDERS configuration and the features.folders permission for non-admin users.

Creating Folders

Create folders to organize your workspace:

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

1. Choose a Name

   Select a descriptive folder name. Names are case-insensitive and unique per user at each level.

2. Add Metadata (Optional)

   Include custom icons or other metadata:

   {"meta": {"icon": "🚀"}}
   
3. Store Additional Data

   Use the data field for custom attributes like descriptions or file references

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

Folder Hierarchy

Creating Nested Folders

Build hierarchical structures:

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

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

Move to Root

{"parent_id": null}

Moves folder to top level

Move to Subfolder

{"parent_id": "folder-456"}

Creates nested structure

Validation

System prevents:

• Duplicate names in destination
• Circular references
• Moving to non-existent parents

Folder Management

Listing Folders

Retrieve your folder structure:

# API endpoint: GET /api/v1/folders/

Returns:

[
  {
    "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
  }
]

The list endpoint automatically validates folder integrity and fixes broken parent references.

Get Folder Details

Retrieve a specific folder:

# API endpoint: GET /api/v1/folders/{id}

Includes:

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

Updating Folders

Modify folder properties:

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

data and meta fields are merged with existing values, not replaced.

Expansion State

Control folder visibility in UI:

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

{
  "data": {
    "files": [
      {"id": "file-123", "type": "file"},
      {"id": "col-456", "type": "collection"},
      {"id": "custom-789", "type": "custom"}
    ]
  }
}

Files

References to uploaded files tracked in the files system

Collections

Knowledge base collections for RAG

Custom Types

Application-specific content references

Automatic Validation

Folder list endpoint validates content:

1. Check File Access

   Verifies you have read access to referenced files

2. Check Collection Access

   Validates knowledge collection permissions

3. Remove Invalid References

   Automatically cleans up inaccessible items

4. Update Folder

   Saves cleaned references back to database

Chats in Folders

Chats can be organized in folders:

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

Folders support hierarchical chat organization. Retrieving folder contents can include subfolders automatically.

Deleting Folders

Remove folders and handle contents:

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

Deletion Options

Delete Contents (Default)

DELETE /api/v1/folders/{id}?delete_contents=true

Behavior:

• Deletes all chats in folder
• Recursively deletes subfolders
• Removes all folder contents
• Permanent deletion

Preserve Contents

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

Recursive Deletion

Folder deletion handles the entire hierarchy:

1. Identify Children

   Finds all subfolders recursively

2. Process Chats

   For each folder, either deletes or moves chats

3. Delete Subfolders

   Removes child folders from deepest level up

4. Delete Parent

   Finally removes the requested folder

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

Permission Requirements

Folder deletion checks:

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

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

# Substring search
folders = Folders.search_folders_by_name_contains(
    user_id,
    query="proj"  # Matches "Projects", "Project Alpha", etc.
)

Name Normalization

Search intelligently handles variations:

Space Handling

“Work Projects” = “work_projects” = “work projects”

Case Insensitive

“PROJECTS” = “projects” = “Projects”

Punctuation

Underscores and spaces treated identically

Whitespace

Multiple spaces collapsed to single space

Folder Integrity

Automatic Validation

The folder list endpoint ensures data integrity:

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

# 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

1. Use Clear Names

   Choose descriptive, meaningful names:

   • ✅ “Client Projects”
   • ✅ “Personal Research”
   • ❌ “Folder1”, “Misc”, “Stuff”
2. Limit Nesting Depth

   Keep hierarchies manageable:

   • 2-3 levels: Ideal for most use cases
   • 4-5 levels: Maximum recommended depth
   • Deeper nesting: Consider reorganization
3. Use Icons Consistently

   Develop an icon system:

   • 📁 General folders
   • 💼 Work-related
   • 🏠 Personal
   • 🚀 Projects
   • 📚 Resources
4. Regular Maintenance

   Keep folders relevant:

   • Archive old folders
   • Consolidate similar folders
   • Remove empty folders
   • Update folder names as needed

Chat Organization

Organize chats by:

• Project: One folder per project
• Time Period: Monthly or quarterly folders
• Topic: Subject-based organization
• Client: Client-specific conversations

Metadata Usage

// 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

Batch Operations

Load all folders in one request instead of individual queries

Lazy Loading

Load folder contents only when expanded in UI

Cache Folder List

Cache folder structure for quick access

Optimize Depth

Limit folder nesting to reduce query complexity

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

# 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

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

{
  "data": {
    "custom_field": "your_data",
    "app_metadata": {
      "workflow_stage": "review",
      "assigned_to": "user-123"
    }
  }
}

API Reference

List Folders

GET /api/v1/folders/

All folders with validation

Get Folder

GET /api/v1/folders/{id}

Single folder details

Create Folder

POST /api/v1/folders/

New folder at root or nested

Update Folder

POST /api/v1/folders/{id}/update

Modify name, metadata, or data

Move Folder

POST /api/v1/folders/{id}/update/parent

Change parent (reorganize)

Toggle Expansion

POST /api/v1/folders/{id}/update/expanded

Update UI expansion state

Delete Folder

DELETE /api/v1/folders/{id}

Remove folder ± contents

All endpoints require authentication and operate within user scope. Folders are private to each user.