Ainova Systems LogoAinova Systems

OCR API Documentation

Complete reference for OCR document processing endpoints

Base URL: https://api.ainova.systems/api/v1/ocr
60+ Languages Supported
Table of Contents

Authentication

API Key Authentication
All endpoints (except health check) require API key authentication

Include your API key in the Authorization header using Bearer token format:

Authorization: Bearer your_api_key_here

Health Check

GET
/api/v1/ocr/healthz
Standard health check endpoint

Authentication

Not required

Response

200 OK - Service is running

Use Case

Infrastructure monitoring and health checks

Submit File for Processing

POST
/api/v1/ocr/submit-file
Submit a document for processing using multipart form data

Request Parameters

file
Required

IFormFile - File to be processed (max size depends on your plan: Free 4MB, paid plans higher limits). Supported formats: PDF, JPEG, PNG, TIFF, BMP

languages
Required

string - Languages for OCR using ISO codes (e.g., "en,lt,ru")

outputs
Required

string - Output formats (e.g., "pdf,text")

models
Optional

string - OCR model to use (default: "tesseract"). Only "tesseract" is available.

priority
Optional

integer - Job priority (1-10, where 1 is highest, default: 5)

webhookUrl
Optional

string - URL to notify when processing is complete. Must be publicly accessible

reference
Optional

string - Customer's own ID/reference for document identification

jobExpiryInMinutes
Optional

integer - Job expiry time in minutes (default: 1440, range: 1-10080)

response
Optional

string - Result handling mode (default: "polling"). Options: "polling", "direct", "webhook"

Response

{
  "id": "uuid",                  // Unique identifier for the task
  "status": "string",            // Current status of the task
  "reference": "string",         // Customer's reference code if provided
  "models": "string",            // OCR model used for processing
  "priority": 5,                 // Job priority (1-10)
  "processingTimeInSeconds": 0.0, // Time taken to process request
  "responseMode": "string",      // How results are returned (direct, polling, webhook)
  "content": [{                  // Array of immediate results (direct mode only)
    "text": "string",            // Plain text content
    "pdf": "string"              // Base64-encoded PDF content
  }],
  "error": {                     // Error details if failed (omitted if null)
    "message": "string"          // Human-readable error description
  }
}

Example Request

curl -X POST https://api.ainova.systems/api/v1/ocr/submit-file \
  -H "Authorization: Bearer your_api_key" \
  -F "file=@document.pdf" \
  -F "languages=en,ru" \
  -F "outputs=text,pdf" \
  -F "models=tesseract" \
  -F "priority=5" \
  -F "response=polling"

Submit Base64 Document

POST
/api/v1/ocr/submit-base64
Submit a document for processing using base64-encoded content

Request Body (JSON)

{
  "documentBase64": "string",    // Required - Base64-encoded document content (max size depends on plan)
  "filename": "string",          // Optional - Filename with extension
  "languages": "string",         // Required - Languages for OCR (e.g., "en,lt,ru")
  "outputs": "string",           // Required - Output formats (e.g., "pdf,text")
  "models": "string",            // Optional - OCR model (default: "tesseract")
  "priority": 5,                 // Optional - Job priority (1-10, default: 5)
  "webhookUrl": "string",        // Optional - URL for completion notifications
  "reference": "string",         // Optional - Customer's reference ID
  "jobExpiryInMinutes": 1440,    // Optional - Job expiry (default: 1440)
  "response": "string"           // Optional - "polling", "direct", "webhook"
}

Example Request

curl -X POST https://api.ainova.systems/api/v1/ocr/submit-base64 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "documentBase64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PAo...",
    "filename": "document.pdf",
    "languages": "en,ru",
    "outputs": "text,pdf",
    "response": "polling"
  }'

Response format: Same as submit-file endpoint

Submit External URL Document

POST
/api/v1/ocr/submit-url
Submit a document for processing from an external URL

Request Body (JSON)

{
  "sourceUrl": "string",         // Required - External URL where document is stored
  "languages": "string",         // Required - Languages for OCR (e.g., "en,lt,ru")
  "outputs": "string",           // Required - Output formats (e.g., "pdf,text")
  "models": "string",            // Optional - OCR model (default: "tesseract")
  "priority": 5,                 // Optional - Job priority (1-10, default: 5)
  "webhookUrl": "string",        // Optional - URL for completion notifications
  "reference": "string",         // Optional - Customer's reference ID
  "jobExpiryInMinutes": 1440,    // Optional - Job expiry (default: 1440)
  "response": "string"           // Optional - "polling", "direct", "webhook"
}

