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

Device Management 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 are sent as key/value pairs in a GET or POST request.

Security

Netreo recommends always using POST for API calls if possible. If security is a concern we recommend the use of HTTPS and POST requests.

Resource

The resource accessed by this API is an individual device at a specified IP address.

This resource offers the following endpoints:

  • Add/Update Device
  • Delete Device
  • Device Metadata
  • Device Note

Resource URL

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

Endpoints

Add/Update Device

Either, adds a new device to OmniCenter, or updates a device if it already exists. To add multiple devices, call the API individually for each device. If the API is executed with an IP address that OmniCenter can match as an IP address on an interface for a device it is already monitoring, that device will be updated with the provided parameters.

GET or POST
/new_device_api.php

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.

Basic Parameters

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

ip
String/Required
The IP address of the device.

snmp_pub
String/Required
The SNMP public community string for the device. Limit 32 characters.

profile
String/Optional
User must be a super-admin to use this parameter.
The name of the user partition the device should be placed into. If this partition already exists, the new device will be placed into it. If this partition does not exist, it will be created, the device will be placed into it, and a new user account will be created tied to the new partition. The username and password for the new account will be the same as the name provided for the partition. Limit 16 characters.
Please note that the use of this option can create security issues, as it potentially creates new OmniCenter user accounts. Use this option only if you are sure this is what you want.

Site Parameters

These parameters allow you to create/update a site in OmniCenter while adding/updating a device. If a site already exists, the device is assigned to that site. The site will also be updated with any site details provided. If the site does not exist, a new site is created and the device assigned to it.

site
String/Optional
The site name that this device should be assigned to. Limit 32 characters.

site_address
String/Optional
A street name and building number. Only used if preceded by site. Limit 50 characters.

site_city
String/Optional
A city name. Only used if preceded by site. Limit 25 characters.

site_state
String/Optional
A state name. Only used if preceded by site. Limit 25 characters.

site_country
String/Optional
A country name. Only used if preceded by site. Limit 25 characters.

site_zip
String/Optional
A city zip code. Only used if preceded by site. Limit 10 characters.

Device Attribute Parameters

These parameters allow you to add attributes to a device by providing name/value pairs. These attributes are displayed on the Documentation device administration page in OmniCenter. Multiple instances are supported. To provide multiple attributes, simply include multiple pairs in order (see request examples).

name[]
String/Optional
The name of an attribute. i.e. “DAX number”. Limit 255 characters. Do not place value inside brackets [ ].

value[]
Required if name[] is used
The value of the preceding attribute. i.e. “dax123455678”. Limit 255 characters. Do not place value inside brackets [ ].

Reference Contact Parameters

These parameters allow you to add reference contacts to a device. These reference contacts are displayed on the Documentation device administration page in OmniCenter. Multiple instances are supported. To provide multiple contacts, use the contact_name[] parameter multiple times. Make sure to provide any contact detail parameters before adding the next contact (see request examples).

contact_name[]
String/Optional
The name of a contact to be displayed in the Documentation device administration page. Limit 255 characters. Do not place value inside brackets [ ].

contact_address[]
String/Optional
A street name and building number. Only used if preceded by contact_name[]. Limit 255 characters. Do not place value inside brackets [ ].

contact_city[]
String/Optional
A city name. Only used if preceded by contact_name[]. Limit 255 characters. Do not place value inside brackets [ ].

contact_state[]
String/Optional
A state name. Only used if preceded by contact_name[]. Limit 255 characters. Do not place value inside brackets [ ].

contact_zip[]
String/Optional
A city zip code. Only used if preceded by contact_name[]. Limit 255 characters. Do not place value inside brackets [ ].

contact_number[]
String/Optional
A telephone number. Only used if preceded by contact_name[]. Limit 255 characters. Do not place value inside brackets [ ].

contact_email[]
String/Optional
An email address. Only used if preceded by contact_name[]. Limit 255 characters. Do not place value inside brackets [ ].

Request Examples

Device Add/Update Using GET

http://38.2.11.62/api/new_device_api.php?pwd=PassWord1&ip=39.1.12.200&snmp_pub=snmp4netreo&profile=Test1Dev&site=Headquarters&site_address=1234%20Somestreet&site_city=Irvine&name[]=DAX Number&value[]=2468&name[]=Circuit ID&value[]=abcdefghijklmnop&contact_name[]=Robert&contact_email[][email protected]&contact_name[]=Susan&contact_email[][email protected]

