The ScreenLab API allows you to create and retrieve scans in a programmatic way using conventional HTTP requests. The data in all POST requests you make should be formatted as JSON objects. All the responses are also sent in JSON format.

Authenticate

Make a post request with the email address and password for your ScreenLab account using the keys "email" and "password" to:

POST https://screenlab.io/api/auth/session

Assuming your login details are valid you will get a response like this:

{"session" : 
	{
	  "accesstoken":"XXXXXXXXcccc00xxx00000cc0000000xxx0aaa0",
	  "valid_until":"Mon May 16 2016 14:37:43 +0100",
	  "is_valid":true,
	  "valid_until_timestamp":1463405863,
	  "uri":"https://screenlab.io/auth/session/"},
	  "code":201,
	  "message":"resource created succesfully"
	}

Use the X-Accesstoken header

Once you have a valid access token you will need to supply it in the "X-Accesstoken" header in order to access the other API end points.

Retrieve your existing scan results

Using your access token you can retrieve an array of JSON objects containing the results of all your existing scans:

GET https://screenlab.io/api/scans

You can get the results for a single scan by making a get request with a scan ID:

GET https://screenlab.io/api/scan/(id)

You will recieve a single JSON object which contains the results:

{
  "name": "http://screenlab.io",
  "created": "2016-05-09 09:34:41",
  "impact": "2.7759",
  "flow": "-4.31957",
  "simplicity": "-2.20759",
  "s3_image_link": "https://screenlab-results.s3.amazonaws.com/screenlab.ioXXXXXXXXXX-final-overlay.png",
  "tags": null,
  "explain_impact_score": "is likely to be described as having a relatively high impact.",
  "explain_flow_score": "balances a lot of different areas of content.",
  "explain_simplicity_score": "presents a volume of information but without being too 'busy'. Depending on your goals you may wish to revise this"
}

Creating new scans

There are two ways that you can create new scans. You can post a JSON object containing a URL with optional width, height and name:

  var scanRequest = {
    "testUrl" : 'http://screenlab.io',
    "name" : 'ScreenLab Via API',
    "width" : 1280,
    "height" : 800
  };
POST https://screenlab.io/api/scan

Alternatively you can post a string containing a BASE64 encoded PNG and a name. When posting BASE64 strings both the string and a scan name are required:

  var scanRequest = {
    "imageData" : 'BASE64 ENCODED STRING',
    "name" : 'A Scan Name'
  };

POST https://screenlab.io/api/scan

Whichever way you create a new scan if it's succesful you will recieve a JSON object of the results in the same format as the GET request result above.

We're excited to see what you build with the API. If you make something cool or if you need any help, please let us know by sending an email to hello@screenlab.io.