Developer API

mintparse API

Convert PDFs to clean, AI-ready Markdown straight from your code — the same pipeline behind the web app. Every request draws from your prepaid credit balance, exactly like the playground.

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, and each conversion spends about 5 credits per page from your balance.

Base URL

https://mintparse.com/api/v1

Authentication

Create an API key on your account page. Send it as a Bearer token on every request:

Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep keys secret — anyone with a key can spend your credits. 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:

400 Bad request — not a PDF, unreadable, or over the page limit

401 Missing or invalid API key

402 Insufficient credit balance — load more credits

404 Job not found (or not owned by this key)

409 Job not finished yet — the result isn’t ready

413 PDF exceeds the size limit

429 Rate limit exceeded — slow down

Rate limits & usage

120 requests / minute per key.
Each conversion spends ~5 credits per page from your prepaid balance.
A document larger than your remaining balance returns 402 — load more credits.
Credits never expire, so unused balance carries forward indefinitely.

Ready to build? Create an API key →