Home

DocAI OCR API Wiki

Documentation for the DocAI OCR API. This page is the endpoint reference; the deeper technical topics live on their own pages:

• Architecture — how the project works end to end
• Infrastructure — GCP services, their configuration, and a service diagram
• OCR Plugin — the ocr_documentai_plugin (Document AI + PyMuPDF)
• Job Manager — the async job queue and worker pool

Endpoints

🏥 System

Endpoint	Description	Parameter (Query or Path)	Parameters
GET /healthz	Returns service health status. Used by load balancers and deployment checks.	N/A	None
GET /openapi.yml	Returns the OpenAPI 3.1 contract as YAML (design-first spec).	N/A	None
GET /openapi.json	Returns the OpenAPI 3.1 contract as JSON.	N/A	None
GET /docs	Serves Swagger UI for interactive API exploration.	N/A	None

📄 OCR (Synchronous)

Endpoint	Description	Parameter (Query or Path)	Parameters
POST /v1/ocr	Accepts a PDF via multipart upload, runs OCR with GCP Document AI (large PDFs are split into chunks processed concurrently), and returns the extracted text layer as text/plain. A ready-to-use tool: the request stays open until OCR completes. Supports up to MAX_PDF_PAGES pages (default 2000). For searchable PDF output, use the async jobs endpoints.	Form (multipart)	file (required, PDF)

⏳ Jobs (Async OCR)

Endpoint	Description	Parameter (Query or Path)	Parameters
POST /v1/jobs	Submits a PDF for asynchronous OCR. Streams the upload to disk, enqueues a background worker, and returns immediately with a job ID and status URL. Supports large documents (up to MAX_UPLOAD_BYTES, default 600 MB). If folder_id is provided, the worker uploads the result to Google Drive after OCR completes.	Form (multipart)	file (required, PDF) filename (optional, download filename when fetching the result) folder_id (optional, Shared Drive folder ID for automatic Drive upload on completion)
GET /v1/jobs/{jobId}	Returns the current status of an OCR job. When status is succeeded, includes resultUrl and, if applicable, driveFileId, driveWebViewLink, or driveUploadError.	Path	jobId (UUID returned by POST /v1/jobs)
GET /v1/jobs/{jobId}/result	Downloads the searchable PDF for a succeeded job. Returns 400 if the job is not yet complete or failed.	Path	jobId
POST /v1/jobs/{jobId}/drive	Uploads the searchable PDF from a succeeded job to Google Drive. Use to retry a failed upload, upload a job created without folder_id, or target a different folder.	Path & Body	Path: jobId Body: folderId (optional, overrides DRIVE_SHARED_FOLDER_ID) Body: filename (optional, output name in Drive)