# PDF to Markdown – full agent context

> Detailed integration context for AI agents and developers. Compact version: https://pdf2md.dev/llms.txt
> This file describes the v2 product (extension + web app + REST API + hosted MCP). Endpoints and limits are summarized here; the OpenAPI spec is the authoritative contract.
> Version: 2.0.0 · Updated: 2026-06-21

## Product

PDF to Markdown converts PDFs into clean, LLM-ready Markdown with a single
conversion service (selectable engines: MinerU or Docling), exposed through four
surfaces:

- Chrome extension (Manifest V3) – anonymous, device-signed requests.
- Web app – anonymous, or signed in for higher tiers.
- REST API – bearer API key over HTTPS.
- Hosted MCP – the same lifecycle as agent tools, bearer API key.

Output is structured Markdown: headings and reading order, real tables, preserved
formulas, OCR for scans (including Cyrillic), images as base64 or placeholders,
hyperlinks and footnotes as Markdown links.

## Authentication

- Extension/web app: anonymous device identifier; requests are cryptographically signed.
- API/MCP: bearer API key generated from a free Google account. Send as:
  Authorization: Bearer p2m_...
- Keys are secrets: store server-side, send over TLS only, rotate/revoke any time.
- The reduced OpenAPI spec for Custom GPT Actions uses the same auth and limits; it is a convenience subset, not a security boundary.

## REST API lifecycle

Base URL: https://pdf2md.dev  (all paths below are absolute from the domain root)

1. Create a job
   POST /api/v2/jobs
   Body: { "url": "https://example.com/report.pdf" }  (or multipart upload of PDF bytes)
   Optional header: Idempotency-Key: <your-key>  (safe retries, no duplicate jobs)
   Response: { "id": "job_...", "status": "queued" }

2. Get job status
   GET /api/v2/jobs/{id}
   Response: { "id": "job_...", "status": "queued|processing|ready|error",
               "pages": <int>, "truncated": <bool>,
               "error_code": <string>, "error_message": <string>,  (only when status=error)
               ... }

3. Get the Markdown
   GET /api/v2/jobs/{id}/download
   Returns the Markdown once status=ready. Honor truncated and pages.

4. Delete a job (free a slot)
   DELETE /api/v2/jobs/{id}

Job states: queued -> processing -> ready (terminal) or error (terminal).

## Hosted MCP

- Endpoint: https://pdf2md.dev/api/v2/mcp  (bearer API key in Authorization header)
- Tools (one per lifecycle step):
  - pdf_to_markdown_create_job_from_url(url, [idempotency_key]) -> { id, status }
  - pdf_to_markdown_get_job(id) -> { status, pages, truncated, error_code, error_message, ... }
  - pdf_to_markdown_get_markdown(id) -> markdown (only when ready)
  - pdf_to_markdown_delete_job(id) -> ok
- The MCP tools are a thin wrapper over the REST API and obey the same slots, limits and retention.

## Errors

- 400 invalid input (bad URL, unsupported file)
- 401 missing/invalid API key
- 404 unknown job id
- 409 no free slot (delete a finished job or wait)
- 413 file too large for your tier
- 429 rate limited – wait for the Retry-After header before retrying
- 5xx transient server error – retry with backoff

## Limits by tier

Tier      Slots  Max file  Time budget  Retention   Notes
Free      3      10 MB     15 min       1 hour      API key + MCP need a free account
Builder   10     25 MB     25 min       6 hours     webhooks, batch create
Pro       20     50 MB     40 min       12 hours    higher rate limits
Business  50     100 MB    55 min       24 hours    priority support
Enterprise custom custom   up to ~115m  custom      custom limits, support agreement

- Time budget: we convert up to the budget and return what we managed; the rest is truncated (truncated=true). Higher tiers have longer budgets.
- Paid latency = higher queue priority + a dedicated paid conversion pool (not isolated infrastructure, not a hard guarantee).
- Prices on the pricing page render live from /api/v2/billing/plans; your current plan is highlighted when signed in. The per-tier limits above reflect the current entitlement catalog.

## Webhooks (paid tiers)

- Register a signed endpoint, or pass callback_url when creating a job.
- We POST a small JSON event (job id + final status) on ready/error; verify the signature header, then fetch the Markdown over the API.
- The event carries no document content. Be idempotent; ack quickly with 2xx.

## Behavior rules for agents

