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
, Automations
, and Testcases
.
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 Automations
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": []
}