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

# Manage Document Collections

> Create and manage knowledge base collections for RAG

Manage knowledge base collections including creation, updating, file management, and deletion. Each knowledge base serves as a container for related documents that can be queried together.

## Create Knowledge Base

```bash theme={null}
POST /api/v1/knowledge/create
```

Create a new knowledge base collection.

### Request Body

<ParamField body="id" type="string">
  Custom identifier for the knowledge base (auto-generated if not provided)
</ParamField>

<ParamField body="name" type="string" required>
  Display name for the knowledge base
</ParamField>

<ParamField body="description" type="string">
  Description of the knowledge base content and purpose
</ParamField>

<ParamField body="data" type="object">
  Additional metadata to store with the knowledge base
</ParamField>

<ParamField body="access_grants" type="array">
  Array of access control rules. Each grant specifies permissions for users or groups.

  <ParamField body="grantee_type" type="string">
    Type of grantee: `"user"` or `"group"`
  </ParamField>

  <ParamField body="grantee_id" type="string">
    ID of the user or group
  </ParamField>

  <ParamField body="permission" type="string">
    Permission level: `"read"` or `"write"`
  </ParamField>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://your-domain.com/api/v1/knowledge/create" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Product Documentation",
      "description": "Knowledge base for product guides and manuals",
      "access_grants": [
        {
          "grantee_type": "group",
          "grantee_id": "support_team",
          "permission": "read"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://your-domain.com/api/v1/knowledge/create"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  payload = {
      "name": "Product Documentation",
      "description": "Knowledge base for product guides and manuals",
      "access_grants": [
          {
              "grantee_type": "group",
              "grantee_id": "support_team",
              "permission": "read"
          }
      ]
  }

  response = requests.post(url, headers=headers, json=payload)
  knowledge_base = response.json()
  print(f"Created knowledge base: {knowledge_base['id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "id": "kb_abc123",
    "name": "Product Documentation",
    "description": "Knowledge base for product guides and manuals",
    "user_id": "user_456def",
    "data": {},
    "created_at": 1678901234,
    "updated_at": 1678901234
  }
  ```
</ResponseExample>

## Update Knowledge Base

```bash theme={null}
POST /api/v1/knowledge/{knowledge_id}/update
```

### Request Body

Same fields as create endpoint. All fields are optional - only provided fields will be updated.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/update" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Product Documentation (Updated)",
      "description": "Updated description for the knowledge base"
    }'
  ```
</RequestExample>

## Get Knowledge Base Details

```bash theme={null}
GET /api/v1/knowledge/{knowledge_id}
```

Retrieve detailed information about a knowledge base including its files.

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "id": "kb_abc123",
    "name": "Product Documentation",
    "description": "Knowledge base for product guides and manuals",
    "user_id": "user_456def",
    "data": {},
    "files": [
      {
        "id": "file_xyz789",
        "filename": "user_guide.pdf",
        "meta": {
          "name": "user_guide.pdf",
          "size": 1234567
        }
      }
    ],
    "write_access": true,
    "created_at": 1678901234,
    "updated_at": 1678901234
  }
  ```
</ResponseExample>

## Manage Files in Knowledge Base

### List Files

```bash theme={null}
GET /api/v1/knowledge/{knowledge_id}/files?page=1&query=search_term
```

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="query" type="string">
  Search term to filter files by name
</ParamField>

<ParamField query="view_option" type="string">
  Filter by view option
</ParamField>

<ParamField query="order_by" type="string">
  Field to sort by (e.g., "name", "created\_at")
</ParamField>

<ParamField query="direction" type="string">
  Sort direction: "asc" or "desc"
</ParamField>

### Remove File from Knowledge Base

```bash theme={null}
POST /api/v1/knowledge/{knowledge_id}/file/remove
```

<ParamField body="file_id" type="string" required>
  ID of the file to remove
</ParamField>

<ParamField query="delete_file" type="boolean" default="true">
  Whether to delete the file entirely or just remove from this knowledge base
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/file/remove?delete_file=false" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"file_id": "file_xyz789"}'
  ```

  ```python Python theme={null}
  import requests

  url = "https://your-domain.com/api/v1/knowledge/kb_abc123/file/remove"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  params = {"delete_file": False}  # Keep file, just remove from KB
  data = {"file_id": "file_xyz789"}

  response = requests.post(url, headers=headers, params=params, json=data)
  print("File removed from knowledge base")
  ```
</RequestExample>

### Update File in Knowledge Base

Reprocess a file and update its embeddings:

```bash theme={null}
POST /api/v1/knowledge/{knowledge_id}/file/update
```

<ParamField body="file_id" type="string" required>
  ID of the file to reprocess
</ParamField>

This will:

1. Remove existing embeddings for the file
2. Re-extract content from the file
3. Re-chunk and re-embed the content
4. Update the vector database

## Reindex Knowledge Base

```bash theme={null}
POST /api/v1/knowledge/reindex
```

**Admin only.** Reindex all files across all knowledge bases. Useful after changing embedding models or chunking settings.

## Reset Knowledge Base

```bash theme={null}
POST /api/v1/knowledge/{knowledge_id}/reset
```

Remove all file associations and embeddings from a knowledge base without deleting the knowledge base itself.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/reset" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</RequestExample>

## Delete Knowledge Base

```bash theme={null}
DELETE /api/v1/knowledge/{knowledge_id}/delete
```

Permanently delete a knowledge base and all its associations. Files are not deleted.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://your-domain.com/api/v1/knowledge/kb_abc123/delete" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  url = "https://your-domain.com/api/v1/knowledge/kb_abc123/delete"
  headers = {"Authorization": "Bearer YOUR_TOKEN"}

  response = requests.delete(url, headers=headers)
  if response.json():
      print("Knowledge base deleted successfully")
  ```
</RequestExample>

## Export Knowledge Base

```bash theme={null}
GET /api/v1/knowledge/{knowledge_id}/export
```

**Admin only.** Export all files in a knowledge base as a ZIP archive containing .txt files with extracted content.

<ResponseExample>
  ```
  Content-Type: application/zip
  Content-Disposition: attachment; filename="Product_Documentation.zip"

  [Binary ZIP file containing text files]
  ```
</ResponseExample>

## Update Access Control

```bash theme={null}
POST /api/v1/knowledge/{knowledge_id}/access/update
```

Update who can access the knowledge base.

### Request Body

<ParamField body="access_grants" type="array" required>
  Array of access control rules (replaces existing grants)
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/access/update" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "access_grants": [
        {
          "grantee_type": "group",
          "grantee_id": "support_team",
          "permission": "read"
        },
        {
          "grantee_type": "user",
          "grantee_id": "user_xyz",
          "permission": "write"
        }
      ]
    }'
  ```
</RequestExample>

## Notes

* Knowledge base IDs must be unique
* The creator automatically gets write access
* Access grants can be filtered by user permissions (e.g., `sharing.public_knowledge`)
* Deleting a knowledge base removes it from associated models
* Files can belong to multiple knowledge bases
* Each knowledge base has its own vector collection for embeddings
* Metadata is embedded for semantic discovery of knowledge bases