SCS

scs is the Mathpix OCR and document API on api.mathpix.com. Its commands wrap the v3 endpoints.

Convert one document to one output, or a folder of documents to a folder of outputs.

A single file. The output path’s extension picks the format:

mpx scs convert paper.pdf paper.mmd
mpx scs convert paper.pdf paper.docx
mpx scs convert notes.md notes.docx
mpx scs convert equation.png equation.mmd

convert routes by input: a .md/.mmd source goes through /v3/converter; a single image with a
text-style output (.mmd, .txt, .html, .tex, .json) goes through the synchronous /v3/text;
any other document, including an image asked for a rich format like .docx, goes through /v3/pdf. A
remote source works too: pass a URL in place of the input path.

A folder. SRC and DST are directories, and --map says which input extensions to convert and
to what:

mpx scs convert ./in/ ./out/ --map pdf:docx,md:docx
mpx scs convert ./in/ ./out/ --map pdf:docx+mmd,tiff:mmd

Multiple formats for one input are joined with +. Without --map, every supported document is
converted to mmd. Files convert in parallel (--concurrency, default 4), one progress line each,
and a report is written to SRC/_mathpix/<run>/report.jsonl. Outputs that already exist are skipped,
so a re-run resumes where an interrupted one stopped.

Flags: --map, --concurrency, --page-ranges, --rm-spaces, --include-equation-tags, and
--options-json (below).

Common options have flags; every other option is reachable with --options-json, a JSON object
merged into the request, including nested conversion_options:

mpx scs convert paper.pdf paper.mmd --options-json '{"rm_fonts": true, "include_chemistry": true}'
mpx scs convert book.pdf book.mmd.overlay.pdf --options-json '{"conversion_options": {"mmd.overlay.pdf": {"pdf_ua": 2}}}'

mpx scs get PDF_ID                 # processing status; add --output json for the raw object
mpx scs download PDF_ID docx -o paper.docx   # fetch one format of a submitted document
mpx scs delete PDF_ID              # permanently delete a document's outputs and input

--async submits through the Files API (/files/v1) instead of /v3/pdf. Use it to write results
straight to your own bucket with --destination, or to submit from a registered data source:

mpx scs convert report.pdf report.mmd --async --destination s3://acme-docs/out/
mpx scs convert s3://acme-docs/in/report.pdf report.mmd --async

A local file is uploaded; a URL or s3:///gs:///Azure source is submitted by reference (bucket
sources need a registered data source, see below). For processing many documents at once, use the
batch jobs below; to convert a local folder, plain convert on a directory already runs in parallel.

Get notified when a document finishes, on any convert (sync or --async):

mpx scs convert paper.pdf paper.mmd \
  --webhook-url https://hooks.example.com/mathpix \
  --webhook-event file.completed --webhook-event file.error \
  --webhook-header 'Authorization=Bearer TOKEN'

Deliveries are signed. Manage the secret you verify them against:

mpx scs webhooks config              # show (creating on first call) the signing secret
mpx scs webhooks rotate-secret [--force]
mpx scs webhooks test https://hooks.example.com/mathpix   # send one signed test delivery

Convert many documents in one call through the Files API:

mpx scs jobs create --uri s3://acme-docs/a.pdf --uri s3://acme-docs/b.pdf --formats docx
mpx scs jobs list
mpx scs jobs get JOB_ID
mpx scs jobs files JOB_ID --status error
mpx scs jobs finalize JOB_ID         # close to new files so job.completed can fire

Register a bucket so the Files API can read from, and write to, it:

mpx scs data-sources identities      # Mathpix's grant identities + your external_id, for the bucket's trust policy
mpx scs data-sources register --config '{"provider":"s3","bucket":"acme-docs","region":"us-east-1","role_arn":"arn:aws:iam::..."}'
mpx scs data-sources list
mpx scs data-sources test ID
mpx scs data-sources delete ID

mpx scs app-token [--expires 300] [--strokes]   # a short-lived token for direct client-side v3/text calls
mpx scs results [--pdf]                          # past image results, or document results with --pdf
mpx scs usage --timespan day --group-by usage_type   # aggregated usage for billing

Always generated and downloadable directly: mmd, lines.json, lines.mmd.json. Requested as
conversion formats: md, docx, tex.zip, html, pptx, xlsx, pdf, latex.pdf,
mmd.overlay.pdf, and the .zip bundles. The CLI requests whatever format your output extension
names and waits for it to finish converting before downloading.