Upload
The Upload endpoint lets you submit a single document file for AI-powered data extraction. The file is stored, queued for AI extraction, and a processing history record is created automatically. You can track progress via the Processing History endpoints.
Upload a File
POST /v1/openapi/uploadUpload a single file for AI-powered data extraction.
Headers:
| Header | Value | Required |
|---|---|---|
X-API-Key | ocr_your_api_key | Yes |
Content-Type | multipart/form-data | Yes |
Request Body (multipart/form-data):
| Field | Type | Required | Description |
|---|---|---|---|
file | File | Yes | The document to upload (PDF or image) |
fileName | string | Yes | Original file name (e.g., invoice-2026.pdf) |
fileType | string | Yes | One of: pdf, image, document |
fileSize | string | Yes | File size in bytes as a string (e.g., "204800") |
mimeType | string | Yes | MIME type of the file (e.g., application/pdf) |
projectId | string | Yes | ID of the target project |
templateId | string | No | ID of the template to use for extraction |
uploadType | string | No | Upload type identifier (optional) |
metadata | string | No | Additional metadata as a JSON string |
batchId | string | No | Associate this upload with an existing batch |
Notes:
- For project tokens,
projectIdmust match the token's project. The field is still required. - For organization tokens,
projectIdmust belong to the token's organization.
Example Request:
curl -X POST "https://api.ocriva.com/v1/openapi/upload" \
-H "X-API-Key: ocr_your_api_key" \
-F "file=@/path/to/invoice-2026.pdf" \
-F "fileName=invoice-2026.pdf" \
-F "fileType=pdf" \
-F "fileSize=204800" \
-F "mimeType=application/pdf" \
-F "projectId=68db4aa2967d9c03fa9b5e74" \
-F "templateId=68db4bb3a67e9c04fb0c6f85"Example Response (201 Created):
{
"id": "68dc1cc4b78f0d15ec2a7f91",
"fileName": "invoice-2026.pdf",
"fileUrl": "https://storage.ocriva.com/org-abc/invoice-2026.pdf",
"publicUrl": "https://storage.ocriva.com/public/org-abc/invoice-2026.pdf",
"filePath": "org-abc/projects/proj-xyz/invoice-2026.pdf",
"fileSize": "204800",
"mimeType": "application/pdf",
"status": "uploaded",
"templateId": "68db4bb3a67e9c04fb0c6f85",
"projectId": "68db4aa2967d9c03fa9b5e74",
"uploadedAt": "2026-03-31T10:00:00.000Z",
"userId": "68da3991c56e8b02ea1b4d60",
"organizationId": "68da2880b45d7a01d90a3c51"
}Common Errors:
| Status | Cause |
|---|---|
400 | No file included, or a required form field is missing |
401 | Token is invalid, or projectId does not match the token scope |
404 | Specified project not found |