SEMSTORM - Audits

Audits API

This document contains basic information how to use SEMSTORM Audits API v3.

SEMSTORM PHP SDK library is under Apache License 2.0, This means that library is distributed without any warranties. What is more, support is not included. If you encounter any problems, please leave us a ticket.

Documentation

Audit

Retrieve audit

Endpoint:
https://api.semstorm.com/api-v3/audits/audit/{_AUDIT_ID_} [GET]

Parameters   PHP  CURL 
parameter method type required default  description
_AUDIT_ID_ GET integer yes - Audit id to retrieve.
Output   RESULT 
method type description
result["audit_info"] array Array with audit parameters and information.
result["audit_info"]["id"] integer Audit id.
result["audit_info"]["uid"] integer Audit owner id. This might be eg. teammate.
result["audit_info"]["parent_id"] integer Audit parent id if exist.
result["audit_info"]["title"] string Audit title.
result["audit_info"]["url"] string Audited url. If this is parent it will be null.
result["audit_info"]["device"] string Audit device. If this is parent it will be null.
result["audit_info"]["audit_type"] string Audit type. If this is parent it will be null.
result["audit_info"]["audit_settings"] array Audit settings. Its structure depends on whether audit is parent and audit type.
result["audit_info"]["status"] string Audit status.
result["audit_info"]["created"] string Timestamp of time when audit was created.
result["audit_info"]["updated"] string Timestamp of time when audit was updated.
result["audit_info"]["type"] string Audit group type.
result["audit_info"]["results_overall"] string Audit main score.
result["audit_data"] array Array with audit result data. If there are no results it will be empty array. Result structure vary beetween audit types.

Description:
Retrieve audit data.

Errors:
Request: "id" is invalid.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/audits/audit/_AUDIT_ID_.json?services_token=__ACCESS_TOKEN__

Output:

"audit_info": { "id": _AUDIT_ID_, "uid": "123", "parent_id": "0", "title": "Example audit", "url": "example.com", "device": "desktop", "audit_type": "lighthouse", "audit_settings": { (...) }, "status": "ready", "created": "1523956574", "updated": "1523956598", "type": "", "result_overall": "45" }, "audit_data": { (...) }

Create audit

Endpoint:
https://api.semstorm.com/api-v3/audits/audit [POST]

Parameters   PHP  CURL 
parameter method type required default  description
title POST string no Audit Audit title.
urls POST array no* - Array of urls to audit. All of those urls will be put into one 'advanced' audit. * Either this or 'keywords' field must be set.
keywords POST array no* - Array of keywords to audit. Each keyword will be created as one 'keyword' audit. * Either this or 'urls' field must be set.
keywords_options POST array no* - Array of keywords options. * This field is requred if field 'keywords' is defined.
device POST array yes - Array of devices to audit. Possible devices: 'desktop', 'mobile'.
audits_settings POST array no* - Array of audit types with their settings to set. * Either this or 'profile_id' field must be set.
profile_id POST integer no* - Profile id which settings will be used for audits. * Either this or 'audits_settings' field must be set.
Keywords options array
parameter type required default  description
engine integer yes - Engine id - it must be set in pair with proper country id (see here).
country integer yes - Country id - it must be set in pair with proper engine id (see here).
location string no - String defining location. It uses location engine to define geographical position, so should be as precise as it can be.
Output   RESULT 
method type description
result["cost"] integer Number of audit tokens this call cost.
result["left"] integer Number of audit tokens left for this account.
result["keywords"] array Array with created keyword audits keyed by keyword.
result["keywords"][_KEYWORD_] integer Keyword audit id.
result["urls"] array Array keyed by parent audit id with child audits (single url audit).
result["urls"][_PARENT_ID_][_CHILD_ID_] integer Child audit id.

Description:
Create audits.

Errors:
Access: Account dont have permission to create audits. - Your account doesnt have access to creating audits via api.
Limit: You dont have enough tokens. Your new audits require need tokens, while you have current. - You have reached your monthly limit for audits.
Request: Empty 'device' field.
Request: Invalid 'device' field
Request: No 'audit_settings' array or 'profile_id' field.
Request: Choose 'audit_settings' or 'profile_id' - cannot use both.
Request: Invalid audit name defined in 'audits_settings' array.
Request: Invalid setting key in audit name in 'audits_settings' array.
Request: Invalid setting key value in audit name in 'audits_settings' array.
Request: Invalid 'profile_id' field.
Request: No 'keywords' array or 'urls' array, define at least one.
Request: Empty 'keywords_options' field.
Request: Invalid 'keywords' value.
Request: Location decoding error.
Request: Location not found.
Request: Empty 'engine' field in keywords options.
Request: Empty 'country' field in keywords options.
Request: Invalid 'engine' field.
Request: Invalid 'country' field.
Request: Invalid 'urls' value.

PHP example code:
Curl:

curl -X POST -d '{ "urls": ["example.com"], "device": ["desktop"], "profile_id": 123 }' https://api.semstorm.com/api-v3/audits/audit.json?services_token=__ACCESS_TOKEN__

Output:

"cost": 2, "left": 998, "urls": { "123456": { "123457": "123457", "123458": "123458" } }

Delete audit

Endpoint:
https://api.semstorm.com/api-v3/audits/audit/{_AUDIT_ID_} [DELETE]

Parameters   PHP  CURL 
parameter method type required default  description
_AUDIT_ID_ GET integer yes - Audit id to delete.
Output   RESULT 
method type description
result[] bool True on success. Throws error on failure.

Description:
Delete audit. Warning! Deletion of audit is irreversable, so use with caution.

Errors:
Request: "id" is invalid.

PHP example code:
Curl:

curl -X DELETE https://api.semstorm.com/api-v3/audits/audit/_AUDIT_ID_.json?services_token=__ACCESS_TOKEN__

Output:

[ true ]

Refresh audit

Endpoint:
https://api.semstorm.com/api-v3/audits/audit/refresh [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST int yes - Audit id.
Output   RESULT 
method type description
result["cost"] integer Number of audit tokens this call cost.
result["left"] integer Number of audit tokens left for this account.
result["refresh"] array Array of audits ids which have been refreshed via this call.

Description:
Refresh audit.

Errors:
Request: "id" is invalid.

PHP example code:
Curl:

curl -X POST -d '{ "id": 1234 }' https://api.semstorm.com/api-v3/audits/audit/refresh.json?services_token=__ACCESS_TOKEN__

Output:

{ "cost": 1, "left": 4999, "refresh": {"1234": "1234"} }

Clone audit

Endpoint:
https://api.semstorm.com/api-v3/audits/audit/clone [POST]

Parameters   PHP  CURL 
parameter method type required default  description
id POST int yes - Audit id. This must be parent audit, as cloning single audit is impossible.
title POST string yes - Audit clone title to set.
Output   RESULT 
method type description
result["cost"] integer Number of audit tokens this call cost.
result["left"] integer Number of audit tokens left for this account.
result["refresh"] array Array of audits ids which have been refreshed via this call.

Description:
Refresh audit.

Errors:
Request: No id parameter.
Request: No title parameter.
Request: "id" is invalid.
Request: Cannot clone audit which is not finished.
Request: Cannot clone single audit, select audit group from front page.
Request: You dont have enough tokens. This audit require need tokens to clone, while you have current.

PHP example code:
Curl:

curl -X POST -d '{ "id": 1234, "title": "clone example" }' https://api.semstorm.com/api-v3/audits/audit/clone.json?services_token=__ACCESS_TOKEN__

Output:

{ "cost": 1, "left": 4999, "clone": {"1234": { "1235": "1235", "1236": "1236" } } }

List audits

Endpoint:
https://api.semstorm.com/api-v3/audits/audit/list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
parent_id POST int no - Audit parent id. If not set list of parents will be displayed, otherwise children of provided parent will be displayed.
sorting POST array no Sorting settings. For more help about sorting see here.
pager POST array no Pager settings.
filters POST array no Filter array.
Sorting array
parameter type required default  description
field string no created Field to sort by. Proper values are: "created", "device", "audit_type", "status", "result_overall". For more help about sorting see here.
sort string no desc Direction of sorting. Value "desc" stands for descending order, and "asc" for ascending order. Possible values are "desc", "asc".
Pager array
parameter type required default  description
items_per_page int no 25 Numbers of items per page. Possible values are 10, 25, 50.
page int no 0 Page number to retrieve counted from 0.
Filters
parameter type possible values description
title string Part of audit title.
audit_type array of strings lighthouse, pagespeed, webpagetest, yellowlab, sitespeedio, content One or more audit types which will be displayed.
device array of strings desktop, mobile One or more devices which will be displayed.
status array of strings wait, inprogress, ready, error One or more statuses which will be displayed.
Output   RESULT 
method type description
result array Array with audits list in defined sorting order.
result[]["id"] int Audit id.
result[]["uid"] int Audit owner id. This might be eg. teammate.
result[]["parent_id"] int Audit parent id. If audit is parent this will be 0.
result[]["title"] string Audit title.
result[]["url"] string Audited url. If this is parent it will be null.
result[]["device"] string Audit device. If this is parent it will be null.
result[]["audit_type"] string Audit type. If this is parent it will be null.
result[]["audit_settings"] array Audit settings. Its structure depends on whether audit is parent and audit type.
result[]["status"] string Audit status.
result[]["created"] string Timestamp of time when audit was created.
result[]["updated"] string Timestamp of time when audit was updated.
result[]["type"] string Audit group type.
result[]["results_overall"] string Audit main score.

Description:
Retrieve audits list.

Errors:
Request: "parent_id" is invalid.

PHP example code:
Curl:

curl -X POST -d '{ "parent_id": 123 }' https://api.semstorm.com/api-v3/audits/audit/list.json?services_token=__ACCESS_TOKEN__

Output:

[ { "id": "1234", "uid": "321", "parent_id": "123", "title": "example", "url": "example.com", "device": "desktop", "audit_type": "pagespeed", "audit_settings": { (...) }, "status": "ready", "created": "1522059489", "updated": "1522135027", "type": "audit", "result_overall": "85" }, (...) ]

Audits settings

Endpoint:
https://api.semstorm.com/api-v3/audits/audit/settings [POST]

Parameters   PHP  CURL 
parameter method type required default  description
This endpoint doesnt accept any parameters.
Output   RESULT 
method type description
result array Array with audit types keyed by audit type name.
result[_AUDIT_TYPE_NAME_]["title"] string Audit title.
result[_AUDIT_TYPE_NAME_]["settings"] array Array with possible settings to configure keyed by parameter name.
result[_AUDIT_TYPE_NAME_]["settings"][_PARAMETER_NAME_]["title"] string Parameter title.
result[_AUDIT_TYPE_NAME_]["settings"][_PARAMETER_NAME_]["description"] string Parameter description.
result[_AUDIT_TYPE_NAME_]["settings"][_PARAMETER_NAME_]["default_value"] mixed Parameter default value.
result[_AUDIT_TYPE_NAME_]["settings"][_PARAMETER_NAME_]["maxlength"]* integer Parameter maximum length. * Exist only for text parameters.
result[_AUDIT_TYPE_NAME_]["settings"][_PARAMETER_NAME_]["options"]* array Parameter possible values. * Exist only for parameters with predefined possible values.

Description:
Retrieve audits types with possible configuration.
Note that this endpoint returns only types accessible for account which making a call, so results may vary between different account.

Errors:

PHP example code:
Curl:

curl -X POST -d '{ "parent_id": 123 }' https://api.semstorm.com/api-v3/audits/audit/settings.json?services_token=__ACCESS_TOKEN__

Output:

{ "lighthouse": { "title": "Google Lighthouse", "settings": { (...) } }, (...) }

Audit profile

Retrieve profile

Endpoint:
https://api.semstorm.com/api-v3/audits/profile/{_PROFILE_ID_} [GET]

Parameters   PHP  CURL 
parameter method type required default  description
_PROFILE_ID_ GET integer yes - Audit profile id to retrieve.
Output   RESULT 
method type description
result["id"] integer Audit profile id.
result["uid"] integer Audit profile owner id.
result["title"] string Audit profile title.
result["types"] array Array of strings - audit types list
result["settings"] array Array keyed by audit types with their settings. Settings structure depends on audit type.

Description:
Retrieve audit profile settings.

Errors:
Request: "id" is invalid.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/audits/profile/_PROFILE_ID_.json?services_token=__ACCESS_TOKEN__

Output:

"id": _PROFILE_ID_, "uid": "123", "title": "example profile", "types": [ "lighthouse", "pagespeed" ], "settings": { "lighthouse": { (...) }, "pagespeed": { (...) }, }

Create profile

Endpoint:
https://api.semstorm.com/api-v3/audits/profile [POST]

Parameters   PHP  CURL 
parameter method type required default  description
title POST string yes - Audit profile title.
Output   RESULT 
method type description
result["id"] integer Audit profile id.

Description:
Retrieve audit profile settings.

Errors:
Request: "id" is invalid.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/audits/profile/_PROFILE_ID_.json?services_token=__ACCESS_TOKEN__

Output:

{ "id": _PROFILE_ID_ }

Update profile

Endpoint:
https://api.semstorm.com/api-v3/audits/profile/{_PROFILE_ID_} [PUT]

Parameters   PHP  CURL 
parameter method type required default  description
_PROFILE_ID_ GET integer yes - Audit profile id to update.
title POST string no - Audit profile title. Default: current title.
settings POST array no - Audit settings. Default: current settings. Warning! If this param is present it will override previous setting completely so not listed audit types will disappear.
Output   RESULT 
method type description
result["id"] integer Audit profile id.
result["uid"] integer Audit profile owner id.
result["title"] string Audit profile title.
result["types"] array Array of strings - audit types list
result["settings"] array Array keyed by audit types with their settings. Settings structure depends on audit type.

Description:
Update audit profile settings.

Errors:
Request: "id" is invalid.
Request: Field 'settings' must be array.
Request: Invalid audit name defined in 'audits_settings' array.
Request: Invalid setting key in audit name in 'audits_settings' array.
Request: Invalid setting key value in audit name in 'audits_settings' array.

PHP example code:
Curl:

curl -X PUT -d '{"title": "example profile"}' https://api.semstorm.com/api-v3/audits/profile/_PROFILE_ID_.json?services_token=__ACCESS_TOKEN__

Output:

"id": _PROFILE_ID_, "uid": "123", "title": "example profile", "types": [ "lighthouse", "pagespeed" ], "settings": { "lighthouse": { (...) }, "pagespeed": { (...) }, }

Delete profile

Endpoint:
https://api.semstorm.com/api-v3/audits/profile/{_PROFILE_ID_} [DELETE]

Parameters   PHP  CURL 
parameter method type required default  description
_PROFILE_ID_ GET integer yes - Audit profile id to delete.
Output   RESULT 
method type description
result[] bool True on success. Throws error on failure.

Description:
Delete audit profile.

Errors:
Request: "id" is invalid.

PHP example code:
Curl:

curl -X DELETE https://api.semstorm.com/api-v3/audits/audit/_PROFILE_ID_.json?services_token=__ACCESS_TOKEN__

Output:

[ true ]

List audit profiles

Endpoint:
https://api.semstorm.com/api-v3/audits/profile/list [POST]

Parameters   PHP  CURL 
parameter method type required default  description
sorting POST array no Sorting settings. For more help about sorting see here.
pager POST array no Pager settings.
filters POST array no Filter array.
Sorting array
parameter type required default  description
field string no title Field to sort by. Proper values are: "title". For more help about sorting see here.
sort string no desc Direction of sorting. Value "desc" stands for descending order, and "asc" for ascending order. Possible values are "desc", "asc".
Pager array
parameter type required default  description
items_per_page int no 25 Numbers of items per page. Possible values are 10, 25, 50.
page int no 0 Page number to retrieve counted from 0.
Filters
parameter type possible values description
title string Part of audit title.
audit_type array of strings lighthouse, pagespeed, webpagetest, yellowlab, sitespeedio, content One or more audit types which profile must have to be displayed.
Output   RESULT 
method type description
result array Array with audits list in defined sorting order.
result array Array with audit profiles list in defined sorting order.
result[]["id"] integer Audit profile id.
result[]["uid"] integer Audit profile owner id.
result[]["title"] string Audit profile title.
result[]["types"] array Array of strings - audit types list
result[]["settings"] array Array keyed by audit types with their settings. Settings structure depends on audit type.

Description:
Retrieve audit profiles list.

Errors:

PHP example code:
Curl:

curl -X POST -d '{}' https://api.semstorm.com/api-v3/audits/audit/list.json?services_token=__ACCESS_TOKEN__

Output:

[ { "id": "1234", "uid": "321", "title": "example profile", "types":[ "lighthouse" ], "settings": { (...) } }, (...) ]