HTTP API

Endpoint: service.prerender.cloud

  1. Take a screenshot of a URL: /screenshot/$URL
  2. Create a PDF of a URL: /pdf/$URL
  3. Prerender/Server-side render a URL: /$URL

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.

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"

Create Screenshot or PDF from a URL

Think of this like a URL-to-JPG, or URL-to-PDF API. You can even use it right from your browser: service.prerender.cloud/screenshot/https://google.com

GET https://service.prerender.cloud/screenshot/$URL

curl http://service.prerender.cloud/screenshot/https://google.com/ > out.jpg

GET https://service.prerender.cloud/pdf/$URL

curl http://service.prerender.cloud/pdf/https://google.com/ > out.pdf

Render a URL (i.e. prerendering, server-side rendering)

You can think of this endpoint almost like a proxy. It returns the serialized HTML of the requested URL (the "origin") - useful for converting JavaScript apps to their JavaScript + HTML representation instead of just JavaScript.

All of our integration libraries (Node, Nginx, Apache etc.) proxy your requests through this endpoint. It can also be used as a conventional API - but if used as a conventional API, be mindful that the default options are designed to favor it as a proxy endpoint (caches, doesn't follow redirects, includes some server-side rendering compatibility add-ons)

GET https://service.prerender.cloud/$URL

curl http://service.prerender.cloud/https://google.com/ > out.html

See more examples.

How various content-types are handled:

  • only text/html is processed (you can't serialize a jpeg)
  • any other content-types are unprocessed and simply proxied
  • application/octet-stream fails with status code 400
  • all requests are subject to billing

Status codes

  1. 5xx from origin will return as 502 Bad Gateway (don't bother retrying)
  2. 1xx-4xx from origin are returned unmodified (including 301/302 redirects)
  3. a retryable error/timeout during prerender.cloud's processing will return as 500 (or 503)
  4. user/request error returns as 400, rate limited as 429

Controlling status codes

  1. if your request includes the Prerender-Follow-Redirects header and the submitted URL returns 301/302, the service will follow the redirects and return final status code
  2. if the page includes a meta tag<meta name="prerender-status-code" content="xxx">, the service will return the specified code (scroll down to read more)

Optional Headers

Configure Server Cache

Prerender-Disable-Cache
  • Disables/ignores the default 300 second (5 minutes) cache on the Prerender.cloud servers
  • curl --header "Prerender-Disable-Cache: true"

Prerender-Cache-Duration
  • Change the default cache duration from 300s (5 minutes) to anything up to 2592000s (1 month)
  • (ignored if cache is disabled)
  • curl --header "Prerender-Cache-Duration: 2592000"

Prerender-Recache
  • Updates/refreshes the cache even if it already exists. It will default to 300s, so use with Prerender-Cache-Duration
  • (ignored if cache is disabled)
  • curl --header "Prerender-Recache: true"

Disable Injected Scripts

Prerender-Disable-Ajax-Preload
  • Removes a JavaScript monkeypatch from the prerendered page that preloads your intial AJAX requests
  • Read more and see Ajax-Preload source code
  • curl --header "Prerender-Disable-Ajax-Preload: true"

Prerender-Disable-Ajax-Bypass
  • Removes a JavaScript monkeypatch from the prerendered page that adds X-Prerendered to the header of all XHR and fetch requests signaling to the middleware to go straight to origin
  • Read more and see Ajax-Bypass source code
  • curl --header "Prerender-Disable-Ajax-Bypass: true"

Prerender-Disable-Head-Dedupe
  • Removes a JavaScript monkeypatch from the prerendered page that is intended to prevent duplicate meta/title/script/style tags
  • Read more and see Head-Dedupe source code
  • Some libs/frameworks detect existing meta/title/style and don't need this, but in our experience this is still a worthwhile default.
  • curl --header "Prerender-Disable-Head-Dedupe: true"

Configure 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-Remove-Script-Tags
  • Removes all script tags except for application/ld+json. This means no client-side JavaScript and thus your app will no longer be isomorphic. Useful for reducing byte payload for the crawling/scraping use case.
  • curl --header "Prerender-Remove-Script-Tags: true"

Prerender-Remove-Trailing-Slash
  • Removes trailing slash from URLs submitted to the API.
  • e.g.: example.com/docs/ -> example.com/docs
  • The primary purpose is to achieve a higher server cache hit rate.
  • The SEO best practice is to use to 301s to redirect trailing slashes to non trailing slashes before prerender.cloud is hit and/or using link rel canonical tag.
  • curl --header "Prerender-Remove-Trailing-Slash: true"

Prerender-Follow-Redirects
  • By default, if your origin server returns 301/302, prerender.cloud will just return that outright - which is appropriate for the common use case of proxying traffic through prerender.cloud.
  • If using the API in a crawling/scraping/batching you may want to follow redirects.
  • curl --header "Prerender-Follow-Redirects: true"

Origin-Header-Whitelist
  • By default, the GET request prerender.cloud makes to your origin server is clean/pure (without any remnants of the original user request). This header allows you to forward certain headers to your origin.
  • At the moment, you can only forward:
    1. special header: Prerendercloud-Is-Mobile-Viewer
    2. any header starting with prerendercloud-
  • Forwarding any header will disable the 5 minute server cache
  • We'll add more options here as users request them.

Configure Server Response

Prerender-With-Metadata
  • Changes the response from text/html to application/json and returns an object 3 fields: {body, meta, links}
  • The values are base64 encoded:
    • Body is the normal pre-rendered response
    • meta is an object that includes (title, metaDescription, h1, ogImage, ogTitle, twitterCard)
    • links is an array of URLs/paths on the page

    This is useful for capturing SEO-relevant metadata during the pre-render.

  • curl --header "Prerender-With-Metadata: true"

Prerender-With-Screenshot
  • Changes the response from text/html to application/json and returns an object 2 fields: {body, screenshot}
  • The values are base64 encoded:
    • Body is the normal pre-rendered response
    • screenshot is a base64 encoded JPEG

    This is useful for savings screenshots or injecting them as open graph images. Often used with Prerender-With-Metadata

  • curl --header "Prerender-With-Screenshot: true"

Optional in-page configuration

Controlling Status Codes
  • The API endpoint returns whatever status the origin returns, which for single-page apps (index.html) is usually 200, unless you change it with these tags. This is irrelevant if you're just using service.prerender.cloud as a batch crawling/scraping tool.
  • 404 status code informs a bot that the page should be removed from their index
    • <meta name="prerender-status-code" content="404">
  • 301 status code informs a bot that their is newer content elsewhere
    • <meta name="prerender-status-code" content="301">
    • <meta name="prerender-header" content="Location: http://www.example.com"> (note: no other headers, currently, can be modified like this)

HTTP Error Codes

Our official libraries are configured to propogate 400 errors to what a visitor of your website would see, but the libraries are (or should be) configured to hide rate limiting (429) and 5xx errors and fallback to non-prerendered content.

400
  • Invalid Request
  • There will be an error message in the HTML, fix your request and retry
  • The client libraries will propogate this, so your users will see it!
  • 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 trying to prerender a request
    • or HTTPS Page is making HTTP (non secure) requests
    • ...or a random bug on our end
  • The error will show up in the prerender.cloud 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
  • 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@prerender.cloud

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@prerender.cloud

Hosted on Roast.io