AlertSite offers two APIs to manage monitors: JSON API and XML API, each has its own capabilities and syntax. This document describes the JSON API. Documentation for the XML API is available in the AlertSite XML API topic.

AlertSite JSON API is a RESTful web service that allows you to manage monitors programmatically by sending and receiving JSON data to/from the AlertSite server. You can use this API to:

List your existing monitors, optionally filtered by type.
Create new monitors, including DéjàClick, Selenium, and SoapUI monitors.
Edit monitors – enable or disable monitors, change monitoring locations, run interval, and so on.
Get information about available monitoring locations, including your private locations.
Delete monitors.

You can access the API using any programming language or tool that supports making HTTP requests and parsing JSON responses.

The JSON API does not include operations to configure monitor blackouts and performance alerts. Use the Management API to do that.

Base URL

The base URL for all API requests is:

https://www.alertsite.com/alertsite-restapi

For example, POST /login means a POST request to https://www.alertsite.com/alertsite-restapi/login.

All requests are sent over a secure HTTPS connection.

JSON format

AlertSite REST API uses JSON as the data format for requests and responses. Requests containing a body (POST and PATCH) must include the Content-Type header:

Content-Type: application/json

Operations

AlertSite REST API provides the following operations:

Operation	Description
Login	Generates the session ID used to authenticate other API calls.
Get Monitors	Returns the configuration information for one, several or all monitors.
Get Locations	Returns information about all available monitoring locations, including private locations.
Add Monitor	Creates a new monitor. Supports uploading of DéjàClick scripts, Selenium scripts and SoapUI projects.
Edit Monitor	Updates the monitor configuration, for example, monitoring locations, run interval, enabled or disabled status.
Delete Monitor	Deletes a monitor specified by ID.

Note that the Add Monitor, Edit Monitor and Delete Monitor operations must be performed using an Admin, Co-Admin or Power User account.

Authentication

The first API call needs to be Login. It returns a session ID:

{
  "metadata" : {
    "login" : "[email protected]",
    "session" : "ef770427109e343e",
    "status" : "0",
    "message" : "No errors."
  }
}

This session ID is then used to authenticate other API calls.

There are two ways to authenticate requests:

By using the Authorization header.
By sending the login and session ID as query string parameters.

Authentication is done by adding the following header to all requests:

Authorization: Bearer BEARER_TOKEN

BEARER_TOKEN is a base64-encoded string login:sessionId. For example, if your login is [email protected] and the session ID is ef770427109e343e, you need to Base64-encode the string [email protected]:ef770427109e343e, which gives you ZGVtb0BleGFtcGxlLmNvbTplZjc3MDQyNzEwOWUzNDNl. The final header will be:

Authorization: Bearer ZGVtb0BleGFtcGxlLmNvbTplZjc3MDQyNzEwOWUzNDNl

Pseudocode to calculate the bearer token and add the Authorization header looks like:

request.addHeader("Authorization", "Bearer " + encode_base64(login + ":" + session))

Using query parameters

Another way to authenticate API calls is to pass the login and session ID as part of the request query string:

PATCH /devices/1234?login=demo%40example.com&session=ef770427109e343e

Note that the email needs to be URL-encoded, for example, @ is converted to %40. Many programming languages provide a method to do this.

This approach is the most suitable for testing API calls using cURL, wget, SoapUI, or similar tools. For production code, we recommend using the Authorization header.

Session ID expiration

Session IDs returned by the Login operation expire after 15 minutes, but get refreshed with each API call. So, the session expires 15 minutes after your last API call. After that any API call that requires authentication will return a session error. In this case, you will need to call Login again to get a new session ID for authentication.

Monitor IDs

Some REST API operations require a numeric monitor ID. You can get a list of all your monitor IDs using the Get Monitors operation. You can also see monitor IDs in AlertSite:

AlertSite UXM

AlertSite 1.0

AlertSite UXM

In monitor settings:
In the table on the Monitors > Overview > Config screen.

AlertSite 1.0

In the browser address bar of the monitor configuration screen:

Click the image to enlarge it.

Errors

API responses include metadata with the status and message fields. Status 0 and message "No errors" indicate a successful request. Any other statuses indicate an error. For example:

{
  "metadata": {
    "login": "[email protected]",
    "status": "40",
    "message": "Invalid login information."
  }
}

Possible errors and reasons are listed in the table below.

Code	Message	Comments
0	No errors.
20	Session is invalid.	Possible reasons: The request authentication information is missing, incomplete, or incorrect. The session ID is incorrect or has expired. Call Login again to get a new session ID for subsequent API calls.
30	Session failure.	The session ID is incorrect or has expired. Call Login again to get a new session ID for subsequent API calls.
40	Invalid login information.	Possible reasons: Incorrect login or password specified in the Login operation. The request authentication information is missing or incorrect. For example, session ID does not match the login. The user is locked.
41	Invalid user information.
47	Your account has not yet been activated.
48	Your login account has insufficient access to use this feature.	The operation requires an Admin, Co-Admin, or Power User account, but was called using a read-only or report-only account.
56	Service Agreement has not been accepted.	The specified user account has never logged into AlertSite before. Log in to AlertSite manually in your browser and accept the Service Agreement.
60	Missing or invalid data.
61	Invalid request. Bad path.	Request URL is incorrect or misspelled.
62	Missing or invalid login parameters.	The login or password (or both) is not specified in the Login operation.
63	Malformed JSON request.	POST and PATCH requests return this error if: JSON in the request body contains syntax errors, such as misplaced quotes, missing commas or duplicate fields. Use www.jslint.com to check your JSON syntax. Request body is missing.
64	Invalid parameter. Error [code] AlertSite.	Common reasons for this error are: A required parameter is missing, misspelled or has an incorrect value. For example, `billing_plancode` should be in the format UBM - A/A and not UBM - A/A:1:50. Incompatible parameters are specified. For example, Round Robin monitoring mode (`"mode": "R"`) with just 1 location instead of 2+ locations. You are trying to create a monitor using the `billing_plancode` that does not support this monitor type. Check which plan is used by your existing monitors and use the same plan code. You are trying to edit a BitBar monitor. These monitors cannot be created and edited via the API. The `script` value (contents of a DéjàClick, Selenium or SoapUI file to upload) is encoded incorrectly. For more information on the format of the `script` value, see Uploading DéjàClick, Selenium and SoapUI Files. Transaction requires between 1 and [max] steps, but you have 0 This error can occur if the specified `test_suite` or `test_case` was not found in the SoapUI project. Double-check the test suite and test case names. No credits available for this plan You have reached the monitor limit for the specified `billing_plancode`. No more monitors can be created using this plan. Feature not available with this plan The request body specifies a monitor parameter that is not supported by your AlertSite plan. If the error mentions a parameter not included in the request, this means that the default value of this parameter is not supported by your plan. Check the monitor configuration in AlertSite 1.0 to see which parameters and values are supported by your AlertSite plan. To avoid the error, change the request body to use a different value for the problematic parameter. For example, if the error says: Feature not available with this plan. ... (Follow Redirection? = YES) set the Follow Redirection parameter to No: "http_follow_redirects": "n"
65	Invalid device.	Possible reasons: The specified monitor ID was not found in your AlertSite account. A wrong HTTP method was used (for example, PATCH instead of POST). The request URL for the Edit Monitor or Delete Monitor operation is missing the monitor ID. The URL should be: https://www.alertsite.com/alertsite-restapi/devices/1234 (with 1234 replaced by your monitor ID)
66	Invalid location(s).	Possible reasons: Request body contains an incorrect location ID. See here for a list of AlertSite global location IDs. If you use private locations, use the Get Locations operation to get all your location IDs. Request body specifies `locations` but is missing `home_location`.
99	Internal CGI error.
501	Invalid HTTP Method. Allowed values are [method names]	For example, the request that should be made via POST was made via GET.

API last access time

Admin and Co-Admins can see which users accessed AlertSite APIs and when they did it last on the Manage Users screen.

Limitations

Monitor types

BitBar monitors cannot be created or edited through the API, but they can be listed by the Get Monitors operation.
Uploading password-protected SoapUI projects through the API is not supported.

Monitor settings

AlertSite JSON API provides access to just a subset of monitor configuration settings. Supported settings are listed in Monitor Data Fields. The following settings cannot be read or changed through the JSON API.

Note:

To modify these settings, use the Management API instead.

Common settings:

Enable local retry
Transaction tracing
Allow AlertSite QA testing
Performance alerts
Monitor blackouts
Custom properties

Web URL monitors:

Emulate browser
Use compression (emulate repeat visitor)
Payload for POST requests and custom HTTP methods

DéjàClick monitor settings:

Browser version
Enable UX
Show only root page UX values

Selenium monitor settings:

Browser version
Object timeout

API endpoint monitors:

Authenticate pre-emptively
Playback engine

Secure Web URL, Secure API endpoint, SoapUI, and FTPS monitor settings:

SSL version
SSL certificate

DNS monitor settings:

Name to resolve

Code examples

This documentation includes code examples in Python and cURL that can be found in the Examples section in individual operation descriptions.

Python examples use the Requests library.

cURL is a command-line tool that allows you to make API calls from command line (Windows command prompt, OS X terminal or Linux shell) without having to write programming code. cURL is preinstalled on macOS and on many Linux systems. Windows users can download cURL from this web site:

http://curl.haxx.se/download.html

AlertSite JSON API