Repository navigation
Home
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
- Configuration — full environment-variable reference
| 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 |
| 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) |
| 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: jobIdBody: folderId (optional, overrides DRIVE_SHARED_FOLDER_ID)Body: filename (optional, output name in Drive) |
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.
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/resultOptional: 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 '{}'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