Developer API

pdfmd.dev API v1

Send a text PDF, get Markdown and page metadata back as JSON. For English scanned PDFs, use the OCR endpoint. Both use the same page allowance, at one page credit per page. Free tier: 100 pages a day per IP without a key, up to 50 pages per file. Resident · Starter is $8.90 a month for 10,000 pages; see pricing.

Convert a file

curl -X POST https://pdfmd.dev/api/v1/convert \
      -F "file=@paper.pdf"

Convert from a URL

curl -X POST https://pdfmd.dev/api/v1/convert \
      -H "content-type: application/json" \
      -d '{"url": "https://arxiv.org/pdf/1706.03762"}'

Response

{
      "id": "sha256 prefix of the file",
      "parserVersion": "0.1.1",
      "title": "Attention Is All You Need",
      "pages": 15,
      "scannedPages": 0,
      "tables": 4,
      "chars": 41616,
      "ms": 5700,
      "pageBreaks": [0, 3120, ...],   // character offsets where each page starts
      "markdown": "# Attention Is All You Need\n\n..."
    }

Limits

An uploaded file can be up to 4 MB (4,000,000 bytes); a PDF fetched from a URL up to 50 MB. A result's JSON can be up to 4 MB: a larger one returns 422 result_too_large and uses none of your pages. Without a key, 50 pages per file; with a key, 400. This Markdown endpoint counts scanned pages in scannedPages without reading their image text; use POST /api/v1/ocr for OCR. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, counted in pages (X-RateLimit-Unit: pages). A file longer than your per-file cap returns 413; running out of pages returns 429. Both include a pricing link. Send a key as x-api-key; get one from pricing.

English OCR for scanned PDFs

POST /api/v1/ocr accepts an uploaded PDF or a public PDF URL. Set output to searchable_pdf or markdown; it defaults to markdown. English printed text only at launch. Existing text layers are kept, and image-only pages are read with OCR. Names, numbers, tables and unusual layouts need checking against the source.

curl -X POST https://pdfmd.dev/api/v1/ocr \
  -F "file=@scan.pdf" \
  -F "output=searchable_pdf" \
  --output scan.searchable.pdf

curl -X POST https://pdfmd.dev/api/v1/ocr \
  -H "content-type: application/json" \
  -d '{"url":"https://example.org/scan.pdf","output":"markdown"}'

For searchable_pdf, a successful response is PDF bytes with Content-Type: application/pdf, X-Pdfmd-Pages and X-Pdfmd-Ocr-Pages. Error responses are JSON. Check the HTTP status before saving a PDF.

For markdown, a successful response is the usual document JSON, plus operation: "ocr", output: "markdown", language: "eng" and ocrPages, the count of image-only pages processed by OCR. Both outputs carry X-Pdfmd-Rx: ocr.

OCR shares the existing API page allowance and API keys at one page credit per page, including pages that already have text. The same upload, public-link and per-file page caps apply. Each result must fit 4 MB; a larger result is refused. OCR requests have up to five minutes, so allow time in your client. A timeout or lost connection does not prove processing stopped or that allowance was unused; check GET /api/v1/me before retrying.

The free browser OCR tool shares the web converter's daily file allowance. OCR creates private temporary worker files that our code removes on success, failure and worker timeout. Results have no saved download URL. Privacy and processing · Measured OCR agreement and its limits.

Use PDFMD from an AI assistant

Add https://pdfmd.dev/mcp as a remote MCP server. The free tier needs no key. One tool, convert_pdf_url, converts a public PDF link using the same API allowance and safety checks.

Add to Claude Add to Cursor Add to VS Code

Claude Codeclaude mcp add --transport http pdfmd https://pdfmd.dev/mcp
Codexcodex mcp add pdfmd --url https://pdfmd.dev/mcp

Claude opens its Add custom connector dialog with the name and URL filled in: check both, continue, and choose no sign-in. ChatGPT has no install link: turn on developer mode (Settings, Apps, Advanced settings; available on some paid plans), then create an app with https://pdfmd.dev/mcp and no authentication.

Any other client that supports remote MCP: add the same URL as a Streamable HTTP server with no authentication. These connection settings do not mean PDFMD has been accepted into an app directory.

Replies contain up to 20,000 Markdown characters. Longer results are clearly marked as excerpts; the whole conversion uses your page allowance. For complete Markdown, use this website or the REST API, which starts another conversion and uses allowance again. There is no saved result link. This connector identifies scanned pages without OCR; for English scans, use the OCR REST endpoint. Local file paths or assistant attachments cannot be used as public links.

Assistant providers can share network addresses, so the anonymous allowance is not necessarily per person. Existing API keys work in clients that support request headers. A timeout does not prove conversion stopped; check your allowance before retrying. See connector privacy.

Your own standing

GET /api/v1/me

Returns whether you are calling anonymously or with a key, your page allowance, how much is left, and when it resets: daily at 00:00 UTC without a key, each billing period with one. Reading this does not use any of your allowance.

{
    "product": "pdfmd",
    "caller": "anon",
    "limitKind": "pages_day",
    "unit": "pages",
    "limit": 100,
    "remaining": 85,
    "used": 15,
    "maxPagesPerFile": 50,
    "resetIso": "2026-09-21T00:00:00.000Z",
    "persistent": true
  }

Privacy

A file goes to the conversion worker we run on Modal and the result comes back in the response. Ordinary text-to-Markdown conversion holds the file and result in memory only. OCR uses private temporary worker files that our code removes on success, failure and worker timeout. Neither gives a saved results URL. How long our hosting providers keep request logs we have not measured; privacy and processing has the detail. You keep every right to your documents.