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

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

<Tabs>
  <Tab title="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)
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X GET "https://your-instance/api/v1/models/list" \
      -H "Authorization: Bearer YOUR_TOKEN"
    ```
  </Tab>
</Tabs>

### Filtering & Search

Find models quickly using advanced filters:

```python theme={null}
# 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)
}
```

<Note>
  Model lists are automatically filtered based on your access permissions and group memberships.
</Note>

## Model Builder

Create custom model configurations through the Web UI.

<Steps>
  <Step title="Access Model Builder">
    Navigate to **Workspace → Models → Create Model**
  </Step>

  <Step title="Configure Base Settings">
    ```json theme={null}
    {
      "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"}]
      }
    }
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="Define Access Controls">
    Configure who can use this model (see [Access Control](#access-control) below)
  </Step>
</Steps>

### Custom Model Features

<CardGroup cols={2}>
  <Card title="Profile Images" icon="image">
    Upload custom icons or use URLs for model branding
  </Card>

  <Card title="System Prompts" icon="message">
    Define default system messages for consistent behavior
  </Card>

  <Card title="Parameter Presets" icon="sliders">
    Save commonly used parameter configurations
  </Card>

  <Card title="Integration Metadata" icon="link">
    Store additional data for external integrations
  </Card>
</CardGroup>

## Model Configuration

### Updating Models

Modify existing model configurations:

```python theme={null}
# 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
  }
}
```

<Warning>
  Only model owners, users with write access, or admins can update model configurations.
</Warning>

### Toggle Model Availability

Enable or disable models without deleting them:

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

<Tabs>
  <Tab title="Read Access">
    Users can:

    * View model in their model list
    * Use model for chat conversations
    * See model metadata and parameters
  </Tab>

  <Tab title="Write Access">
    Users can (in addition to read):

    * Update model configuration
    * Modify parameters and metadata
    * Manage access grants
  </Tab>

  <Tab title="Owner">
    Full control:

    * All write permissions
    * Delete the model
    * Transfer ownership
  </Tab>
</Tabs>

### Configuring Access Grants

Set up access controls for models:

```python theme={null}
# 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"
    }
  ]
}
```

<Note>
  Public model sharing requires the `sharing.public_models` permission for non-admin users.
</Note>

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

<Steps>
  <Step title="Request Export">
    ```bash theme={null}
    GET /api/v1/models/export
    ```

    Returns JSON array of model configurations
  </Step>

  <Step title="Save Configuration">
    Export includes all model metadata, parameters, and access grants
  </Step>

  <Step title="Share or Backup">
    Use exported JSON for:

    * Migration between instances
    * Version control
    * Team sharing
  </Step>
</Steps>

### Importing Models

Bulk import model configurations:

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

<Tip>
  Import automatically updates existing models with matching IDs and creates new ones for unknown IDs.
</Tip>

## Model Synchronization

Sync models from connected providers:

```python theme={null}
# 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:

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

<CardGroup cols={2}>
  <Card title="Tag Structure" icon="tag">
    ```json theme={null}
    {
      "tags": [
        {"name": "production"},
        {"name": "experimental"},
        {"name": "code-specialist"}
      ]
    }
    ```
  </Card>

  <Card title="List All Tags" icon="list">
    ```bash theme={null}
    GET /api/v1/models/tags
    ```

    Returns unique tags across all accessible models
  </Card>
</CardGroup>

## Profile Images

Customize model appearance:

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

<Tip>
  Use descriptive, consistent naming:

  * ✅ `gpt-4-code-review`
  * ✅ `claude-2-creative-writing`
  * ❌ `model1`, `test`, `new-model`
</Tip>

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

<Warning>
  Admin-only: These operations affect all users
</Warning>

```bash theme={null}
# Delete all models (use with extreme caution)
DELETE /api/v1/models/delete/all
```

### Access Control Override

Admins can optionally bypass access controls:

```python theme={null}
# 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

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

    Paginated model list with filtering
  </Card>

  <Card title="Get Model" icon="eye">
    ```
    GET /api/v1/models/model?id={id}
    ```

    Retrieve single model details
  </Card>

  <Card title="Create Model" icon="plus">
    ```
    POST /api/v1/models/create
    ```

    Add new custom model
  </Card>

  <Card title="Update Model" icon="pen">
    ```
    POST /api/v1/models/model/update
    ```

    Modify model configuration
  </Card>

  <Card title="Delete Model" icon="trash">
    ```
    POST /api/v1/models/model/delete
    ```

    Remove model permanently
  </Card>

  <Card title="Manage Access" icon="lock">
    ```
    POST /api/v1/models/model/access/update
    ```

    Configure access controls
  </Card>
</CardGroup>