Give us the address of a page you already publish and get a document back. If your invoice, statement or report is already a web page behind your own login-free URL, there is nothing to re-author — the page is the template.

POST/v1/render/urlAuth required

Everything else matches POST /v1/render: the same authentication, the same credit cost, the same error envelope and the same response headers.

Body parameters

urlrequired

string

The page to render. Must be https, must be reachable from the public internet, and must not carry credentials in the address.

page_setup

object

Page geometry: size, orientation, margin, and running header/footer slots (which accept {{page}} and {{pages}}). Your page’s own @page and print stylesheet are respected.

format

string

default: pdf

Output format. Raster formats return page 1 only for a multi-page document, and say so in X-Pixldocs-Pages-Dropped.

pdfpngwebp

scale

number

default: 1

Output scale multiplier for raster formats, 0.1–4. Ignored for PDF.

watermark

boolean

Force the watermark on. Test keys always watermark.

expect_selector

string

A CSS selector that only the real document contains. If nothing matches it once the page has loaded, the request is refused with 422 expected_content_missing instead of returning a PDF of whatever was served.

Example request

bash

curl -X POST https://api.pixldocs.com/v1/render/url \
  -H "Authorization: Bearer pxd_YOUR_KEY" \
  -H "Content-Type: application/json" \
  --output invoice.pdf \
  -d '{
    "url": "https://billing.example.com/invoices/R-1041/print",
    "page_setup": { "size": "A4", "margin": { "top": "16mm", "bottom": "16mm" } }
  }'

What the page may reach

This is the one endpoint where the renderer touches the network, so the address is checked twice: once here before a credit moves, and again inside the browser for the navigation, every redirect it follows and every stylesheet, image and font the page pulls in. Anything resolving to a private, loopback, link-local or otherwise reserved address is refused — a URL that points inside your own network, or ours, is a 400 url_not_allowed, not a document.

Subresources the guard refuses are still counted, and a render that lost any of them reports it in X-Pixldocs-Blocked-Requests. A page that renders differently from the one in your browser should never be something you have to discover from the pixels.

What the page must be

The page has to be publicly reachable — we cannot log in as you, so a page behind a session cookie renders as your sign-in screen. Put the print view on a URL guarded by an unguessable token instead. A URL that answers 404 or 500 is a 422 from us rather than a tidy PDF of your error page.

Fonts are the one difference from a browser: the renderer prints in the families it bundles (GET /v1/fonts), so a webfont your page loads resolves to a bundled family of the same class. If the exact typeface matters, use POST /v1/render/html or a saved template.

Errors

An address we will not fetch is 400 url_not_allowed, a page that fails to load or answers with an error status is 422 url_fetch_failed, and a page that never finishes loading is 422 url_timeout. None of these cost a credit: the debit happens as the navigation starts and is refunded automatically whenever the request returns no document.

We render as an anonymous visitor and hold no session, so a page behind a login answers us with its sign-in screen at 200. That is refused as 422 url_requires_login rather than returned as a tidy PDF of a login box. Give us a URL that is readable signed-out — a share link or a signed URL — or pass expect_selector when a page legitimately contains a sign-in form.