# Stolid PDF: HTML to PDF API

Turn HTML into a PDF, with a render report your code can read. Generate invoices, statements and reports from the HTML you already have. Each successful render returns the PDF and stable warning codes for detected font, asset, script and overflow issues.

`POST https://api.stolid.dev/v1/pdf`. Free public preview, with keys by email: [request access](https://stolid.dev/access/) or read the [quickstart](https://stolid.dev/docs/quickstart/). Try one template with sample data and attach the files it needs. Up to 20 pages, 30 seconds and a 6 MB request; remote file loading is off.

## A request goes in. A PDF and a render report come out.

The JSON for a successful render includes `pdf_url` and `manifest.warnings`. If `POST /v1/pdf` answers `202`, the render is still running: poll `GET /v1/renders/{render_id}` until it finishes. If you ask for the PDF file itself with `?response=binary`, use that same GET to read the full report.

```bash
curl https://api.stolid.dev/v1/pdf \
  -H "Authorization: Bearer stolid_live_…" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Invoice 0042</h1> …"}'
```

```json
"manifest": {
  "warnings": [
    { "code": "FONT_FALLBACK", "message": "…" },
    { "code": "REQUEST_BLOCKED", "message": "…" },
    { "code": "CONTENT_OVERFLOW", "message": "…" }
  ]
}
```

## Useful feedback, even when the PDF succeeds

Each warning has a stable code and a message. Read `FONT_FALLBACK` to find substituted fonts, `ASSET_FAILED` to find missing files and `CONTENT_OVERFLOW` to find content that runs past the page. Your application decides which warnings need a fix or a review. Codes keep their meaning; new codes may be added over time.

| Code | What it means | What to do |
| --- | --- | --- |
| `FONT_FALLBACK` | A font you asked for is not available; a similar one was used | Send the font file with the request, or choose an available font |
| `FONT_FACE_FAILED` | A font file you declared with `@font-face` could not be used | Check the font file and its name in `assets` |
| `ASSET_FAILED` | A file was missing from `assets` or failed to load | Add the file, or correct its name in the HTML |
| `REQUEST_BLOCKED` | A file request was blocked | Send remote files in `assets` |
| `CONTENT_OVERFLOW` | Content extends past the page width or a clipping container | Let the content wrap, or reduce its width |
| `SCRIPT_ERROR` | A script in your page raised an error | Fix the script, or remove it from the document |

The report lists detected issues. An empty list does not guarantee a correct layout, and some print CSS differences produce no warning. Check the PDF as well. See the [warning-code reference](https://stolid.dev/docs/warning-codes/) and the [print CSS notes](https://stolid.dev/docs/page-options/).

## Made for short documents from your own HTML

One call renders one document. A render counts when it succeeds, including a render with warnings. A failed render does not count.

- Pages: 20 pages per document, at most.
- Time: 30 seconds of render time per call, at most.
- Request: 6 MB in total, including attached files.
- Files: attached. Send CSS, images and fonts in `assets`. Remote file loading is off during the preview.

Stolid PDF suits invoices, statements and reports generated from HTML and attached files. If you need to capture a live web page, produce documents longer than 20 pages or rely on specialised print CSS, read [Files and fonts](https://stolid.dev/docs/files-and-fonts/) and [Page options](https://stolid.dev/docs/page-options/) before you start.

## Python and Node clients

A few lines to render a document and read its warnings. Both clients wait for running renders, retry temporary errors and encode your files for you. The package files come with your preview key email; publication on PyPI and npm is coming soon. See the [client guide](https://stolid.dev/docs/clients/).

```python
from stolid_client import StolidClient

client = StolidClient()  # reads STOLID_API_KEY
html = "<h1>Invoice 0042</h1>"
render = client.create_pdf(html)

for warning in render.warnings:
    print(warning.code, warning.message)
```

```js
import { StolidClient, getWarnings } from '@stolidhq/client';

const client = new StolidClient(); // reads STOLID_API_KEY
const html = '<h1>Invoice 0042</h1>';
const render = await client.createPdf(html);

for (const w of getWarnings(render)) console.warn(w.code, w.message);
```

## Agents can use Stolid PDF over HTTP today

An agent submits HTML, reads the warning codes and revises the document to fix detected issues, inside a retry limit your application sets. Validate the resulting PDF independently: the report does not check every layout issue or the accuracy of the document's contents.

- A bounded fix-and-retry loop: a worked example with a retry limit, a stopping rule and a final check. See [PDF generation for AI agents](https://stolid.dev/docs/ai-agents/).
- OpenAPI and Markdown docs: the complete API description in [openapi.json](https://stolid.dev/openapi.json), and every page of this site as Markdown through [llms.txt](https://stolid.dev/llms.txt).
- Codes first, messages second: warning messages can quote document text. Have the agent choose a fix from the stable code and treat the message as untrusted input.

## Page images for agents (coming soon)

Optional page images will let an agent look at the rendered pages next to the report. Images and warning codes are different signals; your workflow still decides whether a document is ready.

- Ask for images when you need them (coming soon): page images will come back with the response, next to the PDF and the report.
- Planned to count as one call (coming soon): the plan is for a call with page images to count the same as a call without.
- A hosted MCP server (coming soon): the Stolid PDF tool will use the same keys as the HTTP API. See the [MCP server status](https://stolid.dev/docs/mcp/).

## Questions developers ask first

### Does an empty warning list mean the PDF is correct?

No. An empty list means no warnings were reported. The report covers the issues Stolid detects, such as missing fonts, blocked requests and overflowing content, and some print CSS differences produce no warning. Check the PDF as well.

### Can an AI agent use Stolid PDF today?

Yes, through the HTTP API. An agent can submit HTML, read the stable warning codes and revise the document to fix detected issues. Set a retry limit and validate the result in your own workflow. The hosted MCP server and page images are coming soon.

### Can Stolid PDF load images and fonts from a URL?

Not during the public preview: remote file loading is off. Send your CSS, images, fonts and scripts with the request in `assets` and refer to them by name in your HTML. A request for a remote file is reported as `REQUEST_BLOCKED`. Several font families, including Inter, Roboto and Noto, are available by name with no upload.

### Which documents are a good fit?

Short documents you generate from your own HTML: invoices, statements, receipts and reports of up to 20 pages that render within 30 seconds, in a request of up to 6 MB including attached files. Stolid PDF renders with Chromium, so test any print CSS your templates depend on.

### How do I get the Python or Node client?

The package files come with your preview key email, with install steps in the [client guide](https://stolid.dev/docs/clients/). Publication on PyPI as `stolid-client` and on npm as `@stolidhq/client` is coming soon. You can also call the API with plain HTTP from any language.

## Try one template with sample data

Free public preview, access by request. Request a key, render your template and read what the report says about it. 500 live and 100 test calls a month during the preview, no card. [Request access](https://stolid.dev/access/) or write to hello@stolid.dev.

[Preview Terms](https://stolid.dev/legal/terms/) · [Acceptable use](https://stolid.dev/legal/terms/#acceptable-use) · [Privacy Policy](https://stolid.dev/legal/privacy/) · [Data handling](https://stolid.dev/data/) · Report abuse or copyright infringement: hello@stolid.dev

© 2026 Stolid · Operated by an individual in Washington, USA

Source: https://stolid.dev/pdf/
