PDF

Base: /v1/pdf · Auth: API key or Clerk session

`POST /v1/pdf` — Render a PDF

Rate-limited and quota-limited — see Rate Limits & Quotas.

Body

Field	Type	Notes
`html`	string \| null	Inline HTML+CSS. Exactly one of `html`/`template_id`.
`template_id`	string \| null	A saved template’s id.
`variables`	object	Jinja2 variables for either `html` or the template.
`format`	`A4` \| `A3` \| `A5` \| `LETTER` \| `LEGAL`	Default `A4`.
`landscape`	boolean	Default `false`.
`print_background`	boolean	Default `true`.
`margins`	`{top, right, bottom, left}`	Inches. Default `0.4` each.
`page_load`	`{wait_until, timeout_ms, wait_for_selector}`	When the page counts as ready to print. Optional — see below.

`page_load`

Optional. Omit it and the defaults below apply.

Field	Type	Default	Notes
`wait_until`	`load` \| `domcontentloaded` \| `networkidle0` \| `networkidle2`	`load`	`networkidle0` = no network connections for 500ms; `networkidle2` = at most 2. Any other value is a `422`.
`timeout_ms`	integer	`30000`	How long to wait, 1000–120000. Also clamped to the service’s own render budget, so a value above what the server allows silently gets the server’s limit rather than failing.
`wait_for_selector`	string \| null	`null`	CSS selector to wait for before printing, e.g. `#main`. Must not be blank (use `null` for “don’t wait”) and at most 1000 characters.

Response `201`

{
  "id": "string",
  "status": "pending | rendering | completed | failed",
  "download_url": "string | null",
  "file_size_bytes": "integer | null",
  "render_duration_ms": "integer | null",
  "created_at": "datetime"
}

Errors

422 INVALID_HTML_CONTENT, 422 HTML_CONTENT_TOO_LARGE, 422 INVALID_HTML_TEMPLATE (bad Jinja2, or a variable your HTML references that’s missing from variables), 422 INVALID_PDF_OPTIONS, 422 INVALID_PAGE_LOAD_OPTIONS (timeout_ms out of range, or a blank/over-long wait_for_selector), 504 PDF_RENDERING_TIMEOUT (also returned when timeout_ms runs out waiting for wait_until or wait_for_selector), 502 PDF_RENDERING_FAILED, 502 PDF_STORAGE_FAILED, 413 PDF_TOO_LARGE, 422 PDF_TOO_MANY_PAGES, 429 USAGE_LIMIT_EXCEEDED, 429 PLAN_QUOTA_EXCEEDED.

`GET /v1/pdf` — List past jobs

Query: limit (1–100, default 20), offset (default 0). Returns PdfJobResponse[], newest first.

`GET /v1/pdf/{job_id}` — Get a job

Returns a single PdfJobResponse with a freshly-generated download_url.

Errors: 404 PDF_JOB_NOT_FOUND (also returned for someone else’s job).

PDF

POST /v1/pdf — Render a PDF

Body

page_load

Response 201