Upload File

POST /api/files

Upload File

cURL

curl --request POST \
  --url https://api.example.com/api/files \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {}
}'

200

{
  "id": "<string>",
  "filename": "<string>",
  "path": "<string>",
  "user_id": "<string>",
  "meta": {
    "name": "<string>",
    "content_type": "<string>",
    "size": 123,
    "data": {}
  },
  "data": {
    "status": "<string>",
    "content": "<string>",
    "error": "<string>"
  },
  "status": true,
  "created_at": 123,
  "updated_at": 123
}

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

Request

Headers

Authorization · string · required

Bearer token for authentication

Body

file · file · required

The file to upload. File type must be allowed based on server configuration.

metadata · 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

process · boolean · default: "true"

Whether to process the file for content extraction

process_in_background · boolean · default: "true"

Whether to process the file in the background. If false, processing happens synchronously.

Response

id · string

Unique identifier for the uploaded file

filename · string

Original filename

path · string

Storage path of the file

user_id · string

ID of the user who uploaded the file

meta · object

File metadata

name · string

File name

content_type · string

MIME type of the file

size · number

File size in bytes

data · object

Custom metadata provided during upload

data · object

Processing data

status · string

Processing status: pending, completed, or failed

content · string

Extracted text content (available after processing)

error · string

Error message if processing failed

status · boolean

Always true for successful uploads

created_at · number

Unix timestamp of when the file was created

updated_at · number

Unix timestamp of when the file was last updated

Example

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

Response

{
  "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.