Site

A Site is the primary object in the Cursion application and represents the primary domain name all pages of that Site share. The Site object is how the Cursion platform organizes all subsequent objects including Pages, Scans, Tests, Schedules, Alerts, and CaseRuns.

Site object

{
   "id":"46053956-761b-4ca5-8cec-3be796695d12",            // uuid specific to the Site
   "user":"example@gmail.com",                             // user denoted by email
   "site_url":"https://example.com",                       // Site's url begining with https:// or http://
   "time_created":"2021-11-18T15:58:42.821177Z",           // timestamp of object creation
   "time_crawl_started":"2021-11-18T15:58:42.821177Z",     // timestamp of when last site crawl began
   "time_crawl_completed":"2021-11-18T15:58:42.821177Z",   // timestamp of when last site crawl completed
   "tags": ["tag1", "tag2"],                               // <optional> list of info for user to track data
   "info":{ 
      "status":{
         "badge":"success",   // info for front-end badge coloring
         "score": 69.25,      // health score, combination of yellowlab and lighthouse. Type -> float
         "health":"Good"      // health status (Good, Okay, Poor)
      },
      "yellowlab":{           // high level Yellow Lab scores
         "fonts": 100,
         "badCSS": 95,
         "jQuery": 100,
         "images": 100,
         "pageWeight": 94,
         "globalScore": 67,
         "serverConfig": 100,
         "badJavascript": -5,
         "cssComplexity": 99,
         "domComplexity": 100,
         "javascriptComplexity": -28
      },
      "lighthouse":{          // high level Lighthouse scores
         "seo": 85,    
         "average": 78.25,  
         "performance": 60,  
         "accessibility": 75,   
         "best_practices": 93,   
         "pwa": 89,
         "crux": 90
      },
      
      "latest_scan":{
         "id":"fdbfea8a-d049-45df-8085-2be020e3e193",          // most recent Scan uuid
         "time_created":"2021-11-19 19:35:54.297510+00:00",    // timestamp of most recent Scan creation
         "time_completed":"2021-11-19 19:38:58.345660+00:00",  // timestamp of most recent Scan completion
      },
      "latest_test":{
         "id":"eff40980-a9c2-45d6-8929-99564715a216",          // most recent Test uuid
         "score": 97,                                          // most recent Test score (out of 100)
         "time_created":"2021-11-19 19:35:28.315063+00:00",    // timestamp of most recent Test creation
         "time_completed":"2021-11-19 19:38:58.345660+00:00",  // timestamp of most recent Test completion
      }
   }
}

Create a Site

This endpoint allows the creation task to run asynchronously on the server and resolves quickly. The full on boarding of a site may take several minutes to complete as the server is actively generating Cases, crawling the site for Pages, and creating initial base-line Scans for each.

data in this request:

"data": {
   
   "site_url": "https://example.com",     // <required> 
   "page_urls": [                         // <optional> an array of page urls you want to add to the site. This prevents the site from being crawled
      "https://example.com",
      "https://example.com/blog",
      "https://example.com/terms"
   ],    
   "tags": ["tag1", "tag2"],              // <optional> for user to track data
   "no_scan": false,                      // <optional> bool parameter which, when true, will skip the initial Scan creation (defaults to false)
   
   "configs": {                           // <optional> Configurations for webdriver (only needed if no_scan == False)
      "browser":"chrome",                 // browser to be used for the tasks, either chrome or firefox
      "device": "desktop",                // sets the user-Agent, one of dekstop or mobile
      "mask_ids": null,                   // element id's you wish to mask when taking a screenshot (seperated by comma)
      "interval": 5,                      // time (seconds) the driver will wait between checking if page has loaded
      "window_size": "1920,1080",         // dimensions of webdriver window. format -> (width,height)
      "max_wait_time": 60,                // maximum time (seconds) the driver will wait before moving on to next task
      "min_wait_time": 10,                // minimum time (seconds) the driver will wait before checking if page has loaded and or moving on to next task
      "disable_animations": false,        // bool which, when true, will disable all animations and videos on the site during a Scan
      "auto_height": true,                // bool which, when true, will automatically resize the browser window to the full lenghth of a Page
      "timeout": 300                      // maximum time (seconds) the driver will run before completely timing out during an the VRT process
   }

}

Warning

Passing the configs object is optional. However, if you do pass the object you must specify all sub-components.

POST - /site

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{CURSION_API_BASE_URL}/site'
headers = {
   "content-type": "application/json",
   "Authorization" : CURSION_API_TOKEN
}
data = {
   "site_url": "https://example.com"
   "page_urls": [
      "https://example.com",
      "https://example.com/blog",
      "https://example.com/terms"
   ], 
   "tags": ["tag1", "tag2"]
   "no_scan": False,
   "configs": {                    
      "browser": "chrome",
      "device": "desktop",
      "mask_ids": None,
      "interval": 5,
      "window_size": "1920,1080",
      "max_wait_time": 60,
      "min_wait_time": 10
      "disable_animations": False,
      "auto_height": True,
      "timeout": 300
   }
   }
}

