PRTG Manual: HTTP API

All calls to the PRTG API are performed by HTTP GET requests. The URLs consist of a path to the API function and some parameters.

  • If you are accessing the PRTG API inside your secure LAN, you can use HTTP. In environments that are not secure (for example, when accessing your PRTG core server via the internet), you should use HTTPS requests to make sure that your parameters and passwords are encrypted. This way, all communication between the PRTG core server and your client is Secure Sockets Layer (SSL) encrypted.
  • For every API call, the default limit of items is 500. If you want to receive more items per call, add a count=xxx parameter with enough room for all sensors.
  • You must include authentication with API key or user name and passhash (or user name and password) in each request.
    i_square_cyanSee section Authentication for more information.
  • All data in the GET parameters must be UTF-8-encoded and URL encoded.

Output Formats

Most data that you can request from the PRTG API is available in data tables in the Extensible Markup Language (XML), the JavaScript Object Notation (JSON) format, and the comma-separated values (CSV) format (using the XML format is recommended). Here are some sample calls with different output formats.

i_speechExamples

XML

https://yourserver/api/table.xml?content=sensors&columns=sensor

JSON

https://yourserver/api/table.json?content=sensors&columns=sensor

CSV

https://yourserver/api/table.xml?content=sensors&columns=sensor&output=csvtable

The example URLs consist of the following elements.

Element

Description

yourserver

The name of your PRTG server.

/api/table.xml
or
/api/table.json

Addresses an API function. Here, the function renders a table in the XML format or in the JSON format.

content=sensors

Parameter for additional control. In this case, it includes all sensors in the table.

columns=sensor

Parameter for additional control. In this case, only the names of all sensors are shown in the table.

output=csvtable (optional)

Renders a table in the CSV format.

Authentication

All requests to the PRTG API are stateless, which means that there is no multi-step login process of any kind. You must include the authentication with an API key or with a user name and a passhash (or a user name and a password) in each request by using the apitoken parameter or the user name and passhash (or user name and password) parameters:

apitoken parameter

  • apitoken=myapitoken

i_round_blueYou can add, edit, and delete your API keys in the account settings on the API Keys tab.

user name and passhash (or user name and password) parameters

  • username=myuser&passhash=hash (or password=mypassword)

i_round_blueYou can request the passhash for an account with the following API call: https://yourserver/api/getpasshash.htm?username=myuser&password=mypassword
i_round_redMake sure that the user name and password are URL-encoded.

i_speechExamples

https://yourserver/api/table.xml?content=sensors&columns=sensor&apitoken=myapitoken

or:

https://yourserver/api/table.xml?content=sensors&columns=sensor&username=myuser&password=mypassword

or:

https://yourserver/api/table.xml?content=sensors&columns=sensor&username=myuser&passhash=hash

Versioning

Most XML replies from the PRTG API contain a <version> field that contains the program version and buildnumber of the server's PRTG installation. Your client must look at this version number and compare it to the version number that was used to develop the client. Do not accept version numbers older (smaller) than this one. You should display a warning to the user (or stop processing) if the version number differs by 0.1 or more (for example, version 18.1 vs. 18.2, or version 17.x vs. 18.x). PRTG API conventions or parameters might have changed between versions.

i_round_blueNewer versions of the same major version of PRTG reply to API calls just like previous versions did.

Error Handling

Depending on whether an API call was successfully processed or not, the PRTG core server replies with the following HTTP status codes:

HTTP Status Code

Meaning

Comments

200

OK

The API call was successfully completed , the XML response contains the result data.

302

Found

The API call was successfully completed and a new object was created (the redirection URL contains the new object ID).

400

Bad Request

The API call could not be successfully completed. The XML response contains the error message.

401

Unauthorized

The user name/password credentials cannot be accepted.

For 400 error codes, the error .xml document includes the error message as follows:

<?xml version="1.0" encoding="UTF-8" ?>
 <prtg>
 <version>23.4.90.1235+</version>
 <error>Sorry, there is no object with the specified id.</error>
 </prtg>

More

i_square_blueKNOWLEDGE BASE

How can I use the PRTG Application Programming Interface (API)?