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

{
  "markdown": "string",
  "pages": 1,
  "request_id": "string"
}

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
}

Status codes

200: converted successfully.
400: invalid request shape.
401: missing or invalid API key.
422: invalid source URL or unreadable PDF.
429: rate limit or quota exceeded.
502: upstream OCR worker failed.
504: upstream OCR worker timed out.