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.
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:
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:
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:
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:
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:
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:
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:
[{'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.
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)
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: send your CSS, images and fonts with the request.
- Page options: page size, margins, headers and footers.
- API reference: HTTP endpoints, status codes, and common request and response fields. See the OpenAPI file for complete schemas.
- Limits, errors and retries: 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.