Upload Documents for RAG

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"}'

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']}")

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}`);

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

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

{
  "detail": "File type exe is not allowed"
}

POST

api

files

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"}'

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']}")

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}`);

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

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

{
  "detail": "File type exe is not allowed"
}

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

file

required

The document file to upload. Supported formats depend on your configuration (PDF, DOCX, TXT, Markdown, etc.)

string | object

JSON string or object with additional metadata about the file. Can include custom fields for your application.

Query Parameters

boolean

default:"true"

Whether to process the file for RAG (extract text, chunk, and embed)

boolean

default:"true"

Whether to process the file asynchronously in the background

Headers

string

required

Bearer token for authentication

Response

boolean

Whether the upload was successful

string

Unique identifier for the uploaded file

string

Original filename of the uploaded file

string

Storage path of the uploaded file

object

File processing data

string

Processing status: “pending”, “completed”, or “failed”

string

Extracted text content (after processing)

string

Error message if processing failed

object

File metadata

string

Display name of the file

string

MIME type of the file

integer

File size in bytes

object

Custom metadata provided during upload

string

ID of the user who uploaded the file

integer

Unix timestamp when the file was uploaded

integer

Unix timestamp when the file was last updated

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"}'

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']}")

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}`);

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

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

{
  "detail": "File type exe is not allowed"
}

Add File to Knowledge Base

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

POST /api/v1/knowledge/{knowledge_id}/file/add

Request Body

string

required

ID of the uploaded file to add to the knowledge base

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"}'

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")

Batch Upload Files

Upload multiple files to a knowledge base at once:

POST /api/v1/knowledge/{knowledge_id}/files/batch/add

Request Body

[
  {"file_id": "file_1"},
  {"file_id": "file_2"},
  {"file_id": "file_3"}
]

Processing Pipeline

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

Monitoring Processing Status

Check the processing status of a file:

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

Overview

Chat & Messages

Models

Users & Groups

Knowledge

Functions & Tools

Files & Media

Channels

Prompts

Notes & Folders

Evaluations

Configuration

Upload Documents for RAG

Request

Form Data

Query Parameters

Headers

Response

Add File to Knowledge Base

Request Body

Batch Upload Files

Request Body

Processing Pipeline

Monitoring Processing Status

Notes

​Request

​Form Data

​Query Parameters

​Headers

​Response

​Add File to Knowledge Base

​Request Body

​Batch Upload Files

​Request Body

​Processing Pipeline

​Monitoring Processing Status

​Notes

Request

Form Data

Query Parameters

Headers

Response

Add File to Knowledge Base

Request Body

Batch Upload Files

Request Body

Processing Pipeline

Monitoring Processing Status

Notes