API documentation

Base URL: https://pdfoven.com. All requests use JSON and an API key from your dashboard.

Authentication

Send your key as a bearer token: Authorization: Bearer po_live_…. The X-API-Key header also works.

POST /v1/pdf

Renders a PDF. Provide exactly one source:

`html`	An HTML string. Fragments are wrapped in a document with sensible base styles.
`markdown`	A Markdown string (GitHub-flavored).
`url`	A public http(s) URL to capture.
`template` + `data`	An inline Handlebars template and the JSON to fill it with.
`template_id` + `data`	A template saved in your dashboard. If `data` is omitted, its sample data is used.

Optional fields:

`css`	Extra CSS appended to the document.
`options.format`	`A4` (default), `Letter`, `Legal`, `A3`, `A5`, `Tabloid`
`options.landscape`	Boolean, default `false`.
`options.margin`	Uniform margin such as `"0.5in"`, `"12mm"` or `"20px"`.
`options.print_background`	Print background colors and images. Default `true`.
`options.header_template` / `footer_template`	HTML for a repeating header/footer. Use `<span class="pageNumber"></span>` and `<span class="totalPages"></span>`. Requires a margin so it has room.
`options.scale`	0.1 – 2.
`wait_for_selector`	Wait for a CSS selector before rendering, for pages that draw charts with JavaScript.
`timeout_ms`	1,000 – 60,000. Default 30,000.
`response`	`"binary"` (default) returns the file. `"base64"` returns JSON `{ "data": "…", "content_type": "application/pdf", "bytes": 1234 }`.
`filename`	Sets the `Content-Disposition` filename.

curl https://pdfoven.com/v1/pdf \
  -H "Authorization: Bearer $PDFOVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello, PDF</h1>","options":{"format":"Letter","margin":"0.5in"}}' \
  --output hello.pdf

POST /v1/image

Takes the same sources as /v1/pdf and returns a PNG. Call /v1/image?type=jpeg for a JPEG instead. Image options in options: width, height, full_page, device_scale_factor (1–3) and quality (JPEG only). Useful for social share images and certificates.

curl "https://pdfoven.com/v1/image" \
  -H "Authorization: Bearer $PDFOVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"<div style=\"padding:60px;font:700 64px sans-serif\">{{title}}</div>","data":{"title":"Launch day"},"options":{"width":1200,"height":630}}' \
  --output og.png

Templates

Templates are HTML with Handlebars placeholders, plus optional CSS and default page options. Create them in the dashboard with a live preview, or via the API. Markdown templates are also supported.

Built-in helpers:

`{{formatCurrency amount "EUR"}}`	Formats money. Defaults to USD.
`{{formatNumber value 2}}`	Fixed decimals.
`{{formatDate issued_at "medium"}}`	short / medium / long / full.
`{{sum items "amount"}}`	Sums a field across an array.
`{{lineTotal items "qty" "price"}}`	Sum of qty × price across an array.
`{{multiply a b}}`, `{{add a b}}`	Arithmetic.
`{{#if (eq status "paid")}}`	Equality checks.
`{{upper text}}`	Uppercase.

GET /v1/templates

Lists your templates.

POST /v1/templates

{
  "name": "Invoice",
  "engine": "handlebars",
  "content": "<h1>Invoice {{number}}</h1>",
  "css": "h1 { color: #c8155f }",
  "sample_data": { "number": "INV-1" },
  "page_options": { "format": "Letter", "margin": "0.5in" }
}

GET /v1/usage

Returns your plan, limit and renders used this calendar month (UTC).

{ "plan": "starter", "period": "2026-10", "used": 412, "limit": 2000 }

Errors

Errors are JSON: { "error": { "code": "quota_exceeded", "message": "…" } }

400	`invalid_request` — the body failed validation.
401	`unauthorized` — missing or invalid API key.
404	`template_not_found`
422	`template_error` or `render_failed` (blocked URL, timeout, HTTP error).
429	`quota_exceeded` — monthly limit reached. Failed renders don't count.

MCP server for AI agents

PDFOven speaks the Model Context Protocol over Streamable HTTP at https://pdfoven.com/mcp. Agents get three tools: render_pdf, render_image and list_templates. Rendered files come back as embedded resources.

Claude Code:

claude mcp add --transport http pdfoven https://pdfoven.com/mcp \
  --header "Authorization: Bearer $PDFOVEN_KEY"

Cursor / other clients (mcp.json):

{
  "mcpServers": {
    "pdfoven": {
      "url": "https://pdfoven.com/mcp",
      "headers": { "Authorization": "Bearer po_live_..." }
    }
  }
}

Limits

HTML up to 5 MB per request; render timeout up to 60 seconds.
URL rendering is limited to public addresses.
Rendered files are not stored.