# 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](https://stolid.dev/openapi.json) 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](https://stolid.dev/docs/quickstart/). Every error code is listed in [Limits, errors and retries](https://stolid.dev/docs/limits/).

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

| Parameter | Description |
| --- | --- |
| `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`).

| Field | Type | Description |
| --- | --- | --- |
| `html` | string | The HTML document to render. Required. |
| `options` | object | See the options table below. |
| `assets` | object | Your 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](https://stolid.dev/docs/page-options/) has tips for using them.

| Field | Type | Description |
| --- | --- | --- |
| `format` | `A4` or `Letter` or `Legal` or `A3` or `A5` | Default: `"A4"`. |
| `landscape` | boolean | Print in landscape orientation. Default: `false`. |
| `margins` | object | Fields: `bottom`, `left`, `right`, `top`. |
| `scale` | number | Scale of the page content. Default: `1.0`. From 0.1 to 2.0. |
| `print_background` | boolean | Print background colours and images. Default: `true`. |
| `prefer_css_page_size` | boolean | Use the page size from the CSS `@page` rule instead of `format`. Default: `false`. |
| `header_template` | string or null | HTML for a header printed on every page. |
| `footer_template` | string or null | HTML for a footer printed on every page. |
| `wait_until` | `load` or `networkidle` | When the page counts as loaded: at the `load` event, or once network activity has settled. Default: `"load"`. |
| `javascript` | boolean | Run the scripts in the page. Set to false to turn them off. Default: `true`. |
| `allowed_domains` | list of string | Not 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

| Status | Meaning |
| --- | --- |
| 201 | The 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. |
| 202 | Accepted 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. |
| 400 | Error: 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. |
| 401 | Error: UNAUTHORIZED. The API key is missing or not valid. |
| 402 | Error: QUOTA_EXCEEDED. This month's renders for the key's mode are used up. Failed renders are not counted. |
| 409 | Error: IDEMPOTENCY_CONFLICT. This Idempotency-Key was already used with different content. Use a new key. |
| 413 | Error: HTML_TOO_LARGE, ASSETS_TOO_LARGE, REQUEST_TOO_LARGE. The request, the HTML or the assets are over the size limit. |
| 422 | Error: TOO_MANY_PAGES. The document has more than the allowed 20 pages. |
| 500 | Error: 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. |
| 503 | Error: 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. |
| 504 | Error: TIMEOUT. The render took longer than the 30 second limit. It is not counted. |

### Response headers

| Header | Description |
| --- | --- |
| `Location` | Origin-relative render path. Resolve it against `https://api.stolid.dev` and send an authenticated GET. For example, `/v1/renders/rnd_…`. |
| `X-Render-Id` | The render's ID (binary responses). |
| `X-Render-Warnings` | Number 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

| Parameter | Description |
| --- | --- |
| `render_id` (path, required) | The render id. |

### Responses

| Status | Meaning |
| --- | --- |
| 200 | The render in its current state: `running`, `succeeded` or `failed`. |
| 401 | Error: UNAUTHORIZED. The API key is missing or not valid. |
| 404 | Error: NOT_FOUND. No such render in your account: unknown, older than 24 hours, or another account's. |
| 500 | Error: 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

| Status | Meaning |
| --- | --- |
| 200 | Renders counted this calendar month (UTC). |
| 401 | Error: UNAUTHORIZED. The API key is missing or not valid. |
| 500 | Error: 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.

| Field | Type | Description |
| --- | --- | --- |
| `created_at` | string | Required. |
| `id` | string | The render's ID. Use it to fetch the render again with GET /v1/renders/{render_id}. Required. |
| `status` | `running` or `succeeded` or `failed` | `running`: 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_at` | string | When the render finished (succeeded and failed renders only). |
| `error` | object | Why the render failed (failed renders only). Fields: `code`, `message`. |
| `manifest` | object | The 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_url` | string | Download 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. |
| `usage` | object | What the render counted toward your monthly limit (succeeded renders only). Fields: `renders`. |

## The Warning object

One entry of `manifest.warnings`. See [Warning codes](https://stolid.dev/docs/warning-codes/). One detected issue in the render report. New codes may be added: treat a code you do not recognise as information.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `FONT_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. |
| `message` | string | Required. |
| `sample` | string | The text the warning is about (set for FONT_FALLBACK and CONTENT_OVERFLOW). |

## The Usage object

What `GET /v1/usage` returns.

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer | The most renders this key's mode may have counted this month; a new render is refused with QUOTA_EXCEEDED once renders reaches it. Required. |
| `mode` | `live` or `test` | The mode of the API key used. Live and test renders are counted separately. Required. |
| `period_end` | string | Required. |
| `period_start` | string | Required. |
| `renders` | integer | Renders 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](https://stolid.dev/docs/limits/) 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.

[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/api/
