Skip to main content

Create a render

POST 
/renders

Renders a PDF, an image, or a Word or PowerPoint file from a stored template, from ad-hoc HTML or from a public URL: send exactly one of template, html and url. Needs the render:create scope.

Synchronous by default: the answer is the finished render, or the file itself with output=binary. A synchronous render that has no answer after 60 seconds, or finds no free render slot within 30 seconds, continues in the background and answers 202 with X-Render-Async-Fallback: true. With mode: async the answer is always 202. A 202 names the render's result in Location; ask that, poll GET /renders/{id}, or wait for the webhook.

What can be refused is checked before anything is counted: the body (400 invalid_request), the plan (403 forbidden with the feature), the template (404 template_not_found), validate_data (422 data_validation_error), an e-invoice's _invoice block (422 einvoice_data_invalid) and the quota (402 quota_exceeded). A render that fails afterwards (a template error, a page that does not load, a page or size limit, a timeout) answers with its problem, which names the failed render in render_id.

Request​

Responses​

The finished render (synchronous), or with output=binary the file itself.

Response Headers
    RateLimit-Limit

    Size of the workspace's request bucket: the plan's requests per second. Free test keys are also held to 30 requests a minute, and the headers then describe whichever bucket is closer to empty.

    RateLimit-Remaining

    Requests left in the bucket.

    RateLimit-Reset

    Seconds until the bucket is full again.

    X-Units-Charged

    Units this request costs; 0 for test keys, for an answer from the dedup cache, and for a render or batch that was queued, which counts its units when it finishes.

    X-Units-Remaining

    Units left in the organisation's billing period after this request (included units and prepaid packs), rounded down.

    X-Render-Region

    The region that rendered, or will.

    X-Render-Engine

    What filled the source: the template language (jinja2, liquid, handlebars), none for plain HTML and URLs, dedup for an answer from the dedup cache, queued for a render that went to the background.

    X-Render-Deduplicated

    true when an identical request was served from the dedup cache at zero units.

    Server-Timing

    A synchronous render that ran: compile;dur=…, render;dur=…, post;dur=…, upload;dur=… in milliseconds, the phases of timings. Absent on an answer from the dedup cache.

    X-Render-Id

    With output=binary: the render's id (rnd_…), the JSON answer's id.

    X-Render-Pages

    With output=binary: the PDF's page count; empty for images and Word or PowerPoint files.

    X-Render-Expires-At

    With output=binary: when the render's download_url stops working (ISO 8601), the JSON answer's expires_at; empty when there is none.

    Content-Disposition

    With output=binary: attachment; filename="<name>" with the stored file's name, for images too.

    X-Formfeed-PDF-UA

    Only with output=binary on a render that set settings.pdf.ua: what the validator said about the file. The JSON answer carries the same as accessibility.