Getting Started

Get your API key

Once you sign up, we automatically create a default API key for you. Do the following:

1. Go to the API Keys tab.
2. Copy the access key and secret key, and store them in a safe place.
3. If you ever plan to share the entire request URL that contains your access key publicly, consider signing requests. Click the three-dots icon (⋯) next to the key, then click Edit API key. Enable the Require signed requests toggle, then click Save.

Make your first API request

After you get the 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 enabled the Require signed requests toggle for the API key you are using, you will also need to add the signature parameter to the request URL.

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

If you prefer to use POST instead of GET, send the access_key, url, and any other screenshot options as JSON in the request body to the URL below:

https://api.screenshotscout.com/v1/capture

Example:

curl -X POST https://api.screenshotscout.com/v1/capture \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "YOUR_ACCESS_KEY",
    "url": "https://example.com/"
  }'

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.