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 and some endpoints might still change. If you already want to use the PRTG API on your production system, we recommend that you use the PRTG API (v1). For more information, click here.

You can share your feedback about the API here.

If you need help, contact the Paessler support team here.

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: The PRTG API (v1) can still be used but it is completely separated from the PRTG API v2.

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 two 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

Currently you can obtain an API key only through the classic UI: go to Setup > Account Settings > My Account and open the API key tab. There you can create a new API key for use with the new API.

To use it in the Swagger UI, 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}

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.
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.
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.
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

# 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')

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 favorite entries

favorite = true

This simple expression consists of the name of a property (favorite), a comparison operator (=), and a value (true). 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 + '/sensors?filter=' + [System.Web.HttpUtility]::UrlEncode('favorite = true'))

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.

Note: Property names are internal and do not necessarily resemble the JSON field names. This will be changed in the future.

Property Name Data Type Operators Remarks
active boolean =, != only on users and user groups
activedirectory boolean =, != only on users and user groups
admingroup boolean =, != only on user groups
ancestors list of text contains
authorized boolean =, != only on probes
autodiscoveryactive boolean =, != only on groups and devices
autodiscoveryprogress number =, !=, <, <=, >, >= only on groups and devices
clusterprobe boolean =, != only on probes
clusterremoteprobe boolean =, != only on probes
comment text =, !=, matches
coverage number =, !=, <, <=, >, >= only on sensors
crossreference list of text contains
descendants list of text contains
dnsname text =, !=, matches only on devices
downtimetotal duration =, !=, <, <=, >, >= only on sensors
email text =, !=, matches only on users
favorite boolean =, !=
id text =, !=
limitmaxerror number =, !=, <, <=, >, >= only on channels
limitmaxwarning number =, !=, <, <=, >, >= only on channels
limitminerror number =, !=, <, <=, >, >= only on channels
limitminwarning number =, !=, <, <=, >, >= only on channels
location text =, !=, matches
loginname text =, !=, matches only on users
lookupdefinitionid text =, !=, matches only on channels
lookuptype enumeration =, != only on lookup definition
message text =, !=, matches
name text =, !=, matches
parentid text =, !=
percent number =, !=, <, <=, >, >= only on channels
performanceimpact number =, !=, <, <=, >, >= only on sensors
primarygroup text =, != only on users
priority number =, !=, <, <=, >, >=
restrictedsensormode boolean =, != only on user groups
scanninginterval duration =, !=, <, <=, >, >=
sensorkind list of text =, !=, matches only on sensors
sensorkindname text =, !=, matches only on sensors
smallprobe boolean =, != only on probes
probestatus enumeration =, != only on probes
probestatusinfo enumeration =, != only on probes
status enumeration =, !=
tags list of text contains
ticketmail boolean =, != only on users
ticketmode boolean =, != only on user groups
type identifier =, !=
unittype number =, !=
uptimetotal duration =, !=, <, <=, >, >= only on sensors
usertype enumeration =, != only on user groups

Enumerations

An enumeration has a well-defined set of textual value tokens. 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 are two special properties: ancestors and descendants. They provide 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"'))

Example: All objects below group with ID 2005. ancestors includes all objects below the group, not only direct children

ancestors contains "2005"

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

Example: All objects above the device with ID 3218, for example, the path from the device to the root of the tree

descendants contains "3218"

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

Optional Properties

Some property may have no value at all, for example percent for channels. You can filter for objects with no value for a certain property using the reserved word nil as value in your filter expression, for example percent = nil. You can also find objects that have any value for such a field, for example percent != nil.

Example: All channels that have a percent value

percent != nil

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/channels?filter=' + [System.Web.HttpUtility]::UrlEncode('percent != nil'))

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
priority=2 and tags contains "HA" or location = "Main Building"

# 2
priority=2 and (tags contains "HA" or location = "Main Building")

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

