API Reference - v1

DXB OCR Developer API

Sell, automate, and integrate OCR as an API product. Developers can buy credits, create API keys, process images or PDFs, poll jobs, and receive signed webhooks.

Local base URL

http://localhost:8000

Production base URL

https://ocrics.com/api

Version

Auth

Bearer API key

Quickstart

Create an API key from the dashboard on an API-enabled plan, then send a multipart request to the OCR endpoint.

import requests

response = requests.post(
    "https://ocrics.com/api/v1/ocr",
    headers={"Authorization": "Bearer sk_live_..."},
    files={"file": open("invoice.pdf", "rb")},
    data={"output": "json", "lang": "auto"},
)
batch = response.json()
job_id = batch["jobs"][0]["id"]

job = requests.get(
    f"https://ocrics.com/api/v1/ocr/{job_id}",
    headers={"Authorization": "Bearer sk_live_..."},
)
print(job.json())

Authentication

API requests use secret keys created from your dashboard. Store keys server-side only; raw keys are shown once at creation.

Authorization: Bearer sk_live_abc123xyz...

Create keys

POST /v1/api-keys from an authenticated dashboard session.

Revoke keys

DELETE /v1/api-keys/{id} immediately disables a leaked key.

Credits & limits

One credit equals one processed page. Images count as one page. PDFs are charged by page after successful OCR.

Plan	Credits/mo	Concurrent	Max file	API
Free	50	1	5 MB	No
Basic	1,000	2	25 MB	No
Standard	5,000	5	50 MB	No
Premium	25,000	10	100 MB	Yes

Languages

Use lang=auto for default detection, or pass supported custom OCR model language codes such as eng, urd, ara, hin, or fas.

Output formats

Every successful job returns a searchable OCR PDF. For image uploads, the image is placed into a PDF with selectable OCR text overlaid in the same visual position.

POST/v1/ocr

Process one file

Upload one image or PDF and create an async OCR job.

Auth

Bearer API key from an API-enabled account.

Usage points

Use this for invoices, receipts, forms, screenshots, scanned pages, and single PDFs.
The response returns a batch plus one job id. Poll that job until it reaches completed.
When completed, download the searchable PDF with the download endpoint.

filerequired

file

PNG, JPG, JPEG, WEBP, TIFF, BMP, or PDF.

output

string

plain, formatted, or json. Defaults to plain.

lang

string

Language hint for the state-of-the-art custom OCR API model. Use auto, eng, urd, ara, hin, or fas.

extract_entities

boolean

Request structured fields when your plan supports it.

webhook_url

url

Optional completion callback URL. The URL must already be reachable over HTTPS.

Request example

curl https://ocrics.com/api/v1/ocr \
  -H "Authorization: Bearer sk_live_..." \
  -F file=@invoice.pdf \
  -F output=json \
  -F lang=auto

Response example

{
  "id": 42,
  "status": "queued",
  "requested_output": "json",
  "total_files": 1,
  "total_pages": 3,
  "jobs": [
    {
      "id": 101,
      "status": "queued",
      "original_filename": "invoice.pdf",
      "page_count": 3,
      "credits_used": 0,
      "download_urls": {}
    }
  ]
}

Notes

Credits are charged only after successful processing.
Images are converted into searchable PDF output because image formats cannot contain a selectable text layer.

POST/v1/ocr/batch

Process multiple files

Submit several files together and process them as one async batch.

Auth

Bearer API key from an API-enabled account.

Usage points

Use this when a customer uploads multiple documents at the same time.
Plan limits control the number of files, max file size, and concurrent processing.
Each file creates its own job id and each completed job has its own download URL.

filesrequired

file[]

Repeat this multipart field once for each image or PDF.

output

string

plain, formatted, or json. Defaults to plain.

lang

string

Language hint for the custom OCR model. Use auto for default detection.

webhook_url

url

Optional callback URL fired as jobs complete.

Request example

curl https://ocrics.com/api/v1/ocr/batch \
  -H "Authorization: Bearer sk_live_..." \
  -F files=@invoice-1.pdf \
  -F files=@invoice-2.png \
  -F lang=auto

Response example

{
  "id": 43,
  "status": "queued",
  "requested_output": "plain",
  "total_files": 2,
  "total_pages": 4,
  "jobs": [
    { "id": 201, "status": "queued", "original_filename": "invoice-1.pdf" },
    { "id": 202, "status": "queued", "original_filename": "invoice-2.png" }
  ]
}

