# HTML to PDF API quickstart

With your preview key ready, render a PDF and read its render report with curl. Then do the same from Python or Node.

> **Before you start.**
> You need an API key. Stolid PDF is in free public preview: [request access](https://stolid.dev/access/) and we reply by email with your keys. Keep your keys secret, and call Stolid from your server, not from a web page or mobile app. Use your own templates with [sample data](https://stolid.dev/data/) during the public preview, and keep real customer details, personal data and secrets out of requests.

## What you need

A terminal with `curl` and Python 3 installed. Check with `curl --version` and `python3 --version`; each should print its version. The commands use Python only to read the answers.

## 1. Set your key

Put your key in an environment variable, so that no command has to contain it. Set it again in every new terminal.

```bash
export STOLID_API_KEY="stolid_live_…"
```

## 2. Create a PDF

Send your HTML to `POST https://api.stolid.dev/v1/pdf` and save the answer in `render.json`:

```bash
curl -sS -X POST "https://api.stolid.dev/v1/pdf" \
  -H "Authorization: Bearer $STOLID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1 style=\"font-family: sans-serif\">Hello from Stolid PDF</h1>"}' \
  -o render.json
```

Check how it went:

```bash
python3 -c 'import json; r = json.load(open("render.json")); print(r.get("status"), r.get("id"), r.get("error", ""))'
```

You should see something like `succeeded rnd_4f1c...`: your PDF is ready.

If it says `running`, the PDF is still being made. Wait a few seconds, then ask for the same render. This command reads its ID from `render.json`:

```bash
render_id=$(python3 -c 'import json; print(json.load(open("render.json"))["id"])')
curl -sS "https://api.stolid.dev/v1/renders/$render_id" -H "Authorization: Bearer $STOLID_API_KEY" -o render.json
python3 -c 'import json; r = json.load(open("render.json")); print(r.get("status"), r.get("id"), r.get("error", ""))'
```

Repeat that block while it says `running`. Continue only when it says `succeeded`. If it says `failed`, or prints an error without a status, check the error code in [Limits, errors and retries](https://stolid.dev/docs/limits/).

## 3. Download your PDF

The answer contains a download link, `pdf_url`. This command takes it from `render.json` and downloads the file:

```bash
curl -sS -o hello.pdf "$(python3 -c 'import json; print(json.load(open("render.json"))["pdf_url"])')"
```

Open `hello.pdf`. That is your first document from Stolid PDF.

The link works for one hour. Need it later? Ask for the render again (the `GET` command above) and you get a fresh link. You can retrieve a render through the API for 24 hours after it finishes, so save the PDF before then.

A successful response means a PDF was generated. Read its warnings and look at the output before you decide it is ready to use.

## 4. Read the render report

The answer also contains the render report. Print its warnings:

```bash
python3 -c 'import json; print(json.load(open("render.json"))["manifest"]["warnings"])'
```

An empty list (`[]`) means no warnings were reported. The warning list describes detected issues; it is not a pass or fail certificate for the document, so check the PDF too.

To try a font warning, send a page that sets no font:

```bash
curl -sS -X POST "https://api.stolid.dev/v1/pdf" \
  -H "Authorization: Bearer $STOLID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>No font chosen</h1>"}' \
  -o render.json
python3 -c 'import json; r = json.load(open("render.json")); print(r.get("status"), r.get("id"), r.get("error", ""))'
```

If the status is `running`, use the `GET` command from step 2 until it finishes. After `succeeded`, print the warnings with the command above. If the browser's default font is unavailable, the report names the font used instead. For example:

```text
[{'code': 'FONT_FALLBACK', 'message': "'Times New Roman' is not available; text was rendered with Liberation Serif. ..."}]
```

Use an available font or a generic family such as `sans-serif`, as step 2 did, to avoid this fallback. Every code is explained in [Warning codes](https://stolid.dev/docs/warning-codes/).

## 5. Use a client library

The Python and Node clients wait for renders to finish, retry temporary errors, download the PDF and encode your files for you. They read `STOLID_API_KEY` automatically and send requests to `https://api.stolid.dev`.

The clients are coming to PyPI and npm. Until they are published, the package files come with your preview key email. [Clients](https://stolid.dev/docs/clients/) covers installing them.

```python
from stolid_client import StolidClient

with StolidClient() as client:
    render = client.create_pdf("<h1 style='font-family: sans-serif'>Hello from Python</h1>")
    with open("hello-python.pdf", "wb") as f:
        f.write(client.download_pdf(render))
    for warning in render.warnings:
        print("warning:", warning.code, warning.message)
```

```js
import { writeFile } from 'node:fs/promises';
import { StolidClient, getWarnings } from '@stolidhq/client';

const client = new StolidClient();
const render = await client.createPdf("<h1 style='font-family: sans-serif'>Hello from Node</h1>");
await writeFile('hello-node.pdf', await client.downloadPdf(render));
for (const w of getWarnings(render)) console.warn('warning:', w.code, w.message);
```

## Next steps

- [Files and fonts](https://stolid.dev/docs/files-and-fonts/): send your CSS, images and fonts with the request.
- [Page options](https://stolid.dev/docs/page-options/): page size, margins, headers and footers.
- [API reference](https://stolid.dev/docs/api/): HTTP endpoints, status codes, and common request and response fields. See the [OpenAPI file](https://stolid.dev/openapi.json) for complete schemas.
- [Limits, errors and retries](https://stolid.dev/docs/limits/): what a call can do, and how to retry safely.

Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.

[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/docs/quickstart/
