Private Cloud OCR overview

What is Private Cloud OCR

Private Cloud OCR (PCO) is the Mathpix document API running inside your own infrastructure: one container image with the same models and the same request and response shapes as api.mathpix.com, on your GPU, in your Kubernetes cluster or on a single host. Documents, page images and results never leave your network. Code you wrote against v3/pdf and v3/text works unchanged; you point it at a different host.

Beside the per-document endpoints, a deployment adds a batch API over folders in your own object storage, operator endpoints for health, usage and license state, and works with the pco command-line tool.

All Private Cloud OCR pages

page	what it covers
this overview	what PCO is, when to use it, how it works, what differs from the hosted API
Quickstart	prerequisites, install with Docker Compose or Helm, first document, connection variables
Batch jobs	a folder in your bucket in, a folder out: layouts, policy, report, retry, cancel, webhooks
Operations	health, logs and shipping them to your logging tool, usage counters, license states, upgrades, backups, retention, troubleshooting
Reference: /pco/v1/jobs	every batch endpoint, request and response fields, error ids
Reference: operator endpoints	/health, /pco/v1/status, /metrics, /pco/v1/usage, /pco/v1/license, webhook config
POST v3/pdf, POST v3/text, webhooks	the hosted reference pages; a deployment takes the same requests and sends the same notifications

When to use Private Cloud OCR

	v3/pdf on api.mathpix.com	Files API	Private Cloud OCR
Where documents go	Mathpix's cloud	Mathpix's cloud; results can be written to your bucket	nowhere: everything runs inside your network
Use it for	interactive, per-document processing	large archives and pipelines at low per-page cost	regulatory, contractual or latency requirements that rule out sending documents to a cloud API
What you run	nothing	nothing	one container per GPU, plus Redis and an S3-compatible bucket (both can be included)
Batch over a folder	no	yes, with your bucket as a data source	yes, with the deployment's own credentials to your bucket
Pricing	per page, see pricing	per page, volume tiers	an annual minimum with included pages, and overage per 1,000 pages
Model updates	automatic	automatic	a new image tag you roll out when you choose; GET /pco/v1/status shows the model versions

If your constraint is data residency alone, the EU endpoint or the Files API writing into your own bucket may be the lighter option.

How it works

1. Install. One helm install on a cluster with GPU nodes, or docker compose up on one GPU host. The included Redis and SeaweedFS run beside the API, or you point the deployment at your own Redis and bucket. Quickstart.
2. Submit. POST /v3/pdf for one document, POST /v3/text for one image, or POST /pco/v1/jobs for a folder in your bucket. Batch jobs.
3. Collect. Poll GET /v3/pdf/{pdf_id} and download .mmd, .lines.json, .docx and the other formats, or let a job write outputs beside their inputs in your bucket and read its report.

Core concepts

• Deployment — one installation: any number of containers sharing one Redis and one bucket. Every container runs the API and the OCR workers; scaling is adding containers, one per GPU.
• PCO_DEPLOYMENT_ID — the stable name of your installation, chosen at install and kept across upgrades. Mathpix records license check-ins and usage under it.
• License mode — your image is either licensed, checking in with Mathpix every 60–90 seconds and working through outages for 24 hours, or airgapped, never connecting out. Nothing about your documents is sent in either case. Operations.
• Metering mode — metered images report daily page counts to Mathpix every 15 minutes; unmetered images report nothing, and you export a usage statement when your contract is usage-based. The same counters are always readable on your deployment at GET /pco/v1/usage.
• API version — GET /pco/v1/status advertises api_version; the pco tool warns when it meets a deployment newer than it knows.
• The pco tool — a single binary that converts a file, a local folder or a cloud folder against your deployment, with progress, resume and a report. It will be released as open source; every command it runs is an HTTP call you could make yourself.

What is the same as the Mathpix hosted API, and what differs

Same: the POST /v3/pdf request forms (multipart file + options_json, JSON with url, urlencoded), the status body, the download endpoints with their 202-while-converting behaviour, the POST /v3/text body, the error envelope and error ids, the supported input and output formats.

Different:

• No app_id and app_key. The API has no authentication of its own; your network, ingress and Kubernetes policies are the boundary. The pco tool passes through a bearer token or client certificate if your ingress wants one.
• Every documented option of POST /v3/pdf and POST /v3/text is honored with the same validation and error ids, including streaming with GET /v3/pdf/{pdf_id}/stream, the callback_url, callback_events and callback_headers webhook fields on POST /v3/pdf, and async and the callback object on POST /v3/text. The one exception is metadata, which a deployment rejects with opts_unsupported rather than silently ignores: its improve_mathpix key shares your documents with Mathpix to improve the models, which is the thing a private deployment exists to prevent. Batch jobs take the same webhook fields as a hosted job.
• An async request on POST /v3/text without a callback has nowhere to deliver: the hosted API keeps such results for GET /v3/ocr-results, which a deployment does not have. Use a callback, or the synchronous call.
• POST /v3/text sheds load beyond 8 concurrent requests per GPU worker with the hosted 429 http_max_requests, rather than queueing behind a timeout.
• Rate limits and quotas are your hardware's: there is no per-key quota.

Next steps

Start with the Quickstart; the page list above has the rest.