GET/v1/ocr/{id}

Check job status

Fetch the latest state, credits, result metadata, and download URLs for one OCR job.

Auth

Bearer API key. The key must belong to the same user who created the job.

Usage points

Poll this endpoint after creating a job until status is completed, failed, or cancelled.
Use progress and status to update your UI instead of applying your own timeout.
Use the searchable_pdf URL when status is completed.

Request example

curl https://ocrics.com/api/v1/ocr/101 \
  -H "Authorization: Bearer sk_live_..."

Response example

{
  "id": 101,
  "status": "completed",
  "progress": 100,
  "page_count": 3,
  "credits_used": 3,
  "result": {
    "plain_text": "INVOICE\nACME Industries...",
    "entities": {},
    "word_count": 248
  },
  "download_urls": {
    "searchable_pdf": "/v1/ocr/101/download?type=ocr_pdf",
    "text": "/v1/ocr/101/download?type=txt",
    "json": "/v1/ocr/101/download?type=json"
  }
}

Notes

Long jobs can remain processing for a while. Treat the backend job status as the source of truth.
A job fails only when the worker marks it failed and returns an error code.

POST/v1/ocr/{id}/cancel

Cancel a queued or processing job

Ask the backend to stop work on a job that is still queued or processing.

Auth

Bearer API key. The key must belong to the same user who created the job.

Usage points

Use this when a user closes a workflow, uploads the wrong file, or no longer wants to wait.
Completed, failed, cancelled, and deleted jobs cannot be cancelled again.
Cancelled jobs stay in history with cancelled status for auditability.

Request example

curl -X POST https://ocrics.com/api/v1/ocr/101/cancel \
  -H "Authorization: Bearer sk_live_..."

Response example

{
  "id": 101,
  "status": "cancelled",
  "progress": 100,
  "error_code": "cancelled",
  "error_message": "OCR job was cancelled by the user."
}

GET/v1/ocr/{id}/download?type=ocr_pdf

Download searchable PDF

Download the custom OCR output while preserving the original page appearance.

Auth

Bearer API key. The key must belong to the same user who created the job.

Usage points

Use this after GET /v1/ocr/{id} returns completed.
PDF uploads return a searchable PDF with the original visual layout preserved.
Image uploads return a PDF containing the original image with selectable text positioned over it.

typerequired

string

Use ocr_pdf for the searchable layout-preserving PDF.

Request example

curl -L "https://ocrics.com/api/v1/ocr/101/download?type=ocr_pdf" \
  -H "Authorization: Bearer sk_live_..." \
  -o invoice_searchable.pdf

Response example

Binary file response
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice_searchable.pdf"

GET/v1/usage

List API usage

Read recent API calls, response status, and credit usage for the authenticated account.

Auth

Bearer API key or authenticated dashboard session.

Usage points

Use this to show customers a usage table in your own dashboard.
Use credits_used to reconcile billing, metering, and quota displays.
The api_key field returns the key prefix, never the full secret.

Request example

curl https://ocrics.com/api/v1/usage \
  -H "Authorization: Bearer sk_live_..."

Response example

[
  {
    "id": 1,
    "api_key": "sk_live_abcd1234",
    "endpoint": "/v1/ocr",
    "method": "",
    "credits_used": 3,
    "response_status": 202,
    "latency_ms": null,
    "created_at": "2026-05-23T10:15:00Z"
  }
]

POST/v1/api-keys

Create an API key

Create a new secret key for a user on an API-enabled plan.

Auth

Authenticated dashboard session. The raw key is shown only once.

Usage points

Use the dashboard API settings page for normal key creation.
Use a clear name so users can identify where the key is installed.
Store only the returned key value in your server-side secret manager.

namerequired

string

Human-readable key label, for example Production server.

Request example

curl -X POST https://ocrics.com/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <csrf-token>" \
  -b "sessionid=<dashboard-session>; csrftoken=<csrf-token>" \
  -d '{"name":"Production server"}'

Response example

{
  "id": 7,
  "name": "Production server",
  "prefix": "sk_live_abcd1234",
  "scopes": ["ocr:write", "ocr:read", "usage:read"],
  "active": true,
  "last_used_at": null,
  "created_at": "2026-05-23T10:15:00Z",
  "revoked_at": null,
  "key": "sk_live_abcd1234_full_secret_shown_once"
}

Notes

For security, the full key is never returned again after creation.
API key creation requires plan API access.

GET/v1/api-keys

List API keys

List key metadata for the logged-in user without exposing secret key values.

Auth

Authenticated dashboard session.

Usage points

Use this in the dashboard to display active and revoked keys.
Use last_used_at to help users identify stale or unused keys.
Never expect this endpoint to reveal the full key secret.

Request example

curl https://ocrics.com/api/v1/api-keys \
  -b "sessionid=<dashboard-session>"

Response example

[
  {
    "id": 7,
    "name": "Production server",
    "prefix": "sk_live_abcd1234",
    "scopes": ["ocr:write", "ocr:read", "usage:read"],
    "active": true,
    "last_used_at": "2026-05-23T10:22:00Z",
    "created_at": "2026-05-23T10:15:00Z",
    "revoked_at": null
  }
]

DELETE/v1/api-keys/{id}

Revoke an API key

Disable a key immediately without deleting its historical usage records.

Auth

Authenticated dashboard session.

Usage points

Use this when a key is leaked, rotated, or no longer needed.
Revoked keys stop authenticating immediately.
Existing usage events remain visible for reporting.

Request example

curl -X DELETE https://ocrics.com/api/v1/api-keys/7 \
  -H "X-CSRFToken: <csrf-token>" \
  -b "sessionid=<dashboard-session>; csrftoken=<csrf-token>"

Response example

204 No Content

POST/v1/webhooks

Create a webhook endpoint

Auth

Authenticated dashboard session on a webhook-enabled plan.

Usage points

Use webhooks when you do not want to poll every OCR job.
The URL must be HTTPS and cannot point to localhost or a private network.
The secret is returned once and should be used to verify delivery signatures.

urlrequired

url

Public HTTPS callback endpoint.

Request example

curl -X POST https://ocrics.com/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <csrf-token>" \
  -b "sessionid=<dashboard-session>; csrftoken=<csrf-token>" \
  -d '{"url":"https://example.com/webhooks/dxbocr"}'

Response example

{
  "id": 12,
  "url": "https://example.com/webhooks/dxbocr",
  "active": true,
  "created_at": "2026-05-23T10:15:00Z",
  "updated_at": "2026-05-23T10:15:00Z",
  "secret": "webhook_secret_shown_once"
}

GET/v1/webhooks

List webhook endpoints

List registered callback URLs for the logged-in user.

Auth

Authenticated dashboard session.

Usage points

Use this in the dashboard to show active webhook endpoints.
Use the endpoint id for delete operations.
Secrets are not returned in list responses.

Request example

curl https://ocrics.com/api/v1/webhooks \
  -b "sessionid=<dashboard-session>"

Response example

[
  {
    "id": 12,
    "url": "https://example.com/webhooks/dxbocr",
    "active": true,
    "created_at": "2026-05-23T10:15:00Z",
    "updated_at": "2026-05-23T10:15:00Z"
  }
]

DELETE/v1/webhooks/{id}

Delete a webhook endpoint

Remove a callback URL from the logged-in user's account.

Auth

Authenticated dashboard session.

Usage points

Use this when users disconnect an integration.
Future jobs no longer send events to the deleted URL.
Past delivery records remain available to staff in the admin dashboard.

Request example

curl -X DELETE https://ocrics.com/api/v1/webhooks/12 \
  -H "X-CSRFToken: <csrf-token>" \
  -b "sessionid=<dashboard-session>; csrftoken=<csrf-token>"

Response example

204 No Content

Webhooks

Premium/API-enabled plans can register callback URLs. Delivery payloads are signed with HMAC-SHA256 in the DXBOCR-Signature header using the endpoint secret.

Rate limits

Limits are enforced by plan: concurrent jobs, maximum file size, and batch size. When a limit is exceeded the API returns a stable error code.

Error codes

Status	Code	When
400	invalid_request	Missing or malformed parameters
401	unauthorized	Missing or invalid API key
402	insufficient_credits	Not enough credits for the job
403	forbidden_plan	The current plan does not include this feature
413	file_too_large	File exceeds the active plan limit
413	batch_too_large	Batch exceeds the active plan limit
415	unsupported_file_type	Only images and PDFs are supported
429	rate_limited	Concurrent job limit reached
500	processing_failed	The custom OCR model could not process the file

SDKs

Official SDK packages are planned. The REST API is stable enough to integrate directly with cURL, Python, Node.js, or Go today.