Network Assets APIs

The network assets APIs of the Kentik V5 Admin APIs are covered in the following topics:

• About Network Assets APIs
• Device API
• Device Label API

Notes:
- For an overview of all Kentik APIs, see APIs Overview.
- For information on using APIs with cURL, see API Access Via cURL.
- For documentation of the V5 Query API, see V5 Query API.
- For documentation of the V5 Alerting APIs, see V5 Alerting APIs.
- For help using any API version, contact support@kentik.com.

The Kentik V5 Admin APIs offer "network assets" APIs for programmatically managing settings in the Admin section of the Kentik portal, including the following:

• Devices and interfaces: Managed via the Device API, offering similar functionality to the portal’s Device Settings Dialog.
• Device labels: Managed via the Device Label API, provides functionality equivalent to the portal’s Labels Page.

The Device API allows you to manage your organization's devices in Kentik. The available methods for managing devices include:

• Device JSON
• Device List
• Device Info
• Device Create
• Device Update
• Device Apply Labels
• Device Delete
• Interface JSON
• Interface List
• Interface Info
• Interface Create
• Interface Update
• Interface Delete

Notes:
- For information on adding and managing devices via the Kentik portal, see Manage Devices.
- To make calls to this API using cURL, see API Access Via cURL.
- The V5 API tester was discontinued in January 2025.

Device API calls return an HTTP response with a JSON device object, or, an array of such objects for the Device List call. The object contains the fields (name/value pairs) shown in the following example:

{
  "device": {
    "id": "9623",
    "company_id": "1289",
    "device_name": "pd_router",
    "device_subtype": "router",
    "device_description": "test of device settings",
    "plan_id": 123,
    "site_id": 394,
    "device_flow_type": "netflow.v5",
    "device_sample_rate": "1024",
    "sending_ips": [
      "142.254.47.216"
    ],
    "device_snmp_ip": "142.254.47.216",
    "device_snmp_community": "",
    "minimize_snmp": false,
    "device_bgp_type": "device",
    "device_bgp_neighbor_ip": "142.254.47.216",
    "device_bgp_neighbor_asn": "5001",
    "device_bgp_password": null,
    "use_bgp_device_id": null,
    "custom_columns": null,
    "created_date": "2016-09-09T17:27:18.080Z",
    "updated_date": "2016-09-09T17:27:18.080Z"
    "device_snmp_v3_conf": {
      "UserName": "eenie",
      "AuthenticationProtocol": "MD5",
      "AuthenticationPassphrase": "meenie",
      "PrivacyProtocol": "DES",
      "PrivacyPassphrase": "minie"
    },
  }
}

Each device object contains fields with information about an individual device registered in Kentik to your organization. These fields are detailed in the following tables.

Note: For more details about the settings indicated by the name/value pairs, see Device Settings Dialog.

Kentik supports the device subtypes found in the Subtype column of the table in Supported Device Types.

The Device List GET method fetches JSON array of your Kentik devices, with each element representing an individual device.

Note: The “id” value in each device object can be used in subsequent calls to retrieve, update, or delete that specific device.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italics):

Note: If your organization is registered on Kentik’s EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Device List method includes the following elements:

• Response headers
• HTTP response code
• Response body with a JSON device array, where each element is a device object containing device information.

Note: For details on the JSON name/value pairs in a device object, see Device JSON.

The Device Info GET method fetches details of a single device, identified by its ID, from your Kentik devices list.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The “device_id” in the path corresponds to the “id” value in each device object from the Device List array.
- If your organization is registered on Kentik’s EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Device Info method includes the following elements:

• Response headers
• HTTP response code
• A single JSON device object with details about the device specified by device_id.

Note: For details on the JSON name/value pairs in a device object, see Device JSON.

The Device Create POST method adds a new device to Kentik.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Note: If your organization is registered on Kentik’s EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The request body includes the following parameters in a JSON object:

The device_snmp_v3_conf object is included in request JSON to use SNMP V3 for router polling. If omitted, Kentik will assume SNMP V3 is intended.

Note: SNMP V3 authentication and privacy settings are independent. To disable both, set AuthenticationProtocol to NoAuth and PrivacyProtocol to NoPriv.

HTTP Response

A successful response from the Device Create method includes the following elements:

• Response headers
• HTTP response code
• A single JSON device object with details about the newly-added device

Note: For details on the JSON name/value pairs in a device object, see Device JSON.

The Device Update PUT method updates data for a specific device, identified by ID, in your Kentik devices list.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The “device_id” in the path corresponds to the “id” in each device object from the Device List array.
- If your organization is registered on Kentik’s EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

Pass the parameters to be updated in a JSON device object containing only the fields to be changed. Here’s an example for updating a device’s description:

