PRTG API v2 Overview

Introduction

The PRTG API v2 is a REST API. This document describes how to use the PRTG API v2 and what to expect from it.

The PRTG API v2 is not yet feature-complete. Most endpoints are stable and you can use them in production, with the exception of endpoints marked as “experimental”. Experimental endpoints might change, so use them with caution (also see Overview: Maturity of endpoints). If you cannot achieve your objective with the API v2, you can try the PRTG API (v1). For more information, see the PRTG Manual: HTTP API.

You can share your feedback about the API here.

If you need help, contact the Paessler support team from the Paessler Help Desk.

Available Resources

A list of available resources and their endpoints is available in our reference guide.

This is a Swagger UI that contains the documentation of all individual endpoints. You can use it to try out the API calls.

Updates

The new API follows the update cycle of PRTG. Select the Canary release channel to get the latest updates.

Versioning

This documentation refers to the PRTG API v2.

Note: You can still use the PRTG API (v1) but be aware that it is completely separate from the PRTG API v2.

Maturity of endpoints

The endpoints in the API v2 have one of three states:

Stable

If an endpoint is not labeled as deprecated or experimental, it is stable. These endpoints should not change in the future, with the exception of additive changes (e.g., more query parameters, additional data gets returned, etc.).

Experimental

You can recognize an experimental endpoint by the URI prefix: /experimental. The experimental endpoints are always visible and available. These endpoints can have breaking changes between releases since they are in development. Once we finish their development, we remove the /experimental prefix and consider the endpoint stable. There is always at least one PRTG release where the endpoint exists with and without the prefix.
It is also possible that experimental endpoints never become stable. In this case, we remove the endpoint in a future release.

Feature Endpoint Since Stable
Returns a list of probes GET /experimental/probes 24.3.100 -
Returns a list of groups GET /experimental/groups 24.3.100 -
Returns a list of devices GET /experimental/devices 24.3.100 -
Deletes a device DELETE /experimental/devices 24.3.100 -
Creates a new device in a group POST /experimental/groups/{id}/devices 24.3.100 -
Creates a new device in a probe POST /experimental/probes/{id}/devices 24.3.100 -
Returns a list of sensors GET /experimental/sensors 24.3.100 -
Returns a list of channels GET /experimental/channels 24.3.100 -
Returns timeseries data for a predefined time frame GET /experimental/timeseries/{id}/type 24.3.100 -
Returns time series data GET /experimental/timeseries/{id} 24.3.100 deprecated
Returns a list of all enabled feature-toggles GET /experimenal/feature-toggles 24.3.100 deprecated

Deprecated

We remove deprecated endpoints in a future release of PRTG. They are visually marked in grey and have a deprecation warning in the reference guide. The warning will also include a PRTG version when the removal happens.
In most cases, we provide an alternate endpoint that provides a similar function.

Feature Endpoint Since Removed Will be replaced with
list of channels GET /channels 24.3.100 GET /experimental/channels
channel data GET /channels/{id}/overview 24.3.100 GET /channels/{id}
list of measurements GET /channels/data 24.3.100 no version
list of devices GET /devices 24.3.100 GET /experimental/devices
device data GET /devices/{id}/overview 24.3.100 GET /devices/{id}
device clone GET /devices/{id}/clone 24.3.100 replace
device data GET /experimental/devices/{id}/settings 24.3.100 24.3.100
list of groups GET /groups 24.3.100 GET /experimental/groups
group data GET /groups/{id}/overview 24.3.100 GET /groups/{id}
group clone GET /group/{id}/clone 24.3.100 replace
list of probes, groups, devices and sensors GET /objects 24.3.100 no version
list of probes GET /probes 24.3.100 GET /experimental/probes
probe data GET /probes/{id}/overview 24.3.100 GET /probes/{id}
list of sensors GET /sensors 24.3.100 GET /experimental/sensors
sensor data GET /sensors/{id}/overview 24.3.100 GET /sensors/{id}
sensor clone GET /sensors/{id}/clone 24.3.100 replace
list of sensors with alarms GET /sensors/alarms 24.3.100 no version
sensor data GET /experimental/sensors/{id}/settings 24.3.100 24.3.100
list of libraries GET /libraries 24.3.100 no version
list of all enabled feature-toggles GET /experimental/feature-toggles 24.3.100 no version
time series data GET /experimental/timeseries/{id} 24.3.100 no version
list user GET /users 24.3.100 replace
user data GET /users/{id} 24.3.100 replace
list usergroups GET /usergroups 24.3.100 replace
usergroups data GET /usergroups/{id} 24.3.100 replace
list lookup-definitions GET /lookup-definitions 24.3.100 replace
lookup-definitions data GET /lookup-definitions/{id} 24.3.100 replace
settings-lookups data GET /settings-lookups/{name} 24.3.100 replace
schemas GET /schemas/{kind} 24.3.100 replace

Basic Usage

Example of a valid API request:

# PowerShell
Invoke-RestMethod "https://prtg.example.com/api/v2/settings/public"

Authentication

Most endpoints require authentication. They are marked with a lock symbol in the Swagger UI.

There are three kinds of authentication:

After you are authenticated, the lock symbols are closed and you can use protected endpoints.

Using Credentials

Use the POST /session endpoint to authenticate with the Swagger UI. Click the Try it out button, enter valid credentials, and click the Execute button.

Using an API Key

You can create API keys through the PRTG UI (Account Settings | My Account | API Keys) or with the API key endpoint in the API v2 (POST /users/{id}/api-keys).

To use it in the API reference, click the Authorize button in the top-right corner of the endpoint list. A window will open (Available authorizations) where you can enter the API key or the bearer token in the Value field and confirm it with the Authorize button.

Note: You need to enter the API key or the bearer token with the prefix Bearer.

To authenticate with the API, you need to send a bearer token in the Authorization header with your request as follows:

# PowerShell
Invoke-RestMethod -Headers @{'Authorization' = 'Bearer 68015e0e-f3b7-465c-bd3d-729533cf8fce'} 'https://prtg.example.com/api/v2/objects'

You can obtain a bearer token from the /session endpoint with a username and password in a POST request as follows:

# PowerShell
Invoke-RestMethod -Method 'POST' -Body '{"username": "prtgadmin", "password": "prtgadmin"}' 'https://prtg.example.com/api/v2/session'

You can also store the token and build a header for use in later requests:

# PowerShell
$url = 'https://prtg.example.com/api/v2'
$token = (Invoke-RestMethod -Method 'POST' -Body '{"username": "prtgadmin", "password": "prtgadmin"}' ($url + '/session')).token
$headers = @{'Authorization' = 'Bearer ' + $token}

Single sign-on

If your PRTG installation has single sign-on (SSO) configured there will be a SSO Login button on top of the Swagger UI page. Clicking on it, will forward you to the configured SSO provider. If the login there was successful you will be redirected back to the Swagger UI page and should be logged in.

Note: This authentication method can only be used within the Swagger UI and is not suitable for scripting or other methods of automation.

Errors

Status Codes

If an error occurs, the API responds with an HTTP status code. For more information about the HTTP status codes, see RFC 7231, Section 6.

Code Standard Phrase Reason
400 Bad Request The API returns 400 if any of the provided parameters or the request body are invalid.
401 Unauthorized The API returns 401 if the bearer token is missing in the Authorization header.
403 Forbidden The API returns 403 if the requested endpoint requires a certain user access right that the requesting user account does not have.
404 Not Found The API returns 404 if the referenced object does not exist or is not visible to the user.
408 Request Timeout The API returns 408 if reading the request body, executing the request, or writing the response body took too long.
409 Conflict The API returns 409 if the referenced object in a PUT or PATCH request does not exist or is not visible to the user.
500 Internal Server Error The API returns 500 for all errors that do not have an individual HTTP status code.
502 Bad Gateway The API returns 502 if the PRTG core server responded to a forwarded request with an invalid response. This status code can only occur if the PRTG core server is incompatible with the PRTG application server.
503 Service Unavailable The API returns 503 if the connection to the PRTG core server is currently not working.
504 Gateway Timeout The API returns 504 if the PRTG application server did not receive a response from the PRTG core server in time that was needed to complete the request while acting as a gateway or proxy.

Error Format

The body of an error response always has the following format:

{
    "code": "INVALID_FILTER",
    "message": "The filter is invalid.",
    "request_id": "LlBbCc"
}

Error Codes

Code Description
AUTH_FAILED The authentication has failed. Enter valid credentials.
BAD_GATEWAY The response received from the PRTG core server was invalid.
BAD_REQUEST The request could not be processed. Check if the format and the data types are correct.
BODY_TOO_LARGE The body of the POST request is too large. The limit for the body size is 15 kilobyte.
EXECUTION_TIMEOUT The execution time of a request may not exceed 25 seconds.
FORBIDDEN The requested action is not allowed with the user’s current privileges.
GATEWAY_TIMEOUT The request to the PRTG core server has timed out.
INTERNAL_ERROR An unexpected internal error occurred. This is not the user’s fault.
INVALID_DURATION The provided duration is invalid. Enter a duration seconds as floating point number.
INVALID_FILTER The provided filter is invalid.
INVALID_PASSWORD_RESET_TOKEN The password reset token is invalid. Enter a valid password reset token.
LICENSE_INACTIVE The PRTG license is invalid or expired, or the trial period is over.
LOGIN_FAILED The login has failed. Enter a valid user name and password or token.
LOGOUT_FAILED The logout of the active user session has failed.
LOW_PASSWORD_COMPLEXITY The password complexity is too low. Enter a password that matches the password requirements.
NOT_FOUND The resource could not be found in this endpoint. Check the ID of the object.
METHOD_NOT_IMPLEMENTED The requested action is not implemented.
PAUSE_ADMIN The PRTG System Administrator user account cannot be paused.
RENEW_FAILED The renewal of the active user session has failed.
SERVICE_UNAVAILABLE Service unavailable. The PRTG application server could not connect to the PRTG core server.
UNKNOWN An unknown error has occurred. Check the log files for more information.
WRONG_NODE_STATUS The requested action is not possible for the current status of the node.

Pagination

The PRTG API uses pagination in all lists to limit the response to a reasonable size.

You can define the number of elements and the starting point of the page using the limit and offset query parameters. If you omit the limit parameter, the PRTG API uses 3000 entries as the maximum size of the page.

Furthermore, the Link HTTP header (see RFC5988) is used in responses with paginated content to indicate URLs of the previous page and the next page. The header X-Result-Count contains the actual number of items in the actual response, the header X-Total-Count contains the total number of items available.

Example:

# Request
GET /api/v2/devices?limit=50&offset=150 HTTP/1.1

# Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 78
Link: </api/v2/devices?limit=50&offset=100>; rel="previous"
Link: </api/v2/devices?limit=50&offset=200>; rel="next"
X-Result-Count: 50
X-Total-Count: 1000
X-Request-Id: LlBbCc
...

This is how to get data from all pages at once using PowerShell (-FollowRelLink automatically follows the Link HTTP headers):

# PowerShell
# Using $headers from the authentication example.
# This only works in PowerShell 6 and higher.
Invoke-RestMethod -FollowRelLink -Headers $headers -Uri ($url + '/sensors')

Includes

By default, many endpoints only return the most relevant information about an object. You can include additional properties with the include parameter. This parameter expects one or more strings that are separated by a comma (,). The parameter also accepts a wildcard (*) to include every possible option. If the parameter is left empty, the API only returns the default selection of information.

The type of object determines the possible options for the ‘include’ parameter. For a list of options, see the reference guide.

Example: Devices have a “Credentials for Windows Systems” setting. The API does not return this setting by default. To include this setting in your responses, you must add windowsconnection to the include parameter.

Inheritance information

The inheritance option works in a different way to most other options available for the ‘include’ parameter. In PRTG, you can set a device to inherit settings from another device that is above it in the device tree.

For more information, see the PRTG Manual: Inheritance of Settings. By default, the API returns the settings that only apply to the object requested, regardless of whether that setting is inherited or is altered directly on the object.

Example: You have a device on a probe. You define a scanning interval on the probe, and you set every object on the probe to inherit the probe’s scanning interval. Now you have a device with a scanning interval that is not explicitly set on that device. When you request the settings for the device, the API returns the set scanning interval with no additional information on whether the scanning interval inherited or where it is inherited from.

When you add inheritance to the include parameter, the response includes information about the returned objects that show if a value is inherited and where the value is inherited from. All inheritance properties are prefixed with an underscore (_).

{
  "intervalgroup": {
    "_inheritanceSource": {
      "id": "0",
      "name": "Main group",
      "type": "REFERENCED_ROOT",
      "href": "/api/v2/groups/0"
    },
    "_inherited": true,
    "_shadowed": {
      "errorintervalsdown": "1",
      "interval": "60"
    },
    "errorintervalsdown": "1",
    "interval": "60"
  }
}

If you defined the settings of an object explicitly, the _inherited property shows as false. The _shadow property always shows the settings defined in the object that is the source of inheritance.

Filter

Important: Filters are still a work in progress. Parts of the functionality are still missing and we need to improve the matching of text filters (e.g. removing case-sensitivity). The following describes the current status of the implementation. The notation, the names and types of properties, and the functionality will change in the future.

Filters allow you to limit which results a request returns. All endpoints that return a list of results allow you to provide a filter expression using the filter parameter. A filter describes the properties of the entries of interest using a simple language.

Simple Expressions

Example: Only return devices that are online without error or warnings.

status = up

This simple expression consists of the name of a property (status), a comparison operator (=), and a value (up). Each property has a certain data type that determines which comparison operators and what kind of values can be used with the property in a filter expression.

Example: A filter in PowerShell

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/devices?filter=' + [System.Web.HttpUtility]::UrlEncode('status = up'))

Data Types

Each property and value has a specific data type. In a simple filter expression, the data type of the property must be the same as the data type of the value. Each data type has a specific notation:

Data Type Notation Example Expression
text "text" name = "Local Probe"
number 123 priority = 1
boolean true, false favorite = true
identifier up status = up
duration 30.0s scanninginterval > 30.0s
list [1, 2] name in ["Local Probe", "Unknown Devices"]

The data type list is a special case in which the data type of the list elements must be the same as the data type of the property. We can have lists of text, lists of numbers, lists of booleans, lists of identifiers, and lists of durations.

Note: The data type of the property name in the example name in ["Local Probe", "Unknown Devices"] is “text”. Therefore, the elements in the given list value must also be the data type text.

Operators

The following table shows all available operators.

Note: Not every operator can be used with every property. For more information about the supported combinations of properties with operators, see section Properties.

Operator Description
= The equal operator compares if the value of the provided property is exactly equal to the provided value.
!= The not equal operator compares if the value of the provided property is not equal to the provided value.
< The less than operator compares if the value of the provided property is less than the provided value.
<= The less or equal operator compares if the value of the provided property is less than or equal to the provided value.
> The greater than operator compares if the value of the provided property is greater than the provided value.
>= The greater or equal operator compares if the value of the provided property is greater than or equal to the provided value.
in The in operator compares if the value of the provided property is equal to one of the values in the provided list.
contains The contains operator compares if the list value of the provided property contains the provided value.
matches The matches operator compares if the value of the provided property is similar to the provided text value.

Properties

The following table shows a list of all properties and their associated operators.

Property Name Data Type Operators
basic.host text =, !=, in
basic.hostv6 text =, !=, in
id text =, !=
kind text =, !=
name text =, !=, in
parentid text =, !=
intervalgroup.interval duration =, !=, <, <=, >, >=
basic.parenttags list of text contains
status enumeration =, !=
basic.tags list of text contains
type identifier =, !=

Enumerations

An enumeration has a well-defined set of textual value tokens.

Status

The status property can have the following tokens:

In filter expressions, the enumeration tokens are used as identifiers without quotes, for example status = up.

As the support for enumerations in filter expressions is still a work in progress, a detailed documentation of all enumeration properties and their corresponding enumeration tokens is planned in the future.

Object Types

The type property is an enumeration that can have the following values:

Filtering by Tree Structure

There is one special property: parentid. It provides access to the tree structure in filter expressions.

Example: All children of the group with ID 2004

parentid = "2004"

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('parentid = "2004"'))

Complex Expressions

Simple filter expressions can be combined into complex filter expressions by using the logical operators and, or, and not. Parentheses can be used to group expressions and to modify the evaluation order of the simple expressions within a complex filter expression.

The precedence of the logical operators is:

Example: Precedence of and and or

# 1
type=sensor and tags contains "HA" or status = up

# 2
type=sensor and (tags contains "HA" or status = up)

# PowerShell
# 1
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('type=sensor and tags contains "HA" or status = up'))
# 2
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('type=sensor and (tags contains "HA" or status = up)'))

The first expression finds all entries that are either a sensor and have the tag HA, or that are up. In contrast, the second expression finds all entries that are a sensor and either have the HA tag or are up. The difference is that all entries in the second list are a sensor, while entries in the first list can be any type as long as their status is up.

Example: Negation

# 1
tags contains "HA"

# 2
not(tag contains "HA")

# PowerShell
# 1
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('tags contains "HA"'))
# 2
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('not(tag contains "HA")'))

The not operator negates the expression that follows in parentheses. The first expression in the example above matches all entries that have the tag HA. The second expression matches the exact opposite: all entries that do NOT have the tag HA.

Example Expressions

Here are some more examples of filter expressions.

Example: Find all Ping sensors in the group with ID 2004 via the /api/v2/objects API endpoint

type = sensor and tags contains "ping" and parentid = "2004"

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('type = sensor and tags contains "ping" and parentid = "2004"'))

Example: Find all Ping sensors that are in the status “Down” in the group with ID 2004 via the /api/v2/sensors API endpoint

tags contains "ping" and parentid = "2004" and status = down

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/sensors?filter=' + [System.Web.HttpUtility]::UrlEncode('tags contains "ping" and parentid = "2004" and status = down'))

References

References to other objects are represented by a generic structure in JSON. Here is an example of how the primary group of a user is referenced:

Example

{
  "primary_group": {
    "id": "200",
    "type": "REFERENCED_USERGROUP",
    "name": "PRTG Administrators",
    "href": "/api/v2/usergroups/200"
  }
}

The href attribute contains the URL of the REST resource representing the referenced object. In this case, this is the user group with the ID 200.