Example Request

curl -X POST https://api.ainova.systems/api/v1/ocr/submit-url \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com/document.pdf",
    "languages": "en,ru",
    "outputs": "text,pdf",
    "response": "polling"
  }'

Response format: Same as submit-file endpoint

Get Job Status

GET
/api/v1/ocr/jobs/{jobId}
Get the status of a processing task and retrieve processed files

Path Parameters

jobId
Required

UUID - The unique identifier of the task returned from submit endpoints

Response

{
  "jobId": "uuid",               // Unique identifier for the task
  "status": "string",            // Current status: created, accepted, processing, completed, failed, cancelled
  "reference": "string",         // Customer's reference code if provided
  "models": "string",            // OCR model used for processing
  "priority": 5,                 // Job priority (1-10)
  "error": "string",             // Error message if failed
  "createdAt": "datetime",       // When the job was created
  "startedAt": "datetime",       // When processing started
  "completedAt": "datetime",     // When processing completed
  "expiryAt": "datetime",        // When the job expires
  "processingTimeInSeconds": 0.0, // Time elapsed from creation to completion
  "files": {                     // Download URLs when status is "Completed"
    "text": {
      "url": "string",           // Pre-signed URL for text file
      "expiration": "datetime"   // URL expiration time (typically 1 hour)
    },
    "pdf": {
      "url": "string",           // Pre-signed URL for PDF file
      "expiration": "datetime"   // URL expiration time
    },

  }
}

Example Request

curl -X GET https://api.ainova.systems/api/v1/ocr/jobs/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer your_api_key"

Data Types & Enums

Job Status Values
Created
Job has been created but not started
Accepted
Job has been accepted for processing
Processing
Job is currently being processed
Completed
Job has completed successfully
Failed
Job has failed with an error
Cancelled
Job was cancelled
Output Formats
text
Plain text output format
pdf
Searchable PDF with OCR layer
Response Modes
polling
Default Mode

Files are stored and the client must poll for status using the job status endpoint. Best for most use cases.

direct
Immediate Results

Files are returned directly in the API response content array. Use for small documents requiring immediate results.

webhook
Callback Notification

Files are stored and a webhook notification is sent to the specified URL upon completion. Best for async processing.

Webhook Integration

Webhook Configuration
Asynchronous processing with callback notifications

When response is set to "webhook" and webhookUrl is provided:

  1. System processes the document asynchronously
  2. Upon completion, sends POST request to webhook URL
  3. Webhook payload contains the complete job status result - identical to API response

Webhook Consistency

  • Webhook payload structure is identical to GET /api/v1/ocr/jobs/{jobId} API response
  • Same enum serialization (lowercase strings)
  • Same file structure with pre-signed URLs
  • Same error handling and optional fields
