Rendering a PDF

POST /v1/render produces a PDF from a template and data. One successful render costs one credit; a failed render costs nothing.

There are two ways to say what to render, and each has its own guide:

• With a saved template: you keep the template in your account and send its id plus the data.
• With inline HTML: you send the HTML and the data in the same request, and nothing is stored.

This page is the reference for the request and the response, which are the same in both.

Request

{
  "template_id": "0194f2c0-…",
  "data": { "customer": "Ana Souza", "total": "1234.50" },
  "locale": "pt-BR",
  "title": "Invoice 2025-0042",
  "output": "pdf",
  "strict": false
}

Field	Type	Meaning
template_id	string	A template saved in your account. Send this or html.
html	string	Inline HTML, treated as a template. Send this or template_id.
data	object	Values for the template. Defaults to {}.
locale	string	A BCP 47 tag such as pt-BR. Defaults to the template’s locale, then your account’s.
title	string	The document title stored in the PDF.
output	"pdf" or "url"	pdf (default) returns the file. url returns JSON with a signed link.
strict	boolean	Refuse the document if it uses anything the service does not fully support.

Sending both template_id and html, or neither, is a 400.

Response: the PDF

With output: "pdf" the body is the PDF (Content-Type: application/pdf) and these headers describe it:

Header	Value
X-Render-Id	Id of this render.
X-Pages	Number of pages.
X-Credits-Remaining	Your balance after this render.
X-Diagnostics	Number of things the service did not fully support; see Validating.

Response: a link

With output: "url" the PDF is kept for a while and you get JSON back:

{
  "id": "0194f2c1-…",
  "url": "https://api.example.com/v1/files/0194f2c1-…?exp=1760000000&sig=…",
  "expires_at": 1760000000,
  "pages": 1,
  "bytes": 27003,
  "credits_remaining": 999,
  "diagnostics": []
}

The link works without an API key until expires_at, then stops. How long files are kept depends on your plan; see Plans and credits. Share the link with your own customer, or download the file once and store it yourself.

Strict mode

By default an unsupported feature is ignored and reported. With strict: true the request fails with 422 strict_mode_rejected and lists every diagnostic, and no credit is used. Use it in tests to make sure a template stays clean.

Limits

A render is refused when the input, the expanded HTML, the page count or the time exceed your plan’s limits, and when the service is at capacity. See Errors and limits.