PRTG Manual: HTTP API

All calls to the PRTG HTTP 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 API inside your secure LAN, you can simply use HTTP. In insecure environments (for example, when accessing your PRTG server across the internet), you should use HTTPS requests to make sure that your parameters and passwords are encrypted. This way all communication between the PRTG server and your client is 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.
  • Authentication with username and passhash (or username and password) must always be included in each request. See section Authentication for more information.
  • All data in the GET parameters must be UTF-8 encoded and URL encoded.

Here are two example API calls:

icon-speechExamples

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

or:

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

The example URLs consist of the following elements:

  • yourserver: the name of your PRTG server.
  • /api/table.xml: addresses an API function. Here the function renders a table in Extensible Markup Language (XML) 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.

Authentication

All requests to the API are stateless, which means that there is no multi-step login process of an kind. The authentication with username and passhash (or username and password) must always be included in each request by using the username and passhash (or username and password) parameters.

icon-speechExamples

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

or:

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

The example URLs now also contain the credentials for authentication purposes:

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

You can request the passhash for an account with the following API call:

https://yourserver/api/getpasshash.htm?username=myuser&password=mypassword

icon-i-round-redMake sure that the username and password are URL encoded.

Versioning

Most XML replies from the 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). API conventions or parameters may have changed between versions.

icon-i-roundNewer versions of the same major version of PRTG will reply to API calls just as previous versions have.

Error Handling

Depending on whether your API call was processed successfully or not, the PRTG server will reply with the following HTTP status codes:

HTTP Status Code

Meaning

Comments

200

OK

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

302

Found

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

400

Bad Request

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

401

Unauthorized

The username/password credentials cannot be accepted.

For 400 error codes, the error XML document will include the error message as follows:

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

More

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

 

Application Programming Interface (API) Definition—Topics