PDF renders

Create PDFs from HTML or saved templates, check each render, and read the result fields and limits.

See all API resources or read API keys and requests.

Endpoints

createPdf

POST /v1/pdf

Create a PDF

Render one PDF from raw HTML, an inline stateless template, or one owned saved-template version. An omitted saved version resolves to one exact immutable version before data validation, admission, idempotency, queueing, or billing. Template evaluation happens before storage and only evaluated HTML enters render input. Returns 200 for a terminal job or 202 while the accepted job remains queued or running. A terminal job can be succeeded, failed, or cancelled; check status before downloading. Send wait=false to skip the bounded wait. Every mode uses the same queue, renderer, retention, webhook, and fixed one-credit success price.

Authentication: bearer API key. See authentication.

Request body: application/json, PdfRequest.

listPdfHistory

GET /v1/pdf

List render history

List the authenticated account's render jobs, newest first. Failed or cancelled jobs removed through DELETE do not appear. Bounded by keyset: pass the previous page's next_cursor to continue, rather than an offset, so a page already read stays stable while new jobs are created.

Authentication: bearer API key. See authentication.

getPdf

GET /v1/pdf/{id}

Get a PDF's status

Return one render job's current status, in the same representation POST /v1/pdf answers with. Mints a fresh signed download link on every call while the PDF is still available.

Authentication: bearer API key. See authentication.

deletePdf

DELETE /v1/pdf/{id}

Delete a PDF file or an unsuccessful render

Remove a successful job's PDF from storage, or remove a failed or cancelled job from history. The job stays readable by ID, and billing, abuse limits, and idempotency keys stay unchanged. The file is removed before its database marker; a file-removal failure returns 500 and leaves the record live for a safe retry. Repeated requests are safe. At or after the fixed retention cutoff, the removal reason remains expired.

Authentication: bearer API key. See authentication.

Schemas

PdfRequestCommon

Render options shared by raw HTML, stateless-template, and saved-template requests. Every field is optional; an absent field takes the renderer's own default.

Schema rules: {"type":"object"}.

RawPdfRequest

A raw HTML render. The HTML enters the existing render workflow unchanged.

Schema rules: {"allOf":[{"$ref":"#/components/schemas/PdfRequestCommon"},{"type":"object","properties":{"html":{"type":"string","minLength":1,"maxLength":5242880,"description":"The raw HTML document to render. Up to 5,242,880 bytes."}},"required":["html"]}],"unevaluatedProperties":false} — PdfRequestCommon.

StatelessTemplatePdfRequest

A bounded stateless template evaluation followed by the existing PDF render workflow. The request saves no reusable template. Data must be exactly one JSON object. Only evaluated HTML and the effective render options enter short-lived render input storage.

Schema rules: {"allOf":[{"$ref":"#/components/schemas/PdfRequestCommon"},{"type":"object","properties":{"html":{"type":"string","minLength":1,"maxLength":1048576,"description":"The inline Jinja-style template source. The evaluator accepts at most 1,048,576 bytes."},"data":{"type":"object","description":"The JSON-compatible data object available to the template. Arrays, scalars, and null are not accepted as the top-level value. Its canonical recursively key-sorted JSON representation may contain at most 1,048,576 bytes; JSON Schema cannot express that serialized-byte bound."}},"required":["html","data"]}],"unevaluatedProperties":false} — PdfRequestCommon.

SavedTemplatePdfRequest

Render one exact owned saved-template version. Omit version to resolve the latest version once before validation and admission. Data must be exactly one JSON object.

Schema rules: {"allOf":[{"$ref":"#/components/schemas/PdfRequestCommon"},{"type":"object","properties":{"template_id":{"$ref":"#/components/schemas/TemplateId"},"version":{"type":"integer","minimum":1,"description":"An exact immutable version. Omit to select latest once."},"data":{"type":"object","description":"The JSON-compatible data object validated against the selected version's optional schema before evaluation or admission."}},"required":["template_id","data"]}],"unevaluatedProperties":false} — PdfRequestCommon, TemplateId.

PdfRequest

Exactly one supported PDF input mode: raw HTML, an inline stateless template, or one saved-template version. Image request shapes are not part of this endpoint.

Schema rules: {"oneOf":[{"$ref":"#/components/schemas/RawPdfRequest"},{"$ref":"#/components/schemas/StatelessTemplatePdfRequest"},{"$ref":"#/components/schemas/SavedTemplatePdfRequest"}]} — RawPdfRequest, StatelessTemplatePdfRequest, SavedTemplatePdfRequest.

PdfJob

The state of one render job. This is the same shape whether the job just finished (200) or is still in progress (202).

Schema rules: {"type":"object","additionalProperties":false}.

PdfHistoryItem

One job in a bounded account history — the subset of PdfJob a history page lists. Never carries a download link, since a history page can name many jobs at once.

Schema rules: {"type":"object","additionalProperties":false}.

PdfHistoryPage

One bounded page of an account's render history, newest first.

Schema rules: {"type":"object","additionalProperties":false}.

Shared errors, headers, and authentication schemes are in shared types and security.