{
  “device”: {
    “device_description”: “This is a really wonderful device.”
  }
}

HTTP Response

A successful response from the Device Update method includes the following elements:

• Response headers
• HTTP response code
• A single JSON device object with details about the newly-updated device.

Note: For details on the JSON name/value pairs in a device object, see Device JSON.

The Device Apply Labels PUT method removes all existing labels (see Labels) from the specified device and applies the specified new labels.

Notes:
- If no labels are specified, this method will still remove all existing labels from the specified device.
- To create and manage device labels via API, see Device Label API.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The following parameters are passed in a JSON object in the request body:

The example below shows a request body for adding two labels to a device.

{
  "labels": [
    {
      "id": 1096
    },
    {
      "id": 32
    }
  ]
}

HTTP Response

A successful response from the Device Apply Labels method includes the following elements:

• Response headers
• HTTP response code
• A single JSON device object with a labels array showing the labels assigned to the device post-operation. An example of a successful label application is provided below, with placeholders in italics.

{
  "id": "device_id",
  "device_name": "device_name",
  "labels": [
    {
      "id": label_id,
      "name": "label_name",
      "edate": "2019-03-07T00:53:51.759Z",
      "cdate": "2019-03-07T00:53:51.759Z",
      "user_id": "#####",
      "company_id": "####",
      "color": "#800000",
    }
  ]
}

Note: For details on the JSON name/value pairs in an individual labels object, see Device Label Object.

The Device Delete method removes one device, identified by ID, from your collection of Kentik devices.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The “device_id” in the path corresponds to the “id” in each device object from the Device List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Device Delete method includes the following elements:

• Response headers
• HTTP response code 204 (no content)

The interface methods of the Device API return an HTTP response body with an "interface" JSON object (or an array of objects for the Interface List call). The object includes name/value pairs as shown in the following example (placeholders in italics):

{
  "id": "9201304925",
  "company_id": "1289",
  "device_id": "2951",
  "snmp_id": "150",
  "snmp_speed": "1000",
  "snmp_type": 6,
  "snmp_type": 53,
  "snmp_alias": "irs",
  "interface_ip": "198.186.192.33",
  "interface_description": "Vlan350",
  "interface_kvs": "\"updated\"=>\"1\"",
  "interface_tags": "",
  "interface_status": "V",
  "cdate": "2017-04-19T00:40:01.145Z",
  "edate": "2017-05-03T03:20:27.303Z",
  "initial_snmp_id": "150",
  "initial_snmp_alias": "irs",
  "initial_interface_description": "Vlan350",
  "initial_snmp_speed": "1000",
  "interface_ip_netmask": "255.255.255.224",
  "secondary_ips": [
    {
      "address": "198.186.193.51",
      "netmask": "255.255.255.240"
    }
  ],
  "connectivity_type": "",
  "network_boundary": "",
  "initial_connectivity_type": "",
  "initial_network_boundary": ""
  "top_nexthop_asns": null,
  "provider":"",  
  "initial_provider": "",
  "vrf_id": ####
  "vrf": {
    "name" : "test_vrf",
    "description" : "This is still a test",
    "route_distinguisher" : "11.121.111.13:3254",
    "ext_route_distinguisher" : 296507164417724,
    "route_target" : "101:100"
  }
}

Each interface object contains fields with information about an individual interface on a Kentik-registered device. These fields are described in the following tables.

Note: For details on the settings represented by the name/value pairs, see Interfaces Page.

An interface object contains all the information about an individual interface of a device registered with Kentik.

The secondary_ips array contains one or more objects, each specifying a secondary IP address for the interface.

An array of objects showing ASNs that received the most packets from the interface in the past hour.

The vrf object, present only if the interface is assigned to a VRF, consists of elements corresponding to each VRF attribute:

The Interface List GET method retrieves a JSON array of Kentik interfaces for a specified device, with each element representing an individual interface.

Note: The "id" value in each interface object can be used in subsequent calls to retrieve, update, or delete that specific interface.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italics):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Interface List method includes:

• Response headers
• HTTP response code
• A JSON response body with an array of interface objects, each representing an interface of the specified device.

Note: For details of the JSON name/value pairs in an interface object, see Interface JSON.

The Interface Info GET method fetches details about a single interface, identified by its ID, from the specified device's collection of interfaces.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The “interface_id” in the path corresponds to the “id” in each interface object from the Interface List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Interface Info method includes the following elements:

• Response headers
• HTTP response code
• A single JSON interface object with details about the interface specified by interface_id.

Note: For details on the JSON name/value pairs in an interface object, see Interface JSON.

The Interface Create POST method adds a new interface to the specified Kentik-registered device’s collection of interfaces.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The following parameters are passed in a JSON object in the request body:

