Skip to content
standoge edited this page Aug 15, 2026 · 6 revisions

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:

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)

Usage examples

In production the API is served over HTTPS with a self-signed certificate — add --cacert cert.pem (or -k) to the commands below; see Infrastructure for certificate details. Locally, plain http://localhost:8000 works.

Async OCR (large documents)

For PDFs with many pages (1000+), use the job API so the client does not hold a long HTTP connection:

# Submit job
curl -X POST http://localhost:8000/v1/jobs \
  -F "file=@large-document.pdf"

# Poll status (replace JOB_ID)
curl http://localhost:8000/v1/jobs/JOB_ID

# Download result when status is "succeeded"
curl -OJ http://localhost:8000/v1/jobs/JOB_ID/result

Optional: upload the result to Google Drive on completion (use the full Shared Drive folder ID):

curl -X POST http://localhost:8000/v1/jobs \
  -F "file=@large-document.pdf" \
  -F "filename=searchable-document.pdf" \
  -F "folder_id=YOUR_SHARED_DRIVE_FOLDER_ID"

Batch submit (multiple PDFs in parallel; each job uploads independently when OCR finishes):

API=http://YOUR_HOST:8000
ls *.pdf | xargs -n1 -P4 -I{} curl -X POST "$API/v1/jobs" \
  -F "file=@{}" \
  -F "folder_id=YOUR_SHARED_DRIVE_FOLDER_ID"

Or upload after the job succeeds (omit folderId to use DRIVE_SHARED_FOLDER_ID):

curl -X POST http://localhost:8000/v1/jobs/JOB_ID/drive \
  -H "Content-Type: application/json" \
  -d '{"folderId": "YOUR_SHARED_DRIVE_FOLDER_ID", "filename": "searchable-document.pdf"}'

curl -X POST http://localhost:8000/v1/jobs/JOB_ID/drive \
  -H "Content-Type: application/json" \
  -d '{}'

Sync OCR (plain-text extraction)

Upload a PDF and get its OCR text layer back as plain text in the same request. Large PDFs are split into chunks processed concurrently; the connection stays open until OCR completes:

curl -X POST http://localhost:8000/v1/ocr \
  -F "file=@document.pdf" \
  -o document.txt

Clone this wiki locally