Docs / Reference / API reference

Docs menu · API reference

Reference

API reference

The Stolid API renders HTML to PDF over HTTPS and returns a report of detected font, asset, script and overflow issues. This page is generated from the OpenAPI description and covers HTTP endpoints, status codes, and common request and response fields. See the OpenAPI file for complete schemas.

Base URL and authentication

The base URL is https://api.stolid.dev. Authenticate every request with your API key as a bearer token: Authorization: Bearer stolid_live_…. Test keys start with stolid_test_; live and test keys are counted separately.

All errors have the same shape. error.render_id is the ID of the render associated with this error, when available. Use GET /v1/renders/{render_id} to check its status.

JSON
{"error": {"code": "INVALID_OPTIONS", "message": "…", "render_id": "rnd_…"}}

For a first request, see the Quickstart. Every error code is listed in Limits, errors and retries.

POST /v1/pdf

Render HTML to PDF. Renders the HTML (and any assets it uses) to a PDF. The request stays open for about 10 seconds. If the render finishes in that time the answer is 201 with the PDF ready; otherwise it is 202 and the render carries on: poll GET /v1/renders/{render_id} until it is succeeded or failed. A render that fails while the request is open is answered with the error (for example 504 TIMEOUT), not with a Render. Only succeeded renders count toward your monthly limit.

Parameters

ParameterDescription
response (query, optional)json (default): the Render, with a pdf_url. binary: the PDF itself, if the render finishes while the request is open (about 10 seconds); otherwise the 202 response, exactly as for json.
Idempotency-Key (header, optional)Optional name for this request, 1-255 printable ASCII characters without spaces, for example your invoice number. Repeating a request with the same key and the same content within 24 hours returns the original render instead of making a new one, and it is not counted twice; the same key with different content is a 409. Use a new key for each new document.

Request body

A JSON object (Content-Type: application/json).

FieldTypeDescription
htmlstringThe HTML document to render. Required.
optionsobjectSee the options table below.
assetsobjectYour files (stylesheets, images, fonts), keyed by the relative name your HTML uses for them, such as style.css or images/logo.png (no leading /). Each value is the file's content as standard base64, padded, without line breaks. Assets are the only resources a render can load: nothing is downloaded from the internet.

Options

The fields of options. Page options has tips for using them.

FieldTypeDescription
formatA4 or Letter or Legal or A3 or A5Default: "A4".
landscapebooleanPrint in landscape orientation. Default: false.
marginsobjectFields: bottom, left, right, top.
scalenumberScale of the page content. Default: 1.0. From 0.1 to 2.0.
print_backgroundbooleanPrint background colours and images. Default: true.
prefer_css_page_sizebooleanUse the page size from the CSS @page rule instead of format. Default: false.
header_templatestring or nullHTML for a header printed on every page.
footer_templatestring or nullHTML for a footer printed on every page.
wait_untilload or networkidleWhen the page counts as loaded: at the load event, or once network activity has settled. Default: "load".
javascriptbooleanRun the scripts in the page. Set to false to turn them off. Default: true.
allowed_domainslist of stringNot available during the public preview. A request that sets this to a non-empty list is refused with 400 INVALID_REQUEST. Send the files your page needs in assets instead.

Responses

StatusMeaning
201The render finished while the request was open (about 10 seconds), so the PDF is ready now. With response=json (default) the body is the Render with status succeeded and a pdf_url. With response=binary the body is the PDF itself (application/pdf); X-Render-Id and X-Render-Warnings carry the render's ID and its number of warnings.
202Accepted but not finished: the render is still running after the wait (the first render on an account can take up to a minute). The body is the Render with status running, also with response=binary; there is no PDF yet. Poll GET /v1/renders/{render_id} with the id from the body until status is succeeded or failed. Nothing is lost by waiting, and repeating the POST with the same Idempotency-Key returns this same render.
400Error: INVALID_REQUEST, INVALID_OPTIONS. The request is not valid. The message says what to fix: the JSON, the Content-Type header, an asset name or an option value.
401Error: UNAUTHORIZED. The API key is missing or not valid.
402Error: QUOTA_EXCEEDED. This month's renders for the key's mode are used up. Failed renders are not counted.
409Error: IDEMPOTENCY_CONFLICT. This Idempotency-Key was already used with different content. Use a new key.
413Error: HTML_TOO_LARGE, ASSETS_TOO_LARGE, REQUEST_TOO_LARGE. The request, the HTML or the assets are over the size limit.
422Error: TOO_MANY_PAGES. The document has more than the allowed 20 pages.
500Error: INTERNAL_ERROR. A problem on the service side. For a create whose outcome is unknown, retry with the original Idempotency-Key. If error.render_id is present, check the render's status before resubmitting. Use a new key only to rerender a document after a confirmed failure.
503Error: EGRESS_UNAVAILABLE. A temporary problem on the service side. A render that failed this way is not counted; try again with a new Idempotency-Key.
504Error: TIMEOUT. The render took longer than the 30 second limit. It is not counted.

