RenderRequest

One render. Send exactly one source: template, html or url (400 invalid_request otherwise).

templatestring

The template, by slug or id (tpl_…; the UUID works too). Omit when using html or url.

Possible values: <= 200 characters

Example: invoice-de

versionstring

published (default), the name of a release channel such as staging (Starter plan and above), latest (the newest version, usually the draft the editor works on; test keys only) or a version number. Channels, published included, are cached for up to a minute; a channel with a canary sends its share of renders to the canary version, chosen by canary_key, else by the Idempotency-Key so a retry lands on the same version, else at random. A draft renders as it is at that moment.

Default value: published

htmlstringnullable

Ad-hoc HTML, at most 5 MB. With an engine it is rendered as a template over data, with the brand kit and the shared partials; without one it is printed as given.

urlstring<uri>nullable

A public https page to print, up to 2,048 characters. It is loaded like a browser would, without your cookies or headers. Private, internal and metadata addresses are refused: with 400 invalid_request where the address shows it, with 422 navigation_failed where a name resolves to one. Plain http, an HTTP error status or a page that does not load within 30 seconds fail with 422 navigation_failed. URL renders are never deduplicated.

engineEnginenullable

The template language of html; left out or null, the HTML is not templated.

Possible values: [jinja2, liquid, handlebars]

data object

The data the template renders with; {} when left out. Plain html and url renders read only its _invoice block, for an e-invoice. It is checked against the template's schema only with validate_data.

property name*any

outputOutputFormat

