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

# Upload Documents for RAG

> Upload and process documents for retrieval-augmented generation

Upload a document file and optionally process it for embedding into a knowledge base. The file is chunked, embedded, and stored in the vector database for semantic search.

## Request

### Form Data

<ParamField body="file" type="file" required>
  The document file to upload. Supported formats depend on your configuration (PDF, DOCX, TXT, Markdown, etc.)
</ParamField>

<ParamField body="metadata" type="string | object">
  JSON string or object with additional metadata about the file. Can include custom fields for your application.
</ParamField>

### Query Parameters

<ParamField query="process" type="boolean" default="true">
  Whether to process the file for RAG (extract text, chunk, and embed)
</ParamField>

<ParamField query="process_in_background" type="boolean" default="true">
  Whether to process the file asynchronously in the background
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

## Response

<ResponseField name="status" type="boolean">
  Whether the upload was successful
</ResponseField>

<ResponseField name="id" type="string">
  Unique identifier for the uploaded file
</ResponseField>

<ResponseField name="filename" type="string">
  Original filename of the uploaded file
</ResponseField>

<ResponseField name="path" type="string">
  Storage path of the uploaded file
</ResponseField>

<ResponseField name="data" type="object">
  File processing data

  <ResponseField name="status" type="string">
    Processing status: "pending", "completed", or "failed"
  </ResponseField>

  <ResponseField name="content" type="string">
    Extracted text content (after processing)
  </ResponseField>

  <ResponseField name="error" type="string">
    Error message if processing failed
  </ResponseField>
</ResponseField>

<ResponseField name="meta" type="object">
  File metadata

  <ResponseField name="name" type="string">
    Display name of the file
  </ResponseField>

  <ResponseField name="content_type" type="string">
    MIME type of the file
  </ResponseField>

  <ResponseField name="size" type="integer">
    File size in bytes
  </ResponseField>

  <ResponseField name="data" type="object">
    Custom metadata provided during upload
  </ResponseField>
</ResponseField>

<ResponseField name="user_id" type="string">
  ID of the user who uploaded the file
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix timestamp when the file was uploaded
</ResponseField>

<ResponseField name="updated_at" type="integer">
  Unix timestamp when the file was last updated
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://your-domain.com/api/v1/files/?process=true" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -F "file=@/path/to/document.pdf" \
    -F 'metadata={"source":"user_upload","category":"documentation"}'
  ```

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

  url = "https://your-domain.com/api/v1/files/"
  headers = {"Authorization": "Bearer YOUR_TOKEN"}
  files = {"file": open("/path/to/document.pdf", "rb")}
  data = {
      "metadata": '{"source":"user_upload","category":"documentation"}'
  }
  params = {"process": True, "process_in_background": True}

  response = requests.post(url, headers=headers, files=files, data=data, params=params)
  file_info = response.json()
  print(f"File uploaded with ID: {file_info['id']}")
  print(f"Processing status: {file_info['data']['status']}")
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('file', fileInput.files[0]);
  formData.append('metadata', JSON.stringify({
    source: 'user_upload',
    category: 'documentation'
  }));

  const response = await fetch(
    'https://your-domain.com/api/v1/files/?process=true&process_in_background=true',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      },
      body: formData
    }
  );
  const fileInfo = await response.json();
  console.log(`File uploaded: ${fileInfo.id}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success (Background Processing) theme={null}
  {
    "status": true,
    "id": "file_abc123",
    "filename": "product_guide.pdf",
    "path": "files/abc123_product_guide.pdf",
    "data": {
      "status": "pending"
    },
    "meta": {
      "name": "product_guide.pdf",
      "content_type": "application/pdf",
      "size": 245678,
      "data": {
        "source": "user_upload",
        "category": "documentation"
      }
    },
    "user_id": "user_456def",
    "created_at": 1678901234,
    "updated_at": 1678901234
  }
  ```

  ```json 200 - Success (Completed) theme={null}
  {
    "status": true,
    "id": "file_abc123",
    "filename": "product_guide.pdf",
    "path": "files/abc123_product_guide.pdf",
    "data": {
      "status": "completed",
      "content": "Product Guide\n\nChapter 1: Getting Started..." 
    },
    "meta": {
      "name": "product_guide.pdf",
      "content_type": "application/pdf",
      "size": 245678,
      "collection_name": "file-abc123"
    },
    "hash": "sha256_hash_of_content",
    "user_id": "user_456def",
    "created_at": 1678901234,
    "updated_at": 1678901235
  }
  ```

  ```json 400 - Invalid File Type theme={null}
  {
    "detail": "File type exe is not allowed"
  }
  ```
</ResponseExample>

## Add File to Knowledge Base

After uploading a file, add it to a knowledge base:

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

### Request Body

<ParamField body="file_id" type="string" required>
  ID of the uploaded file to add to the knowledge base
</ParamField>

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

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

  url = "https://your-domain.com/api/v1/knowledge/kb_123/file/add"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  data = {"file_id": "file_abc123"}

  response = requests.post(url, headers=headers, json=data)
  knowledge = response.json()
  print(f"Knowledge base now has {len(knowledge['files'])} files")
  ```
</RequestExample>

## Batch Upload Files

Upload multiple files to a knowledge base at once:

```bash theme={null}
POST /api/v1/knowledge/{knowledge_id}/files/batch/add
```

### Request Body

```json theme={null}
[
  {"file_id": "file_1"},
  {"file_id": "file_2"},
  {"file_id": "file_3"}
]
```

## Processing Pipeline

1. **Upload**: File is stored and assigned a unique ID
2. **Extraction**: Text content is extracted based on file type (PDF, DOCX, etc.)
3. **Chunking**: Content is split into chunks (configured via CHUNK\_SIZE and CHUNK\_OVERLAP)
4. **Embedding**: Each chunk is embedded using the configured embedding model
5. **Storage**: Embeddings are stored in the vector database for retrieval

## Monitoring Processing Status

Check the processing status of a file:

```bash theme={null}
GET /api/v1/files/{file_id}/process/status?stream=true
```

This returns a Server-Sent Events (SSE) stream with status updates:

```
data: {"status": "pending"}
data: {"status": "completed"}
```

## Notes

* Supported file types are configurable via `ALLOWED_FILE_EXTENSIONS`
* Maximum file size is controlled by `FILE_MAX_SIZE` setting
* Processing extracts text using various engines (PyMuPDF, Tika, Docling, etc.)
* Audio files are transcribed using the configured STT engine
* Files are automatically chunked and embedded if `process=true`