Device Import 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 POST request.

Resource

The resource accessed by this API is a managed device in Netreo. You may add a new device or update an existing device. Only one device may be added or updated per API call.

This resource offers the following endpoints:

• Device Import

Resource URL

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

Endpoints

Device Import

POST
/device-import/import
Adds a new managed device or updates an existing device specified by name or IP supplied as parameters.

Parameters

The parameters for this endpoint can be included as request body parameters in a POST request. Both the name and ip parameters are required for calls to this API.

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.

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

ip
String/Required
The IP address or host name of this device. Use the FQDN when entering a host name.

snmp_pub
String/Optional
The SNMP public community string for the device. It should be a maximum of 32 characters, with no spaces. 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.

snmp_priv
String/Optional
The SNMP private community string for the device. It should be a maximum of 32 characters, with no spaces. 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.

device_username
String/Optional
The username to use when logging into the device if you are configuring a Windows device or using TACACS/RADIUS style authentication. This username is required for Windows devices that use WMI or WinRM polling, and on network devices for configuration management and Looking Glass functions if TACACS or RADIUS is in use. If a Windows domain is needed, add it to the username as follows: "domain/username".

device_password
String/Optional
The password to use with the username specified for initial login to the device or the first password to enter if no username is required. This password is required for Windows devices that use WMI or WinRM polling, and on network devices for configuration management and Looking Glass functions.

enable
String/Optional
The enable-with password for network devices that use a second level of authentication to issue configuration commands. This password is required for configuration management. Do not use this field when configuring Windows devices.

category
String/Optional
The name of the category device group to place the device in. If no category is specified, the device is placed in the "New Devices" category.

host_alert
String/Optional
A list of action groups to be added to the device as host alert contacts. The “blackhole” action group is a default notification action group that does not generate any notifications. Note: If you do not include an action group here or in a device template applied to this device, you will not receive alert notifications when this device goes down!

List format for host_alert parameter:

action group name:escalation tier value;action group name:escalation tier value

site
String/Optional
The name of the site device group to place the device in (25 characters maximum). If no site is specified the device is placed in the "Unknown" site.

description
String/Optional
A description that will override the autodetected description for this device. (255 characters maximum.)

template
String/Optional
The name of the device template that you would like to assign to this device at the “device” hierarchy level.

band_width_override
String/Optional
Enter a bandwidth speed to manually override the autodetected bandwidth speed value for this device.

availability_alarming
String/Optional
Set this to 1 to enable monitoring for host and service outages on this device. Set to 0 to disable. You should generally set this to enabled, unless you have a specific reason to switch it off.

parent_name
String/Optional
The name of the layer-3 parent for this device from the list of currently managed devices. If you didn't allow Netreo to auto-discover the devices on your network and are manually adding them now, this field won’t apply to the very first device you add manually—so make sure the first device you add is the parent of all other devices. Additional devices can then be added with a parent device.

performance_trending
String/Optional
Set this to 1 to enable the collection of performance statistics for this device (device polling). Set to 0 to disable.

enable_threshold_checking
String/Optional
Set this to 1 to enable threshold checks to actively monitor the collected performance data for problems. Set to 0 to disable. You should generally set this to enabled, unless you have a specific reason to switch it off.

include_reports
String/Optional
Set to 1 to set this device as validated and allow it to be included in Netreo reports. Set to 0 to set this device as not validated and prevent its inclusion in Netreo reports.

keep_template
String/Optional
Set this to 1 to enable device templates to be applied to this device (recommended). Set to 0 to disable. Entering 0 for this parameter means that any device template supplied in the Template field earlier will be applied once, then forgotten—which is not recommended except when applying default device templates as a one-time operation.

strategic_group_name
String/Optional
The name of a strategic group device group to place this device in (only one group may be specified). If no strategic group is specified here the device is not placed in any strategic groups.

snmp_version
String/Optional
The name of the version of SNMP you would like to use for communication with this device. Options are: leave blank for system default, v1, v2c and v3. If no version is specified, Netreo uses the version supplied in the "Default" device template.

dev_auth_profile
String/Optional
The name of a user partition to place this device in (255 characters maximum). If no user partition is specified the device is not placed in a user partition.

auto_config
String/Optional
Set to 1 to enable auto-configuration rules to run on this device for onboarding. Set to 0 to disable the use of auto-configuration rules.

v3username
String/Required if using SNMPv3
The SNMPv3 username to use for this device.

v3authpass
String/Required if using SNMPv3
The SNMPv3 password to use for this device.

v3authproto
String/Required if using SNMPv3
The SNMPv3 algorithm to use for this device. Options are SHA or MD5.

v3engineid
String/Required if using SNMPv3
The SNMPv3 engine ID to use for this device.

v3privpass
String/Required if using SNMPv3
The SNMPv3 private key to use for this device.

v3privproto
String/Required if using SNMPv3
The SNMPv3 private algorithm to use for this device. Options are AES, 3DES or AES128.

Request Examples

Adding a new device by using POST with API Authentication Enabled

curl -X POST
  "http://38.2.11.62/fw/index.php?r=restful/device-import/import"
  -F device_name=device_name
  -F ip=00.00.00.100
  -F template=some_template_name
  -F auto_config=1
  -F password=netreo_api_auth_key

Response

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

Response Examples

Device Add

{
    "success": "device_name saved.",
    "message": " An immediate discovery poll of the device has been queued."
}

{"error":"A device name is only allowed to have characters 'A-Z', 'a-z', '0-9', '_', and '-'."}

Device Update

{
    "success":"device_name updated.",
}

{"error":"IP is a required field."}

Response Schema