Device Search API
  • 04 Jan 2024
  • 3 Minutes to read
  • Dark
    Light
  • PDF

Device Search API

  • Dark
    Light
  • PDF

Article summary

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 must be sent as key/value pairs in a POST request.

Resource

The resource accessed by this API is the list of Netreo managed devices.

This resource offers the following endpoints:

  • Find Device List

Resource URL

{your.netreo.ip.or.name}/fw/index.php?r=restful

Endpoints

Find Device List

POST
/devices/find
Retrieves a list of devices that are associated with the IP address or host name specified in the parameters.

Parameters

The parameters for this endpoint must be included as request body parameters in a POST request. The ip and name parameters are mutually exclusive, only one may be used in an API call.

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

ip
String/Required if name not provided.
The IP address of the managed device in Netreo to return device information for. Do not use if supplying the name parameter.

name
String/Required if ip not provided.
The name of the managed device in Netreo to return device information for. Allows partial name matching using a LIKE query. Not case-sensitive. Do not use if supplying the ip parameter.

Request Examples

Curl using POST with the ip parameter and API Authentication Disabled

curl -X POST \
  'http://38.2.11.62/fw/index.php?r=restful/devices/find' \
  -F ip=10.200.39.2

Curl using POST with the ip parameter and API Authentication Enabled

curl -X POST \
  'http://38.2.11.62/fw/index.php?r=restful/devices/find' \
  -F ip=10.200.39.2
  -F password=pass123

Curl using POST with the name parameter and API Authentication Disabled

curl -X POST \
  'http://38.2.11.62/fw/index.php?r=restful/devices/find' \
  -F name=dallas

Curl using POST with the name parameter and API Authentication Enabled

curl -X POST \
  'http://38.2.11.62/fw/index.php?r=restful/devices/find' \
  -F name=dallas
  -F password=pass123
Using curl to POST

When using POST with https://ip_address, a certificate must be installed on the Netreo server and curl -k used. Otherwise curl will fail.

When using POST with https://FQDN, curl -X may be used.

Response

Supplying an incorrect password, or no password with API authentication enabled, will return an "Incorrect password" error.

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

Note: The output will be returned as standard JSON without indentation or line breaks. It is formatted here to make the example easier to read.

Response Examples

Successful retrieval of a single device using the ip parameter.

[
    {
        "dev_index": "14",
        "name": "Boston-S1.netreo.net",
        "ip": "10.200.39.2",
        "description": "",
        "category": "New Routers",
        "site": "Dev Lab",
        "model": "",
        "poll": "1",
        "monitor": "1",
        "snmp_version": null,
        "create_time": "2019-04-09 05:12:39"
    }
]

Successful retrieval of a list of devices using the name parameter with partial match for "dallas".

[
    {
        "dev_index": "2",
        "name": "Dallas-R1.netreo.net",
        "ip": "10.200.36.1",
        "description": "",
        "category": "New Routers",
        "site": "Internal",
        "model": "",
        "poll": "1",
        "monitor": "1",
        "snmp_version": null,
        "create_time": "2019-04-09 05:10:02"
    },
    {
        "dev_index": "3",
        "name": "Dallas-S1.dallass1.netreo.net",
        "ip": "10.200.36.20",
        "description": "",
        "category": "New Routers",
        "site": "Internal",
        "model": "",
        "poll": "1",
        "monitor": "1",
        "snmp_version": null,
        "create_time": "2019-04-09 05:10:20"
    },
    {
        "dev_index": "6",
        "name": "Dallas-S2.dallas.netreo.net",
        "ip": "10.200.36.254",
        "description": "",
        "category": "New Routers",
        "site": "Internal",
        "model": "",
        "poll": "1",
        "monitor": "1",
        "snmp_version": null,
        "create_time": "2019-04-09 05:11:14"
    }
]

Error response from attempting to use both the ip and name parameters.

{
    "Failure": "Cannot have both name and ip parameters set."
}

Error response when no matching devices are found.

"No Devices found."

Response Schema

OutputTypeDescription
dev_indexstringThe Netreo internal identification number for the device returned below.
namestringThe name of the managed device as seen in the Netreo UI.
ipstringThe IP address of the device.
descriptionstringThe contents of the Device Note field, found in device administration on the Documentation tab.
categorystringThe name of the category the device is assigned to.
sitestringThe name of the site the device is assigned to.
modelstringThe manufacturer's model description for the device.
serial_number
stringThe manufacturer's serial number for the device. If the device contains multiple modules, this is the chassis serial number.
pollstringIndicates whether or not the device is being polled for statistical performance data and the performance of that polling.
0 = not polling
1 = polling normally
2, 3 or 4 = varying degrees of slow polling (recovering)
5 = slow polling
monitorstringIndicates whether or not the device is being monitored for host and service status. 0 = no, 1 = yes.
snmp_versionstringThe version of SNMP set for Netreo to use to communicate with this device. This device-specific setting overrides the Netreo default SNMP version setting. "null" = no specific version override has been set, Netreo will use its default SNMP version setting.
create_timestringThe date and time that this device was successfully added to Netreo. Time is in the format yyyy-MM-dd HH:mm:ss.

Was this article helpful?