API Reference
Upload Endpoints
File upload and processing endpoints
Upload Endpoints
Base path: /api/v1/upload
POST /api/v1/upload
Upload a file synchronously. The file is parsed, processed through the RAG pipeline, and stored in the vector database.
Content-Type: multipart/form-data
Form Fields:
| Field | Type | Default | Description |
|---|---|---|---|
file | file | required | File to upload |
section | string | "uploaded" | Document section/category |
Supported File Types:
| Category | Extensions |
|---|---|
| Text | .txt, .md, .rst |
| Documents | .pdf, .docx, .pptx |
| Web | .html, .htm |
| Data | .json, .csv, .xlsx |
| Images | .png, .jpg, .jpeg, .tiff, .bmp |
Response:
{
"success": true,
"filename": "manual.pdf",
"title": "User Manual",
"chunks_added": 42,
"chunks_updated": 0,
"chunks_skipped": 0,
"error": null,
"is_duplicate": false,
"duplicate_type": null,
"existing_doc_id": null,
"existing_doc_title": null,
"duplicate_message": null
}Duplicate Detection Fields
| Field | Type | Description |
|---|---|---|
is_duplicate | bool | Whether the file was detected as a duplicate |
duplicate_type | string | null | Type of duplicate: "filepath" or "content_hash" |
existing_doc_id | string | null | ID of the existing document if duplicate |
existing_doc_title | string | null | Title of the existing document if duplicate |
duplicate_message | string | null | Human-readable duplicate detection message |
Example:
curl -X POST http://localhost:9000/api/v1/upload \
-H "X-API-Key: your-key" \
-F "file=@document.pdf" \
-F "section=manuals"POST /api/v1/upload/async
Upload a file asynchronously in the background. Same form fields as the sync endpoint.
Response:
{
"task_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"message": "Processing file 'document.pdf' in background",
"created_at": "2025-01-15T10:30:00.000000"
}POST /api/v1/upload/bulk
Upload multiple files at once.
Form Fields:
| Field | Type | Description |
|---|---|---|
files | file[] | Multiple files to upload |
section | string | Document section/category |
Response:
{
"total_files": 3,
"successful": 2,
"failed": 0,
"duplicates": 1,
"total_chunks_added": 85,
"results": [
{
"filename": "doc1.pdf",
"success": true,
"title": "Document 1",
"chunks_added": 42,
"chunks_updated": 0,
"chunks_skipped": 0,
"error": null,
"is_duplicate": false,
"duplicate_message": null
}
],
"errors": []
}Example:
curl -X POST http://localhost:9000/api/v1/upload/bulk \
-H "X-API-Key: your-key" \
-F "files=@doc1.pdf" \
-F "files=@doc2.docx" \
-F "section=manuals"POST /api/v1/upload/bulk/zip
Upload a ZIP archive. All files inside are extracted and processed.
Form Fields:
| Field | Type | Description |
|---|---|---|
file | file | ZIP archive to upload |
section | string | Document section/category |