CH logo® Knowledge Base
Contents Search
 
 

 

Network Assets APIs

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

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.

 

 
 top

About Network Assets APIs

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 Detect 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 Admin.
  • Device labels: Supported via the Device Label API; which provides functionality equivalent to the portal settings covered in Device Labels Page.

 

 
 top

Device API

Note: Users whose level is Member have access only to the GET methods of this API.

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

Notes:
-
For information on adding and managing devices via the Kentik Detect portal, see Device Settings.
- To make calls to this API using cURL, see API Access Via cURL.

 

 
 top  |  section

Device JSON

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

 

Device Object

JSON name Type Description
id number The system-assigned ID of the device.
company_id number The system-assigned ID of the customer.
device_name string User-supplied name string for the device.
device_subtype string The subtype of the device; see Device Subtypes.
device_description string User-supplied description string for the device.
plan_id number The ID of the plan to which this device is assigned. Available plan(s) can be found via the Plans API.
- Valid value: integer.
site_id number The system-assigned ID of the site (if any) to which this device is assigned.
device_flow_type string If router, the type of flow the device is sending to Kentik (NetFlow v5, NetFlow v9, sFlow, or IPFIX). If host, then IPFIX, the flow type sent from the Kentik nProbe host agent.
Note: The flow type is auto-detected by Kentik Detect.
device_sample_rate string Total packets transiting the device for each packet processed for flow data (see Flow Sampling).
sending_ips array of strings An array of IPs from which the device will send flow to Kentik Detect.
device_snmp_ip string The IP address that should be used to poll the device (router).
device_snmp_community string The SNMP community to use when polling the device (router).
minimize_snmp boolean The interval at which SNMP will be polled:
- If false, interface counter will be polled every 10 minutes and interface description every 30 minutes.
- If true, interface counter won’t be polled and interface description will be polled every 6 hours.
device_bgp_type string Reserved for internal use.
device_bgp_neighbor_ip string BGP Neighbor IP
device_bgp_neighbor_asn string BGP Neighbor ASN (16- or 32-bit)
device_bgp_password string BGP Password
use_bgp_device_id string Use this device’s BGP table, rather than creating a new BGP session.
custom_columns N.A. Internal use only.
created_date string Date-time of registration of the device in Kentik Detect creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
updated_date string Date-time of most-recent edit to the device, in UTC, e.g. 2015-01-27T01:39:17.186Z
device_snmp_v3_conf object See device_snmp_v3_conf Object

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

 

Device Subtypes

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

 

device_snmp_v3_conf Object

JSON name Type Description
UserName string The user name to use for SNMP v3 authentication.
Note: Required if AuthenticationProtocol is MD5 or SHA, or if PrivacyProtocol is DES or AES-128.
AuthenticationProtocol string SNMP v3 authentication protocol.
- Valid values: NoAuth (none), MD5, SHA.
AuthenticationPassphrase string Password for SNMP V3 authentication.
Note: Required if AuthenticationProtocol is MD5 or SHA.
PrivacyProtocol string The SNMP V3 privacy type:
- Valid values: NoPriv (none), DES (56-bit DES encryption), AES-128.
PrivacyPassphrase string Password for SNMP V3 privacy.
Note: Required if PrivacyProtocol is DES or AES-128.

 

 
 top  |  section

Device List

This GET method retrieves a list of a customer’s Kentik Detect 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):

URL https://api.kentik.com/api/v5/devices
Request GET /api/v5/devices HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Device Info

This GET method retrieves information about a single device, identified by ID, in the list of a customer’s Kentik Detect 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):

URL https://api.kentik.com/api/v5/device/device_id
Request GET /api/v5/device/device_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Device Create

This POST method adds a new device to a customer’s Kentik Detect 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):

URL https://api.kentik.com/api/v5/device
Request POST /api/v5/device HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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:

Parameter Type Description
device_name string Required: The name of the device:
- Valid characters: alphanumeric and underscores.
- Length: min=4, max=60.
device_subtype string Required: The type of device:
- Valid values: see Device Subtypes.
device_description string A description of this device:
- Valid characters: any.
- Length: max=128.
plan_id number Required: The ID of the plan to which this device is assigned. Available plan(s) can be found via the Plans API.
- Valid value: integer.
site_id number The ID of the site (if any) to which this device is to be assigned. Site IDs are system generated when a site is created.
- Valid value: integer.
device_sample_rate string Required: Total packets transiting the device for each packet processed for flow data.
sending_ips array of strings Required: The IP(s) from which flow is sent.
Note: Cannot be an IP that is already sending flow to a different device registered in Kentik Detect.
device_snmp_ip string The SNMP IP to use when polling the device.
Note: Ignored unless device_subtype is set to router.
device_snmp_community string The SNMP community to use when polling the device.
Note: Ignored unless device_subtype is set to router.
minimize_snmp boolean Required when device type is router: The interval at which SNMP will be polled:
- If “false”, interface counter will be polled every 10 minutes and interface description every 3 hours.
- If “true”, interface counter won’t be polled and interface description will be polled every 6 hours.
device_snmp_v3_conf object See Setting device_snmp_v3_conf.
Note: If included, Kentik Detect will poll this router with SNMP V3.
device_bgp_type string Required: Device BGP type. Valid values:
- “none” (use generic IP/ASN mapping)
- “device” (peer with the device itself)
- “other_device” (share routing table of existing peered device)
device_bgp_neighbor_ip string A valid IPv4 address to use for peering with this device.
Notes:
- Either this field or its IPv6 equivalent is required when device_bgp_type is set to “device.”
- Cannot be an IP that is already being used to peer with a different Kentik Detect device.
device_bgp_neighbor_ip6 string A valid IPv6 address to use for peering with this device.
Notes:
- Either this field or its IPv4 equivalent is required when device_bgp_type is set to “device.”
- Cannot be an IP that is already being used to peer with a different Kentik Detect device.
device_bgp_neighbor_asn string The valid AS number (16- or 32-bit ASN) of the autonomous system that this device belongs to.
Note: Required when device_bgp_type is set to “device.”
device_bgp_password string Optional BGP MD5 password (shared authentication password for BGP peering). Valid characters: alphanumeric. Length: 32.
Note: Required when device_bgp_type is set to “device.”
use_bgp_device_id string The ID of the device whose BGP table should be shared with this device.
Note: Required when device_bgp_type is set to “other_device”).
- Valid value: a system-generated device_id.

 

Setting device_snmp_v3_conf

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 Detect will assume that you want to use SNMP V3 instead.

Parameter Type Description
UserName string The user name to use for SNMP v3 authentication.
Note: Required if AuthenticationProtocol is MD5 or SHA, or if PrivacyProtocol is DES or AES-128.
AuthenticationProtocol string SNMP v3 authentication protocol.
- Valid values: NoAuth (none), MD5, SHA.
AuthenticationPassphrase string Password for SNMP V3 authentication.
Note: Required if AuthenticationProtocol is MD5 or SHA.
PrivacyProtocol string The SNMP V3 privacy type:
- Valid values: NoPriv (none), DES (56-bit DES encryption), AES-128.
PrivacyPassphrase string Password for SNMP V3 privacy.
Note: Required if PrivacyProtocol is DES or AES-128.

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.

 

 
 top  |  section

Device Update

This PUT method updates system data about one device, identified by ID, in a customer’s list of existing Kentik Detect 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):

URL https://api.kentik.com/api/v5/device/device_id
Request PUT /api/v5/device/device_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Device Apply Labels

This PUT method removes all existing labels (see Device 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):

URL api.kentik.com/api/v5/devices/device_id/labels
Request POST /api/v5/devices/device_id/labels HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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:

Parameter Type Description
labels array An array of id objects.
Note: If the method is called without passing a labels array in the request body then the call will remove any existing labels without adding any new labels.
id integer The id of a label to apply to the device.

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.

 

 
 top  |  section

Device Delete

This DELETE method removes one device, identified by ID, from a customer’s collection of Kentik Detect 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):

URL https://api.kentik.com/api/v5/device/device_id
Request DELETE /api/v5/device/device_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Interface JSON

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

 

Interface Object

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

JSON name Type Description
id string The system-assigned ID of the interface.
company_id string The system-assigned ID of the customer.
device_id string The system-assigned ID of the device to which this interface belongs.
snmp_id string The interface index (ifIndex) as defined in the device and retrieved via SNMP. Same as initial_snmp_id unless manually overridden when device is created or updated in Kentik Detect.
snmp_speed number The capacity of the interface in Mbps. Same as initial_snmp_speed unless manually overridden when device is created or updated in Kentik Detect.
snmp_type integer Reserved for internal use.
snmp_alias string User-specified text that will be used by Kentik Detect as the description of the interface. Same as initial_interface_description unless manually overridden when device is created or updated in Kentik Detect.
interface_ip string The IP address assigned to the interface.
interface_description string User-specified text that will be used by Kentik Detect as the name of the interface. Same as initial_snmp_alias unless manually overridden when device is created or updated in Kentik Detect.
interface_kvs number Reserved for internal use.
interface_tags number Reserved for internal use.
interface_status   Reserved for internal use.
cdate string Date-time of registration of the interface in Kentik Detect creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
edate string Date-time of most-recent edit to the interface, in UTC, e.g. 2015-01-27T01:39:17.186Z
initial_snmp_id string Most recent SNMP-polled SNMP ID of the interface on its device.
initial_snmp_alias string Most recent SNMP-polled interface description.
initial_interface_description string Most recent SNMP-polled interface name.
initial_snmp_speed string Most recent SNMP-polled interface capacity (Mbps).
interface_ip_netmask string The netmask configured for the interface (applies to IPv4 interfaces only).
secondary_ips array See secondary_ips Array.
connectivity_type string Reserved for internal use.
network_boundary string Reserved for internal use.
initial_connectivity_type string Same as connectivity_type.
initial_network_boundary string Same as network_boundary.
top_nexthop_asns array An array of ASNs; see Top Next Hop ASNs.
provider object The provider, as determined by provider classification, via which traffic from a given externally facing interface reaches the Internet; see Provider Classification.
initial_provider string Reserved for internal use.
vrf_id   If the interface is assigned to a VRF, the ID of that VRF, otherwise null.
vrf   Present only if the interface is assigned to a VRF; see VRF Attributes.

 

secondary_ips Array

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

JSON name Type Description
address string A secondary ip for the interface.
netmask string The netmask configured for this secondary interface_ip (applies to IPv4 interfaces only).

 

Top Next Hop ASNs

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.

JSON name Type Description
ASN number The number of an AS.
packets number The number of packets in the hour preceding the call.

 

VRF Attributes

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:

Parameter Type Description
name string Name of the VRF entry.
description string Description of the VRF entry.
route_target string Route Target Community of the VRF entry.
route_distinguisher string Route Distinguisher of the VRF entry.
ext_route_distinguisher integer External Route Distinguisher of the VRF entry.

 

 
 top  |  section

Interface List

This GET method retrieves a list of a customer’s Kentik Detect 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):

URL https://api.kentik.com/api/v5/device/device_id/interfaces
Request GET /api/v5/device/device_id/interfaces HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Interface Info

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):

URL https://api.kentik.com/api/v5/device/device_id/interface/interface_id
Request GET /api/v5/device/device_id/interface/interface_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Interface Create

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):

URL https://api.kentik.com/api/v5/device_id/interface
Request POST /api/v5/device_id/interface HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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:

Parameter Type Description
snmp_id string Required: The interface index (ifIndex) as defined in the device and retrieved via SNMP. See Getting an Interface Index.
interface_description string Required: User-specified text that will be used by Kentik Detect as the name of the interface.
snmp_alias string User-specified text that will be used by Kentik Detect as the description of the interface.
interface_ip string The IP address assigned to the interface.
interface_ip_netmask string The netmask configured for the interface (applies to IPv4 interfaces only).
snmp_speed number Required: The capacity of the interface in Mbps.
secondary_ips array Array of secondary_ip objects; see Secondary IPs Array.
vrf object An object specifying the VRF attibutes of the interface; see VRF Object.

 

Secondary IPs Array

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

Parameter Type Description
address string In secondary_ip object, a secondary ip for the interface.
netmask string In secondary_ip object, the netmask configured for this secondary interface_ip (applies to IPv4 interfaces only)

 

VRF Object

An object specifying the VRF attibutes of the interface:

Parameter Type Description
name string Required: Name of the VRF entry.
description string Required: Description of the VRF entry.
route_target string Required: Route Target Community of the VRF entry.
route_distinguisher string Required: Route Distinguisher of the VRF entry.
ext_route_distinguisher integer External Route Distinguisher of the VRF entry.

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.

 

 
 top  |  section

Interface Update

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):

URL https://api.kentik.com/api/v5/device/device_id/interface/interface_id
Request PUT /api/v5/device/device_id/interface/interface_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Interface Delete

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):

URL https://api.kentik.com/api/v5/device/device_id/interface/interface_id
Request DELETE /api/v5/device/device_id/interface/interface_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top

Device Label API

Note: Users whose level is Member have access only to the GET methods of this API.

The Device Label API enables programmatic management of your company’s device labels in Kentik Detect. The methods available to manage device labels are covered in the following topics:

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

 

 
 top  |  section

Device Label JSON

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

 

Device Label Object

JSON name Type Description
id number The system-assigned ID of the device label.
name string User-specified text of the device label (e.g. “ISP”).
color string The color, in hex, associated with this device label (e.g. “#f1d5b9”).
user_id string The ID of the user who created or last edited the label.
company_id string The system-assigned ID of the customer in which the label exists.
devices array See Devices Array for Labels.
created_date string Date-time, in UTC (ISO 8601), at which the device label was created (e.g. 2015-01-27T01:39:17.186Z).
updated_date string Date-time at which the label was most-recently edited.

 

Devices Array for 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.

JSON name Type Description
id string The system-assigned ID of the device.
device_name string Name specified by user when device was last edited.
device_subtype string See Device Subtypes.

 

 
 top  |  section

Device Label List

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):

URL api.kentik.com/api/v5/deviceLabels
Request GET /api/v5/deviceLabels HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Device Label Info

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):

URL api.kentik.com/api/v5/deviceLabels/label_id
Request GET api/v5/deviceLabels/label_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Device Label Create

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):

URL api.kentik.com/api/v5/deviceLabels
Request POST api/v5/deviceLabels HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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:

Parameter Type Description
name string Required: A unique string (not already used by an existing device label).
- Length: max=100.
color string Required: A color value expressed in hex (e.g. “#a9c5e0”).

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.

 

 
 top  |  section

Device Label Update

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):

URL api.kentik.com/api/v5/deviceLabels/label_id
Request PUT /api/v5/deviceLabels/label_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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.

 

 
 top  |  section

Device Label Delete

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):

URL api.kentik.com/api/v5/deviceLabels/label_id
Request DELETE /api/v5/deviceLabels/label_id HTTP/1.1
Host: api.kentik.com
X-CH-Auth-API-Token: user_api_token
X-CH-Auth-Email: user@domain.suffix
Content-Type: application/json

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
}

 

In this article: