REST API endpoints

[lucas-profoundvision]

I’ve been experimenting with OCRmyPDF and think it fills an important niche. Many OCR options are either paid APIs, difficult to deploy, or part of much larger document-processing platforms with significant operational overhead. Sometimes developers simply need a fast, reliable OCR tool for ordinary scanned PDFs.

I’d like to reopen the discussion around exposing OCRmyPDF’s capabilities through a supported REST API.

OCR remains a barrier in many AI-driven document-processing workflows. Local OCR is already very capable for clean scans, so quality is often not the main limitation. In my view, the larger barrier is ease of integration: paid APIs are frequently chosen because they offer a straightforward HTTP interface, even when local OCR would be sufficient.

I have read the concerns in #1581 and wanted to add this perspective. A supported Docker Compose deployment and REST API would make OCRmyPDF much easier to adopt in automation and AI workflows, especially those built around CLI tools and HTTP services.

It could remain fully self-hosted, while an optional hosted/paid offering could potentially provide a sustainable revenue stream for the project.

[UmeshCode1]

This is a very relevant proposal, especially as RAG and multimodal AI pipelines increasingly demand self-hosted, deterministic OCR pipelines over proprietary document APIs.

Having built and scaled OCR microservices in production, the primary friction point maintainers face when wrapping CLI engines like OCRmyPDF in HTTP interfaces is the fundamental impedance mismatch between HTTP request/response lifecycles and PDF OCR execution semantics (as previously touched on in #1581).

Here is a pragmatic architecture for how a supported REST API / Docker deployment can be structured without overburdening the core library:

---

1. Asynchronous Job Processing Over Synchronous REST

Direct synchronous execution (POST /ocr returning the processed PDF) breaks down quickly:

• Multi-page or high-DPI PDFs frequently take 30s to 5+ minutes to OCR, routinely tripping gateway timeouts (e.g. Cloudflare’s 100s ceiling, AWS ALB 60s, Nginx proxy_read_timeout).
• A surge of concurrent uploads can easily exhaust worker threads and cause OOM kills (Tesseract + Ghostscript can consume 1–2GB+ per large document).

Recommended API Contract (Async Queue):

1. Submit Job: POST /api/v1/documents
   • Accepts multipart PDF and optional flags (deskew, clean, language, sidecar).
   • Responds immediately with 202 Accepted:

     {
       "job_id": "ocr_8f3a9e21",
       "status": "queued",
       "poll_url": "/api/v1/documents/ocr_8f3a9e21",
       "created_at": "2026-09-29T00:20:00Z"
     }

2. Poll Status: GET /api/v1/documents/{job_id}
   • Returns { "status": "processing", "progress": 0.45 } or { "status": "completed", "download_url": "/api/v1/documents/ocr_8f3a9e21/download", "pages": 12 }.
3. Webhook Callback (Optional): Supplying a webhook_url in the initial POST avoids polling overhead in automation workflows.

---

2. Microservice Topology (Separation of Concerns)

To keep the core ocrmypdf Python package lightweight and focused, the HTTP API is best packaged as a companion service (e.g. ocrmypdf-server or an official Docker Compose recipe):

[ Client / AI Pipeline ]
           │
           ▼
[ Reverse Proxy / Caddy ] (HTTPS, rate-limiting, upload buffering)
           │
           ▼
[ FastAPI Gateway (Stateless) ] ──▶ [ Redis Queue ]
                                         │
                                         ▼
                               [ OCRmyPDF Workers (Celery/RQ) ]
                                         │
                                         ▼
                              [ Ephemeral S3 / Shared Volume ]

---

3. Critical Operational Considerations for Self-Hosting

If implementing an official Docker Compose stack:

• Tesseract Thread Clamping: Tesseract defaults to OpenMP multi-threading, which can thrash CPU cores under concurrent containerized jobs. Setting OMP_THREAD_LIMIT=1 per worker process and scaling the number of workers yields dramatically better total document throughput.
• Process Isolation: Invoking OCR via Python API ocrmypdf.ocr() within an isolated subprocess or Celery worker prevents C-library memory leaks (liblept/libtesseract) from bloating the web gateway.
• Sidecar Text Extraction: For LLM embeddings and vector databases, exposing a /download?format=text or /sidecar endpoint returning just the extracted plaintext/JSON coordinates provides huge value without needing to download the entire re-baked PDF.

A reference docker-compose.yml bundling FastAPI + Redis + ocrmypdf would be a fantastic ecosystem companion project that satisfies this need immediately for community self-hosters!