REST API

Screenshotbot has a relatively simple REST API. In most cases, you shouldn’t need to use this API directly, and we suggest you instead use recorder.jar.

Uploading a test run to screenshotbot, is a two/three step process. First you find-or-create each image using the md5sum of the image. For each image, if its the first time screenshotbot is seeing the image, we might ask you to upload the actual png (If you’ve uploaded it previously, it will tell you not to do that). Once you have all your images uploaded, you create a run. Screenshotbot will process your run and decide if it needs to do anything with it such as sending out GitHub issues.

General Overview

All our APIs are accessed from https://api.screenshotbot.io/api/. All requests will accept two arguments to indicate your API user: api-key, and api-secret-key. (You can get these values from you dashboard).

All resource objects will have "type" attribute that tells you what type it is. It will always be one of the documented types.

API responses will be returned in a JSON object that looks like this

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

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>
}