Render Links

A render link is a dynamic URL that can be used directly to request a render from Urlbox's API.

The format of a render link is:

https://api.urlbox.io/v1/api-key/token/format?url=example.com

To create a valid render link:

1. Replace api key with your project api key.
2. Replace token with a signed token.*
3. Replace format with the desired output format.
4. Construct a query string made up of various render options.

Authentication

Authentication is through generating the signed token, which is a HMAC-SHA256 hash of the query string, signed by your project secret key.

The token generation should therefore be done server-side, and not in the browser, as you don't want to expose your secret key to the public.

Here is an example using node.js, with the query string set to url=example.com&width=600&height=400

import hmacSha256 from "crypto-js/hmac-sha256";
const secretKey = "YOUR_URLBOX_SECRET";
const options = "url=example.com&width=600&height=400";
const token = hmacSha256(options, secretKey).toString();

The same example, in Python:

import hmac
import hashlib
 
secret_key = "YOUR_URLBOX_SECRET"
options = "url=example.com&width=600&height=400"
token = hmac.new(bytes(secret_key , 'latin-1'), msg = bytes(options , 'latin-1'), digestmod = hashlib.sha256).hexdigest()

In Ruby:

require 'openssl'
 
secret_key = "YOUR_URLBOX_SECRET"
options = "url=example.com&width=600&height=400"
token = OpenSSL::HMAC.hexdigest('sha256', secret_key, options)

and in PHP:

$secret_key = "YOUR_URLBOX_SECRET";
$options = "url=example.com&width=600&height=400";
$token = hash_hmac('sha256', $options, $secret_key);

You can also check the token is correct from the command line:

echo -n "url=example.com&width=600&height=400" | openssl sha256 -hmac "YOUR_URLBOX_SECRET" 

Forcing Secure Render Links

If you want to force render links to be authenticated, you can enable the Force Secure Render Links option in your project's settings. Any render links requested without a valid token will receive a 401 Unauthorized response.

Options

The options portion of the render link is a query string made up of various render options. These are passed in as key=value pairs, where the key is the option name and concatenated together with & characters.

The only required option is one of url or html, which specifies the URL or HTML you want to render.

When rendering large payloads of HTML, (or custom js or css) in order to avoid passing around a huge render link, and avoiding the maximum URL length, it is recommended to use the JSON based REST API, to pass the HTML in as a JSON or form-encoded payload.

Because the options are passed in as the query string part of the render link, you must URL encode any special characters in the render options values. See the URL Encoding section for more details.

Response

The response from the API will be the binary data in the format you specified.

For example, when the format is png, the Content-Type of the response will be an image/png PNG image. This means the render link can be embedded directly into an HTML <img> tag on your page or in an email, or in a <meta> tag for open graph images to be unfurled across various social media and messaging platforms.

You can request a JSON response by setting the response_type option to json. This will return a JSON object with the following properties:

{
  "renderUrl":"path-to-temporary-url-of-render",
  "size":"size-of-render-in-bytes"
}

Caching and Auto Refreshing

Render links are cached for 30 days by default. This means that if you request the same render link twice within 30 days, the second request will return the same render as the first request.

Once the cache expires, the next time a render link is requested, the render will be generated again. The cache expiry time is a way of controlling how fresh, or stale, your screenshots are.

To reduce the cache duration time, set the ttl option to the number of seconds you want the render to be cached for. For example, to cache the render for 1 hour, set ttl=3600.

Deduplication

Render links are deduplicated, when two duplicate render links are requested at the same time, the second request will receive a 307 Temporary Redirect to continue waiting for the first request.

Long Running Requests

Requests will receive a 307 Temporary Redirect after 95 seconds. The Location header will contain the URL to follow to continue waiting for the render to finish processing.

The redirect timeout can be configured using the redirect_after option.

Errors

If there is an error with the request, the API will return a 4xx or 5xx status code. The response body will contain a JSON object with the following properties:

{
  "error": {
    "message": "error-message",
    "code": "error-code",
  }
}

URL Encoding

Because the options are passed in the query string, any special characters in the URL must be URL encoded. Sometimes referred to as percent encoding, this is a way of encoding special characters such that they can be passed in a URL and decoded on the other side.

For example, trying to render a URL that itself has a query string:

url=https://example.com/?foo=bar&baz=qux

If you were to pass this URL directly in the query string, the & characters would be interpreted as the start of a new option, and the URL would be truncated to https://example.com/?foo=bar.

To avoid this, you must URL encode the URL before passing it in the query string. The URL encoded version of the above URL would be:

url=https%3A%2F%2Fexample.com%2F%3Ffoo%3Dbar%2526baz%253Dqux

Many languages have built in functions for URL encoding, in JavaScript you would use the encodeURIComponent function:

const encodedString = encodeURIComponent(originalString);

In Python use the quote function from the urllib.parse module.

from urllib.parse import quote
encoded_string = quote(original_string)

In Ruby, use the CGI.escape method from the cgi module.

require 'cgi'
encoded_string = CGI.escape(original_string)

In PHP, use the rawurlencode function.

$encoded_string = rawurlencode($original_string);

In Golang, use the PathEscape function from the net/url package.

import "net/url"
encodedString := url.PathEscape(originalString)

In C#, use the EscapeDataString method from the System.Uri class.

string encodedString = Uri.EscapeDataString(originalString);

In Java, use the URLEncoder.encode method. Note that you also have to specify the encoding, which in most cases would be "UTF-8".

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
 
try {
    String encodedString = URLEncoder.encode(originalString, "UTF-8");
} catch (UnsupportedEncodingException e) {
    e.printStackTrace();
}

URI Length limit

When passing in large payloads, for example html, js or css, you may run into the maximum URI length limit of 2048 characters.

To avoid this, switch to using the JSON based REST API, where you can POST the HTML in as a JSON or form-encoded payload.

Examples

Render a full page screenshot of Urlbox.io

Create the render link, using the options: url=https://urlbox.io and full_page=true.

https://api.urlbox.io/v1/api-key/token/png?url=https%3A%2F%2Furlbox.io&full_page=true

Put the generated render link into an <img> tag:

<img src="https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/4dfa2abf70ae21f3ab8dff5023ecd08334f8527d/png?url=https%3A%2F%2Furlbox.io&full_page=true"/>

and the result is: