Model Management

Configure, manage, and customize AI models in Open WebUI

Overview

Open WebUI provides comprehensive model management capabilities, allowing you to configure, customize, and control access to AI models across your organization.

Model Discovery

Listing Available Models

View all models accessible to your account:

UI

Navigate to Settings → Models to browse:

• Base models from connected providers
• Custom models created in your workspace
• Shared models from other users
• Community models (if enabled)

API

curl -X GET "https://your-instance/api/v1/models/list" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filtering & Search

Find models quickly using advanced filters:

# API endpoint: GET /api/v1/models/list
# Query parameters from routers/models.py:61-88
{
  "query": "gpt",           # Search by name
  "view_option": "all",     # all, personal, shared
  "tag": "production",      # Filter by tag
  "order_by": "created_at", # Sort field
  "direction": "desc",      # asc or desc
  "page": 1                 # Pagination (30 per page)
}

Model lists are automatically filtered based on your access permissions and group memberships.

Model Builder

Create custom model configurations through the Web UI.

1. Access Model Builder

   Navigate to Workspace → Models → Create Model

2. Configure Base Settings

   {
     "id": "my-custom-gpt",
     "name": "My Custom GPT-4",
     "meta": {
       "profile_image_url": "/models/custom-icon.png",
       "description": "Specialized for code review",
       "tags": [{"name": "code"}, {"name": "review"}]
     }
   }
   
3. Set Parameters

   Customize model behavior:

   • Temperature: Control randomness (0-2)
   • Top P: Nucleus sampling threshold
   • Max Tokens: Response length limit
   • Stop Sequences: Custom stopping conditions
4. Define Access Controls

   Configure who can use this model (see Access Control below)

Custom Model Features

Profile Images

Upload custom icons or use URLs for model branding

System Prompts

Define default system messages for consistent behavior

Parameter Presets

Save commonly used parameter configurations

Integration Metadata

Store additional data for external integrations

Model Configuration

Updating Models

Modify existing model configurations:

# API endpoint: POST /api/v1/models/model/update
# From routers/models.py:473
{
  "id": "model-id",
  "name": "Updated Name",
  "meta": {
    "profile_image_url": "new-url",
    "tags": [{"name": "updated"}]
  },
  "params": {
    "temperature": 0.7,
    "top_p": 0.9
  }
}

Only model owners, users with write access, or admins can update model configurations.

Toggle Model Availability

Enable or disable models without deleting them:

curl -X POST "https://your-instance/api/v1/models/model/toggle?id=model-id" \
  -H "Authorization: Bearer YOUR_TOKEN"

Access Control

Permission Levels

Open WebUI supports granular access control:

Read Access

Users can:

• View model in their model list
• Use model for chat conversations
• See model metadata and parameters

Write Access

Users can (in addition to read):

• Update model configuration
• Modify parameters and metadata
• Manage access grants

Owner

Full control:

• All write permissions
• Delete the model
• Transfer ownership

Configuring Access Grants

Set up access controls for models:

# API endpoint: POST /api/v1/models/model/access/update
# From routers/models.py:519
{
  "id": "model-id",
  "name": "Model Name",
  "access_grants": [
    {
      "access_type": "user",
      "resource_id": "user-id-123",
      "permission": "read"
    },
    {
      "access_type": "group",
      "resource_id": "group-engineering",
      "permission": "write"
    },
    {
      "access_type": "public",
      "permission": "read"
    }
  ]
}

Public model sharing requires the sharing.public_models permission for non-admin users.

Group-Based Access

Models automatically become available to users based on group membership:

1. Create a group (e.g., “Data Science Team”)
2. Add users to the group
3. Grant the group read/write access to models
4. All group members automatically inherit access

Model Import/Export

Exporting Models

Backup or share model configurations:

1. Request Export

   GET /api/v1/models/export
   

   Returns JSON array of model configurations

2. Save Configuration

   Export includes all model metadata, parameters, and access grants

3. Share or Backup

   Use exported JSON for:

   • Migration between instances
   • Version control
   • Team sharing

Importing Models

Bulk import model configurations:

# API endpoint: POST /api/v1/models/import
# From routers/models.py:247
{
  "models": [
    {
      "id": "imported-model-1",
      "name": "Imported Model",
      "meta": {...},
      "params": {...}
    }
  ]
}

Import automatically updates existing models with matching IDs and creates new ones for unknown IDs.

Model Synchronization

Sync models from connected providers:

# API endpoint: POST /api/v1/models/sync
# Admin only - from routers/models.py:320
{
  "models": [
    {"id": "gpt-4", "name": "GPT-4", ...},
    {"id": "claude-2", "name": "Claude 2", ...}
  ]
}

This endpoint:

• Creates models that don’t exist in the database
• Updates existing models with new metadata
• Maintains access control settings
• Preserves custom configurations

Base Models

Retrieve provider-native models:

# Admin only endpoint
GET /api/v1/models/base

Returns unmodified model list from:

• Ollama
• OpenAI-compatible APIs
• Other configured providers

Model Tags

Organize models with custom tags:

Tag Structure

{
  "tags": [
    {"name": "production"},
    {"name": "experimental"},
    {"name": "code-specialist"}
  ]
}

List All Tags

GET /api/v1/models/tags

Returns unique tags across all accessible models

Profile Images

Customize model appearance:

# Get model profile image
GET /api/v1/models/model/profile/image?id=model-id

Supported sources:

• HTTP URLs: Direct image links
• Data URLs: Base64-encoded images (format: data:image/png;base64,...)
• Default: Returns Open WebUI favicon if no custom image

Best Practices

Model Naming

Use descriptive, consistent naming:

• ✅ gpt-4-code-review
• ✅ claude-2-creative-writing
• ❌ model1, test, new-model

Access Management

1. Start Restrictive: Begin with minimal access, expand as needed
2. Use Groups: Prefer group-based access over individual grants
3. Regular Audits: Review access grants periodically
4. Document Purposes: Add descriptions explaining model use cases

Performance Optimization

• Pagination: Use page parameters for large model lists
• Filtering: Apply filters server-side rather than client-side
• Caching: Model lists are cached; use appropriate cache headers

Admin Features

Bulk Operations

Admin-only: These operations affect all users

# Delete all models (use with extreme caution)
DELETE /api/v1/models/delete/all

Access Control Override

Admins can optionally bypass access controls:

# Configuration option
BYPASS_ADMIN_ACCESS_CONTROL = True

When enabled, admins can:

• View all models regardless of access grants
• Modify any model configuration
• Manage access for all users

API Reference

List Models

GET /api/v1/models/list

Paginated model list with filtering

Get Model

GET /api/v1/models/model?id={id}

Retrieve single model details

Create Model

POST /api/v1/models/create

Add new custom model

Update Model

POST /api/v1/models/model/update

Modify model configuration

Delete Model

POST /api/v1/models/model/delete

Remove model permanently

Manage Access

POST /api/v1/models/model/access/update

Configure access controls