Pre-rendering API#

Example Usage#

These curl requests are merely meant for education and understanding.

The standard approach to using headless-render-api.com for server-side rendering (pre-rendering) is configuring a webserver (Node, Apache, nginx, golang, Ruby, etc.) to forward all requests to service.headless-render-api.com (except those from headless-render-api.com itself)

e.g. as Node.js middleware: app.use(require("prerendercloud"))
e.g. as standalone pushstate server: cd build && npx prerendercloud-server
see all client integrations

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.headless-render-api.com/http://example.com/coffee%26cream?key=val&key2=val2";

// straight UTF-8 heart
"https://service.headless-render-api.com/http://example.com/♥";

// percent-encoded heart
"https://service.headless-render-api.com/http://example.com/%E2%99%A5";

Non-working example#

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

Without API Token#

curl --compressed -X GET "https://service.headless-render-api.com/https://reactjs-hello-world.netlify.com/"

With API Token#

curl --compressed -X GET \
 -H "X-Prerender-Token: mySecretToken"\
 "https://service.headless-render-api.com/https://reactjs-hello-world.netlify.com/"

Disable AJAX Preload#

Note: http headers are case-insensitive

curl --compressed -X GET \
 -H "Prerender-Disable-Ajax-Preload: true"\
 "https://service.headless-render-api.com/https://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.headless-render-api.com/https://reactjs-hello-world.netlify.com/"

Disable headless-render-api.com 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.headless-render-api.com/https://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.headless-render-api.com, 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.headless-render-api.com/https://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.headless-render-api.com/https://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.headless-render-api.com/https://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
  1. curl -sI https://www.YOUR-SERVER.com | grep -i Vary
  - should return: Vary: User-Agent

Headless-Render-API