REST API

Screenshotbot provides an API so that you can build internal tooling or write custom scripts.

In most cases, you shouldn’t need to use this API directly, and we suggest you instead use the command line interface instead. In particular, you should avoid calling this API from your tests directly.

This API is still useful query the data that you've already uploaded, or do things like automatically accepting changes.

General Overview

All our APIs are accessed from https://api.screenshotbot.io/api/. For Enterprise customers you should use the endpoint that you access it from, for example https://customer.screenshotbot.io/api/.

In most cases, error handling is done using HTTP error codes, with success being 200. In some older endpoints we always return 200, but wrap the response as follows:

    {
      "success": <true|false>
      "response": <actual-response>
      "error": <error message if success is false>
    }

We try to maintain backward compatibility, but this is not guaranteed. To specify a particular API version to maintain compatibility with, pass the optional X-client-api-version HTTP request parameter. The current API version is 17.

Authentication

We use HTTP Basic authentication, with the username being the API Key, and the password being the API Secret.

For example, if using curl, you can make read requests like so:

      curl -u api-key:api-secret https://api.screenshotbot.io/api/...

Find or create an image record

Send a POST request to /api/image.

Arguments:

• hash: An md5sum of the image file
• content-type: Content type of the image. Currently only image/png is supported.

Response

    {
      "id": <unique-id>,
      "uploadUrl": <a url to upload to>
    }

If the uploadUrl is present, it means you have to upload the image via a PUT request to the given URL. This will usually only be present the first time you upload this specific image (determined by the md5sum). However we might ask you to reupload images occasionally, so you should not rely on this assumption.

Create a run

Send a POST request to /api/run.

Arguments:

• channel: A channel name chosen by the user. If the channel doesn’t exist we’ll create it.
• github-repo: A link to GitHub repo for the project. Please contact us if you host your repository elsewhere. Can be omitted for non production runs.
• commit: A SHA1 hash denoting the current Git commit. Can be omitted for non trunk runs.
• is-clean: Boolean, true if the current git repository is clean. Can be omitted for non trunk runs`.
• branch: The branch name. For example master, or v2.0.1. Can be omitted for non trunk runs.
• is-trunk: If this is a primary branch that’s being tracked. For instance you might track master branch or a release branch. But you wouldn’t track a feature branch created by a developer.
• screenshot-records: A JSON-encoded list of screenshot objects.

Each screenshot object has the following structure:

    {
       "name": <name of the screenshot>,
       "imageId": <id of the image object associated with this screenshot>
    }

Response:

    {
      "id": <id of the run>
    }