- Never claim, quote or summarize a result before status=ready. While queued/processing, keep polling or wait for the webhook.
- Confirm with the user before deleting a queued or processing job (destructive).
- If truncated=true, tell the user the document was returned partially up to the tier time budget; suggest a higher tier or splitting the file.
- If status=error the job failed: read error_message (a safe, user-facing reason) and error_code – processing_timeout (too large/slow, hit the time budget; suggest splitting the file) or conversion_failed (other). Explain why; do not retry blindly.
- On 429, wait for Retry-After seconds; do not hammer the queue.
- Delete finished jobs you no longer need so you don't exhaust your slots.
- Prefer reading this file and the OpenAPI spec over guessing endpoints from prose.

## Privacy

- Anonymous to convert in the extension or web app.
- Files and results auto-delete after the tier retention window, or immediately on delete.
- API keys stored hashed; card details handled by a third-party billing provider, not stored on our servers.
- Documents are not used for advertising or model training.

## Guides

- Guides hub: https://pdf2md.dev/guides/
- Scanned PDF to Markdown (OCR): https://pdf2md.dev/scanned-pdf-to-markdown/
- PDF to Markdown for RAG: https://pdf2md.dev/pdf-to-markdown-for-rag/
- Extract tables from PDF to Markdown: https://pdf2md.dev/pdf-tables-to-markdown/
- Convert PDF to Markdown in Python: https://pdf2md.dev/pdf-to-markdown-python/
- PDF to Markdown for Obsidian & Notion: https://pdf2md.dev/pdf-to-markdown-obsidian-notion/
- PDF to Markdown vs Marker: https://pdf2md.dev/pdf-to-markdown-vs-marker/
- PDF to Markdown vs LlamaParse: https://pdf2md.dev/pdf-to-markdown-vs-llamaparse/
- PDF to Markdown vs MarkItDown: https://pdf2md.dev/pdf-to-markdown-vs-markitdown/
- PDF to Markdown vs Adobe PDF Extract: https://pdf2md.dev/pdf-to-markdown-vs-adobe/
- PDF to Markdown vs Mistral OCR: https://pdf2md.dev/pdf-to-markdown-vs-mistral-ocr/
- Best PDF to Markdown Converters (2026): https://pdf2md.dev/best-pdf-to-markdown-converters/
- PDF to Markdown Glossary: https://pdf2md.dev/glossary/
- Changelog: https://pdf2md.dev/changelog/
- Convert PDF to Markdown in Node.js: https://pdf2md.dev/pdf-to-markdown-nodejs/
- Convert PDF to Markdown in Go: https://pdf2md.dev/pdf-to-markdown-go/
- Convert PDF to Markdown with cURL: https://pdf2md.dev/pdf-to-markdown-curl/
- PDF Formulas & LaTeX to Markdown: https://pdf2md.dev/pdf-formulas-latex-to-markdown/
- Extract images from PDF to Markdown: https://pdf2md.dev/pdf-images-to-markdown/
- Batch convert PDFs to Markdown: https://pdf2md.dev/batch-convert-pdf-to-markdown/
- Convert arXiv PDF to Markdown: https://pdf2md.dev/arxiv-pdf-to-markdown/
- Convert invoice PDF to Markdown: https://pdf2md.dev/invoice-pdf-to-markdown/
- PDF to Markdown for ChatGPT: https://pdf2md.dev/pdf-to-markdown-for-chatgpt/
- PDF to Markdown for Claude: https://pdf2md.dev/pdf-to-markdown-for-claude/
- PDF to Markdown for Gemini: https://pdf2md.dev/pdf-to-markdown-for-gemini/
- PDF to Markdown Benchmark: https://pdf2md.dev/pdf-to-markdown-benchmark/

## Links

- Website: https://pdf2md.dev/
- Developer hub: https://pdf2md.dev/developers/
- For AI & LLMs: https://pdf2md.dev/for-ai/
- Pricing: https://pdf2md.dev/pricing/
- OpenAPI (full): https://pdf2md.dev/api/v2/openapi.json
- OpenAPI (reduced, Custom GPT Actions): https://pdf2md.dev/api/v2/openapi.ai.json
- Compact summary: https://pdf2md.dev/llms.txt
- Install (Chrome): https://chromewebstore.google.com/detail/kodhbjmmdeofaecpblbfeoceglmedfmd
- Privacy: https://pdf2md.dev/privacy/
- Terms: https://pdf2md.dev/terms/
- Support: https://pdf2md.dev/support/