# send the request
res = requests.post(
   url=url, 
   headers=headers, 
   data=json.dumps(data)
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
    "id":"188b882a-f644-4304-b2b9-def9d8c76b57",
    "user":"example@gmail.com",
    "site_url":"https://example.com",
    "time_created":"2021-11-22T14:54:19.134671Z",
    "tags": ["tag1", "tag2"],
    "info":{
        "latest_scan":{
            "id": null,
            "time_created": null,
            "time_completed": null,
         },
        "latest_test":{
            "id": null,
            "time_created": null,
            "score": null
        },
        "yellowlab":{
         "fonts": null,
         "badCSS": null,
         "jQuery": null,
         "images": null,
         "pageWeight": null,
         "globalScore": null,
         "serverConfig": null,
         "badJavascript": null,
         "cssComplexity": null,
         "domComplexity": null,
         "javascriptComplexity": null
         },
         "lighthouse":{   
            "seo": null,    
            "average": null,  
            "performance": null,  
            "accessibility": null,   
            "best_practices": null,
            "pwa": null,
            "crux": null    
         },
         "status":{
            "score": null,
            "health": null,
            "badge": "neutral"
         }
    }
}

Retrieve a Site

This endpoint returns a single Site object and is useful as a simple "detailed view" of the site.

GET - /site/<site:id>

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/site/<site:id>'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.get(
    url=url, 
    headers=headers, 
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "id":"46053956-761b-4ca5-8cec-3be796695d12",
   "user":"example@gmail.com",
   "site_url":"https://example.com",
   "time_created":"2021-11-18T15:58:42.821177Z",
   "tags": ["tag1", "tag2"],
   "info":{
      "status":{
         "badge":"success",
         "health":"Good",
         "score": 80,
      },
      "yellowlab":{ 
         "fonts": 100,
         "badCSS": 95,
         "jQuery": 100,
         "images": 100,
         "pageWeight": 94,
         "globalScore": 67,
         "serverConfig": 100,
         "badJavascript": -5,
         "cssComplexity": 99,
         "domComplexity": 100,
         "javascriptComplexity": -28
      },
      "lighthouse":{
         "seo": 85,
         "average": 78.25,
         "performance": 60,
         "accessibility": 75,
         "best_practices": 93,
         "pwa": 89,
         "crux": 90,
      },
      "latest_scan":{
         "id":"fdbfea8a-d049-45df-8085-2be020e3e193",
         "time_created":"2021-11-19 19:35:54.297510+00:00",
         "time_completed":"2021-11-19 19:38:58.345660+00:00",
      },
      "latest_test":{
         "id":"eff40980-a9c2-45d6-8929-99564715a216",
         "score": 97,
         "time_created":"2021-11-19 19:35:28.315063+00:00",
         "time_completed":"2021-11-19 19:38:58.345660+00:00",
      }
   }
}

Retrieve many Sites

This endpoint returns a paginated response with all Site objects filtered by your account and ordered by time_created. This endpoint is useful when needing to displaying your sites in a table view for example. The limit parameter specifies the total number of objects you want returned per "group" (we recommend keeping this under 10 for best performance). The offset parameter specfies which "group" to return. For example, limit=10&offset=10 in a total dataset of 30 objects would return 10 sites in range site #10 - site #20.

