Getting Started

The Clearshot Screenshot API has been built from the ground up to provide a simple, reliable, cost-effective and fast API that any developer/company can use to take perfect website screen captures. Included are a range of features to customize your requests to suit your use case.

Quick Start

To get started fast, here are some examples you can use/test. You’ll need to get a token here.

				
					curl https://app.clearshotapi.com/api/screenshot? \
url=https://apple.com \
&response_type=image \
&access_token=__YOUR_ACCESS_TOKEN__
				
			
				
					$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://app.clearshotapi.com/api/screenshot/",
  CURLOPT_HTTPHEADER =>
    array(
      "Authorization: Bearer [-- YOUR ACCESS TOKEN HERE --]",
      "Accept: application/json"
    ),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => http_build_query(
    array(
      "url" => "https://apple.com",
      "json" => "true"
    )
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  $json_response = json_decode($response);
}
				
			
				
					import requests
import json

headers = {
  "Authorization": "Bearer [-- YOUR ACCESS TOKEN HERE --]",
  "Accept": "application/json"
}
payload = {
  "url": "https://apple.com",
  "json": "true"
}

url = 'https://app.clearshotapi.com/api/screenshot'

response = requests.post(url, headers = headers, params = {}, data = json.dumps(payload))

response.raise_for_status()
response.json()
				
			
				
					var request = require("request");

var options = {
  method: "POST",
  url: "https://app.clearshotapi.com/api/screenshot",
  headers: {
    "Authorization": "Bearer [-- YOUR ACCESS TOKEN HERE--]",
    "Accept": "application/json"
  },
  json: true,
  form: {
    "url": "https://apple.com",
    "json": "true"
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  var data = body;
});
				
			
				
					package main

import (
  "encoding/json"
  "net/http"
  "bytes"
)

type ScreenshotCaptureResult struct {
  Image        string `json:"image,omitempty"`
  Width        string `json:"width,omitempty"`
  Height       string `json:"height,omitempty"`
  RemoteStatus string `json:"remote_status,omitempty"`
  Cached       bool   `json:"cached,string,omitempty"`
  URL          string `json:"url,omitempty"`
}

func main() {
  payload := []byte(`{"url":"https://apple.com","json":"true"}`)

  client := &http.Client{}

  req, err := http.NewRequest("POST", "https://app.clearshotapi.com/api/screenshot", bytes.NewBuffer(payload))

  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer [-- YOUR ACCESS TOKEN HERE --]")
  req.Header.Set("Accept", "application/json")

  resp, err := client.Do(req)

  if err != nil {
    panic(err)
  }

  var result ScreenshotCaptureResult

  err = json.NewDecoder(resp.Body).Decode(&result)
  if err != nil {
    panic(err)
  }
}
				
			

API Access Key & Authentication

Clearshot provides API access through HTTPS GET and POST endpoints.

All calls to the API need to be authorized using a valid access token which can be managed on the Clearshot admin panel.

For GET requests, the access token should be passed via the query string. Here is an example:
For POST requests, the access token should be passed in the header data.

				
					GET https://app.clearshotapi.com/api/screenshot?access_token=YOUR_ACCESS_TOKEN&url=https://apple.com
				
			

Parameters

Listed below are the available parameters for the screenshot API.
To use a parameter, include the parameter and a value in the query string or POST data.

Here’s an example with providing viewport sizing parameters in a GET request:

				
					GET https://app.clearshotapi.com/api/screenshot?height=1080&width=1920&access_token=YOUR_ACCESS_TOKEN
				
			
ParameterDefaultDescription
access_token (required)A valid API access token is required to make requests. You can manage your access tokens in the admin panel.
url (required)The complete URL including protocol of the web page you want to capture.
modefullpageChoose the capture mode. Either fullpage, viewport or element
height1080The height in pixels of the viewport to capture. This is ignored if mode parameter is set to full_page.
width1920The width in pixels of the viewport to capture.
response_typeimageChoose a response type. image will return an image type response which you can save directly. json will provide a json response with HTTP status code and a hosted image link. This image should be saved immediately as images are deleted after a pre-determined time period. (Usually 30 days).

A json type responsed will contain image, url and remote_status. Image is the URL of the hosted screenshot. URL is the URL of the captured page. Remote_status is the HTTP response code received from the target URL.
formatjpegThe format of the image captured. Chose either jpeg or png.
delay0The delay in seconds (after page load) to wait before capturing a screenshot. Choose from 0 to 10 seconds (maximum).
file_nameYou can provide a filename which will be used when storing the screenshot.
user_agentSet a User Agent header to be used when capturing a screenshot, to emulate a device or browser type. Ensure the User Agent string is URL encoded to be used correctly. You can find a list of user agents sorted by device/software/layout engine here.
block_adsfalseBlocks common advertising networks to prevent ads from being captured in screenshots. Set this to true or false.
accept_lang Set the Accept Language header on requests to the target page to capture screenshots in the specified language. More information is available here.
grayscalefalseApply a grayscale filter to the captured screenshot.
jsJavascript string to be injected onto the target page. The string must be URL encoded to be properly parsed and injected.
css CSS styling string to be injected onto the target page. The string must be URL encoded to be properly parsed and injected.

API Errors

If an API request fails, an HTTP error code will be returned. The error codes below provide a description of why the error occurred.
For successful API requests, you can expect the HTTP code 200.

Common API Errors:
CodeTypeDescription
400bad_requestInvalid parameters or the target URL provides an error.
401unauthorizedAn invalid API access key was supplied.
429usage_limit_reached The given user account has reached its monthly allowed request volume.
403function_access_restrictedThe given API endpoint is not supported on the current subscription plan.
500internal_errorAn internal error occurred.

Render Modes Explained

The mode parameter allows you to define the size of the screenshot you will be capturing. Below we’ll run through the 2 different modes and how they operate.

 

Full Page

Full page or fullpage as the mode parameter value is the default mode.
As the name suggests, this mode captures a screenshot of the entire target page. The height of the image is determined by the page length. Whilst height is automatic, you can pass a width parameter to determine the width of the page capture.

When capturing full page screenshots, we recommend using the jpeg format (instead of png) to avoid very large file sizes and slower image loading performance.

 

Viewport

Viewport mode restricts the render sizing to a specified set of dimensions. To enable viewport capture mode, set mode to the value: viewport.

The viewport dimensions (in pixels) are passed to the API via the width and height parameters.

The default viewport size is 1280×1024.

Note that when providing viewport dimensions, this will affect the webpage render sizing and can trigger responsive breakpoints in the target URLs styling. As a result, the returned image may not always be the exact size of the dimensions passed in the request.

 

 

Element

This mode allows you to capture a specific element on the page. To specify what element you wish to capture, simply set your mode to element and provide a CSS selector to element_selector.

The default viewport for element capture is 1280x1024px.