Quickstart

This page gets you from a fresh API key to a first response, and points you at the right reference page for everything after that. It is deliberately minimal: one request per endpoint, no options.

The complete developer documentation — every request parameter, response field, error code, and code samples in cURL, Python, JavaScript and the SDK — lives at docs.mathpix.com. Once you have a response back, that is where to go next.

If you do not have a key yet, see Creating an API key. If you would rather click than write code, upload a file in the Playground — it runs the same two endpoints from your browser.

Every request carries two headers, app_id and app_key, from the API Keys tab of your organization on console.mathpix.com.

For client-side apps, do not ship the key — mint a short-lived app token instead. See Authentication for both patterns, and Authorization for when to pick which.

v3/text handles a single image of printed or handwritten math, text, tables, or diagrams, and returns the result synchronously.

curl -X POST https://api.mathpix.com/v3/text \
-H 'app_id: APP_ID' \
-H 'app_key: APP_KEY' \
-H 'Content-Type: application/json' \
--data '{"src": "https://mathpix-ocr-examples.s3.amazonaws.com/cases_hw.jpg"}'

The recognized content comes back as Mathpix Markdown in text, alongside confidence scores.

That is the smallest possible request. Form uploads, output formats, line and word data, alphabet detection, and the rest of the options are in Process an Image. For worked examples of what the API returns for math, handwriting, tables, chemistry and diagrams, see Examples.

v3/pdf accepts PDF, EPUB, DOCX, PPTX and other document formats, and runs asynchronously — you submit the document, then collect the result when it is ready.

curl -X POST https://api.mathpix.com/v3/pdf \
-H 'app_id: APP_ID' \
-H 'app_key: APP_KEY' \
-H 'Content-Type: application/json' \
--data '{"url": "https://cdn.mathpix.com/examples/cs229-notes1.pdf", "conversion_formats": {"docx": true}}'

The response returns a pdf_id. You then either poll for status or have Mathpix call you back when the document finishes, and download the formats you asked for.

Process a Document covers the whole flow: status polling, every output format, line-level JSON, page ranges, and streaming. Webhooks covers the callback alternative to polling.

mpxpy wraps authentication, polling, and downloads:

from mpxpy.mathpix_client import MathpixClient

client = MathpixClient(app_id="APP_ID", app_key="APP_KEY")

pdf = client.pdf_new(url="https://cdn.mathpix.com/examples/cs229-notes1.pdf", convert_to_docx=True)
pdf.wait_until_complete(timeout=60)
print(pdf.to_md_text())

Install it with pip install mpxpy. See Getting Started with the Python SDK for configuration, output formats, and error handling.

This guide and the developer docs do different jobs. Use whichever matches your question: