Headless-Render-API

logo
PricingDocsSupportBlogSign In

PDF API

This document describes the PDF functionality/endpoint, its associated HTTP header options, and possible error responses.

Endpoint: service.headless-render-api.com

PDF Path: /pdf/$URL

Example URL: 

https://service.headless-render-api.com/pdf/https://example.com/

The target $URL is obviously part of the path, but do not re-encode or re-escape it beyond what you'd enter into a browser URL field. Both UTF-8 encoding and percent-encoding are acceptable.

Related links:

Auth

Send your secret API token (you'll get it after creating an account) as a header with all your requests to avoid rate limiting.
X-Prerender-Token
  • curl --header "X-Prerender-Token: secret-token"

Print webpage to PDF API

A print webpage to PDF API. Try it in your browser: service.headless-render-api.com/pdf/https://example.com

cURL

curl https://service.headless-render-api.com/pdf/https://example.com/ > out.pdf

Node.js client

// npm install prerendercloud
await prerendercloud.pdf("https://example.com/", {
  // Note: using noPageBreaks forces the following
  //  - pageRanges: "1",
  //  - preferCssPageSize: true
  noPageBreaks: true,
  printBackground: true,

  // emulatedMedia options: (screen, print, braille, embossed, handheld, projection, speech, tty, tv)
  emulatedMedia: "screen",

  // pageRanges: "1-3",
  // scale: 1.5,  // Default: 1, min: 0.1, max: 2.0
  // preferCssPageSize: true,
  // printBackground: true,
  // landscape: true,
  // marginTop: 1.75,
  // marginRight: 0.5,
  // marginBottom: 1.75,
  // marginLeft: 0.5,
  // paperWidth: 8.5,
  // paperHeight: 11,
});

Optional HTTP Headers for PDFs

prerender-pdf-no-page-breaks
  • Attempts to remove all page breaks (only for PDF)
    Alternatively, use "@page" in CSS for complete control @page {size: 8.5in 11in;}



    Use of this "no-page-breaks" option overwrites these other options:
    prerender-pdf-page-ranges=1
    prerender-pdf-prefer-css-page-size=true
    and ignores prerender-pdf-margin-* options
  • curl --header "prerender-pdf-no-page-breaks: true"
prerender-pdf-page-ranges
  • Paper ranges to print, one based, e.g., '1-5, 8, 11-13'. Pages are printed in the document order, not in the order specified, and no more than once. Defaults to empty string, which implies the entire document is printed. The page numbers are quietly capped to actual page count of the document, and ranges beyond the end of the document are ignored. If this results in no pages to print, an error is reported. It is an error to specify a range with start greater than end.
  • curl --header "prerender-pdf-page-ranges: 1-3, 5, 7, 10-15"
prerender-pdf-scale
  • Scale of the webpage rendering. Defaults to 1. Min: 0.1, max: 2
  • curl --header "prerender-pdf-scale: 1"
prerender-pdf-prefer-css-page-size
  • Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.

    Use of prerender-pdf-no-page-breaks forces this option to true
  • curl --header "prerender-pdf-prefer-css-page: true"
prerender-pdf-print-background
  • Print background graphics. Defaults to false
  • curl --header "prerender-pdf-print-background: true"
prerender-pdf-landscape
  • Whether to render the PDF in landscape mode (Paper orientation). Defaults to false.
  • curl --header "prerender-pdf-landscape: true"
prerender-pdf-margin-top
  • Top margin in inches. Defaults to 1cm (~0.4 inches).
    Ignored if using prerender-pdf-no-page-breaks or prerender-pdf-prefer-css-page-size
  • curl --header "prerender-pdf-margin-top: 0.4"
prerender-pdf-margin-right
  • Right margin in inches. Defaults to 1cm (~0.4 inches).
  • curl --header "prerender-pdf-margin-right: 0.4"
prerender-pdf-margin-bottom
  • Bottom margin in inches. Defaults to 1cm (~0.4 inches).
  • curl --header "prerender-pdf-margin-bottom: 0.4"
prerender-pdf-margin-left
  • Left margin in inches. Defaults to 1cm (~0.4 inches).
  • curl --header "prerender-pdf-margin-left: 0.4"
prerender-pdf-paper-width
  • Paper width in inches. Defaults to 8.5 inches
  • curl --header "prerender-pdf-paper-width: 8.5"
prerender-pdf-paper-height
  • Paper height in inches. Defaults to 11 inches.
  • curl --header "prerender-pdf-paper-height: 11"

Optional HTTP Headers for Browser Emulated Media

prerender-emulated-media
  • Emulates the given media type or media feature for CSS media queries

    default: screen

    Possible values are: screen, print, braille, embossed, handheld, projection, speech, tty, tv
  • curl --header "Prerender-Emulated-Media: screen"

Optional HTTP Headers for Headless-Render-API Server Behavior

prerender-wait-extra-long
  • Waits longer than normal for a page to finish rendering. Similar to Puppeteer's { waitUntil: 'networkidle' }. Useful for pages that depend on AJAX/XHR that fire late or IPFS hosted pages
  • curl --header "Prerender-Wait-Extra-Long: true"
prerender-dont-wait-for-web-sockets
  • By default, headless-render-api.com will wait for all ws activity to finish, but it doesn't make sense to "wait" for them to finish if they never stop. An example: real time prices on a stock price website.
  • curl --header "prerender-dont-wait-for-web-sockets: true"
prerender-block-cookies
  • By default, headless-render-api.com sends cookies back to the server. Use this to block them.
  • curl --header "prerender-block-cookies: true"

HTTP Error Codes

400
  • Invalid Request
  • There will be an error message in the HTML, fix your request and retry
  • Example causes:
    • malformed URL
    • a localhost URL/IP
    • or a page responds with content-type: application/octet-stream
429
  • Rate limited
  • Requests made without API tokens (or expired/missing billing information) will get this - see pricing
500
  • General Error
  • Example causes:
    • 10s (timeout) while waiting for a page to finish rendering (waits until all in-flight requests finish, load event, domContent event etc.)
    • or HTTPS Page is making HTTP (non secure) requests
    • ...or a random bug on our end
  • The error will show up in the headless-render-api.com web UI (after you sign in)
502
  • Bad Gateway (your origin returned 5xx)
  • It means we received a 5xx when trying to visit your page
  • Or it means we received a 403 (forbidden). Typically this means your page is behind a login wall or a firewall (like Cloudflare) is blocking the headless-render-api user-agent (make an exception to allow user-agents matching /prerendercloud/)
  • Probably not retryable. It depends on the site you're requesting. If it's your site, make sure it's up and running correctly
503
  • Over capacity (Rare)
  • Retry the request with some backoff
  • We'll see the error and our autoscaler will increase capacity within 5 minutes, but you should email us anyway: support@headless-render-api.com
504
  • Gateway Timeout (Rare)
  • Retry the request with some backoff
  • This is unexpected and should not happen. We'll see it, but you should email us anyway: support@headless-render-api.com