API

All screenshots are generated via our easy to use API. Using the API will consume 1 credit from your quota.

Generating API Tokens

You may create any number of API tokens once logged in. This allows you to create different tokens for different applications or teams within your business, and allows you to revoke them whenever you require.

API tokens should be kept secret at all times, and we recommend creating multiple when using them in seperate locations, should one be compromised.

Authentication

screendot uses a standard Bearer token to authenticate your requests. Send the following header to authenticate any request:

Authorization: Bearer YOUR_TOKEN_HERE

There are multiple examples available in our Examples page, but a simple curl request would look as follows:

curl -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN_HERE" \ 
    "https://screendot.io/api/standard?url=https://www.google.com"

Common Example

The most common use case is wanting to specify the viewport, and resize the image to be smaller. In the example below we set the viewport to 1920x1080, but shrink the image to 300px wide.

curl -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN_HERE" \ 
    "https://screendot.io/api/standard?url=https://www.google.com&browserWidth=1920&browserHeight=1080&width=300"

Response Type

By default the response to API queries will be an image, the actual screenshot you requested. However, you may send the "response" variable to "url" or "json" to alter that behaviour. URL requests will give you the CDN URL for your screenshot, and JSON requests will give you a JSON object with details about the screenshot, as shown below:

{
    "id":"8dfc6f3ba8c186e47edcfd2533d41711-193a0396.jpg",
    "url":"https:\/\/cdn.screendot.io\/i\/8dfc6f3ba8c186e47edcfd2533d41711-193a0396.jpg",
    "size":10204,
    "image":{
        "format":"jpg",
        "width":800,
        "height":null
    },
    "browser":{
        "width":1920,
        "height":1080
    }
}

Remember, the default response type is "image" which will return the binary image data for you to store.

Specifying Image Formats

screendot supports the following image formats: jpg, gif, png, webp. If you do not specify a format, you will receive a jpg image back. Add the format=X request variable to your API requests as shown below.

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    "https://screendot.io/api/standard?url=https://www.google.com&format=png"

Specifying Browser Dimensions

screendot allows you to customize the browser dimensions to simulate different screen sizes or mobile devices. By default screenshots are taken in 1920x1080 resolution. To change that, send browserWidth and browserHeight request variables as shown below.

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    "https://screendot.io/api/standard?url=https://www.google.com&browserWidth=800&browserHeight=600"

Tip: This feature allows you to simulate a mobile device by setting the width and height to the right parameters.

Specifying Image Dimensions

The above example allows you to specify the browser size, but screendot also allows you to resize the actual image after the screenshot is taken, by sending a width and height parameter.

You may send either height or width and screendot will automatically maintain the aspect ratio of the image. If you send both it may be squished to fit.

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    "https://screendot.io/api/standard?url=https://www.google.com&width=320"

Forcing a Refresh

screendot caches images by default, allowing you to benefit from the performance improvements associated with that. We store cached images for a maximum of 30 days, and will always prefer to return you a cached image where possible.

Should you wish to force screendot to fetch a brand-new screenshot, simply add the &refresh=true parameter to your query, as shown in the example below:

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    "https://screendot.io/api/standard?url=https://www.google.com&refresh=true"

Note that the CDN caches images, meaning you must send no-cache headers to refresh the CDN, add a unique query parameter to it, or request the image back directly if you need to refresh and the rest of your parameters are identical.

Custom Delay

You can add a custom amount of delay in milliseconds to the screenshot, which will cause screendot to wait an extra amount of time for the page to load. Add the &delay=X parameter with up to 10,000 ms of delay to sleep for 10 seconds.

The below example will wait 1 second (1000ms) before screenshotting google.com.

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    "https://screendot.io/api/standard?url=https://www.google.com&delay=1000"

Full Page

When screenshotting you may optionally have screendot scroll down the page to do a full page screenshot of the whole page. To do this, simply add the &fullPage=true parameter to your query.

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    "https://screendot.io/api/standard?url=https://www.google.com&fullPage=true"

Field Restrictions

Field	Rules
url	Valid http or https URL
delay	Optional, between 0 and 10000
browserWidth	Optional, between 50 and 4096
browserHeight	Optional, between 50 and 10000
width	Optional, between 50 and 4096
width	Optional, between 50 and 10000
format	Optional, one of "jpg", "gif", "webp", "png"
refresh	Optional, boolean
fullPage	Optional, boolean
response	Optional, one of "json", "image", "url"