Docs / Getting started / HTML to PDF API quickstart

Docs menu · HTML to PDF API quickstart

Getting started

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 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 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.

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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.

3. Download your PDF

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

Terminal
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:

Terminal
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:

Terminal
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:

Output
[{'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.

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 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)
Node
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

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