Device Management 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 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.netreo.ip.or.name}/api

Endpoints

Add/Update Device

Either, adds a new device to Netreo, 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 Netreo 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.

View OpenAPI documentation here.

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 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
The IP address of the device.

device_name
String/Optional
The name of this device as it should appear in Netreo. No special characters are allowed, except underscore (_) and dash (-).

snmp_pub
String/Required
The SNMP public community string for the device. Limit 32 characters. Netreo APIs do not support device template interrogation for any device template other than "Default." If you do not include an SNMP string in the API call and your Default device template does not include credentials for the device you are trying to add, the device may not be added to Netreo or may be added incorrectly.

subtype
String/Optional
The title (name) of a valid device subtype. The subtype supplied must be related to the device type of the device being added/updated. (This parameter is usable only for on-premise deployments of Netreo. It will not work when calling the API from Netreo SaaS.)

profile
String/Optional
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 Netreo user accounts. Use this option only if you are sure this is what you want.

rediscover
String/Optional
This option is for updating devices and only applies to managed devices that already exist within Netreo.
Set to 1 to force a discovery poll for this device. A discovery poll puts the device through the normal discovery process for new devices, including autoconfiguration rules processing and applying device templates. Defaults to 0.

poll
String/Required
An option to determine the polling and monitoring status for the device. Possible values are '1' or '0'. If this option is to set '1', then the device will be added with polling and monitoring activated. If this option is set to '0', then on device creation the following behaviors will be executed: (A) The device will only be checked for availability. (B) The device type will be set to 'Ping-Only'. (C) Auto-configuration rules will be applied to the device. (D) Device templates will be applied to the device.

enabled
String/Required
An option to determine if a device gets added in an enabled or disabled state. Possible values are '1' or '0'. If this option is to set '1', then the device will be added according the setting of the 'poll' option. If this option is set to '0', then the device will be added with polling and monitoring disabled.

Category Parameters

These parameters allow you to create/update a category in Netreo while adding/updating a device. If a category already exists, the device is assigned to that category. If the category does not exist, a new category is created and the device assigned to it.

category
String/Optional
The category name that this device should be assigned to.

Site Parameters

These parameters allow you to create/update a site in Netreo 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.

Strategic Group Parameters

These parameters allow you to create/update a strategic group in Netreo while adding/updating a device. If a strategic group in the list already exists, the device is assigned to that strategic group. If a strategic group in the list does not exist, a new strategic group is created and the device assigned to it.

strategic_group
String/Optional
A list of strategic group names that this device should be assigned to. Separate names in the list with a colon ":"

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 tab of the Device Dashboard while in administrative view. 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 tab of the Device Dashboard while in administrative view. 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[]=robert@email.add&contact_name[]=Susan&contact_email[]=susan@here.now

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

Delete Device

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

View OpenAPI documentation here.

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

name
String/Required
The name of the device as it appears in Netreo. 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

Device Metadata

Retrieves the metadata for a specific device.

View OpenAPI documentation here.

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 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
The IP address or FQDN 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":"manager.branch123@customer.com",
                    "Contact Name":"Branch Manager",
                    "Contact Number":"949-555-1212"
                }
            }
        }
}

Response Schema

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