GET - /site?limit=10&offset=0

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/site?limit=10&offset=0'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.get(
    url=url, 
    headers=headers, 
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "count":30,
   "next":"https://api.cursion.dev/v1/ops/site?limit=10&offset=20",
   "previous":"https://api.cursion.dev/v1/ops/site?limit=10&offset=10",
   "results":[
      {
         "id":"46053956-761b-4ca5-8cec-3be796695d12",
         "user":"example@gmail.com",
         "site_url":"https://example.com",
         "time_created":"2021-11-18T15:58:42.821177Z",
         "tags": ["tag1", "tag2"],
         "info":{
            "status":{
               "badge":"success",
               "health":"Good",
               "score": 80,
            },
            "yellowlab":{ 
               "fonts": 100,
               "badCSS": 95,
               "jQuery": 100,
               "images": 100,
               "pageWeight": 94,
               "globalScore": 67,
               "serverConfig": 100,
               "badJavascript": -5,
               "cssComplexity": 99,
               "domComplexity": 100,
               "javascriptComplexity": -28
            },
            "lighthouse":{
               "seo": 85,
               "average": 78.25,
               "performance": 60,
               "accessibility": 75,
               "best_practices": 93,
               "pwa": 89,
               "crux": 90,
            },
            "latest_scan":{
               "id":"fdbfea8a-d049-45df-8085-2be020e3e193",
               "time_created":"2021-11-19 19:35:54.297510+00:00",
               "time_completed":"2021-11-19 19:38:58.345660+00:00",
            },
            "latest_test":{
               "id":"eff40980-a9c2-45d6-8929-99564715a216",
               "score": 97,
               "time_created":"2021-11-19 19:35:28.315063+00:00",
               "time_completed":"2021-11-19 19:38:58.345660+00:00",
            }
         }
      },
      {
         "id":"46053956-761b-4ca5-8cec-3be796695d12",
         "user":"example@gmail.com",
         "site_url":"https://exampletwo.com",
         "time_created":"2021-11-18T15:58:42.821177Z",
         "tags": ["tag1", "tag2"],
         "info":{
            "status":{
               "badge":"success",
               "health":"Good",
               "score": 80,
            },
            "yellowlab":{ 
               "fonts": 100,
               "badCSS": 95,
               "jQuery": 100,
               "images": 100,
               "pageWeight": 94,
               "globalScore": 67,
               "serverConfig": 100,
               "badJavascript": -5,
               "cssComplexity": 99,
               "domComplexity": 100,
               "javascriptComplexity": -28
            },
            "lighthouse":{
               "seo": 85,
               "average": 78.25,
               "performance": 60,
               "accessibility": 75,
               "best_practices": 93
               "pwa": 89,
               "crux": 90
            },
            "latest_scan":{
               "id":"fdbfea8a-d049-45df-8085-2be020e3e193",
               "time_created":"2021-11-19 19:35:54.297510+00:00",
               "time_completed":"2021-11-19 19:38:58.345660+00:00",
            },
            "latest_test":{
               "id":"eff40980-a9c2-45d6-8929-99564715a216",
               "score": 97,
               "time_created":"2021-11-19 19:35:28.315063+00:00",
               "time_completed":"2021-11-19 19:38:58.345660+00:00",
            }
         }
      },
      {
         "id":"46053956-761b-4ca5-8cec-3be796695d12",
         "user":"example@gmail.com",
         "site_url":"https://examplethree.com",
         "time_created":"2021-11-18T15:58:42.821177Z",
         "tags": ["tag1", "tag2"],
         "info":{
            "status":{
               "badge":"success",
               "health":"Good",
               "score": 80,
            },
            "yellowlab":{ 
               "fonts": 100,
               "badCSS": 95,
               "jQuery": 100,
               "images": 100,
               "pageWeight": 94,
               "globalScore": 67,
               "serverConfig": 100,
               "badJavascript": -5,
               "cssComplexity": 99,
               "domComplexity": 100,
               "javascriptComplexity": -28
            },
            "lighthouse":{
               "seo": 85,
               "average": 78.25,
               "performance": 60,
               "accessibility": 75,
               "best_practices": 93,
               "pwa": 89,
               "crux": 90
            },
            "latest_scan":{
               "id":"fdbfea8a-d049-45df-8085-2be020e3e193",
               "time_created":"2021-11-19 19:35:54.297510+00:00",
               "time_completed":"2021-11-19 19:38:58.345660+00:00",
            },
            "latest_test":{
               "id":"eff40980-a9c2-45d6-8929-99564715a216",
               "score": 97,
               "time_created":"2021-11-19 19:35:28.315063+00:00",
               "time_completed":"2021-11-19 19:38:58.345660+00:00",
            }
         }
      },
      ### SHORTENED FOR DISPLAY PURPOSES ###
   ]
}

Delete a Site

Because Sites are the primary objects within the Cursion API, once a Site is deleted a cascade effect ensues and all assocaited Scans , Tests, Schedules, and Alerts are subsequently deleted.

Caution

Please use caution with this endpoint as it is irreversible.

DELETE - /site/<site:id>

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/site/<site:id>'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.delete(
    url=url, 
    headers=headers, 
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

   {
      "message": "site deleted successfully"
   }

Delete many Sites

This endpoint allows the user to send an array of Site id's to be deleted. Cursion will iterate through the id's and respond with an object detailing which Sites were successfully deleted and which were not.

Caution

Please use caution with this endpoint as it is irreversible.

POST - /sites/delete

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/sites/delete'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

data = {
   "ids": ['<site:id1>', '<site:id2>', '<site:id3>']
}

# send the request
res = requests.post(
    url=url, 
    headers=headers, 
    data=data,
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "status": true,
   "num_succeeded": 3,
   "succeeded": [
      '<site:id1>', 
      '<site:id2>', 
      '<site:id3>'
   ],
   "num_failed": 0,
   "failed": []
}