API Reference | SmartOCR

Authentication

Authenticate your API requests by including your secret API key in the x-api-key header. You can generate and manage your API keys in the developer dashboard.

x-api-key: sk_live_...

Extract Custom Schema

Post/v1/extract

Upload a document (PDF or Image) and a JSON schema. The API will route the document to the optimal engine and return a strictly typed JSON object matching your schema.

Request Parameters (multipart/form-data)

fileRequired

binary (PDF, PNG, JPEG)

The document file to be parsed. Max size 5MB.

schemaRequired

string (JSON)

A stringified JSON object defining the exact keys and types you want extracted.

File Integrity & Safety

To guarantee secure and reliable processing, the SmartOCR API performs strict real-time validation on all uploaded files before sending them to the inference engines.

Magic Byte Signature Verification

To prevent extension-spoofing attacks (e.g. renaming an executable to a .pdf), we verify file headers at the binary level. If the magic bytes do not match the declared MIME type, the request will fail with:

"Invalid [format] file signature. The file may be corrupted or renamed."

PDF Structural Integrity Check

All PDF uploads undergo deep structural analysis. If a PDF is corrupted, lacks a catalog, or has parsing anomalies, the API returns:

"Corrupted or invalid PDF file structure."

Encryption Detection

Password-protected, encrypted, or DRM-locked PDF documents cannot be processed. These will be rejected immediately with:

"Password protected PDFs are not supported."

Status Codes

SmartOCR uses standard HTTP response codes to indicate the success or failure of an API request.

200
OK
Successful extraction.
400
Bad Request
Invalid schema format, missing file, corrupted structures, spoofed file signatures, or password-protected PDFs.
401
Unauthorized
API key is missing, invalid, or inactive.
402
Payment Required
Out of credits. Top up required.
429
Too Many Requests
Rate limit exceeded (10 req/min for free, 100 for premium).
500
Server Error
All fallback providers failed to process the document.

curl -X POST https://api.smartocr.dev/v1/extract \
  -H "x-api-key: sk_test_12345" \
  -F "file=@/path/to/invoice.pdf" \
  -F 'schema={"invoiceNumber": "string", "totalDue": "number"}'

Response200 OK

{
  "extractedData": {
    "invoiceNumber": "INV-2847",
    "totalDue": 9782.00
  },
  "confidenceScore": 95,
  "processedAt": "2026-05-31T18:00:00.000Z",
  "creditsRemaining": 499,
  "rawText": "LENS & LIGHT CO.\n847 Mission St, San Francisco...\nTotal Due: $9,782.00"
}