API Changelog

Uptrends' API will be improved and extended over time. We’ll add new endpoints and methods as needed for new functionality.

When adding new functionality, our goal is to stay backward-compatible. However, sometimes change is inevitable and a new version of the API may not be compatible with what you’ve coded and used so far. You should check the API changelog regularly to be on top of all changes and to act on changes when necessary.

If you are looking for the documentation of the API, please check out the articles in the category Uptrends' API.

Also, if you are interested in the changes to the Uptrends app, check out the general changelog.

November 2024

VaultItem Update

The POST/v4/VaultItem, PUT/v4/VaultItem/{vaultItemGuid}, and PATCH/v4/VaultItem/{vaultItemGuid} now accept the SecretEncodingMethod field when updating or creating the One-time password configuration vault item. This new field accepts Hex or Base32 as string values. The Base32 format is the default encoding method if the SecretEncodingMethod field is not specified.

September 2024

VaultItem Update

The GET /v4/VaultItem now returns an additional data item, VaultItemUsedBy which returns details about which items or monitors are using each vault item.

August 2024

Checkpoint API

The API endpoint /Checkpoint/Server/{serverId} now also returns private location servers.

VaultItem Update

The GET /v4/VaultItem endpoint is now able to return the same extent of details for each vault item, similar to how details are returned for a single item in a GET /v4/VaultItem/{GUID}.

June 2024

Breaking change: the /Register API for SSO-only operators

The Uptrends API requires registration before it can be used. Operators can create a set of API-specific credentials, based on their regular Uptrends credentials. There are two ways to register a set of API credentials:

• Operators can make use of the regular Uptrends interface, and add an API user through the API management tab in their operator settings.
• Alternatively, operators can register for credentials in the API itself, via a request POST /Register by supplying their regular Uptrends credentials.

As of this update, operators who can only log in using Single sign-on (SSO) can no longer attempt to make use of this second option for registering API credentials, since they do not have ‘regular’ Uptrends credentials to use.

In such cases, we recommend making a separate operator account, and using that to register for API credentials.

October 2023

Breaking change: page load metrics for browser-based monitoring

Note: the following is a breaking change to the MonitorCheck API. The change will go live on Wednesday, November 8th.

The Uptrends MonitorCheck API can be used to retrieve detailed information about individual monitor checks. For browser-based monitoring, the waterfall chart can be retrieved via the GET /MonitorCheck/{monitorCheckId}/Waterfall call, which returns all the waterfall metrics, including Core Web Vitals and W3C navigation timings, if they are present in the check result.

Currently, the MonitorCheck API returns Core Web Vitals and W3C navigation timings in two separate JSON objects: PageLoadMetrics and W3CNavigationTiming. Going forward, these separate objects will be combined into a single array, PageLoadMetricsCollection as follows:

  "Attributes": {
    "PageLoadMetricsCollection": [
      {
        "CumulativeLayoutShift": 0.029,
        "FirstContentfulPaint": 2914,
        "LargestContentfulPaint": 3014,
        "TotalBlockingTime": 819,
        "TimeToInteractive": 12516,
        "TimeToFirstByte": 2068,
        "SendStart": 2059,
        "LoadEventEnd": 6721,
        "DomInteractive": 2652,
        "DomComplete": 6719
      }
    ],
    ...

Specifying variables in alert definitions via the API

When configuring alerting through a custom integration in Uptrends, operators can use the UI to specify certain required variables in the escalation level of the alert definition, instead of in the integration options. This allows users to use a single integration for various scenarios, such as sending alerts for different sets of monitors to different teams, but with the same message content.

When the option to specify variables in the escalation level is selected in the integration settings, the variables must instead be configured when the integration is set to be used in the settings of the alert definition. To do this, an extra text field appears in the integration selection list in the alert definition settings.

Until now, this option was unavailable when configuring alert definitions through the API. We’ve added a new option to the /AlertDefinition/{alertDefinitionGuid}/EscalationLevel/{escalationLevelId}/Integration request (where you configure which integrations are tied to each escalation level in the alert definition). The new property will be:

{
    ...
    "VariableValues": {
        "ApiUrl": "https://api.escalationlevel-specific-url.com/alerts"
    },
    ...
}

This property is the equivalent of this option in the application UI:

September 2023

Change in checkpoint’s IPv6 addresses

Previously, when using the checkpoint API to retrieve checkpoint information, the checkpoint’s IPv4 addresses were displayed as a simple list in an array, while the IPv6 addresses (if applicable) were a list of objects. For example, the Amsterdam checkpoint IP addresses were previously listed as follows:

     "Ipv4Addresses": [
        "178.217.84.4",
        "188.241.149.95",
        "66.212.22.2",
        "185.145.63.225",
        "5.182.210.227",
        "5.182.210.168"
    ],
    "IpV6Addresses": [
        {
            "IpAddress": "2a01:5cc0:1:2::4"
        },
        {
            "IpAddress": "2607:fcd0:cd40:1400::2"
        }
    ],

Uptrends has resolved this inconsistency now, and returns the IPv6 addresses in the same way:

    "IpV6Addresses": [
        "2a01:5cc0:1:2::4",
        "2607:fcd0:cd40:1400::2",
    ],

Be aware that if you’ve automated the retrieval of checkpoint IP addresses, e.g. for whitelisting purposes, this may be a breaking change.

January 2023

Version 3 of the API has reached its end of life as of January 2023, and has been disabled. You can still find its documentation in our knowledge base, but it will no longer work. If you have existing scripts or procedures in place that are still making use of version 3, these will fail, and we recommend you switch to version 4 as quickly as possible. See our upgrade guide for more information on switching from API version 3 to version 4.

Update May 2023: The documentation for version 3 of our API has been removed, and is no longer accessible.

December 2022

Monitor creation date info through the API

The /Monitor endpoint can be used to retrieve definitions of the monitors in your account (via GET /Monitor/{monitorGuid}), among other things. The response will now also include a CreatedDate, indicating when the monitor was created.

November 2022

Small changes to /Register endpoint

As you may have read in our regular changelog, this release we’ve added the option to ‘Create and revoke Uptrends API credentials via UI’. In order to align the Uptrends API v4 with the user interface, we have added 2 new options to the /Register endpoint:

• It’s now possible to specify an optional description when registering a new API account by using the description field.
• It’s now possible to create an API account for another operator when the calling operator has sufficient rights by using the operatorGuid field.

September 2022

Upcoming change: timestamps in the API response

Currently, timestamps that are part of the response for any API v4 call are being converted to JSON in one of two ways:

• Millisecond count is equal to 0: 2022-09-21T13:08:47
• Millisecond count is not equal to 0: 2022-09-21T13:08:47.682

This inconsistency can lead to problems when the data containing these timestamps is automatically parsed and handled. Because of this, we’re making a change: the millisecond count will no longer be shown for any timestamps included in the API response. Going forward, all timestamps will have the format 2022-09-21T13:08:47.

June 2022

Upcoming checkpoint IP addresses

The Uptrends API can be used to retrieve checkpoint IP addresses, for automated whitelisting. Previously, responses to such requests to our checkpoint API were typically an up-to-date list of current checkpoint IP addresses. However, Uptrends' checkpoint network is always in motion. New checkpoints are added, existing checkpoints are removed or relocated, or IP addresses are changed. That could mean that the list of IP addresses you were using to whitelist might fall behind until the next synchronization, leading to unnecessary errors.

We’re now registering upcoming checkpoint IP addresses and including them in the API response. That way your whitelist will be up to date ahead of time.

Relationships in statistics API

Responses from the Statistics API (which can be used to retrieve statistical data for your monitors or monitor groups) will now include some additional metadata about the response. The new Relationships array already exists for other API endpoints, and contains additional information about the request like a link to the Monitor or MonitorGroup API request to retrieve additional information about the monitor (group) itself.

        "Relationships": [
            {
                "Id": "4c3a9529-7934-4978-9c36-c377b232g7hb",
                "Type": "Monitor",
                "Links": {
                    "Self": "/Monitor/4c3a9529-7934-4978-9c36-c377b232g7hb"
                }
            }  
        ]

May 2022

Fix for start/end parameters in statistics API

Our API supports retrieving statistical monitor data, with the Statistics API. You can specify either a preset period for which to retrieve the data (with available values such as Last24Hours), or set a custom period using start and end URL parameters. For example, GET /Statistics/Monitor/{monitorGuid}?Start=2022-04-08&End=2022-04-09 retrieves statistical data for a single monitor, for the specified period.

There was an issue where the minute indicator in the start and end timestamps wasn’t being mapped correctly, which could have led to incomplete (or even empty) results in the API response. This issue has been resolved.

February 2022

Update to status API

The Status API retrieves status information for a specific monitor, based on the most recent monitor check. This endpoint can be used for information regarding the current monitor status. We’ve expanded the response to now also include a value for TotalTime - information about the total time metric for the most recent monitor check.

January 2022

Returning the correct monitor data

When a non-Administrator operator with the View data permission on a certain monitor retrieved that monitor definition through the API (via GET /Monitor/{monitorGuid}), the response did not include all relevant data. That was incorrect, since the same data was already available through the UI but not the API, and has been rectified. Now, when these operators retrieve a monitor, the response will include values for MonitorGuid, Name, MonitorType, MonitorMode, IsActive, and GenerateAlert.

August 2021

Announcement: deprecation of version 3 of our API

The Uptrends API currently supports two versions side-by-side. Version 3 is the older legacy version of our API, and version 4 is the currently recommended version. With a much more complete set of features, version 4 has been the focus of our development for some time. As such, we’ve decided to deprecate version 3 of our API, and it will be retired and become unavailable by December 2022.

For customers currently still making active use of version 3 of our API, it should be noted that it will still be supported up until that time. However, we do recommend switching over to making use of version 4 as soon as possible. To assist you in this, we’ve written an API v3 to v4 upgrade guide, which will cover the key differences between the two API versions and how to bridge them in your scripts and software.

July 2021

Breaking change: changes in OperatorGroup authorization response

The Uptrends API allows you to manage permissions for operators and operator groups, assigning roles such as Administrator, Financial operator, or allowing Infra access. The OperatorGroup API contains several options for retrieving, adding or deleting such permissions.

We have changed the way in which the permissions are specified for operator groups in the API, which could affect any automated creation, removal, or retrieval of information about operator group permissions you may have set up. Currently, retrieving information about permissions works by requesting:

GET /OperatorGroup/{operatorGroupGuid}/Authorization

which returns a response along the following lines (depending on which permissions have been set up for that particular operator group):

[
      {
        "AuthorizationId": "{authIdGuid1}",
        "AuthorizationType": "FinancialOperator",
        "OperatorGroupGuid": "{operatorGroupGuid}"
    },
    {
        "AuthorizationId": "{authIdGuid2}",
        "AuthorizationType": "AllowInfra",
        "OperatorGroupGuid": "{operatorGroupGuid}"
    },
    ...
]

Going forward, that same request will have its response simplified, simply listing the permissions granted and no other information. The response will no longer contain an operatorGroupGuid or AuthorizationId (the latter will disappear completely, meaning permissions will no longer have an individual GUID assigned to them). It will look like this:

{
    "FinancialOperator",
    "AllowInfra",
    ...
}

Adding a new operator group permission currently works by sending a POST request to:

/OperatorGroup/{operatorGroupGuid}/Authorization with a request body specifying an “AuthorizationType”. The currently available values for AuthorizationType for operator groups is available in the Uptrends API Swagger UI, under Models (at the bottom), and then OperatorGroupAuthorizationType.

Going forward, new permissions can be added to an operator group by sending a POST request to:

/OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationType} without including a request body.

Deleting a permission from an operator group is currently done by sending a DELETE request to /OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationGuid} - but as noted above, “authorizationGuid” will disappear entirely as an entity and can no longer be used. Instead, you can delete permissions by referring to them directly by name in the request URL: /OperatorGroup/{operatorGroupGuid}/Authorization/{authorizationType}

February 2021

Breaking change: sensitive values in multi-step API monitors

Our multi-step API monitor type allows you to execute multiple consecutive HTTP requests, where each new request uses one or more pieces of data retrieved from a previous request to perform its task. Often, one of the steps will involve submitting credentials to gain access to a particular resource. In the past, these credentials would be added as predefined variables to the monitor definition, and then marked as Sensitive.

To improve the security of how we handle such credentials, we’re going to be moving away from that setup. Instead, the credentials will be placed in the vault. With that change, the option to mark predefined variables as sensitive in multi-step API monitors becomes obsolete, and we will be removing it.

This will affect the way in which you can create or interact with multi-step API monitors through our API. Currently, the monitor definition for this monitor type will contain an array “PredefinedVariables”, where each of the individual variables has a true/false boolean “Sensitive”. In the near future, this boolean will be removed from the definition. If you wish to create or update an existing multi-step API monitor in your account through the Uptrends API, this field must no longer be included.

Change: renamed routing

For Uptrends APIv4 we have an inconsistent way of naming routes. In most cases singular is used, but plural on a few occasions. The route now contains only singular parts, e.g. /MonitorGroup/{monitorGroupGuid}/Member instead of /MonitorGroup/{monitorGroupGuid}/Members.

We still support the old routes for backwards compatibility.