Render

Render a PDF

Supply exactly one of url or html. Returns application/pdf.

header_html and footer_html are Chromium print templates: they support the classes date, title, url, pageNumber and totalPages, which Chromium substitutes at print time.

Counts one render.pdf. A PDF may have at most 100 pages; a document that prints to more is refused with 422 pdf_too_long and nothing is counted. PDFs are never cached.

post/v1/pdf

Request

  • Base URL: https://api.ironfang.com/render
  • URL: https://api.ironfang.com/render/v1/pdf
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Makes a synchronous render happen, and count, at most once. Any string up to 255 characters, remembered per account. The first request under a key is admitted and rendered as usual; a synchronous result is not kept, so the same request again under the key is a 409 idempotency_key_used and reserves nothing - send a new key to render again. A different request under a used key is a 409 idempotency_conflict. An identical request inside the cache window is still served from cache.

Request body

authorizationstring

Sets the Authorization header - the common case, spelled once. An explicit Authorization in headers wins over this.

block_adsboolean

Drop requests to known ad and tracker networks before they load. Stopped as network requests rather than hidden afterwards, so the page never spends time fetching them.

block_cookie_bannersboolean

Hide common consent banners, and undo the scroll lock they set - without which a full-page capture is one viewport tall.

Hidden, not accepted. Clicking "accept" would be a decision made on the site owner's behalf and recorded as theirs.

cssstring

Custom stylesheet, at most 65536 UTF-8 bytes. Applied after normal load/wait conditions and built-in hiding, before script, actions, settling and capture. Supports screenshots and PDFs, including @media print rules. Malformed stylesheet syntax is a 400 bad_request; Chromium determines supported properties and values.

device_scale_factornumber

Pixel density. 2 is retina: the same CSS size at twice the pixels.

headersobject

Extra HTTP headers sent with every request for the page.

hide_selectorsstring[]

CSS selectors to hide before capturing. Applied after load, so elements injected by script are covered.

no_cacheboolean

Force a fresh render instead of serving a cached one. Always billable. Excluded from the cache key, so repeated fresh requests do not collide.

scriptstring

JavaScript statements executed inside the target page's main-frame context after load/wait conditions and css, before actions and capture. Runs as an async function body: use await or return a promise for asynchronous work. Completion is awaited; return values are discarded. At most 16384 UTF-8 bytes and 5000 ms execution, further bounded by the remaining timeout_ms budget. Syntax errors, execution failures and timeouts return 422 render_failed with a sanitized message. Supports screenshots and PDFs; no browser-session or Playwright/Puppeteer APIs are exposed.

timeout_msinteger

Per-render timeout. Clamped to the service maximum - it can lower the ceiling but not raise it.

user_agentstring

Overrides the user agent, including any set by device.

wait_for_selectorstring

Wait for this element before capturing. Fails the render if it never appears, rather than returning a half-drawn page.

wait_until'load' | 'domcontentloaded' | 'networkidle'

When the page counts as ready. networkidle waits for traffic to stop and is bounded by the render timeout, because a page with polling never truly idles.

footer_htmlstring

Chromium print footer template.

header_htmlstring

Chromium print header template.

htmlstring

Markup to print. Mutually exclusive with url.

landscapeboolean
page_rangesstring

Pages to keep, numbered from 1: pages (5), ranges (1-3) and ranges open at the end (8-, to the last page), separated by commas. The PDF holds each selected page once, in document order, whatever order or repetition they were named in. Pages past the end are ignored; ranges that select no page are a 422 page_range_empty. The whole document is printed first and must be within the page bound (a 422 pdf_too_long otherwise), so a small range never renders an unbounded document. It counts as one PDF, as any PDF does.

paper_format'a3' | 'a4' | 'a5' | 'letter' | 'legal' | 'tabloid'

Named page size. Omit for Chromium's default, which is Letter. Sizes are portrait; landscape rotates them.

paper_heightstring

The custom page height, as paper_width.

paper_widthstring

A custom page width with its unit: in, cm, mm, pt or px (CSS: 96 px and 72 pt an inch), such as 210mm or 8.5in. Give it with paper_height, and not with paper_format: two sizes are refused, not reconciled. Each side is 1 to 100 inches. The page size, in order: a page's own @page { size } when prefer_css_page_size is set; otherwise paper_width/paper_height; otherwise paper_format; otherwise Letter. landscape rotates whichever of the last three applies.

prefer_css_page_sizeboolean

Let the page's own CSS @page { size: ... } decide the page size when it declares one. landscape does not rotate a CSS size. Without an @page size, the request's size applies as usual.

print_backgroundboolean

Include background colours and images. Off by default, matching a browser's print dialog.

scalenumber

Print scale. Omit or 0 for 1.0.

urlstring uri

Page to print. Mutually exclusive with html.

Example request

{
  "actions": [
    {
      "selector": "#show-more",
      "type": "click"
    },
    {
      "selector": "#details",
      "type": "wait_for_selector"
    }
  ],
  "css": ".chat-widget { display: none !important; }",
  "script": "document.querySelector('#pricing')?.click();",
  "page_ranges": "1-3, 5, 8-",
  "paper_height": "297mm",
  "paper_width": "210mm",
  "success_rules": {
    "fail_on_status": [
      "4xx",
      "5xx"
    ],
    "forbid_text": [
      "Sign in to continue"
    ],
    "require_selector": "#invoice"
  }
}

Response

The rendered PDF.

Changes

No recorded changes to this operation across all 1 revision of this API.