Folders - Open WebUI

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"
  }
}

Choose a Name

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

Add Metadata (Optional)

Include custom icons or other metadata:

{"meta": {"icon": "🚀"}}

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
Move to Subfolder
Validation

{"parent_id": null}

Moves folder to top level

{"parent_id": "folder-456"}

Creates nested structure

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:

Check File Access

Verifies you have read access to referenced files

Check Collection Access

Validates knowledge collection permissions

Remove Invalid References

Automatically cleans up inaccessible items

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)
Preserve Contents

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

Behavior:

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

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:

Identify Children

Finds all subfolders recursively

Process Chats

For each folder, either deletes or moves chats

Delete Subfolders

Removes child folders from deepest level up

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

Use Clear Names

Choose descriptive, meaningful names:

✅ “Client Projects”
✅ “Personal Research”
❌ “Folder1”, “Misc”, “Stuff”

Limit Nesting Depth

Keep hierarchies manageable:

2-3 levels: Ideal for most use cases
4-5 levels: Maximum recommended depth
Deeper nesting: Consider reorganization

Use Icons Consistently

Develop an icon system:

📁 General folders
💼 Work-related
🏠 Personal
🚀 Projects
📚 Resources

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.

​Overview

​Creating Folders

​Folder Hierarchy

​Creating Nested Folders

​Moving Folders

​Folder Management

​Listing Folders

​Get Folder Details

​Updating Folders

​Expansion State

​Folder Contents

​Storing References

Files

Collections

Custom Types

​Automatic Validation

​Chats in Folders

​Deleting Folders

​Deletion Options

​Recursive Deletion

​Permission Requirements

​Search & Discovery

​Search by Name

​Partial Search

​Name Normalization

Space Handling

Case Insensitive

Punctuation

Whitespace

​Folder Integrity

​Automatic Validation

​Preventing Duplicate Names

​Best Practices

​Folder Organization

​Chat Organization

​Metadata Usage

​Performance Considerations

​Efficient Queries

Batch Operations

Lazy Loading

Cache Folder List

Optimize Depth

​Large Folder Trees

​Integration with Other Features

​Chats

​Files & Collections

​Custom Applications

​API Reference

List Folders

Get Folder

Create Folder

Update Folder

Move Folder

Toggle Expansion

Delete Folder

Overview

Creating Folders

Folder Hierarchy

Creating Nested Folders

Moving Folders

Folder Management

Listing Folders

Get Folder Details

Updating Folders

Expansion State

Folder Contents

Storing References

Automatic Validation

Chats in Folders

Deleting Folders

Deletion Options

Recursive Deletion

Permission Requirements

Search & Discovery

Search by Name

Partial Search

Name Normalization

Folder Integrity

Automatic Validation

Preventing Duplicate Names

Best Practices

Folder Organization

Chat Organization

Metadata Usage

Performance Considerations

Efficient Queries

Large Folder Trees

Integration with Other Features

Chats

Files & Collections

Custom Applications

API Reference