Example API requests#

These curl requests are merely meant for education and understanding.

The standard approach to using prerender.cloud is configuring a webserver (Node, Apache, nginx, golang, Ruby, etc.) to forward all requests to service.prerender.cloud (except those from prerender.cloud itself)

Constructing the API URL#

Do not re-encode or re-escape the URL beyond what is entered into a browser URL field. Both UTF-8 encoding and percent-encoding are acceptable. If you're using our official libraries, this is handled automatically.

Working examples#

// path with encoded ampersand and query params
// (side note: this coffee%26cream path on example.com doesn't work)
"https://service.prerender.cloud/http://example.com/coffee%26cream?key=val&key2=val2"

// straight UTF-8 heart
"https://service.prerender.cloud/http://example.com/♥"

// percent-encoded heart
"https://service.prerender.cloud/http://example.com/%E2%99%A5"

Non-working example#

// a percent-encoded question mark, %3F, will break query parameters
"https://service.prerender.cloud/http://example.com/%3Fkey=val"

Without API Token#

curl --compressed -X GET "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"

With API Token#

curl --compressed -X GET\
 -H "X-Prerender-Token: mySecretToken"\
 "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"

Disable AJAX Preload#

curl --compressed -X GET\
 -H "Prerender-Disable-Ajax-Preload: true"\
 "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"

Disable AJAX Preload and AJAX Bypass#

curl --compressed -X GET\
 -H "Prerender-Disable-Ajax-Preload: true"\
 -H "Prerender-Disable-Ajax-Bypass: true"\
 "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"

Disable Prerender.cloud server caching#

By default, we cache prerendered content on our server for 5 minutes.

curl --compressed -X GET\
 -H "Prerender-Disable-Cache: true"\
 "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"

Origin-Header-Whitelist#

Note: Using this functionality disables the 5-minute server cache

This functionality is useful because your origin-server receives a request from service.prerender.cloud, not from the original user-agent, IP or anything else revealing the original visitor. Be mindful that serving different content based on information you forward decreases cacheability, which is why we disable the server-cache when you use this feature.

Any header starting with prerendercloud-#

2 steps: put the header in origin-header-whitelist, and then include the header itself.

curl --compressed -X GET\
 -H "Origin-Header-Whitelist: Prerendercloud-Connecting-Ip-Random-Suffix-Abc"\
 -H "Prerendercloud-Connecting-Ip-Random-Suffix-Abc: ::ffff:127.0.0.1"\
 "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"

Multiple headers starting with prerendercloud-#

Note: We currently limit origin-header-whitelist to 150 chars, email us if you need more

curl --compressed -X GET\
 -H "Origin-Header-Whitelist: Prerendercloud-1abc, Prerendercloud-2abc"\
 -H "Prerendercloud-1abc: ::ffff:127.0.0.1"\
 -H "Prerendercloud-2abc: googlebot"\
 "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"

Prerendercloud-Is-Mobile-Viewer#

Prerendercloud-Is-Mobile-Viewer is a convenience header you can include in your Origin-Header-Whitelist header for getting a true/false on whether the user-agent is mobile or not. It's designed to mimic AWS' CloudFront CloudFront-Is-Mobile-Viewer

curl --compressed -X GET\
 -H "Origin-Header-Whitelist: Prerendercloud-Is-Mobile-Viewer"\
 "https://service.prerender.cloud/http://reactjs-hello-world.netlify.com/"
  • use this if you need to return different data dependening on user-agent
  • your origin server will receive the Prerendercloud-Is-Mobile-Viewer header with either true or false
  • If you use this, and indeed return different content based on this value, then use the Vary header
    • Here are commands you can run to verify you've configured it correctly:
      1. curl --user-agent "prerendercloud" -sI https://www.YOUR-SERVER.com | grep -i vary
        • should return: Vary: Prerendercloud-Is-Mobile-Viewer
      2. curl -sI https://www.YOUR-SERVER.com | grep -i Vary
        • should return: Vary: User-Agent
Hosted on Roast.io