API Reference
Ocriva provides a RESTful API for integrating document processing into your applications.
Base URL
https://api.ocriva.comAuthentication
All API requests require authentication via Bearer token (JWT) or API Token.
IMPORTANT
Never expose your API tokens in client-side code, browser extensions, or public repositories. Always use server-side requests or environment variables to store tokens securely.
Using JWT
curl -X POST https://api.ocriva.com/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "your-password"}'Using API Token
curl https://api.ocriva.com/upload/YOUR_ORG_ID/file \
-H "Authorization: Bearer YOUR_API_TOKEN"Using API Key (Recommended for Open API)
For external integrations, use your API key directly:
curl https://api.ocriva.com/v1/openapi/projects \
-H "X-API-Key: ocr_your_api_key"See the Open API Overview for full authentication details.
IMPORTANT
Never expose your API tokens in client-side code or public repositories. Use server-side requests and store tokens in environment variables.
Endpoints
Upload
Upload a File
POST /upload/:organizationId/fileUpload a single file for processing.
Headers:
Authorization: Bearer <token>Content-Type: multipart/form-data
Body (form-data):
| Field | Type | Required | Description |
|---|---|---|---|
file | File | Yes | The document file to upload |
fileName | string | Yes | Original file name |
fileType | string | Yes | pdf, image, or document |
projectId | string | Yes | Target project ID |
templateId | string | No | Template for processing |
Response:
{
"id": "upload_id",
"fileName": "invoice.pdf",
"fileUrl": "https://storage.example.com/...",
"status": "uploaded",
"templateId": "template_id"
}WARNING
Individual file uploads are limited in size. Files exceeding the limit will be rejected with a 413 Payload Too Large error. For large PDFs or high-resolution images, compress or split the document before uploading.
Batch Upload
POST /batch/:organizationId/uploadUpload multiple files as a batch (max 50 files).
WARNING
Batch uploads accept a maximum of 50 files per request. The request timeout scales automatically with file count.
IMPORTANT
Batch upload is limited to 50 files per request. For larger volumes, split files into multiple batch submissions. Each file in the batch is processed independently and credits are deducted per document.
Body (form-data):
| Field | Type | Required | Description |
|---|---|---|---|
files | File[] | Yes | Files to upload (max 50) |
projectId | string | Yes | Target project ID |
templateId | string | No | Template for processing |
name | string | No | Batch name |
TIP
Keep batches to 50 files or fewer and set a descriptive name for each batch. Very large or complex files in a single batch can approach request timeout limits — if you experience timeouts, reduce batch size or compress files before uploading.
Processing History
List Processing History
GET /processing-history?projectId=<id>&status=<status>&page=1&limit=20Get Processing Result
GET /processing-history/:id?projectId=<id>Templates
List Templates
GET /templates?projectId=<id>Create Template
POST /templatesOpen API
For external service integrations, Ocriva provides a dedicated Open API with direct API key authentication:
- Overview & Authentication — Base URL, auth methods, rate limiting, error handling
- Upload — Upload files for processing
- Templates — Manage extraction templates
- Projects — List projects
- Processing History — View results and export data
- Batch Operations — Batch upload and export
Rate Limits
API requests are subject to rate limiting based on your subscription plan.
WARNING
Exceeding rate limits will result in 429 Too Many Requests responses. Implement exponential backoff in your integration to handle these gracefully. Contact support if your use case requires higher throughput.
Error Handling
All errors follow this format:
{
"statusCode": 400,
"message": "Error description",
"error": "Bad Request"
}SDKs
Coming soon: TypeScript and Python SDKs.