Alerting API

Netreo's API system must be enabled to use this API. See How to Enable Netreo API Access

Calls to this API are made using HTTP/HTTPS and are sent as key/value pairs in a GET or POST request.

Resource

The resource accessed by this API is an Netreo passive service check. Service checks are used to monitor applications and services running on a managed device.

The Netreo Alerting API allows external APIs to retrieve or set the status information on a service check assigned to a device in Netreo. This allows an external API to read the status of a service check and take its own actions, or update the status of a service check in Netreo. Updating a check's status will cause Netreo to take its own appropriate actions (such as sending an alert notification for a critical state).

If you want Netreo to send alerts based on status updates received from an external API, it's recommended that you add a "Generic Passive Service Check" to the devices in question specifically for this purpose. If you try to make a status update on a check that doesn't exist, Netreo will create a new passive service check on the device for you anyway—but, it's still better to create the check yourself so that you have more control. (Remember to include a unique description for the service check in its configuration, as you will be referring to it in the API call.) It's highly recommended that you add this check through the use of device templates. Add the check to a device template and assign it to the device type you want to monitor, or create a new device subtype and assign the template to that.

This resource offers the following endpoints:

• Service Check Status

Resource URL

{your.netreo.ip.or.name}/api

Endpoints

Service Check Status

GET or POST
/passive_alert_api.php
Either retrieves or sets the status information on a passive service check assigned to a device.

Parameters

The parameters for this endpoint can be included as query string parameters in a GET request, or as request body parameters in a POST request.

pwd
String/Required if authentication is enabled.
The API key set in Netreo’s API Administration. Case-sensitive.

pin
String/Required when using Netreo SaaS-based APIs. Not applicable to on-premise deployments.
The pin number supplied in Netreo’s API Administration.

method
String/Required
Must be the first parameter. Two values currently supported:

• getInfo to read service check status info from an existing passive service check.
• update to write service check status info to an existing passive service check, or create a new check if it does not already exist. Note: When checks are created in this manner they are always created in an OK state. You will then have to call the API again in order to change the state of the check to any other state.

device_info
String/Required
The NAME, IP_ADDRESS, or DEVICE_INDEX of the device that contains the passive service check to be updated. If this device does not exist in Netreo, the Netreo API system will return an error.

check_name
String/Required
The value in the description field of the specified passive service check. Should be URL encoded if special characters are defined. Must be unique on this device (i.e., only one service check on each device can have a particular description). If the method is update and the specified service check does not exist, it will be created. (See note in method about creating passive service checks this way.)

state
String/Required for method update
The state to set the passive service check to. Must be one of OK, WARNING, CRITICAL, UNKNOWN.

check_status_info
String/Required for method update
Any notes associated with this status change. These notes will be logged in the alert log and are typically also sent out with the alert notifications. Limited to 256 characters of plain text. Note: Any text after a pipe character ( | ) will be ignored as "debug output." These notes are returned as detail in the JSON formatted response output.

Request Examples

Read Status Info Using GET with API Authentication Disabled

http://38.2.11.62/api/passive_alert_api.php?method=getInfo&device_info=TEST-PC&check_name=ping

Read Status Info Using GET with API Authentication Enabled

http://38.2.11.62/api/passive_alert_api.php?method=getInfo&device_info=TEST-PC&check_name=ping&pwd=PassWord1

Update Status Info Using GET with API Authentication Disabled

http://38.2.11.62/api/passive_alert_api.php?method=update&device_info=TEST-PC&check_name=ping&state=critical&check_status_info=API%20status%20change%20test

Update Status Info Using GET with API Authentication Enabled

http://38.2.11.62/api/passive_alert_api.php?method=update&device_info=TEST-PC&check_name=ping&state=critical&check_status_info=API%20status%20change%20test&pwd=PassWord1

Response

A successful or unsuccessful call to this API will return a standard JSON object.

Response Examples

Read

{"result":"completed","device":"TEST-PC","service description":"PING","service status":"OK","detail":"Ping OK: Packet Loss 0% RTA = 0.380 ms"}

Update

{"result":"completed","device":"TEST-PC","service description":"PING","service status":"CRITICAL","detail":"API status change test."}

Response Schema