1. Support
  2. Knowledge base
  3. Uptrends' API
  4. API v3 to v4 upgrade guide

API v3 to v4 upgrade guide

We’re changing our user interface. Some info may not yet be up to date. Please check From classic to new UI.

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.

We are currently approaching the end of life for our API v3, and 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=&End= ​/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
By using the Uptrends website, you consent to the use of cookies in accordance with our Cookie Policy.