Webhook Payload Structure
Complete job status result wrapped in a result object
{
  "result": {
    "id": "uuid",                    // Required - Unique identifier for the task
    "status": "string",              // Required - Current status (e.g., "completed", "failed")
    "reference": "string",           // Optional - Customer's reference code if provided
    "models": "string",              // Required - OCR model(s) used (comma-separated string)
    "priority": 5,                   // Required - Job priority (1-10, where 1 is highest)
    "responseMode": "string",        // Required - How results are returned ("webhook")
    "error": "string",               // Optional - Error message if failed
    "createdAt": "datetime",         // Required - When the job was created
    "startedAt": "datetime",         // Optional - When processing started
    "completedAt": "datetime",       // Optional - When processing completed
    "expiryAt": "datetime",          // Optional - When the job expires
    "processingTimeInSeconds": 0.0,  // Required - Time elapsed from creation to completion
    "files": [{                      // Optional - Array of download URLs (empty array if no files ready)
      "models": "string",            // OCR models used for this result
      "pdf": {                       // Download URL for PDF output (omitted if not requested)
        "url": "string",             // Pre-signed URL for downloading the file
        "expiration": "datetime"     // When the download URL expires
      },
      "text": {                      // Download URL for text output (omitted if not requested)
        "url": "string",             // Pre-signed URL for downloading the file
        "expiration": "datetime"     // When the download URL expires
      }
    }]
  }
}
Successful Processing Example
{
  "result": {
    "id": "132376e4-201a-43c1-b71e-cd2e86980706",
    "status": "completed",
    "reference": "A123456789",
    "models": "tesseract",
    "priority": 5,
    "responseMode": "webhook",
    "createdAt": "2025-01-05T18:00:00Z",
    "startedAt": "2025-01-05T18:01:00Z", 
    "completedAt": "2025-01-05T18:10:00Z",
    "expiryAt": "2025-01-06T18:00:00Z",
    "processingTimeInSeconds": 600.0,
    "files": [{
      "models": "tesseract",
      "pdf": {
        "url": "https://s3.example.com/results/132376e4-201a-43c1-b71e-cd2e86980706_pdf.pdf?X-Amz-Expires=3600",
        "expiration": "2025-01-05T19:10:00Z"
      },
      "text": {
        "url": "https://s3.example.com/results/132376e4-201a-43c1-b71e-cd2e86980706_text.txt?X-Amz-Expires=3600",
        "expiration": "2025-01-05T19:10:00Z"
      }
    }]
  }
}
Failed Processing Example
{
  "result": {
    "id": "132376e4-201a-43c1-b71e-cd2e86980706",
    "status": "failed",
    "reference": "A123456789",
    "models": "tesseract",
    "priority": 5,
    "responseMode": "webhook",
    "error": "Invalid file format: corrupted PDF",
    "createdAt": "2025-01-05T18:00:00Z",
    "startedAt": "2025-01-05T18:01:00Z",
    "completedAt": "2025-01-05T18:02:00Z",
    "expiryAt": "2025-01-06T18:00:00Z",
    "processingTimeInSeconds": 120.0,
    "files": []
  }
}

Supported Languages

60+ Languages Available
Specify languages as comma-separated ISO 639-1 codes (e.g., "en,ru,de")

European Languages

sqAlbanian
euBasque
beBelarusian
bgBulgarian
caCatalan
hrCroatian
csCzech
daDanish
nlDutch
enEnglish
etEstonian
fiFinnish
frFrench
glGalician
deGerman
elGreek
huHungarian
isIcelandic
gaIrish
itItalian
lvLatvian
ltLithuanian
mkMacedonian
mtMaltese
noNorwegian
plPolish
ptPortuguese
roRomanian
ruRussian
srSerbian
skSlovak
slSlovenian
esSpanish
svSwedish
ukUkrainian
cyWelsh
bsBosnian
brBreton
lbLuxembourgish
gdScottish Gaelic

Asian Languages

asAssamese
bnBengali
cebCebuano
zh-cnChinese (Simplified)
zh-twChinese (Traditional)
hiHindi
jaJapanese
koKorean
paPunjabi
taTamil
teTelugu
thThai
boTibetan
urUrdu
viVietnamese

Middle Eastern

arArabic
azAzerbaijani
trTurkish

African Languages

amAmharic
swSwahili

Note: If an unsupported language code is provided, the API will return a 400 Bad Request error with details about supported languages.

Error Handling

HTTP Status Codes
200
OK - Request successful
400
Bad Request - Invalid parameters
401
Unauthorized - Missing/invalid API key
403
Forbidden - Insufficient permissions
404
Not Found - Resource not found
500
Internal Server Error
Common Error Messages
"Invalid file format"

Unsupported file type

"File too large"

Exceeds size limits

"Processing timeout"

Job took too long

"Invalid language code"

Unsupported OCR language

"Priority must be between 1 and 10"

Invalid priority value

Error Response Format
{
  "error": {
    "message": "Human-readable error description"
  }
}

Rate Limits & Constraints

File Size Limits (depends on the plan)
Direct File Upload
4MB max (free plan)
Base64 Content
4MB max (free plan)
External URL
4MB max (free plan)
Job Configuration
Default Job Expiry
24 hours
Max Job Expiry
7 days
Priority Range
1-10
URL Expiry
1 hour
Priority System
Control processing order with priority levels (1 = highest, 10 = lowest)
1-2
Critical priority (emergency documents, SLA-critical)
3-4
High priority (important business documents)
5
Normal priority (default) - Standard document processing
6-8
Low priority (batch processing, non-urgent)
9-10
Lowest priority (archive, test, bulk processing)

Processing Logic: Jobs are processed by priority first, then by creation time (FIFO) within the same priority level.

Ready to start processing documents?

Get your API key and start building with OCR API today

Quick Start Guide