Left out, the template decides: pdf for a template of kind pdf, settings.image.format (the request's, then the template's; png without one) for kind image, settings.office.output (else the template's own format) for kinds docx and pptx. Ad-hoc html and url render pdf. On the Free plan, test renders of docx and pptx templates may only request pdf (403 test_output_unavailable).

Possible values: [pdf, png, jpg, webp, docx, pptx]

settings object

Rendering settings. A request's settings are deep-merged over the template's, which are merged over the defaults: only the keys you send change, and a section set to null (such as footer: null) is removed. The settings reference explains each key with examples.

paper object

PDF page size. Defaults to A4 portrait.

formatstring

A0 to A6, Letter, Legal, Tabloid or Ledger; A4 by default. Ignored when width and height are set.

Example: A4

widthstringnullable

Custom page width as a CSS length; needs height too.

Example: 100mm

heightstringnullable

Custom page height as a CSS length; needs width too.

Example: 150mm

landscapeboolean

Default value: false

margin object

Page margins as CSS lengths; 20mm top and bottom and 15mm left and right by default. Header and footer are drawn inside the top and bottom margin.

topstring

Example: 20mm

rightstring

Example: 15mm

bottomstring

Example: 20mm

leftstring

Example: 15mm

header objectnullable

Printed across the whole page width inside the top margin; null removes the template's.

htmlstring

Markup of the running header, rendered with the template's language and data. Elements with the classes pageNumber and totalPages show the page numbers.

heightstring

Height of the header box as a CSS length.

paddingstring

CSS padding inside the header box; 0 for designs that run edge to edge.

Default value: 0 10mm

footer objectnullable

Printed across the whole page width inside the bottom margin; null removes the template's.

htmlstring

Markup of the running footer, rendered like the header.

heightstring

Height of the footer box as a CSS length.

paddingstring

CSS padding inside the footer box; 0 for designs that run edge to edge.

Default value: 0 10mm

printBackgroundboolean

Print background colours and images.

Default value: true

scalenumber

Scales the page content, from 0.1 to 2.

Default value: 1

preferCssPageSizeboolean

Let @page rules in the CSS decide the page size instead of paper.

Default value: false

pageRangesstring

Keep only these pages of a PDF; empty keeps all. The page count, the plan's page limit and the units count the pages that are kept.

Default value:

Example: 1-3, 5

waitFor object

When the page counts as loaded, before it is printed or captured.

networkIdle object

auto waits for the load event, the fonts and the requests still running, and for half a second of network idle only on a URL or a document with scripts of its own. true always waits for that half second, false never does.

oneOf

boolean
string

boolean

selectorstringnullable

Wait until an element matching this CSS selector exists and is visible.

Default value: null

timeoutMsinteger

How long to wait for selector, in milliseconds, at most 30,000; then the render fails with render_timeout.

Possible values: >= 0

Default value: 5000

delayMsinteger

An extra pause after everything else, in milliseconds; a value above 10,000 counts as 10,000.

Possible values: >= 0

Default value: 0

tailwindboolean

Compile the Tailwind utility classes the document uses, for templates and plain html alike.

Default value: false

pdf object

PDF output only: what the file says about itself, and its structure for assistive technology.

metadata object

The document properties. The title is what a PDF reader shows in its title bar and a screen reader announces first; PDF/UA-1 requires one.

titlestring

Rendered with the data like the template, so it may use template expressions. Applies to stored templates and to html with an engine; a plain html or url render ignores it, so give such a page a <title> instead.

Example: Rechnung {{ invoice.number }}

authorstring

Rendered with the data like title for stored templates and html with an engine; written as given for plain html, url and Word and PowerPoint templates.

Example: Fennlor Studio GmbH

subjectstring

Rendered like author.

keywordsstring

Rendered like author, as one text; left out of the file when it comes out empty.

taggedboolean

Writes the structure tree (headings, lists, tables, links) a screen reader reads the document by.

Default value: false

outlineboolean

Writes bookmarks from the headings.

Default value: false

ua objectnullable

Makes the file a PDF/UA-1 document (ISO 14289-1): tagged, repaired where the browser's output breaks the standard, and held against veraPDF's machine-checkable rules of PDF/UA-1. true is { "check": "strict" }. The render carries the verdict as accessibility, and the file names itself PDF/UA-1 only when it passed. A passed check does not make a document accessible: alternative texts, reading order and contrast are in the template. Cannot be combined with post.merge_after, and is not available for Word and PowerPoint templates; each answers 400 invalid_request. With an e-invoice the file is a PDF/A-3b and a PDF/UA-1 document at once: both are checked in the file that is delivered, and the render carries both reports. false in a request switches off what the template declares. Asked for by a request whose output is an image, it answers 400 too; declared by an image template it is ignored. No plan limit and no extra unit.

oneOf

boolean
PdfUaOptions

boolean

image object

Image output (png, jpg, webp): the browser window the page is captured in.

widthinteger

Window width in CSS pixels; 1200 by default.

Example: 1200

heightinteger

Window height in CSS pixels; 630 by default.

Example: 630

deviceScaleFactornumber

Pixel density: 2 makes a 1200 × 630 window a 2400 × 1260 image.

Default value: 2

formatstring

Output of an image template when the request names no output. jpg is accepted as well.

Possible values: [png, jpeg, webp]

qualityinteger

JPEG and WebP quality; 90 by default.

Possible values: >= 1 and <= 100

fullPageboolean

Capture the whole height of the page instead of the window.

Default value: false

transparentboolean

Transparent background (PNG).

Default value: false

clipSelectorstringnullable

CSS selector of one element to capture instead of the window; the first match counts. When none appears within 30 seconds, the render fails with render_timeout.

Default value: null

office object

Word and PowerPoint templates. Page setup, margins, headers and footers come from the document; the Chromium settings above do not apply.

outputstring

Output when the request names none; the template's own format without it.

Possible values: [docx, pptx, pdf]

localestring

BCP 47 tag that formats dates and numbers, picks the translation dictionary and sets <html lang>; en-GB by default.

Example: de-DE

timezonestring

IANA time zone for dates; Europe/Berlin by default.

Example: Europe/Berlin

currencystring

ISO 4217 code the money helper uses when none is given; EUR by default.

Example: EUR

einvoice objectnullable

Makes the template an invoice template: every PDF rendered from it is a ZUGFeRD / Factur-X e-invoice built from the _invoice block of the data, as if the request said post.einvoice. A request's settings.einvoice and post.einvoice merge over it field by field; post.einvoice: false switches it off for one request. Image output of the same template is not affected. false in a request switches off what the template declares.

oneOf

EinvoiceOptions
boolean

What kind of e-invoice a render makes. Every field has a default, so {} asks for a Factur-X invoice in the EN 16931 profile.

profilestring

en16931 carries every field of the European standard; basic is the smallest profile that is an invoice on its own. Any other profile answers 422 einvoice_profile_unsupported.

Possible values: [basic, en16931]

Default value: en16931

flavourstring

ZUGFeRD and Factur-X are one specification under two names, and the file is the same. The choice decides the name and release the render reports (Factur-X 1.09 or ZUGFeRD 2.5).

Possible values: [factur-x, zugferd]

Default value: factur-x

xmlstring

both stores the XML as a file of its own beside the PDF, kept and deleted with it; the render links it as einvoice.xml_url.

Possible values: [embedded, both]

Default value: embedded

display_checkstring

What happens when the PDF does not show a value of the XML (the invoice number, the totals): warn reports it in einvoice.display.missing, strict fails the render with 422 einvoice_display_mismatch.

Possible values: [warn, strict]

Default value: warn

design object

The visual editor's layers of an image template, stored with a version. Authoring data only: renders use the version's HTML and CSS, which the editor writes from it, and a render request's design is ignored. Kept as it is when you copy a version; at most 256 kB. See the visual editor guide.

property name*any

filenamestring

Name of the output file, up to 200 characters, as the download URL and Content-Disposition show it. It is taken as written: template expressions are not evaluated, so build the name in your code. Characters other than letters, digits, ., -, _, (, ) and spaces become _, the name is cut to 150 characters, and the output's extension is added when missing. document.<extension> when left out.

Example: invoice-2026-0042.pdf

expires_inintegernullable

Seconds until the output expires, at least 1. It shortens the retention the plan and the workspace set and cannot lengthen it: a longer value is cut to that retention. null uses the retention. A test render is kept a day at most. On plans without a retention limit (Business and above) an output without expires_in and without a workspace retention never expires.

Possible values: >= 1

accessstring

The workspace's setting when left out, signed unless it says public. signed: download_url carries a signature and works for seven days at most; read the render again for a new link. public: a plain CDN URL that anyone who has it can open until the output expires.

Possible values: [public, signed]

modestring

sync answers with the finished render, or 202 after 60 seconds while it continues in the background; async answers 202 at once.

Possible values: [sync, async]

Default value: sync

localestringnullable

Overrides the locale of a template or of html with an engine: formats dates and numbers and selects the translation dictionary. Plain html and url renders take settings.locale instead.

Possible values: <= 20 characters

webhook_urlstring<uri>nullable

Receives render.completed or render.failed for this render, synchronous or not. An https URL on a public host, up to 2,048 characters; unsigned unless webhook_secret is set.

webhook_secretstringnullable

Signs the deliveries to webhook_url (same scheme as an endpoint secret). Write-only, never returned; without it those deliveries stay unsigned.

Possible values: >= 16 characters and <= 200 characters

meta object

Your own data (an order id, say), returned unchanged with the render and in its webhook events.

property name*any

Your own data (an order id, say), returned unchanged with the render and in its webhook events.

regionRegionnullable

Where the render runs; the workspace's region when left out. Leave it out: every workspace is in eu today.

Possible values: [eu, us, apac]

dedupeboolean

Answer a request identical to one of the last 24 hours in the workspace (the same template version or HTML, data, settings, locale, output and access, and the same brand kit and shared partials) from the earlier render at zero units. The answer is the earlier render, with its id, file and expiry, deduplicated: true and this request's meta. Live keys only; never for url renders, renders with post (an e-invoice included) or with a storage.key. false always renders.

Default value: true

canary_keystringnullable

Decides the canary split of a channel: renders with the same value land on the same version, so one customer's documents look alike. Use an opaque id; it is not stored. Without it the Idempotency-Key decides, which keeps a retry on its version but splits separate renders independently.

Possible values: non-empty and <= 200 characters

Example: customer-4711

validate_databoolean

Checks data against the template's stored data schema before anything is rendered or counted; a mismatch answers 422 data_validation_error listing every error. Needs a template with a stored schema (400 otherwise). In a batch, nothing is queued unless every item that asks for it fits.

Default value: false

post objectnullable

Post-processing of a PDF render, applied in the order merge, watermark, password (0.5 units per step on live keys; Starter plan and above, 403 forbidden with feature: post_processing below), and the e-invoice, which is a step of its own (one unit; live renders from the Starter plan on). Test renders make a limited number of e-invoices a day, each with the test mark: 20 on Free, 100 on Starter, 500 on Pro and 2,000 on Business; Enterprise does not count them. Post-processing on an image output answers 400. An unknown step is refused, never skipped.

einvoice object

Makes the PDF a ZUGFeRD / Factur-X e-invoice: a PDF/A-3b that carries the invoice as XML, built from the _invoice block of data and validated before the file is delivered. A block that is missing or breaks a rule of EN 16931 answers 422 einvoice_data_invalid before anything is rendered; a file that fails validation is never delivered, and never replaced by a plain PDF. Not together with password (PDF/A forbids encryption), and never served from the dedup cache. With settings.pdf.ua the same file is held to PDF/UA-1 as well, and the render carries accessibility beside einvoice. false switches off what the template's settings.einvoice declares, for this request. Asked for on an image output it answers 400 invalid_request. A plan without e-invoices, or a day's test e-invoices used up, answers 403 forbidden with feature: einvoice.

oneOf

EinvoiceOptions
boolean

What kind of e-invoice a render makes. Every field has a default, so {} asks for a Factur-X invoice in the EN 16931 profile.

profilestring

en16931 carries every field of the European standard; basic is the smallest profile that is an invoice on its own. Any other profile answers 422 einvoice_profile_unsupported.

Possible values: [basic, en16931]

Default value: en16931

flavourstring

ZUGFeRD and Factur-X are one specification under two names, and the file is the same. The choice decides the name and release the render reports (Factur-X 1.09 or ZUGFeRD 2.5).

Possible values: [factur-x, zugferd]

Default value: factur-x

xmlstring

both stores the XML as a file of its own beside the PDF, kept and deleted with it; the render links it as einvoice.xml_url.

Possible values: [embedded, both]

Default value: embedded

display_checkstring

Possible values: [warn, strict]

Default value: warn

merge_afterstring[]

PDFs appended after this document, in order: render ids (rnd_…) of succeeded PDF renders stored in the region this render runs in, or PDFs of the workspace library by name (such as terms.pdf) or file id (fil_…). Each up to 100 characters. Not with settings.pdf.ua. The appended pages are not metered again.

Possible values: >= 1, <= 49

watermark object

Either a text or an image from the workspace library, not both; drawn as POST /pdf/watermark draws it.

textstring

The text, 1 to 200 characters of Latin, Greek or Cyrillic script.

Possible values: non-empty and <= 200 characters

imagestring

A PNG or JPEG of the workspace library, by name (such as logo.png) or file id (fil_…).

Possible values: <= 200 characters

opacitynumber

From 0 (invisible) to 1 (opaque).

Possible values: >= 0 and <= 1

Default value: 0.2

rotationnumber

Degrees clockwise as in CSS, -360 to 360. Left out, a text runs diagonally (-45) and an image stands upright (0).

Possible values: >= -360 and <= 360

colorstring

Hex colour of the text; grey (#737380) by default, ignored for an image.

Possible values: Value must match regular expression ^#?[0-9a-fA-F]{6}$

password object

Encrypts the PDF with AES-256, always as the last step. Send at least one of its fields. Not with an e-invoice.

userstring

Needed to open the document. No line breaks.

Possible values: non-empty and <= 127 characters

ownerstring

Lifts the restrictions; a random one nobody knows when omitted. No line breaks.

Possible values: non-empty and <= 127 characters

permissionsstring[]

What a reader without the owner password may do. Left out, all four are allowed; [] allows none.

Possible values: [print, copy, modify, annotate], <= 4

storage objectnullable

The copy for the workspace's own bucket (bring your own storage). Left out, every output is copied under the connection's key template. false leaves this document out. key names its object below the connection's prefix instead of the key template: relative, without . or .. segments, at most 1024 bytes; an existing object is overwritten. A render with its own key is never answered from the dedup cache, and one without a connection answers 409 storage_not_configured. In a batch, each item carries its own.

oneOf

boolean
object

boolean

Possible values: [false]

RenderRequest
{
  "template": "invoice-de",
  "version": "published",
  "html": "string",
  "url": "string",
  "engine": "jinja2",
  "data": {},
  "output": "pdf",
  "settings": {
    "paper": {
      "format": "A4",
      "width": "100mm",
      "height": "150mm",
      "landscape": false
    },
    "margin": {
      "top": "20mm",
      "right": "15mm",
      "bottom": "20mm",
      "left": "15mm"
    },
    "header": {
      "html": "string",
      "height": "string",
      "padding": "0 10mm"
    },
    "footer": {
      "html": "string",
      "height": "string",
      "padding": "0 10mm"
    },
    "printBackground": true,
    "scale": 1,
    "preferCssPageSize": false,
    "pageRanges": "1-3, 5",
    "waitFor": {
      "networkIdle": true,
      "selector": null,
      "timeoutMs": 5000,
      "delayMs": 0
    },
    "tailwind": false,
    "pdf": {
      "metadata": {
        "title": "Rechnung {{ invoice.number }}",
        "author": "Fennlor Studio GmbH",
        "subject": "string",
        "keywords": "string"
      },
      "tagged": false,
      "outline": false,
      "ua": true
    },
    "image": {
      "width": 1200,
      "height": 630,
      "deviceScaleFactor": 2,
      "format": "png",
      "quality": 0,
      "fullPage": false,
      "transparent": false,
      "clipSelector": null
    },
    "office": {
      "output": "docx"
    },
    "locale": "de-DE",
    "timezone": "Europe/Berlin",
    "currency": "EUR",
    "einvoice": {
      "profile": "en16931",
      "flavour": "factur-x",
      "xml": "embedded",
      "display_check": "warn"
    },
    "design": {}
  },
  "filename": "invoice-2026-0042.pdf",
  "expires_in": 0,
  "access": "public",
  "mode": "sync",
  "locale": "string",
  "webhook_url": "string",
  "webhook_secret": "string",
  "meta": {},
  "region": "eu",
  "dedupe": true,
  "canary_key": "customer-4711",
  "validate_data": false,
  "post": {
    "einvoice": {
      "profile": "en16931",
      "flavour": "factur-x",
      "xml": "embedded",
      "display_check": "warn"
    },
    "merge_after": [
      "string"
    ],
    "watermark": {
      "text": "string",
      "image": "string",
      "opacity": 0.2,
      "rotation": 0,
      "color": "string"
    },
    "password": {
      "user": "string",
      "owner": "string",
      "permissions": [
        "print"
      ]
    }
  },
  "storage": false
}