1. Home
  2. API Reference
  3. Device Search API

Device Search API

OmniCenter’s API system must be enabled to use this API. See, How to Enable OmniCenter 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 OmniCenter managed devices.

This resource offers the following endpoints:

  • Find Device List

Resource URL

{your.omnicenter.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 OmniCenter’s API Administration. Case-sensitive.

ip
String/Required if name not provided.
The IP address of the managed device in OmniCenter 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 OmniCenter 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' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -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' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -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' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -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' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F name=dallas
  -F password=pass123

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 OmniCenter internal identification number for the device returned below.
name string The name of the managed device as seen in the OmniCenter 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 No longer used. Currently, this field can only be set when importing a device using the device import feature of OmniCenter.
poll string Indicates whether or not the device is being polled for statistical performance data. 0 = no, 1 = yes.
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 OmniCenter to use to communicate with this device. This device-specific setting overrides the OmniCenter default SNMP version setting. “null” = no specific version override has been set, OmniCenter will use its default SNMP version setting.
create_time string The date and time that this device was successfully added to OmniCenter. Time is in the format yyyy-MM-dd HH:mm:ss.
Updated on November 21, 2019

Was this article helpful?

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Comments

    1. Yep. You’re absolutely right Glenn. Good spotting. I’ll fix it right now.

      And, thanks.

Leave a Reply