# HTML to PDF API

Reference for Munition's HTML to PDF route: send self-contained HTML, get a public A4 PDF URL. Routes, input schema, output, price and limits.

Send a self-contained HTML document, with its CSS inline and its images as `data:` URIs, and get back an A4 PDF at a public URL. It suits reports, invoices, proposals and source lists that an agent writes as HTML. The route takes the HTML itself, not the URL of a web page.

## Routes and price

There is no MPP route for HTML to PDF.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/render/pdf` | `render_pdf_direct` | 0.02 |
| Account balance | MCP tool `render_pdf` | `render_pdf` | 0.02 |

## Input

Body of `POST /v1/render/pdf`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `html` | string | yes | — | A complete HTML document, at most 1 MiB in UTF-8, following the rules below. |
| `filename` | string | no | — | 1 to 180 characters, without `..` anywhere. Used for a readable URL, such as `invoice-2026-09.pdf`. |

Any other field is refused with `400`.

### What the HTML may contain

- **Allowed:** HTML and inline CSS, with images and fonts embedded as `data:` URIs (PNG, JPEG, GIF, WebP and SVG images; WOFF, WOFF2, TTF and OTF fonts), and links to `#fragments` of the same document.
- **Refused:** `<script>`, `<iframe>`, `<frame>`, `<object>`, `<embed>`, `<applet>`, `<base>`, `<form>`, `<link>`, `<meta http-equiv>`, active SVG (`animate`, `set`, `use`, `foreignObject`), `srcset`, inline event handlers such as `onclick=`, `javascript:` URLs, CSS `@import`, CSS `image()` and `image-set()`, any `src`, `href` or `url()` that is not a `data:` URI or a `#fragment` (relative paths included), and any backslash.

The renderer runs with JavaScript disabled, offline, and aborts every request the document makes.

## Response

Response of `POST /v1/render/pdf`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | The render id. |
| `publicUrl` | string | yes | The PDF's public URL, on `files.munition.io`. |
| `expiresAt` | string | yes | When the PDF becomes eligible for deletion, 7 days after the render. |
| `bytes` | integer | yes | The PDF's size in bytes. |
| `pages` | integer | yes | The number of A4 pages. |
| `sha256` | string | yes | The lowercase hex SHA-256 of the PDF. |
| `renderMs` | integer | yes | The render time in milliseconds. |

## Limits

- **Input:** 1 MiB of HTML.
- **Output:** A4, at most 20 pages and 10 MiB, rendered within a 10-second budget. These limits can only be checked once the PDF is rendered, which is after payment: a document that breaks them fails with `503 render_effect_pending` and the payment is kept. Split a long document into several PDFs.
- **The URL is public.** It cannot be guessed, but anyone with it can open the PDF: do not render confidential content.
- **Retention:** `expiresAt` is when the PDF becomes eligible for deletion, not an exact cutoff: cleanup runs later and cached copies can last longer. A PDF cannot be renewed, unlike an upload.
- **Validation order:** a request without a payment header gets the `402` without its body being read, so the challenge says nothing about your HTML. A paid request is checked (JSON, schema, forbidden content) before its payment is verified, so a `400` costs nothing.
- **The 400 body** of this route has `reason` (`invalid_json`, `invalid_input` or `forbidden_html`), up to three `issues` with a `path` and a `rule`, and a minimal valid `example`. It never echoes your HTML.

## Example

Called without payment, the route answers `402` with the price in the `PAYMENT-REQUIRED` header. Sign the payment and send the request again as in [Copy-paste examples](/docs/payments/examples), with the same `Idempotency-Key` for every retry of this render.

```bash
curl -sS -i https://api.munition.io/v1/render/pdf \
  -H 'Content-Type: application/json' \
  --data '{"html":"<h1>Report</h1><p>Generated by an agent.</p>","filename":"report.pdf"}'
```

Paid, it costs 0.02 USDC and answers `200`. A response of `POST /v1/render/pdf` looks like this:

```json
{
  "id": "pdf_example",
  "publicUrl": "https://files.munition.io/render/pdf_example-report.pdf",
  "expiresAt": "2026-09-15T00:00:00.000Z",
  "bytes": 1000,
  "pages": 1,
  "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
  "renderMs": 100
}
```

To retry this route safely, send the identical request: the same payment header, `Idempotency-Key` and body. If a render fails after payment, do not pay again: see [Errors and refunds](/docs/payments/errors#when-payment-settles-but-the-service-fails).
