mintparse API

Overview

The API is a thin wrapper over the conversion pipeline: upload a PDF, poll the job, fetch the Markdown or a zipped bundle. Every request is authenticated with an API key. Conversions draw from your subscription's monthly page quota, falling back to your prepaid wallet — exactly like the web app.

Authentication

Create an API key on your account page (Pro or Max plan). Send it as a Bearer token on every request:

Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep keys secret — anyone with a key can spend your quota. Revoke a key anytime from your account page.

Convert a document

POST /api/v1/convert

Upload a single PDF as multipart form data under the field file. Returns a job id to poll. Conversion runs asynchronously (~1–4 min).

curl -X POST https://mintparse.com/api/v1/convert \
  -H "Authorization: Bearer $MINTPARSE_KEY" \
  -F "file=@paper.pdf"

Response · 202

{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "pages": 12
}

Check job status

GET /api/v1/jobs/{job_id}

Poll every few seconds. status is one of queued, processing, done, failed.

{
  "job_id": "a1b2c3d4-...",
  "status": "processing",
  "filename": "paper.pdf",
  "pages": 12,
  "progress_pct": 64,
  "error": null
}

Get the result

Once status is done, fetch the Markdown directly, or download a zip bundle (Markdown + extracted images).

GET /api/v1/jobs/{job_id}/markdown — returns text/markdown

GET /api/v1/jobs/{job_id}/download — returns a .zip bundle

Full example

A complete convert-poll-fetch loop in bash:

KEY="mp_live_..."
BASE="https://mintparse.com/api/v1"

# 1. Submit
JOB=$(curl -s -X POST "$BASE/convert" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@paper.pdf" | jq -r .job_id)

# 2. Poll until done
while :; do
  S=$(curl -s "$BASE/jobs/$JOB" -H "Authorization: Bearer $KEY" | jq -r .status)
  [ "$S" = "done" ] && break
  [ "$S" = "failed" ] && { echo "conversion failed"; exit 1; }
  sleep 5
done

# 3. Fetch the Markdown
curl -s "$BASE/jobs/$JOB/markdown" -H "Authorization: Bearer $KEY" -o paper.md

Errors

Errors return a JSON body {"detail": "..."} with these status codes:

Rate limits & usage

• · Pro — 120 requests/minute
• · Max — 600 requests/minute
• · Pages convert against your monthly plan quota first, then your prepaid wallet.
• · A document over your remaining quota + wallet returns 402 — top up your wallet or upgrade.

Ready to build? Create an API key →