Upload Documents

Endpoint

POST /upload

Upload one or more documents to receive document IDs for extraction. Upload stores the files; schema generation and extraction perform document conversion later.

Authentication

string

required

API key for authentication. Your unique API key.

Request Parameters

file[]

required

One or more document files to upload.Extraction-compatible formats:

application/pdf (.pdf)
image/jpeg (.jpg, .jpeg)
image/png (.png)
image/tiff (.tiff)
image/bmp (.bmp)

Other file types may upload, but schema generation and extraction can fail if the backend cannot convert the file.

Response

string[]

Array of UUID v4 document identifiers. Use these IDs for extraction requests.

Examples

curl -X POST https://api.documind.cloud/api/v1/upload \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'files=@invoice1.pdf' \
  -F 'files=@invoice2.pdf' \
  -F 'files=@receipt.jpg'

import requests

API_KEY = "your_api_key_here"
headers = {"X-API-Key": API_KEY}

# Upload single file
with open("invoice.pdf", "rb") as f:
    files = {"files": f}
    response = requests.post(
        "https://api.documind.cloud/api/v1/upload",
        headers=headers,
        files=files
    )

document_ids = response.json()
print(f"Uploaded document ID: {document_ids[0]}")

# Upload multiple files
files_to_upload = [
    ("files", open("doc1.pdf", "rb")),
    ("files", open("doc2.pdf", "rb")),
    ("files", open("doc3.jpg", "rb"))
]

response = requests.post(
    "https://api.documind.cloud/api/v1/upload",
    headers=headers,
    files=files_to_upload
)

# Close file handles
for _, file_handle in files_to_upload:
    file_handle.close()

document_ids = response.json()
print(f"Uploaded {len(document_ids)} documents")

const fs = require('fs');
const FormData = require('form-data');

// Upload single file
const formData = new FormData();
formData.append('files', fs.createReadStream('invoice.pdf'));

const response = await fetch('https://api.documind.cloud/api/v1/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.API_KEY,
    ...formData.getHeaders()
  },
  body: formData
});

const documentIds = await response.json();
console.log(`Uploaded document ID: ${documentIds[0]}`);

// Upload multiple files
const multiForm = new FormData();
multiForm.append('files', fs.createReadStream('doc1.pdf'));
multiForm.append('files', fs.createReadStream('doc2.pdf'));
multiForm.append('files', fs.createReadStream('doc3.jpg'));

const multiResponse = await fetch('https://api.documind.cloud/api/v1/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.API_KEY,
    ...multiForm.getHeaders()
  },
  body: multiForm
});

const multiDocIds = await multiResponse.json();
console.log(`Uploaded ${multiDocIds.length} documents`);

[
  "550e8400-e29b-41d4-a716-446655440000"
]

[
  "550e8400-e29b-41d4-a716-446655440000",
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "7c9e6679-7425-40de-944b-e07fc1f90ae7"
]

File Size & Limits

The backend does not enforce a documented per-file or per-request count limit in application code. Infrastructure may still reject oversized requests before they reach the backend. For larger batches, split files into multiple upload requests and retry failed requests.

Storage Duration

No public retention SLA is exposed by the backend. Keep your own source documents if you need long-term archival.

Processing Time

The API returns document IDs after the files are stored. OCR, layout analysis, and model processing happen later during schema generation or extraction; the backend does not expose a public upload timing SLA.

Error Responses

400 Bad Request

Malformed multipart request:

{
  "detail": "There was an error parsing the body"
}

Common causes:

Missing files form field
Invalid multipart body
Corrupt upload stream

413 Payload Too Large

Request exceeds size limits:

{
  "detail": "Request Entity Too Large"
}

Solution: Split your batch into smaller requests.

500 Internal Server Error

Server-side processing error:

{
  "detail": "Failed to upload documents. Please try again later."
}

Solution: Retry the request. If the error persists, contact support.

Best Practices

Batch Upload for Efficiency

Upload multiple documents in a single request to reduce API calls:

# ✓ Good: Batch upload
files = [("files", open(f, "rb")) for f in file_paths]
response = requests.post(url, headers=headers, files=files)

# ✗ Avoid: Multiple single uploads
for file_path in file_paths:
    response = requests.post(url, headers=headers, 
                           files={"files": open(file_path, "rb")})

Handle File Handles Properly

Always close file handles after upload:

# Using context manager (recommended)
with open("document.pdf", "rb") as f:
    response = requests.post(url, files={"files": f})

# Or explicitly close
files = [("files", open(f, "rb")) for f in file_paths]
try:
    response = requests.post(url, files=files)
finally:
    for _, fh in files:
        fh.close()

Validate Files Before Upload

Check file format before uploading:

import os

SUPPORTED = {'.pdf', '.jpg', '.jpeg', '.png', '.tiff', '.bmp'}

def validate_file(file_path):
    ext = os.path.splitext(file_path)[1].lower()
    if ext not in SUPPORTED:
        raise ValueError(f"Unsupported format: {ext}")
    
    return True

# Validate before upload
valid_files = [f for f in file_paths if validate_file(f)]

Store Document IDs

Map document IDs to original filenames for tracking:

# Create mapping
filename_to_id = {}

for file_path in file_paths:
    with open(file_path, "rb") as f:
        response = requests.post(url, files={"files": f})
        doc_id = response.json()[0]
        filename_to_id[os.path.basename(file_path)] = doc_id

# Save mapping for later reference
import json
with open("document_mapping.json", "w") as f:
    json.dump(filename_to_id, f, indent=2)

Next Steps

After uploading documents, you can:

Generate Schema

Auto-generate extraction schema from a sample document

Extract Data

Extract structured data using a schema

List Documents

View documents with extraction records

Getting Started

Extraction Workflow

Review Workflow

Data Endpoints

Integration Patterns

Endpoint

Authentication

Request Parameters

Response

Examples

File Size & Limits

Storage Duration

Processing Time

Error Responses

400 Bad Request

413 Payload Too Large

500 Internal Server Error

Best Practices

Next Steps

Generate Schema

Extract Data

List Documents

​Endpoint

​Authentication

​Request Parameters

​Response

​Examples

​File Size & Limits

​Storage Duration

​Processing Time

​Error Responses

​400 Bad Request

​413 Payload Too Large

​500 Internal Server Error

​Best Practices

​Next Steps

Generate Schema

Extract Data

List Documents

Endpoint

Authentication

Request Parameters

Response

Examples

File Size & Limits

Storage Duration

Processing Time

Error Responses

400 Bad Request

413 Payload Too Large

500 Internal Server Error

Best Practices

Next Steps