Headless-Render-API

logo
PricingDocsSupportBlogSign In

API docs

This page describes the functions of our HTTP API: pre-rendering, screenshots, PDFs, and scraping.
Each function targets a specific URL and is accessible through GET requests.
You can configure the options via HTTP headers.

Primary API Client: Node.js

To access Node.js client documentation, visit the Node.js client GitHub repository

Contact us

If you need a specific feature from a headless browser, please email us at support@headless-render-api.com

API Endpoint:

service.headless-render-api.com

API paths and functionality:
  1. /$url, for pre-rendering
  2. /screenshot/$url, for screenshots
  3. /pdf/$url, for PDFs
  4. /scrape/$url, for scraping

Open API Spec:

AI LLM (ChatGPT) Spec:

Notes:

For the target $URL, include it as part of the path without re-encoding or re-escaping beyond what's required for a standard browser URL input. Both UTF-8 encoding and percent-encoding are acceptable

The pre-rendering API is designed for webserver middleware. A faster, separate endpoint is available for scraping purposes without pre-rendering features.

The Screenshot, PDF, and Scrape APIs are accessible via simple HTTP GET requests

The scrape endpoint serializes HTML just like the pre-render endpoint, but without the injected JavaScript, preloaded state, custom serialization, and proxy functionality, making it up to twice as fast for HTML serialization. If you're looking to scrape JavaScript apps (or plain old HTML apps), this is your endpoint.

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"

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
  • 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