- 04 Jan 2024
- 3 Minutes to read
- Print
- DarkLight
- PDF
Device Search API
- Updated on 04 Jan 2024
- 3 Minutes to read
- Print
- DarkLight
- PDF
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
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
Output | Type | Description |
---|---|---|
dev_index | string | The Netreo internal identification number for the device returned below. |
name | string | The name of the managed device as seen in the Netreo UI. |
ip | string | The IP address of the device. |
description | string | The contents of the Device Note field, found in device administration on the Documentation tab. |
category | string | The name of the category the device is assigned to. |
site | string | The name of the site the device is assigned to. |
model | string | The manufacturer's model description for the device. |
serial_number | string | The manufacturer's serial number for the device. If the device contains multiple modules, this is the chassis serial number. |
poll | string | Indicates 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 |
monitor | string | Indicates whether or not the device is being monitored for host and service status. 0 = no, 1 = yes. |
snmp_version | string | The 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_time | string | The date and time that this device was successfully added to Netreo. Time is in the format yyyy-MM-dd HH:mm:ss. |