Choosing a PDF API: 7 questions to ask before you commit

Every PDF generation API looks the same on the landing page: send HTML or a URL, get back a PDF. The differences that actually cost you money and engineering time show up later — in the invoice, in a rendering bug three months in, or in a rate-limit wall during your busiest week. Here are the seven questions worth asking before you pick one, and why each one matters.

1. Is pricing per page or per document?

Per-page pricing punishes exactly the workloads that make PDF generation valuable: multi-page invoices, long reports, contracts with schedules attached. A 12-page report costs 12x what a 1-page receipt costs, even though the render is a single API call either way. Per-document pricing charges for the call, not the content — you can generate a 40-page report and a one-page receipt for the same price. If you're evaluating vendors, run your actual document mix through a PDF cost calculator rather than trusting the sticker price on the pricing page. Docweave prices per document for this reason; see the breakdown on the pricing page.

2. What input sources does it accept?

Three source types cover almost every real use case: raw HTML (you control the markup, most flexible), a URL (render an existing page as-is, useful for public reports or dashboards), and a template plus JSON (store a layout once, fill it with data per request — the right shape for invoices and certificates generated in bulk). If a vendor only supports one of these, you'll eventually hit a workflow it can't handle. Check the glossary entry on HTML-to-PDF APIs if you want the full taxonomy, and look at how each vendor documents the template+JSON path specifically — it's the one most likely to be underbaked or bolted on later.

3. What rendering engine is under the hood, and how faithful is it?

This is the question people skip and regret. A PDF API is only as good as its rendering engine's fidelity to real CSS — flexbox, grid, web fonts, @media print rules, page-break control. Engines built on real Chromium (via Playwright or Puppeteer) render the same way your browser does, because it is your browser. Lighter-weight or custom engines built to avoid the Chromium footprint often diverge on exactly the CSS features you'll want for a polished invoice or report: multi-column layouts, custom fonts, precise page breaks. Ask for a live sample render of a document with the CSS features you actually use — not the vendor's demo template. See headless Chromium PDF generation for what a Chromium-backed pipeline looks like end to end, and programmatic PDF generation for the broader landscape.

4. Does it support AI agents and MCP natively?

If you're building or plan to build agent workflows — an AI assistant that drafts a report and needs to export it, an automation that generates a contract from a conversation — a REST-only API means writing a custom tool wrapper yourself, and re-writing it every time the schema shifts. An API with a first-class MCP server means an agent can call generate_pdf directly with no glue code. Docweave ships an open-source MCP server (npx @docweave/mcp) alongside the REST API; a minimal call looks like this:

await generate_pdf({
  source: { type: "html", html: "<h1>Contract Draft</h1><p>...</p>" },
  outputPath: "./contract.pdf"
});

If a vendor's "AI support" turns out to be a blog post about prompting ChatGPT to write your HTML, that's not the same thing — check whether the MCP server is real, maintained, and open source. More on this on PDF generation for AI agents.

5. Does it support idempotency keys?

Networks retry. Clients time out and resend. Without an idempotency key, a retried request can render — and bill — the same document twice. Pass a stable idempotencyKey per logical request and a well-built API will return the original result instead of re-rendering:

curl https://docweave.dev/api/v1/pdf \
  -X POST \
  -H "Authorization: Bearer dw_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/pdf" \
  --output invoice.pdf \
  -d '{
    "source": { "type": "html", "html": "<h1>Invoice #1042</h1>" },
    "idempotencyKey": "invoice-1042-attempt-1"
  }'

This matters most for anything billed per-render or triggered by webhooks — invoices, receipts, contracts. Ask specifically whether idempotency is enforced server-side or left to you to dedupe on your end.

6. What are the rate limits and concurrency model?

Rendering is CPU- and memory-heavy — a real browser is running per request. That means rate limits and concurrent-render caps are real constraints, not arbitrary throttles. Ask what happens at your expected peak: end-of-month invoice runs, a bulk certificate batch after a course cohort finishes, a report export triggered by every user at 9am. Get the actual numbers (requests/minute, concurrent renders, queueing behavior on burst) rather than accepting "generous limits" as an answer.

7. Hosted, self-host, or both?

A hosted API is the fastest path to shipping — no browser binaries to manage, no egress isolation to build yourself (URL-to-PDF is an SSRF vector, and running it safely takes real infrastructure work). But it's worth knowing whether there's a self-host or open-source escape hatch if the vendor shuts down, changes pricing dramatically, or you need to run inside a network the vendor can't reach. An open-source MCP server you can run yourself is one form of this; full self-hosted rendering is another, heavier one. Weigh this against how much infrastructure work you're actually willing to own — for most teams, hosted is the right trade, but going in with eyes open matters.

Putting it together

None of these questions require the vendor to be perfect — they require the vendor to be honest about tradeoffs. A per-page pricing model isn't a scam if you mostly generate one-page receipts. A non-Chromium engine isn't a dealbreaker if your documents are plain text. What matters is knowing which tradeoffs you're accepting. If you want a broader side-by-side, our guide to picking a PDF generation API covers more vendors in more depth, and the alternatives to PDFShift and alternatives to DocRaptor pages go deeper on two specific well-known options if you're already comparing against them.

For reference, the full Docweave API docs show the REST and MCP surfaces side by side, including source types, template handling, and error shapes — worth skimming even if you end up choosing something else, just to have a baseline to compare against.