Render a PDF

POST /v1/pdf/render, the one product-specific verb. Send a stored template and data, or inline HTML, and get back a finished job.

Render a PDF, synchronously or asynchronously

posthttps://api.paperpony.dev/v1/pdf/render

Send either template_id or html, never both.

Synchronous and asynchronous are the same path. With async unset the request waits: if the render finishes within 20 seconds you get 200 with the finished job, and if it does not you get 202 with the same job object still running, which you then poll with GET /v1/jobs/{id}. With async: true you get 202 immediately. The body is the same shape in every case.

A synchronous render that fails answers with the error envelope rather than a 200 carrying status: failed, because every error in this API uses one shape. That envelope carries job_id, so the timings, the page count and the error detail are still readable from GET /v1/jobs/{id}.

Credits. One credit per page, minimum one per job. Failed renders and timeouts charge nothing. Test-mode keys run the whole pipeline, produce watermarked output and charge zero.

Free tier. Free-plan renders run with JavaScript disabled, so a document that builds itself with a script renders differently there than on a paid plan. Free-plan and test-key output is watermarked.

Not yet supported. webhook_url from the specification is deliberately rejected rather than accepted and ignored; webhook delivery arrives in a later phase.

Parameters

Name	In	Description
`Idempotency-Key`	header	Retry safety. The same key on the same account within 24 hours returns the original job and charges nothing. Reusing a key with a different body is an error, not a silent replay.

Body

Send exactly one of template_id or html.

renderPdf request body
Field	Type	Description
`template_id`	`string`
`html`	`string`	Handlebars over HTML. Up to 5 MB; reference large assets by URL rather than inlining them.
`data`	`object`	Values for the template.
`options`	`object`	Every field is optional; the values shown are the defaults.
`format`	`"A0" \| "A1" \| "A2" \| "A3" \| "A4" \| "A5" \| "A6" \| "Letter" \| "Legal" \| "Tabloid" \| "Ledger"`	default "A4"
`orientation`	`"portrait" \| "landscape"`	default "portrait"
`margin`	`object`	CSS lengths. A bare number is read as pixels.
`print_background`	`boolean`	default true
`scale`	`number`	default 1 · min 0.1 · max 2
`header_html`	`string \| null`	Rendered into the top margin. Templated with the same data as the body. Chromium recognises the classes pageNumber, totalPages, date, title and url inside it. Needs an explicit font-size, and a top margin large enough to hold it.default null
`footer_html`	`string \| null`	default null
`page_ranges`	`string \| null`	default null
`wait_for`	`"load" \| "domcontentloaded" \| "networkidle"`	default "networkidle"
`timeout_ms`	`integer`	default 15000 · min 1000 · max 60000
`filename`	`string`	Sanitized, not rejected: path separators, null bytes and control characters are stripped and the result is capped at 100 characters.default "document.pdf"
`async`	`boolean`	Answer 202 immediately instead of waiting for the render.default false

Example

curlJavaScriptPython

curl https://api.paperpony.dev/v1/pdf/render \
  -X POST \
  -H "Authorization: Bearer $PAPERPONY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "template_id": "tpl_01JZ3M8Q0000000000000000AB",
  "data": {
    "number": "INV-0001",
    "customer": "Fabrikam Ltd",
    "total": 4308
  },
  "options": {
    "format": "A4",
    "margin": {
      "top": "20mm",
      "bottom": "20mm"
    }
  }
}'

import { PaperPony } from 'paperpony';

const pony = new PaperPony({ apiKey: process.env.PAPERPONY_API_KEY });

const job = await pony.pdf.render({
  template_id: 'tpl_01JZ3M8Q0000000000000000AB',
  data: { number: 'INV-0001', customer: 'Fabrikam Ltd', total: 4308 },
  options: { format: 'A4', margin: { top: '20mm', bottom: '20mm' } },
});

console.log(job.output_url, job.page_count, job.credits_charged);

import os
import requests

response = requests.post(
    "https://api.paperpony.dev/v1/pdf/render",
    headers={"Authorization": f"Bearer {os.environ['PAPERPONY_API_KEY']}"},
    json={
    "template_id": "tpl_01JZ3M8Q0000000000000000AB",
    "data": {
        "number": "INV-0001",
        "customer": "Fabrikam Ltd",
        "total": 4308
    },
    "options": {
        "format": "A4",
        "margin": {
            "top": "20mm",
            "bottom": "20mm"
        }
    }
},
)
response.raise_for_status()
print(response.json())

Returns

renderPdf response
Field	Type	Description
`id`required	`string`
`status`required	`"queued" \| "processing" \| "succeeded" \| "failed"`
`product`required	`string`
`mode`required	`"sync" \| "async"`
`template_id`required	`string \| null`
`output_url`required	`string \| null`	Signed and expiring, never permanent. Signed fresh on every read of the job.
`output_bytes`required	`integer \| null`
`output_expires_at`required	`string \| null`	When the object itself is deleted, from the plan's retention.date-time
`page_count`required	`integer \| null`
`credits_charged`required	`integer`
`credits_remaining`required	`integer`
`watermarked`required	`boolean`
`error`required	`object \| null`
`code`required	`string`
`message`required	`string`
`created_at`required	`string`	date-time
`started_at`required	`string \| null`	date-time
`finished_at`required	`string \| null`	date-time

Responses

Status	Code	Meaning
`200`		The render finished inside the synchronous budget.
`202`		The job is queued or still running. Poll `GET /v1/jobs/{id}`.
`401`	unauthorized · invalid_api_key	No credential, or the credential is malformed, unknown or revoked.
`402`	insufficient_credits	The account has fewer credits than the request needs. The message states the balance and the reset date.
`403`	account_suspended	The key is valid but the account may not use the API. Nothing sets this automatically: billing is not built, so it can only be set by hand. Write to hello@paperpony.dev if you see it.
`404`	template_not_found	No route matches the path (not_found), or the resource does not exist on this account (template_not_found, job_not_found).
`413`	payload_too_large · page_weight_exceeded	payload_too_large: what you sent is over a limit. page_weight_exceeded: what the document pulled in while rendering is.
`422`	invalid_request	The body or the query failed validation. The message names the field.
`429`	rate_limited	Too many requests. Authenticated routes count per account, never per key.
`500`	internal_error	Unexpected failure. Quote request_id when reporting it.
`502`	render_failed	The renderer could not produce output. The message names what failed.
`504`	render_timeout	The render exceeded options.timeout_ms.

Every error uses one envelope, and every response carries an X-Request-Id. Quote it if you report a problem.