ScreenLab API Docs

This documentation covers the main tasks for interacting with the ScreenLab API, including authentication, retrieving scan lists and individual scans, and creating new scans.

Authenticating and Obtaining an ID Token

To use the ScreenLab API, you first need to authenticate and obtain an ID token.

Endpoint

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

Request body

{
  "email": "your_email@domain.com",
  "password": "your_password"
}

Response

If authentication is successful, you'll receive a JSON object with a `token` key containing your ID token.

Code examples

JavaScript

PHP

Python


async function getIdToken(email, password) {
  const response = await fetch('https://api.screenlab.io/auth', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email, password })
  });
  const data = await response.json();
  return data.token;
}


function getIdToken($email, $password) {
  $ch = curl_init('https://api.screenlab.io/auth');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'email' => $email,
    'password' => $password
  ]));
  curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  $data = json_decode($response, true);
  return $data['token'];
}


import requests

def get_id_token(email, password):
    response = requests.post('https://api.screenlab.io/auth', json={
        'email': email,
        'password': password
    })
    data = response.json()
    return data['token']

Getting a List of Scans

To retrieve a list of all your scans:

Endpoint

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

Headers

Authorization: YOUR_ID_TOKEN

Response

If the request is successful you will receive a JSON object containing your scan results.

Code examples

JavaScript

PHP

Python


async function getScans(idToken) {
  const response = await fetch('https://api.screenlab.io/scans/', {
    headers: {
      'Authorization': idToken
    }
  });
  return await response.json();
}


function getScans($idToken) {
  $ch = curl_init('https://api.screenlab.io/scans/');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $idToken
  ]);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return json_decode($response, true);
}


import requests

def get_scans(id_token):
    response = requests.get('https://api.screenlab.io/scans/', headers={
        'Authorization': id_token
    })
    return response.json()

Getting a Single Scan by ID

To retrieve a specific scan by its ID:

Endpoint

GET https://api.screenlab.io/scans/{id}

Headers

Authorization: YOUR_ID_TOKEN

Response

If the request is successful you will receive a list of your scans in an array of JSON objects.

Code examples

JavaScript

PHP

Python


async function getScan(idToken, scanId) {
  const response = await fetch(`https://api.screenlab.io/scans/${scanId}`, {
    headers: {
      'Authorization': idToken
    }
  });
  return await response.json();
}


function getScan($idToken, $scanId) {
  $ch = curl_init("https://api.screenlab.io/scans/$scanId");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $idToken
  ]);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return json_decode($response, true);
}


import requests

def get_scan(id_token, scan_id):
    response = requests.get(f'https://api.screenlab.io/scans/{scan_id}', headers={
        'Authorization': id_token
    })
    return response.json()

Creating a New Scan Using a URL

To create a new scan using a URL:

Endpoint

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

Headers

Authorization: YOUR_ID_TOKEN
Content-Type: application/json

Request body

{
  "name": "Scan Name",
  "url": "https://example.com",
  "type": "overlay",
  "location": "us",
  "width": 1920,
  "height": 1080,
  "explanation": true // optional
}

Note: When using a URL, the location, width and height fields are required along with name, type, and url. To receive a written explanation of the scans results include the explanation boolean set to true. Be aware that explanations are generated asynchronously and will not immediately be included in the returned JSON object. Fetch the scan results again in 2-3 minutes and the explanation should then be present.

Response

If the request is successful you will receive a JSON object containing your scan results.

Code examples

JavaScript

PHP

Python


async function createScanWithUrl(idToken, name, url, type, location, width, height) {
  const response = await fetch('https://api.screenlab.io/scans/', {
    method: 'POST',
    headers: {
      'Authorization': idToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name, url, type, location, width, height })
  });
  return await response.json();
}


function createScanWithUrl($idToken, $name, $url, $type, $location, $width, $height) {
  $ch = curl_init('https://api.screenlab.io/scans/');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => $name,
    'url' => $url,
    'type' => $type,
    'location' => $location,
    'width' => $width,
    'height' => $height
  ]));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $idToken,
    'Content-Type: application/json'
  ]);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return json_decode($response, true);
}


import requests

def create_scan_with_url(id_token, name, url, type, location, width, height):
    response = requests.post('https://api.screenlab.io/scans/', 
        headers={
            'Authorization': id_token,
            'Content-Type': 'application/json'
        },
        json={
            'name': name,
            'url': url,
            'type': type,
            'location': location,
            'width': width,
            'height': height
        }
    )
    return response.json()

Creating a New Scan Using a Base64 Encoded Image

To create a new scan using a base64 encoded image:

Endpoint

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

Headers

Authorization: YOUR_ID_TOKEN
Content-Type: application/json

Request body

{
  "name": "Scan Name",
  "imageData": "BASE64_ENCODED_IMAGE_DATA",
  "type": "overlay"
}

Note: When using a URL, the location, width and height fields are required along with name, type, and url.

Response

If the request is successful you will receive a JSON object containing your scan results.

Code examples

JavaScript

PHP

Python


async function createScanWithImage(idToken, name, imageData, type) {
  const response = await fetch('https://api.screenlab.io/scans/', {
    method: 'POST',
    headers: {
      'Authorization': idToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name, imageData, type })
  });
  return await response.json();
}


function createScanWithImage($idToken, $name, $imageData, $type) {
  $ch = curl_init('https://api.screenlab.io/scans/');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => $name,
    'imageData' => $imageData,
    'type' => $type
  ]));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $idToken,
    'Content-Type: application/json'
  ]);
  
  $response = curl_exec($ch);
  curl_close($ch);
  
  return json_decode($response, true);
}


import requests

def create_scan_with_image(id_token, name, image_data, type):
    response = requests.post('https://api.screenlab.io/scans/', 
        headers={
            'Authorization': id_token,
            'Content-Type': 'application/json'
        },
        json={
            'name': name,
            'imageData': image_data,
            'type': type
        }
    )
    return response.json()