Developer Docs

Making an API request

The url format for making a screenshot request to's API is:


  • YOUR_API_KEY should be replaced by your actual urlbox API key which you can get by registering for an account.
    (If you have already registered, you can find your API Key by logging in to your account.)

  • GENERATED_TOKEN should be replaced by a hash which is generated server side by taking the HMAC SHA1 of the query string and signing it with your API Secret.
    Example code is below to get you started in no time

  • FORMAT should be one of either png or jpg depending on which format you want the resulting image

  • REQUEST_OPTIONS should be replaced by a query string that contains all of the options you want to set.
    A table of all options and their defaults are shown below

An example, valid urlbox url is shown below, with the following options:

  • format is set to png
  • url is set to
  • thumb_width is set to 600 pixels wide
  • ttl is set to 108000 seconds which is equivalent to 1 day, meaning the screenshot will be freshly generated once daily

Simply putting this url as the src attribute in a normal img tag, the resulting image is: screenshot API showing a screenshot thumbnail of

Request Options

Below is a table listing all of the available options to the API.
Combine these options as parameters in the query string for e.g. ?

url-The URL of the website you want to screenshot
width1280Viewport width of the browser in pixels
height1024Viewport height of the browser in pixels
selector-Take a screenshot of the element that matches this selector
thumb_width-Width in pixels of the generated thumbnail, leave off for full-size screenshot
user_agent-User-Agent string used to emulate a particular client.
accept_langen-USSets an Accept-Language header on requests to the target URL
authorization-Sets an Authorization header on requests to the target URL
cookie-Set a cookie value before taking a screenshot. E.g. OptIn=true. Can be set multiple times to set more than one cookie.
delay-Amount of time to wait in milliseconds before urlbox takes the screenshot
wait_for-Waits for the element specified by this selector to be visible on the page before taking a screenshot
timeout30000Amount of time to wait in milliseconds for the website at url to respond
full_pagefalseSpecify whether to capture the full-length of the website
flashfalseEnable the flash plugin for flash using websites
forcefalseTake a fresh screenshot instead of getting a cached version
ttl2592000 (30 days)Short for 'time to live'. Number of seconds to keep a screenshot in the cache. Note the default is also the maximum value for this option.
quality80JPEG only - image quality of resulting screenshot (0-100)
disable_jsfalseTurn off javascript on target url to prevent popups
retinafalseTake a 'retina' or high definition screenshot equivalent to setting a device pixel ratio of 2.0 or @2x. Please note that retina screenshots will be double the normal dimensions and will normally take slightly longer to process due to the much bigger image size.
transparentfalseIf a website has no background color set, the image will have a transparent background (PNG only)
click-Element selector that is clicked before taking a screenshot e.g. #clickme would click the element with id="clickme"
hover-Element selector that is hovered before taking a screenshot e.g. #hoverme would hover over the element with id="hoverme"
bg_color-Hex code or css color string. Some websites don't set a body background colour, and will show up as transparent backgrounds with PNG or black when using JPG. Use this setting to set a background colour. If the website explicitly sets a transparent background on the html or body elements, this setting will be overridden.
crop_width-Crop the width of the screenshot to this size in pixels
hide_selector-Hides all elements that match the element selector by setting their style to `display:none !important;`. Useful for hiding popups.
highlight-Word to highlight on the page before capturing a screenshot
highlightfgwhiteText color of the highlighted word
highlightbgredBackground color of the highlighted word
use_s3falseSave the screenshot directly to the S3 bucket configured on your account
s3_path-The s3 path to save the screenshot to in your S3 bucket

Frequently Asked Questions

More than likely it's because you changed one or more of the parameters (e.g. url, width, full_page) without generating a new token. Remember that the token is unique to the specific request options.
It's to prevent anyone on the internet taking your API Key and being able to generate arbitrary requests with it.
Simply use the full_page option, and set it to true

