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.
- To test V5 APIs, see V5 API Tester.
- For assistance using any API version please contact support@Kentik.com.

The Kentik V5 Admin APIs include a set of "network assets" APIs that enable programmatic management of settings in the Admin section of the Kentik portal. These include APIs for the following:

• Devices and interfaces: Supported via the Device API; which provides functionality equivalent to the portal settings covered in Device Settings Dialog.
• Device labels: Supported via the Device Label API; which provides functionality equivalent to the portal settings covered in Labels Page.

The Device API enables programmatic management of your company's devices in Kentik. The methods available to manage devices are covered in the following topics:

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

Calls to the Device API each return an HTTP response body containing a "device" object in JSON (or, in the case of the Device List call, an array of such objects). The object is made up of 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"
    },
  }
}

The fields of each device object contain information on an individual device registered with a given Kentik customer (company). These fields are described in the following tables

Note: For further information about the settings represented by the name:value pairs above, see Device Settings Dialog.

Kentik supports the device subtypes listed in the Subtype column of the table in the KB topic Supported Device Types.

This GET method retrieves a list of a customer’s Kentik devices. The list is a JSON array whose elements each correspond to an individual device.

Notes:
- The “id” value in the device object for each device can be used in subsequent calls to get information about, update, or delete that device.
- To try this call, go to the V5 API Tester.

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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A response body containing a device array in JSON. The array contains an element for each of the company’s devices; each element is a device object containing information about one device.

Note: For a description of the JSON name:value pairs in a device object, see Device JSON.

This GET method retrieves information about a single device, identified by ID, in the list of a customer’s Kentik devices.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The “device_id” value at the end of the path can be found in the “id” value in the device object that makes up each element of the array returned from Device List.
- 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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON device object containing information about the device specified with device_id.

Note: For a description of the JSON name:value pairs in a device object see Device JSON.

This POST method adds a new device to a customer’s Kentik devices.

Note: To try this call, go to the V5 API Tester.

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 device_snmp_v3_conf object is included in request JSON when you want to use SNMP V3 for router polling. If the object is not included, Kentik will assume that you want to use SNMP V3 instead.

Note: The SNMP V3 authentication and privacy settings are each independent of the other. To use SNMP V3 without either, specify AuthenticationProtocol as NoAuth and PrivacyProtocol as NoPriv.

HTTP Response

A successful response to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON device object containing information about the newly added device.

Note: For a description of the JSON name:value pairs in a device object see Device JSON.

This PUT method updates system data about one device, identified by ID, in a customer’s list of existing Kentik devices.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The “device_id” value at the end of the path can be found in the “id” value in the device object that makes up each element of the array returned from Device List.
- 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 into the call with a JSON device object that contains only the fields (name:value pairs) that are to be updated. The following example shows the device object that would be used to update the device’s description:

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

HTTP Response

A successful response to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON device object containing information about the newly updated device.

Note: For a description of the JSON name:value pairs in a device object see Device JSON.

This PUT method removes all existing labels (see Labels) applied to the specified device and applies to that device one or more device labels specified in this call.

Note:
- This method may be called without specifying any labels to add, in which case all of the specified device's existing labels (if any) will still be removed.
- To create and manage device labels via API, see Device Label API.
- To try this call, go to the V5 API Tester.

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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON device object containing a labels array with information about the labels currently assigned to the device (after completion of the operation). An example of what's returned when you successfully apply a single label is shown 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 descriptions of the JSON name:value pairs in an individual labels object, see Device Label Object.

This DELETE method removes one device, identified by ID, from a customer's collection of Kentik devices.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The "device_id" value at the end of the path can be found in the "id" value in the device object that makes up each element of the array returned from Device List.
- 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 to this call includes the following elements:

• The response headers.
• The HTTP response code 204, indicating that the request was received and understood but that there was no need to return a response body.

The interface methods of the Device API each return an HTTP response body containing an "interface" object in JSON (or, in the case of the Interface List call, an array of such objects). The object is made up of the fields (name:value pairs) 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"
  }
}

The fields of each interface object contain information on an individual interface on a device registered with Kentik. These fields are described in the following tables.

Note: For further information about the settings represented by the name:value pairs above, see Interfaces Page.

The elements of an interface object contain all information about an individual interface of a device that is registered with Kentik.

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

An array of objects representing the ASNs to which the interface has sent the most packets in the one-hour time-span immediately preceding the call.