The first expression finds all entries that have either priority 2 and the tag HA, or that are located in the Main Building. In contrast, the second expression finds all entries that have priority 2 and either have the HA tag or are located in the Main Building. The difference is that all entries in the second list have the priority 2, while entries in the first list can have any priority as long as their location is Main Building.

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 ancestors contains "2004"

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('type = sensor and tags contains "ping" and ancestors contains "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 ancestors contains "2004" and status = down

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

Example: Find all devices and groups with a priority of less than 5

priority < 5 and (type = device or type = group)

# PowerShell
Invoke-RestMethod -Headers $headers -Uri ($url + '/objects?filter=' + [System.Web.HttpUtility]::UrlEncode('priority < 5 and (type = device or type = group)'))

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.

Sorting

Sorting allows you to sort list results by multiple properties, providing a comma-separated list of field names. Order them in ascending or in descending order by prefixing the field name with a plus sign (+) or minus sign (-). By default, the results are sorted in ascending order, so you can leave out the plus sign (+).

# Sort by ascending position and descending priority
Invoke-RestMethod -FollowRelLink -Headers $headers -Uri $url + '/sensors?sort_by=position,-priority'

Note: Property names are internal and do not necessarily resemble the JSON field names. This will be changed in the future.

Object Property Name JSON
probe id id
parentid
position position
name name
message info
lon geo_position.longitude
lat geo_position.latitude
geohash geoposition.geohash
dependency dependency
status status
priority priority
favorite favorite
scanninginterval scanning_interval
group id id
parentid
position position
name name
lon geo_position.longitude
lat geo_position.latitude
geohash geoposition.geohash
dependency dependency
status status
priority priority
favorite favorite
scanninginterval scanning_interval
lastautodiscovery autodiscovery.last_autodiscovery
autodiscoveryactive autodiscovery.active
autodiscoverytype autodiscovery.autodiscovery_type
device id id
parentid
position position
name name
message info
icon icon
lon geo_position.longitude
lat geo_position.latitude
geohash geoposition.geohash
dependency dependency
status status
priority priority
favorite favorite
scanninginterval scanning_interval
dnsname host
lastautodiscovery autodiscovery.last_autodiscovery
autodiscoveryactive autodiscovery.active
autodiscoverytype autodiscovery.autodiscovery_type
sensor id id
parentid
position position
name name
message message
status status
priority priority
favorite favorite
sensorkindname sensor_kind
performanceimpact performance_impact
lastup last_up
lastdown last_down
uptimetotal uptime_toal
downtimetotal downtime_total
coverage coverage
scanninginterval scanning_interval
user id id
name display_name
loginname login_name
type role
active active
homepage homepage
email email
lastlogin last_login
timezone time_zone
dateformat date_time_format
activedirectory ad_user
activedirectorypath ad_path
primarygroup primary_group
audiblealarms audible_alarm
theme theme
autorefresh auto_refresh
autorefreshinterval auto_refresh_interval
ticketmail ticket_email
usergroup id id
name name
active active
activedirectory active_directory
activedirectoryname active_directory_name
restrictedsensormode restricted_sensor_mode
defaulthome default_home

Actions

The requests to trigger an action in the API usually use the POST HTTP method. If the request refers to an individual object, the request URL contains the ID of the object. The request body takes a JSON object that contains all information that is needed to perform the desired action.

Example: pause the sensor with ID 2233

# Request URL
POST /api/v2/sensors/2233/pause

# Request Body
{
  "duration": 300,
  "message": "Maintenance: Paused for 5 minutes."
}

An action request can affect one or more objects. If the action request affects more than one object, the JSON object contains a filter expression that can be used to define which objects should be affected.

Example: Pause all Ping sensors that have a priority of less than 3

# Request URL
POST /api/v2/sensors/pause

# Request Body
{
  "filter": 'tags contains "ping" and priority < 3',
  "duration": 300,
  "message": "Maintenance: Paused for 5 minutes."
}

Tags

For every object in your setup, you can define tags in the object settings to additionally categorize these objects. Tags are always one word, so no spaces or commas are allowed in a tag.