Use our plugin to add screenshots or website thumbnails to your wordpress site. Signup for either the Urlbox trial or one of our paid plans, then enter your credentials into the Urlbox wordpress plugin settings page, and use the shortcode [urlbox url=''] to start generating website thumbnails right in your wordpress site or blog.

Send us the offending screenshot and we will try our best to make it look beautiful for you.
Well you can try setting cookies using our cookie option. You would need to authenticate with whichever website you want to screenshot, then copy the cookies that are saved in your browser and send them to Urlbox using the cookie parameter.
Yes. Check out the click and hover parameters.
Multiple ways. You can pass in a html selector e.g. '.popup' or '#overlay-modal' into the hide_selector option. You could also pass in a html selector to the click option which simulates a click on the target element. Finally some popups can be hidden using cookies. If you know which cookie needs to be set in order to disable the popup from showing, just pass the cookie name and value into the cookie option e.g. 'ShowPopup=no'.
Yes, so long as you are on a Startup or above plan. Retina screenshots are much more intensive to process than a regular resolution screenshot, and they take up a lot more space. On average they will take at least twice as long to render.

Use the wait_for option, pass it a selector. Urlbox will wait up to 30 seconds for the element to be in the DOM before taking a screenshot.


Use the selector option, pass it a selector. Please note that if the selector is incorrect or Urlbox does not find the element in the DOM after 30 seconds have passed, the screenshot request will fail.

Example Code

Sample code is available in the following languages: Node.js, Ruby, PHP, Python, Java and C#.
If you would like help integrating our API with your language please get in touch


Sample code to take website screenshots in Node.js

Check out our npm package here, and on github

// npm install urlbox --save

import Urlbox from 'urlbox';

// Plugin your API key and secret
const urlbox = Urlbox(YOUR_API_KEY, YOUR_API_SECRET);