Present only if the interface is assigned to a VRF, the vrf object is made up of elements that each correspond to an attribute of that VRF:

This GET method retrieves a list of a customer's Kentik interfaces on a specified device. The list is a JSON array whose elements each correspond to an individual interface.

Notes:
- The "id" value in the interface object for each interface can be used in subsequent calls to get information about, update, or delete that interface.
- To try this call, go to the V5 API Tester.

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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A response body containing an interface array in JSON. The array contains an element for each of the specified device's interfaces; each element is an interface object containing information about one interface.

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

This GET method retrieves information about a single interface, identified by ID, in the specified device's collection of interfaces.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The "interface_id" value at the end of the path can be found in the "id" value in the interface object that makes up each element of the array returned from Interface List.
- 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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON interface object containing information about the interface specified with interface_id.

Note: For a description of the JSON name:value pairs in a interface object see Interface JSON.

This POST method adds a new interface to the collection of interfaces on the specified Kentik-registered device.

Note: To try this call, go to the V5 API Tester.

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 address and netmask parameters.

An object specifying the VRF attibutes of the interface:

HTTP Response

A successful response to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON interface object containing information about the newly added interface.

Note: For a description of the JSON name:value pairs in an interface object see Interface JSON.

This PUT method updates system data about one interface, identified by ID, in the specified device's collection of existing interfaces.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The "interface_id" value at the end of the path can be found in the "id" value in the interface object that makes up each element of the array returned from Interface List.
- 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 interface object passed into the call need only contain snmp_id (required) and any other fields (see table under HTTP Request in Interface Create) that are to be updated. The following example shows the interface object that would be used to update the interface’s description:

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

HTTP Response

A successful response to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON interface object containing information about the newly updated interface.

Note: For a description of the JSON name:value pairs in an interface object see Interface JSON.

This DELETE method removes one interface, identified by ID, from the collection of interfaces on a Kentik-registered device.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The "interface_id" value at the end of the path can be found in the "id" value in the interface object that makes up each element of the array returned from Interface List.
- 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 to this call includes the following elements:

• The response headers.
• The HTTP response code 204, indicating that the request was received and understood but that there was no need to return a response body.

The Device Label API enables programmatic management of your company's device labels in Kentik. The methods available to manage 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 each return an HTTP response body containing a device label object in JSON (or, in the case of the Device Label List call, an array of such objects). The object is made up of the fields (name:value pairs) 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"
}

The fields of each device label object contain information on an individual device label within a given Kentik customer (company). These fields are described in the following tables.

Notes: For further information about the settings represented by the name:value pairs below, see Labels.

An array of device objects that each contain a subset of the elements in the full device object (see Device JSON). Each device object in the array represents a device to which this label is applied. The table below shows the included elements.

This GET method retrieves a list of the device labels that currently exist in your organization. The list is a JSON array whose elements each correspond to an individual device label.

Notes:
- The "id" value in the object representing each device label can be used in subsequent calls to get information about, update, or delete that device label.
- To try this call, go to the V5 API Tester.

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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A response body containing a device label array in JSON. The array contains an element for each of your organization's device labels; each element is an object containing information about one device label.

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

This GET method retrieves information about a single device label, identified by ID, in your organization's collection of device labels.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The "label_id" value at the end of the path can be found in the "id" value in the device label object that makes up each element of the array returned from Device Label List.
- 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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON device label object containing information about the device label specified with label_id.

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

This POST method adds a new device label to your organization's collection of device labels.

Note: To try this call, go to the V5 API Tester.

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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON device label object containing information about the newly added device label.

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

This PUT method updates system data about one device label, identified by ID, in your organization's collection of device labels.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The "label_id" value at the end of the path can be found in the "id" value in the device label object that makes up each element of the array returned from Device Label List.
- 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 into the call with a JSON device label object:

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

The following example shows the device label object that would be used to update the device label’s color to dark blue:

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

HTTP Response

A successful response to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON device label object containing information about the newly updated device label.

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

This DELETE method removes one device label, identified by ID, from your organization's collection of device labels.

Note: To try this call, go to the V5 API Tester.

HTTP Request

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

Notes:
- The "label_id" value at the end of the path can be found in the "id" value in the device label object that makes up each element of the array returned from Device Label List.
- 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 to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON object (shown below) confirming that the operation completed successfully.

{
  "success": true
}