For a long time now, you could manage your account and monitors, or retrieve monitor data, using version 3 of the Uptrends API (API v3). Since then, we’ve introduced a newer version of our API (API v4), which includes many more features and an overall better experience.
Version 3 of our API is no longer supported, and has been disabled. We recommend you switch to version 4 as soon as possible. This article will guide you through the process, and list the key differences to keep in mind when switching API versions. In addition to some functional changes, there are some differences in terminology used, for example in monitor definitions. In care you’re using the API for things like creating or updating monitors, you’ll need to adjust the names of some fields in your request body to match the API v4 monitor definition, as an example.
Similarities
The Uptrends API v3 and API v4 are both REST APIs, which allow you to perform basic CRUD (Create, Read, Update, Delete) operations on certain Uptrends entities. Generally speaking, both APIs function in a very similar fashion, offering functionality to retrieve, create, update or delete items such as monitors in your account.
In both cases, access requires HTTP Basic Authentication based on valid Uptrends credentials. It’s worth noting, however, that API v4 requires you to create a separate API account - more on this below.
Advantages
The newer API v4 offers a much more extensive set of features than its older counterpart. Examples of functionality available in v4 that isn’t present in v3 include operator management, retrieving monitor check data, dashboard management, modifying or creating alert definitions, retrieving your SLA data, and much more! For a full overview of the functions supported by API v4, visit its Swagger page.
API v4 handles authentication slightly differently (more on that below), which means you won’t have to use your regular Uptrends credentials when setting up scripts or applications to interact with the Uptrends API.
Differences
If you’re using any scripts or applications to interact with our API, there are some key differences to keep in mind. In this section, we’ll go through these differences, so that you can adjust the setup with which you’re accessing the API accordingly.
Base URL
The API v3 base URL is https://api.uptrends.com/v3
followed by the specific operation URL. For API v4, the base URL has changed to https://api.uptrends.com/v4
followed by the specific operation URL.
For example, retrieving all monitor definitions through the API v3 requires a GET to https://api.uptrends.com/v3/probes
whereas the API v4 equivalent would be a GET to https://api.uptrends.com/v4/Monitor
to retrieve the same information.
Operation URLs
In the example above (retrieving all monitor definitions), you can see that the specific operation URL for this particular operation has also changed from /probes
to /Monitor
. Most operation URLs have changed in a similar fashion going from API v3 to v4. We’ve included a complete mapping of API v3 endpoints and their API v4 equivalents below.
Object definitions
In addition to the changes to operation URLs, the actual definitions of Uptrends entities (monitors, monitor groups, operators, etc…) have also changed. As an example, let’s look at some abridged responses from both APIs, to requests GET /probes
and GET /Monitor
for API v3 and v4 respectively.
The API v3 response will look as follows (some information has been omitted for brevity):
{
"Guid": "c353669c0e3b4f818adef562894f5506",
"Name": "Galactic Resorts FPC",
"URL": "http://www.galacticresorts.com/",
"CheckFrequency": 5,
"ProbeType": "FullPageCheck",
"IsActive": true,
"GenerateAlert": false,
"Notes": "Example monitor notes",
...
}
Compare that to the v4 response (again some information has been omitted):
{
"MonitorGuid": "c353669c-0e3b-4f81-8ade-f562894f5503",
"Name": "Galactic Resorts FPC",
"MonitorType": "FullPageCheck",
"GenerateAlert": false,
"IsActive": true,
"CheckInterval": 5,
"Notes": "Example monitor notes",
"Url": "http://www.galacticresorts.com/",
...
}
You can see that certain objects haven’t changed. For example, both APIs respond with a Name
field, which contains the monitor’s name. However, there are certain key differences in terms used. For example, the Guid
field from the v3 response has become MonitorGuid
in v4, and CheckFrequency
has become CheckInterval
. A complete overview of differences in object definitions can be found in this article. Some of those objects are specific to certain monitor types, and are listed in separate tables.
Authentication
Our API v3 requires Basic Authentication, using the same Uptrends username/password you’d use to log into the Uptrends web application.
Authentication works slightly differently in API v4, in that you’ll have to register for a separate API account first. We’ve explained the process of registering for an account and API v4 authentication in this knowledge base article. For any calls made to API v4, you’ll need to use the credentials received as a result of the steps outlined in that article.
Comparison of operations
Below, you can find a series of tables mapping common operations in API v3 with their API v4 equivalents.
Monitor operations
Description | API v3 endpoint | API v4 endpoint | Method |
---|---|---|---|
Return the definition of all monitors available in the account | /probes | /Monitor | GET |
Create a new monitor | /probes | /Monitor | POST |
Return the definition of the specified monitor | /probes/{ProbeGuid} | /Monitor/{monitorGuid} | GET |
(Partially) update the definition of the specified monitor | /probes/{ProbeGuid} | /Monitor/{monitorGuid} | PUT or PATCH |
Delete the specified monitor | /probes/{ProbeGuid} | /Monitor/{monitorGuid} | DELETE |
Monitor group operations
Description | API v3 endpoint | API v4 endpoint | Method |
---|---|---|---|
Get all monitor groups | /probegroups | /MonitorGroup | GET |
Create a new monitor group | /probegroups | /MonitorGroup | POST |
Get the details of a monitor group | /probegroups/{ProbeGroupGuid} | /MonitorGroup/{monitorGroupGuid} | GET |
Update the monitor group with the Guid specified | /probegroups/{ProbeGroupGuid} | /MonitorGroup/{monitorGroupGuid} | PUT |
Delete the specified monitor group | /probegroups/{ProbeGroupGuid} | /MonitorGroup/{monitorGroupGuid} | DELETE |
Get a list of all members of a monitor group | /probegroups/{ProbeGroupGuid}/members | /MonitorGroup/{monitorGroupGuid}/Member | GET |
Add the specified monitor to the monitor group | /probegroups/{ProbeGroupGuid}/members | /MonitorGroup/{monitorGroupGuid}/Member/{monitorGuid} | POST |
Remove the specified monitor from the monitor group | /probegroups/{ProbeGroupGuid}/members | /MonitorGroup/{monitorGroupGuid}/Member/{monitorGuid} | DELETE |
List alert history for all monitors in group | /probegroups/{ProbeGroupGuid}/alerts?Start= |
/Alert/MonitorGroup/{monitorGroupGuid} | GET |
Monitor status and statistics
Description | API v3 endpoint | API v4 endpoint | Method |
---|---|---|---|
Get a list of all monitor group status data. | /probegroups/{ProbeGroupGuid}/status | /Status/MonitorGroup/{monitorGroupGuid} | GET |
Get all monitor status data. | /probes/{ProbeGuid}/status | /Status/Monitor/{monitorGuid} | GET |
Get the monitor group statistics. | /probegroups/{ProbeGroupGuid}/statistics?Start=<startdate>&End=<enddate>&Dimension=<dimension> | /Statistics/MonitorGroup/{monitorGroupGuid} | GET |
Get the monitor statistics. | /probes/{ProbeGuid}/statistics?Start=<startdate>&End=<enddate>&Dimension=<dimension> | /Statistics/Monitor/{monitorGuid} | GET |
List checkpoint servers
Description | API v3 endpoint | API v4 endpoint | Method |
---|---|---|---|
List all checkpoint servers | /checkpointservers | /Checkpoint | GET |