Response

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

Response Examples

Device Add

{"success":"Device successfully added."}
{"failure":"Device addition failed."}

Device Update

{"success":"Device successfully updated."}
{"failure":"Unable to authenticate user."}

Response Schema

Output Type Description
success string Returns confirmation of successful call.
failure string Returns explanation of failed call.

Delete Device

Deletes a managed device from OmniCenter. Same as deleting a device using the UI from device administration.

GET or POST
/device_delete_api.php

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

name
String/Required
The name of the device as it appears in OmniCenter. Will still work if the device name is an IP address.

Request Example

Delete Device Using GET with API Authentication Disabled

http://38.2.11.62/api/device_delete_api.php?name=127.0.0.7

Delete Device Using GET with API Authentication Enabled

http://38.2.11.62/api/device_delete_api.php?name=127.0.0.7&pwd=PassWord1

Response

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

Response Examples

{"result":"completed","detail":"Device 127.0.0.7 has been deleted."}
{"result":"error","detail":"Missing require information for this API."}

Response Schema

Output Type Description
result string completed indicates the request was successfully processed by OmniCenter.
error indicates the request encountered an error during processing. A description pair indicating the issue will follow this pair, in place of the remaining data.
detail string Returns a description of the call results.

Device Metadata

Retrieves the metadata for a specific device.

GET or POST
/device_info_api.php

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

ip
String/Required
The IP address or hostname of the device you want to retrieve info for.

method
String/Required
Currently, only getInfo is supported.

Request Examples

Retrieving Device Information Using GET with API Authentication Disabled

http://38.2.11.62/api/device_info_api.php?ip=10.200.39.1&method=getInfo

Retrieving Device Information Using GET with API Authentication Enabled

http://38.2.11.62/api/device_info_api.php?ip=10.200.39.1&method=getInfo&pwd=PassWord1234

Response

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

Response Example

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.

{
    "result":"completed",
    "name":"Boston-R1",
    "device_index":"40178",
    "description":"",
    "category":"Site Routers",
    "site":"Boston",
    "related_strategic_groups":
    [
        "Infrastructure"
    ],
    "device_documentation":
        {
            "16940":
            {
                "name":"Circuit_ID",
                "value":"A92847-2123-54251B-123"
            },
            "16939":
            {
                "name":"Support_Contract",
                "value":"12345"
            },
            "reference_contact":
            {
                "10433":
                {
                    "Contact Email":"[email protected]",
                    "Contact Name":"Branch Manager",
                    "Contact Number":"949-555-1212"
                }
            }
        }
}

Response Schema

Output Type Description
result string Returns "completed" if the call was successfully received and processed by OmniCenter. Followed by the remaining data.
Returns "error" if the call encountered an error. A description pair indicating the issue will follow.
name string The device name as it is listed in OmniCenter.
device_index number The unique number OmniCenter uses to identify this device internally.
description string The contents of the “Device Note” field from the “Main” device administration page, if any.
category string The category (device group) the device belongs to.
site string The site (device group) the device belongs to.
related_strategic_groups array[string] A list of strategic groups the device belongs to, if any.
device_documentation object The contents of the “Documentation” device administration page, including reference contacts and name/value pairs, if any.

Device Note

Either adds or updates the contents of the DEVICE NOTE field on the “Main” device administration page for a device.

GET or POST
/new_device_note_api.php

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

method
String/Required
Must be the first parameter. Only value currently supported is addnote for both adding and updating note contents.

ip
String/Required
The IP address of the managed device whose note you would like to add/update.

device_note
String/Required
The contents of the DEVICE NOTE field. Will overwrite any existing value.

Request Examples

Add/Update Note Using GET with API Authentication Disabled

http://38.2.11.62/api/new_device_note_api.php?method=addnote&ip=127.0.0.6&device_note=this%20is%20new%20note%20for%20device

Add/Update Note Using GET with API Authentication Enabled

http://38.2.11.62/api/new_device_note_api.php?method=addnote&ip=127.0.0.6&device_note=this%20is%20new%20note%20for%20device&pwd=PassWord1

Response

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

Response Examples

{"Success":"Device successfully updated."}
{"result":"error","detail":"Missing method in your request."}

Response Schema

Output Type Description
success string Returns confirmation of successful call.
result string error indicates the request encountered an error during processing.
detail string Returns a description indicating the issue when result is error.
Updated on May 11, 2020

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

Leave a Reply