# 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.

## Product

PDF to Markdown converts PDFs into clean, LLM-ready Markdown using one server-side
conversion engine, 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/api/v2

1. Create a job
   POST /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 /v2/jobs/{id}
   Response: { "id": "job_...", "status": "queued|processing|ready|error",
               "pages": <int>, "truncated": <bool>, ... }

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

4. Delete a job (free a slot)
   DELETE /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, ... }
  - 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).
- Live values render on the pricing page from /api/v2/billing/plans.

## 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.
- 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.

## 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: support@pdf2md.dev