Skip to main content

Files API overview

What is the Files API​

The Mathpix Files API is a high-throughput, asynchronous document processing API. It's designed for large-scale workloads — converting whole document archives, running continuous ingestion pipelines, or batching up to 200,000 files in a single call — at a lower per-page cost than v3/pdf.

When to use Files API vs v3/pdf​

v3/pdf (Mathpix OCR API)Files API
Use it forReal-time, per-document processing in interactive appsProcessing existing document archives, one-time conversion of large PDF collections, continuous high-volume pipelines, data-wall workloads
SubmissionOne document per requestOne document, or batches of up to 200,000 files per /jobs call
Result deliveryPolled from Mathpix-hosted URLsPolled from Mathpix-hosted URLs or written directly to your S3 / GCS / Azure bucket
Per-page priceFlat — see pricing$1.50 / 1,000 pages below 30M/month; $1.00 / 1,000 pages above
Single-document latencyLower (optimized for interactive)Higher per document — but a million-document workload completes far sooner

How it works​

Every Files API workflow is the same three steps, whether you submit one document or 200,000:

  1. (Optional) Connect your storage. Register a data source once to read inputs from — and write results back to — your own S3, GCS, or Azure bucket. Skip this if you only submit public/presigned https:// URLs.
  2. Submit. Send one document with POST /files/v1/uri (or a direct upload with POST /files/v1), or a batch with POST /files/v1/jobs. Submission returns immediately — processing happens asynchronously.
  3. Poll, then collect. Poll the file or job for completion, then download outputs (mmd, docx, tex.zip, …) — or, if you set a destination_uri, have them written straight to your bucket.

Core concepts​

  • file_id — the handle for a single document, returned by every submission. Use it to poll status and download results: see Async Document Lifecycle.
  • job_id — groups many files submitted together so you can track and list them as a unit: see Async Batch Document Processing.
  • custom_id — your own per-file identifier, echoed back in job listings so you don't have to track Mathpix's file_ids. Paired with a job_id, it also makes submission idempotent (safe to retry).
  • Data sources — the keyless grant that lets Mathpix read from and write to your cloud storage. No credentials are shared; you grant access via IAM role (AWS), AD app (Azure), or service-account impersonation (GCS): see Data Sources.

Looking for the product pitch — pricing, positioning, and why teams choose the Files API? See mathpix.com/files-api.

Webhooks​

Pass a callback_url on any submission, and Mathpix sends a signed HTTP POST request to that URL when a document or batch reaches its final state (file.completed, file.error, job.completed). Polling keeps working exactly as before, and the notification bodies carry the same state the polling endpoints return. The webhooks guide is the step-by-step integration, and the webhooks reference is the endpoint-by-endpoint contract.

Next steps​