Getting Started

This guide will walk you through the steps you need to take to capture your first screenshot. The entire process will take no more than a few minutes.

Create your first API key

Once you have signed up, you need to create your first API key. Do the following:

Go to the "API Keys" tab.
Press the "+ Create API key" button, enter the Name (used for your reference only) of the key. If you ever plan to share the entire request URL that contains your access key publicly, consider toggling the "Require signed requests" toggle. Press "Create".
Save the generated access key and secret key in a safe place. You won't be able to view them again from your account panel. Press "Done".

Make your first API request

After you have created your first API key, you are ready to send your first API request.

Screenshot Scout supports both GET and POST HTTP requests.

To take a screenshot of a page with a GET HTTP request, send a request to:

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/

Replace the access_key parameter value with your access key, and the url parameter value with the URL of the page you would like to take a screenshot of.

If you switched the "Require signed requests" toggle while creating your API key, you will also need to add the signature parameter to the request URL. Learn more about signed requests here.

Sending an API request to the request URL above without specifying any additional screenshot options will request rendering a PNG screenshot using a standard desktop viewport with all sensible defaults. If you would like to change this, please explore the available screenshot options.

Response

We support two response types: binary (default) and JSON.

Binary

To request a binary response (the default response type), send an API request to this URL:

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/

The API will return a binary response that you can then use like this inside HTML:

<img src="https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/" alt="A screenshot of example.com" />

Along with the returned binary, we will also return the exact screenshot URL via this response header: Screenshot-Scout-Screenshot-URL

The screenshot URL will be accessible for up to 4 hours after rendering, but this is not guaranteed. If you want this to be guaranteed, or if you want to store screenshots for longer, consider using caching.

JSON

To request a JSON response, add response_type=json to the request URL:

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&response_type=json

The returned JSON will look like this:

{
  "screenshot_url": "https://cdn.screenshotscout.com/cdafae824c3a09d30a9660cd6473025b7ec7d9d8828722490502511c97076163.png"
}

Errors

Whenever an error occurs when you send an API request, we will return a JSON object with the error details:

{
  "error_code": "invalid_options",
  "error_message": "One or more options are invalid.",
  "errors": [
    {
      "option": "url",
      "message": "The \"url\" option is required."
    }
  ]
}

The JSON will always contain a machine-readable error code and a descriptive error message. The HTTP response status code will indicate the type of the error.