// Set your options
const options = {
  url: '',
  thumb_width: 600,
  format: 'jpg',
  quality: 80

const imgUrl = urlbox.buildUrl(options);

// Now set it as the src in an img tag to render the screenshot
<img src={imgUrl} />


Sample code to take website screenshots in Ruby

# ruby gem coming soon
require 'openssl'
require 'open-uri'

def encodeURIComponent(val)
def urlbox(url, options={}, format='png')
  urlbox_apikey = 'YOUR_API_KEY'
  urlbox_secret = 'YOUR_API_SECRET'
  query = {
    :url         => url, # required - the url you want to screenshot
    :force       => options[:force], # optional - boolean - whether you want to generate a new screenshot rather than receive a previously cached one - this also overwrites the previously cached image
    :full_page   => options[:full_page], # optional - boolean - return a screenshot of the full screen
    :thumb_width => options[:thumb_width], # optional - number - thumbnail the resulting screenshot using this width in pixels
    :width       => options[:width], # optional - number - set viewport width to use (in pixels)
    :height      => options[:height], # optional - number - set viewport height to use (in pixels)
    :quality     => options[:quality] # optional - number (0-100) - set quality of the screenshot
  query_string = query.
    sort_by {|s| s[0].to_s }.
    select {|s| s[1] }.       
    map {|s| {|v| encodeURIComponent(v.to_s) }.join('=') }.
  token = OpenSSL::HMAC.hexdigest('sha1', urlbox_secret, query_string)

### USAGE: (format can be png or jpg, we default to png) ###
url = urlbox("", {thumb_width: 200, full_page: true, quality: 90}, 'jpg')
puts url
# url: ""


Sample code to take website screenshots in PHP

Check out our composer package here, and on github

// composer require urlbox/screenshots

$urlbox = UrlboxRenderer::fromCredentials('API_KEY', 'API_SECRET');
$options['url'] = '';
$urlboxUrl = $urlbox->generateUrl($options);

// $urlboxUrl is now ''

// Now stick it in an img tag


Sample code to take website screenshots in Python

#pypy package coming soon

import hmac
from hashlib import sha1
import urllib
def urlbox(args):
    apiKey = "xxx-xxx"
    apiSecret = "xxx-xxx"
    queryString = urllib.urlencode(args)
    hmacToken =, queryString, sha1)
    token = hmacToken.digest().encode('hex')
    return "" % (apiKey, token, queryString)

argsDict = {'url' : ""}
print urlbox (argsDict)


Sample code to take website screenshots in Java

import java.math.BigInteger;
import java.util.Map;
import java.util.HashMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Urlbox { 

  private String key;
  private String secret;

  Urlbox(String api_key, String api_secret) {
    this.key = api_key;
    this.secret = api_secret;

  // main method demos Example Usage
  public static void main(String[] args) { 
    String urlboxKey = "your-urlbox-api-key";
    String urlboxSecret = "your-urlbox-secret";

    // Set request options
    Map<String, Object> options = new HashMap<String, Object>();
    options.put("width", 1280);
    options.put("height", 1024);
    options.put("thumb_width", 240);
    options.put("full_page", "false");
    options.put("force", "false");

    // Create urlbox object with api key and secret
    Urlbox urlbox = new Urlbox(urlboxKey, urlboxSecret);
    try {
      // Call generateUrl function of urlbox object
      String urlboxUrl = urlbox.generateUrl("", options);
      // Now do something with urlboxUrl.. put in img tag, etc..
    } catch (UnsupportedEncodingException ex) {
      throw new RuntimeException("Problem with url encoding", ex);

  public String generateUrl(String url, Map<String,Object> options) throws UnsupportedEncodingException {

    String encodedUrl = URLEncoder.encode(url, "UTF-8");
    String queryString = String.format("url=%s", encodedUrl);

    for (Map.Entry<String, Object> entry : options.entrySet()) {
      String queryParam = "&"+entry.getKey()+"="+entry.getValue(); 
      queryString += queryParam;

    String token = generateToken(queryString, this.secret);
    String result = String.format("", this.key, token, queryString);
    return result;
  private String generateToken(String input, String key) {
    String lSignature = "None";
    try {
      Mac lMac = Mac.getInstance("HmacSHA1");
      SecretKeySpec lSecret = new SecretKeySpec(key.getBytes(), "HmacSHA1");

      byte[] lDigest = lMac.doFinal(input.getBytes());
      BigInteger lHash = new BigInteger(1, lDigest);
      lSignature = lHash.toString(16);
      if ((lSignature.length() % 2) != 0) {
        lSignature = "0" + lSignature;
    } catch (NoSuchAlgorithmException lEx) {
      throw new RuntimeException("Problems calculating HMAC", lEx);
    } catch (InvalidKeyException lEx) {
      throw new RuntimeException("Problems calculating HMAC", lEx);
    return lSignature;


Sample code to take website screenshots in C#

Check out our nuget package here

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Text;
using System.Security.Cryptography;
using System.IO;
public class Urlbox {
  public string urlGenerator(string url) {
    var urlboxApiKey = "xxx-xxx";
    var urlboxApiSecret = "xxx-xxx";
    var encodedUrl = HttpUtility.UrlEncode(url);
    byte[] key = Encoding.ASCII.GetBytes(urlboxApiSecret);
    var queryString = string.Format("url={0}", encodedUrl);
    var uniqueHash = generateHash(queryString, key);
    return string.Format("{0}/{1}/png/?{2}", urlboxApiKey, uniqueHash, queryString );           

  public static string generateHash(string input, byte[] key) {
    HMACSHA1 myhmacsha1 = new HMACSHA1(key);
    byte[] byteArray = Encoding.ASCII.GetBytes(input);
    MemoryStream stream = new MemoryStream(byteArray);
    return myhmacsha1.ComputeHash(stream).Aggregate("", (s, e) => s + String.Format("{0:x2}", e), s => s);