An array of secondary IP objects, each of which must include the address and netmask parameters.

An object specifying the VRF attributes of the interface:

HTTP Response

A successful response from the Interface Create method includes the following elements:

• Response headers
• HTTP response code
• A single JSON interface object with details about the newly-added interface.

Note: For details of the JSON name/value pairs in an interface object, see Interface JSON.

The Interface Update PUT method modifies system data for a specific interface, identified by ID, within the specified device's existing interfaces.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The “interface_id” in the path corresponds to the “id” in each interface object from the Interface List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

When updating an interface, the JSON object must include the required snmp_id and any fields to be updated (see table under HTTP Request in Interface Create). The following example shows an update to the interface’s description:

{
  "snmp_id": "150"
  "interface_description": "This is a truly great interface."
}

HTTP Response

A successful response from the Interface Update call includes the following elements:

• Response headers
• HTTP response code
• A single JSON interface object with details about the newly-updated interface.

Note: For details of the JSON name/value pairs in an interface object, see Interface JSON.

The Interface Delete method removes a specified interface by ID from a Kentik-registered device’s collection of interfaces.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The “interface_id” in the path corresponds to the “id” in each interface object from the Interface List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Interface Delete method includes the following elements:

• Response headers
• The HTTP response code 204 (no content)

The Device Label API allows for programmatic management of your device labels in Kentik. Available methods for managing device labels are covered in the following topics:

• Device Label JSON
• Device Label List
• Device Label Info
• Device Label Create
• Device Label Update
• Device Label Delete

Notes:
- For information on adding and managing device labels via the Kentik portal, see Labels.
- To make calls to this API using cURL, see API Access Via cURL.

Calls to the Device Label API return an HTTP response body with a JSON device label object, or an array of such objects for the Device Label List call. The object includes fields (name/value pairs) as shown in the following example:

{
  "id": 32,
  "name": "ISP",
  "color": "#f1d5b9",
  "user_id": "#####",
  "company_id": "####",
  "order": 0,
  "devices": [
    {
      "id": "#####",
      "device_name": "my_device_1",
      "device_subtype": "router"
    },
  ],
  "created_date": "2018-05-16T20:21:10.406Z",
  "updated_date": "2018-05-16T20:21:10.406Z"
}

Each device label object contains fields with information about an individual device label. These fields are described in the following tables.

Note: For details of the settings represented by these name/value pairs, see Labels.

An array of device objects, each containing a subset of elements from the full device object (see Device JSON), represents devices associated with labels. The table below lists the included elements.

The Device Label List GET method retrieves a JSON array of device labels that currently existing in your organization, with each element representing an individual device label.

Note: The "id" value in each device label object can be used in subsequent calls to retrieve, update, or delete that specific device label.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italics):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Device Label List call includes the following elements:

• Response headers
• HTTP response code
• A response body including a JSON array of device labels. Each element in the array is an object containing information about a device label.

Note: For details of the JSON name/value pairs in a device label object, see Device Label JSON.

The Device Label Info GET method fetches details of a specific device label by ID from your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The "label_id" in the path corresponds to the “id” in the device_label object from the Device Label List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Device Label Info method includes the following elements:

• Response headers
• HTTP response code
• A single JSON device label object with details about the device label specified by label_id.

Note: For details of the JSON name/value pairs in a device label object, see Device Label JSON.

The Device Label Create POST method adds a new device label to your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The following parameters are passed in a JSON object in the request body:

HTTP Response

A successful response from the Device Label Create method includes the following elements:

• Response headers
• HTTP response code
• A single JSON device label object with details about the newly-added device label.

Note: For details of the JSON name/value pairs in a device label object, see Device Label JSON.

The Device Label Update PUT method modifies data for a specified device label by ID in your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The "label_id" in the path corresponds to the “id” in the device_label object from the Device Label List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The parameters to be changed are passed in a JSON device label object:

• To update the label's name, include the name field only.
• To update the label's color, include both the name and color fields.

Example of a device label object to update the color to dark blue:

{
  "name": "Edge"
  "color": "#000080"
}

HTTP Response

A successful response from the Device Label Update method includes the following elements:

• Response headers
• HTTP response code
• A single JSON device label object with details about the newly-updated device label.

Note: For details on the JSON name/value pairs in a device label object, see Device Label JSON.

The Device Label Delete method removes a device label by ID from your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italic):

Notes:
- The "label_id" in the path corresponds to the “id” in the device_label object from the Device Label List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

HTTP Response

A successful response from the Device Label Delete method includes the following elements:

• Response headers
• HTTP response code
• A single JSON object confirming the operation completed successfully:

{
  "success": true
}