Response headers

HeaderDescription
LocationOrigin-relative render path. Resolve it against https://api.stolid.dev and send an authenticated GET. For example, /v1/renders/rnd_….
X-Render-IdThe render's ID (binary responses).
X-Render-WarningsNumber of warnings in the render report (binary responses). GET the render for the details.

GET /v1/renders/{render_id}

Get a render. Returns a render as it is now: running, succeeded (with a fresh pdf_url and the manifest) or failed (with error). A failed render is returned with HTTP 200 and status failed, not as an error response. Renders are kept for 24 hours; a render that does not exist, has expired, or belongs to another account is 404.

Parameters

ParameterDescription
render_id (path, required)The render id.

Responses

StatusMeaning
200The render in its current state: running, succeeded or failed.
401Error: UNAUTHORIZED. The API key is missing or not valid.
404Error: NOT_FOUND. No such render in your account: unknown, older than 24 hours, or another account's.
500Error: INTERNAL_ERROR. A problem on the service side. Try again.

GET /v1/usage

Current-month usage. Renders counted this calendar month (UTC) for the mode of the API key you use, and the limit. Live and test keys are counted separately.

Responses

StatusMeaning
200Renders counted this calendar month (UTC).
401Error: UNAUTHORIZED. The API key is missing or not valid.
500Error: INTERNAL_ERROR. A problem on the service side. Try again.

The Render object

The object that POST /v1/pdf and GET /v1/renders/{render_id} return.

FieldTypeDescription
created_atstringRequired.
idstringThe render's ID. Use it to fetch the render again with GET /v1/renders/{render_id}. Required.
statusrunning or succeeded or failedrunning: still being rendered, ask again in a moment. succeeded: the PDF is ready (pdf_url, manifest and usage are present). failed: no PDF was made (error says why) and the render is not counted. Only succeeded and failed are final. Required.
completed_atstringWhen the render finished (succeeded and failed renders only).
errorobjectWhy the render failed (failed renders only). Fields: code, message.
manifestobjectThe render report (present on succeeded renders): warnings lists detected issues. Other sections give detail such as the page count, timings, fonts, blocked requests and layout; new sections may be added. Fields: warnings.
pdf_urlstringDownload link for the PDF (succeeded renders only), valid for about an hour. Download it without your API key. Anyone who has the link can download the PDF, so do not share or log it. GET the render again for a fresh link.
usageobjectWhat the render counted toward your monthly limit (succeeded renders only). Fields: renders.

The Warning object

One entry of manifest.warnings. See Warning codes. One detected issue in the render report. New codes may be added: treat a code you do not recognise as information.

FieldTypeDescription
codestringFONT_FALLBACK: a font you asked for is not available and a similar one was used. FONT_FACE_FAILED: a font file you declared with @font-face could not be used. ASSET_FAILED: the page asked for a file that was not in assets. REQUEST_BLOCKED: the page asked for something from the internet. CONTENT_OVERFLOW: something is wider than the page and is cut off. SCRIPT_ERROR: a script in the page raised an error. Required.
messagestringRequired.
samplestringThe text the warning is about (set for FONT_FALLBACK and CONTENT_OVERFLOW).

The Usage object

What GET /v1/usage returns.

FieldTypeDescription
limitintegerThe most renders this key's mode may have counted this month; a new render is refused with QUOTA_EXCEEDED once renders reaches it. Required.
modelive or testThe mode of the API key used. Live and test renders are counted separately. Required.
period_endstringRequired.
period_startstringRequired.
rendersintegerRenders counted in the current calendar month (UTC) for this mode. Required.

Error codes

The code of an error is one of: INVALID_REQUEST, INVALID_OPTIONS, UNAUTHORIZED, QUOTA_EXCEEDED, NOT_FOUND, IDEMPOTENCY_CONFLICT, HTML_TOO_LARGE, ASSETS_TOO_LARGE, REQUEST_TOO_LARGE, TOO_MANY_PAGES, RATE_LIMITED, INTERNAL_ERROR, EGRESS_UNAVAILABLE, TIMEOUT. Limits, errors and retries says what to do about each one.

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