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

Upload a file to Open WebUI. The file can be processed in the background for content extraction and embedding generation.

## Request

### Headers

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

### Body

<ParamField body="file" type="file" required>
  The file to upload. File type must be allowed based on server configuration.
</ParamField>

<ParamField body="metadata" type="object | string">
  Optional metadata for the file. Can be a JSON object or JSON string.

  **Properties:**

  * `channel_id` (string): Associate file with a channel
  * `language` (string): Language hint for audio transcription
  * Additional custom metadata as needed
</ParamField>

<ParamField query="process" type="boolean" default="true">
  Whether to process the file for content extraction
</ParamField>

<ParamField query="process_in_background" type="boolean" default="true">
  Whether to process the file in the background. If `false`, processing happens synchronously.
</ParamField>

## Response

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

<ResponseField name="filename" type="string">
  Original filename
</ResponseField>

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

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

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

  <ResponseField name="name" type="string">
    File name
  </ResponseField>

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

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

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

<ResponseField name="data" type="object">
  Processing data

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

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

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

<ResponseField name="status" type="boolean">
  Always `true` for successful uploads
</ResponseField>

<ResponseField name="created_at" type="number">
  Unix timestamp of when the file was created
</ResponseField>

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

## Example

```bash theme={null}
curl -X POST https://your-domain.com/api/files \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf" \
  -F 'metadata={"language":"en"}'
```

```json Response theme={null}
{
  "status": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "document.pdf",
  "path": "550e8400-e29b-41d4-a716-446655440000_document.pdf",
  "user_id": "user123",
  "meta": {
    "name": "document.pdf",
    "content_type": "application/pdf",
    "size": 153600,
    "data": {
      "language": "en"
    }
  },
  "data": {
    "status": "pending"
  },
  "created_at": 1709856000,
  "updated_at": 1709856000
}
```

## File Processing

When `process=true`, the file is automatically processed based on its content type:

* **Audio files**: Transcribed using configured STT engine
* **Documents**: Text extracted for embedding and search
* **Images/Videos**: Processed if external content extraction is enabled

Processing status can be monitored via `GET /api/files/{id}/process/status`.