Screenshot API Documentation

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.

The following documentation will provide detailed information about API usage, request parameters, responses and available endpoints. Through-out, useful examples are provided to assist you in getting started quickly and easily.

Quick Start

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

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.cleardot.com/api/screenshot?height=1080&width=1920&access_token=YOUR_ACCESS_TOKEN
				
			
Parameter Default Description
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.
mode fullpage Choose the capture mode. Either fullpage, viewport or element
height 1080 The height in pixels of the viewport to capture. This is ignored if mode parameter is set to full_page.
width 1920 The width in pixels of the viewport to capture.
response_type image Choose 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.
format jpeg The format of the image captured. Chose either jpeg or png.
delay 0 The delay in seconds (after page load) to wait before capturing a screenshot. Choose from 0 to 10 seconds (maximum).
file_name You can provide a filename which will be used when storing the screenshot.
user_agent Set 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_ads false Blocks 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.
grayscale false Apply a grayscale filter to the captured screenshot.
js Javascript 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:

Code Type Description
400 bad_request Invalid parameters or the target URL provides an error.
401 unauthorized An invalid API access key was supplied.
429 usage_limit_reached The given user account has reached its monthly allowed request volume.
403 function_access_restricted The given API endpoint is not supported on the current subscription plan.
500 internal_error An 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.

Code Examples

Below are code examples for a range of languages. Implementation in a language/framework that is not listed is usually as simple as using your favourite HTTP request package to make a GET or POST request and receive the response. Should you have any questions about implementation, feel free to reach out to our support team.