Endpoint

POST /v1/convert

Prefer the terminal? The official CLI wraps this endpoint: npx pdftomarkdown document.pdf — see the CLI guide.

Authentication

Send Authorization: Bearer <api_key>. The public demo key is shown in the main docs and converter, but production usage should use a Developer key.

Input schema

{
  "input": {
    "pdf_url": "https://pdftomarkdown.dev/samples/invoice.pdf",
    "pdf_base64": "JVBERi0x...",
    "include_raw": false,
    "max_pages": 3
  }
}

Provide exactly one of pdf_url or pdf_base64.

Success schema

{
  "complete": true,
  "markdown": "# CONTOSO LTD.\n\n# INVOICE\n\nINVOICE: INV-100\nDATE: 11/15/2019\nDUE DATE: 12/15/2019\n\n| SALESPERSON | P.O. NUMBER | REQUISITIONER | SHIPPED VIA | F.O.B. POINT | TERMS |\n| --- | --- | --- | --- | --- | --- |\n|  | PO-3333 |  |  |  |  |\n\n| QUANTITY | DESCRIPTION | UNIT PRICE | TOTAL |\n| --- | --- | --- | --- |\n| 1 | Test for 23 fields | $100.00 | $100.00 |\n\nTOTAL DUE: $610.00\n\n> Processed by pdfToMarkdown.dev",
  "pages": 1,
  "request_id": "req_example_invoice"
}

A success always has complete: true. Simple rectangular HTML tables are converted to escaped GFM pipe tables. Complex tables with spans or nested content remain sanitized CommonMark-compatible raw HTML to avoid losing structure.

Error schema

{
  "error": "rate_limited",
  "message": "Free Hacker-tier limit reached (3 requests per minute per IP). Retry shortly, or get a free API key with higher limits at https://pdftomarkdown.dev/auth/github.",
  "request_id": "req_rate123",
  "retry_after_seconds": 60
}

If the complete canonical payload exceeds the response budget, the endpoint fails explicitly:

{
  "error": "response_too_large",
  "message": "The complete OCR result exceeds the response size limit. Set input.max_pages or split the PDF into smaller documents.",
  "docs": "https://pdftomarkdown.dev/docs/",
  "request_id": "req_large123",
  "pages": 25,
  "max_response_bytes": 3500000,
  "response_bytes": 3900000
}

Status codes

200: converted successfully.
400: invalid request shape.
401: missing or invalid API key.
422: invalid source URL or unreadable PDF.
413: complete response exceeds the size limit (response_too_large).
429: rate limit or quota exceeded.
502: upstream OCR worker failed.
504: upstream OCR worker timed out.