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 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 the settings listed under “Assets” in the sidebar of the Admin section of the Kentik Detect portal. The following APIs are available in this category:

  • Devices and interfaces: Supported via the Device API; which provides functionality equivalent to the portal settings covered in Device Admin.
  • Sites: Supported via the Site API; which provides functionality equivalent to the portal settings covered in Site Admin Dialogs.
  • Flow Tags: Supported via the Tag API; which provides access to the information found on the portal’s Plans 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_type": "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 (router or host).
company_id number The system-assigned ID of the customer.
device_name string User-supplied name string for the device.
device_type string Router or host (kprobe host agent).
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    
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_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

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

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

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

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_type string Required: The type of device:
- Valid values: router or host-nprobe-dns-www.
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_type is set to router.
device_snmp_community string The SNMP community to use when polling the device.
Note: Ignored unless device_type 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

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

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

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

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:

{
  "id": "9201304925",
  "company_id": "1289",
  "device_id": "2951",
  "snmp_id": "150",
  "snmp_speed": "1000",
  "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": ""
}

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 (router or host) 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_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.

 

secondary_ips Array

The secondary_ips array contains one or more elements 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  |  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

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

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

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

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, each of which must include address and netmask parameters.
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)

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

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

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

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

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

Plan API

The Plan API, which enables programmatic management of your organization’s Kentik Detect plans (see About Plans), is covered in the following topics:

Notes:
-
To view information on your organization’s plans, go to the Plans Page (Admin » Plans) of the Kentik Detect portal.
- To make calls to this API using cURL, see API Access Via cURL.

 

 
 top  |  section

Plan JSON

Calls to the Plan API each return an HTTP response body containing a “plans” array in JSON that is made up of all of the customers current plans. The following example shows the object returned for a customer that has a single plan (“Default”). The plan supports three device types and currently includes three assigned devices:

{
  "plans": [
    {
      "id": 550,
      "company_id": 1289,
      "name": "Default"
      "description": "This is the default plan to which your devices should be added.",
      "active": true,
      "max_devices": 75,
      "max_fps": 4000,
      "bgp_enabled": true,
      "fast_retention": 120,
      "full_retention": 120,
      "cdate": "2016-10-27T00:35:42.652Z",
      "edate": null,
      "max_bigdata_fps": 30,
      "deviceTypes": [
        {
          "device_type": "router"
        },
        {
          "device_type": "host-nprobe-basic"
        },
        {
          "device_type": "host-nprobe-dns-www"
        }
      ],
      "devices": [
        {
          "device_name": "superx4",
          "device_type": "router",
          "id": "1206"
        },
        {
          "device_name": "superx2_readnews_com",
          "device_type": "router",
          "id": "4806"
        },
        {
          "device_name": "host_nprobe_basic",
          "device_type": "host-nprobe-basic",
          "id": "8937"
        }
      ],
    }
  ]
}

  
Note: Depending on which filter groups and individual filters are defined in a plan, the returned JSON may not include all of the fields shown above.

Each plan object contains information on an individual plan created by Kentik for your organization. The structures that make up the object are described in the following topics.

 

Plan Object

The highest level in the hierarchy of a plan, containing the following elements:

JSON name Type Description
id number The system-assigned unique ID of the plan.
company_id number The system-assigned unique ID of your organization.
name string A name for the plan. Every Kentik Detect customer is initially provided with a plan called “Default.”
Note: Plan names are assigned by the Kentik sales team in coordination with customers, and are not necessarily unique. If multiple plan objects return with the same name, check the value of the “active” field to see which plan is active.
description string An optional description of the plan.
active boolean Indicates if the plan is currently activated.
max_devices number The maximum number of devices that can send flow records to Kentik Detect under this plan.
max_fps number Per device limit on flow records per second that can be sent to Kentik Detect (excess FPS may trigger rate-limiting).
bgp_enabled boolean Indicates whether or not devices on this plan may be peered to enable Kentik Detect to collect BGP routing data.
fast_retention number The number of days that data will be stored in the Fast dataseries.
full_retention number The number of days that data will be stored in the Full dataseries.
cdate string The system-assigned date-time of filter creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
edate string The system-assigned date-time of most-recent modification, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
max_bigdata_fps object Max FPS applied to fast data rollups. See About Dataseries Resolution.
deviceTypes array The types of allowed devices. See DeviceTypes Array.
devices array The devices currently assigned to this plan. See Devices Array.

 

DeviceTypes Array

JSON name Type Description
device_type string A type of device that sends flow records to Kentik Detect.
- Valid values: router, host-nprobe-basic, host-nprobe-dns-www

 

Devices Array

JSON name Type Description
device_name string The user-assigned name of a device associated with this plan.
device_type string A type of device that sends flow records to Kentik Detect.
- Valid values: router, host-nprobe-basic, host-nprobe-dns-www
id number The system-assigned unique ID of a device associated with this plan.

 

 
 top  |  section

Plan List

This GET method retrieves a list of the plans that have been saved by users in your organization. The list is a JSON array whose elements each correspond to an individual plan.

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

URL https://api.kentik.com/api/v5/plans
Request GET /api/v5/plans 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

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A response body containing a JSON array. The array contains an element for each of your organization’s saved plans; each element contains information about that plan.

Note: For a description of the JSON name:value pairs in an individual element of the array see Plan JSON.

 

 
 top

Site API

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

The Site API enables programmatic management of your company’s sites in Kentik Detect (see About Sites). The methods available to manage sites are covered in the following topics:

Notes:
-
For information on adding and managing sites via the Kentik Detect portal, see Add or Edit Site.
- To make calls to this API using cURL, see API Access Via cURL.

 

 
 top  |  section

Site JSON

Calls to the Site API each return an HTTP response body containing a “site” object in JSON (or, in the case of the Site List call, an array of such objects). The object is made up of the fields (name:value pairs) shown in the following example:

{
  "site": {
    "id": 2,
    "site_name": "LAX",
    "lat": 33.7700504,
    "lon": -118.1937395,
    "company_id": 1289
  }
}

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

JSON name Type Description
id number The system-assigned ID of the site.
site_name string User-supplied name string for the site.
- Valid characters: alphanumeric, spaces, and underscores.
- Length: min=3, max=40.
lat number The latitude of the site.
- Valid values: min=-90, max=90.
lon number The longitude of the site.
- Valid values: min=-180, max=180.
company_id number The system-assigned ID of the customer.

Note: In the portal, the settings represented by the name:value pairs above are set in the Site Admin Dialogs.

 

 
 top  |  section

Site List

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

Notes:
- The “id” value in the site object for each site can be used in subsequent calls to get information about, update, or delete that site.
- 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/sites
Request GET /api/v5/sites 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

HTTP Response

A successful response to this call includes the following elements:

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

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

 

 
 top  |  section

Site Info

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

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/site/site_id
Request GET /api/v5/site/site_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

Note: The “site_id” value at the end of the path can be found in the “id” value in the site object that makes up each element of the array returned from Site List.

HTTP Response

A successful response to this call includes the following elements:

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

Note: For a description of the JSON name:value pairs in a site object see Site JSON.

 

 
 top  |  section

Site Create

This POST method adds a new site to a customer’s Kentik Detect sites.

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/site
Request POST /api/v5/site 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

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

JSON name Type Description
site_name string Required: User-supplied name string for the site.
- Valid characters: alphanumeric, spaces, and underscores.
- Length: min=3, max=40.
lat string Required: The latitude of the site.
- Valid values: min=-90, max=90.
lon string Required: The longitude of the site.
- Valid values: min=-180, max=180.

HTTP Response

A successful response to this call includes the following elements:

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

Note: For a description of the JSON name:value pairs in a site object see Site JSON.

 

 
 top  |  section

Site Update

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

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/site/site_id
Request PUT /api/v5/site/site_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

Note: The “site_id” value at the end of the path can be found in the “id” value in the site object that makes up each element of the array returned from Site List.

The parameters to be changed are passed into the call with a JSON site object that contains only the fields (name:value pairs) that are to be updated. The following example shows the site object that would be used to update the site’s name:

{
  "site": {
    "site_name": "SFO"
  }
}

Note: When using the Site Update call in the V5 API Tester, you must specify the lat and lon fields even if you do not intend to change their value (empty fields will result in a value of -1).

HTTP Response

A successful response to this call includes the following elements:

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

Note: For a description of the JSON name:value pairs in a site object see Site JSON.

 

 
 top  |  section

Site Delete

This DELETE method removes one site, identified by ID, from a customer’s collection of Kentik Detect sites.

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/site/site_id
Request DELETE /api/v5/site/site_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

Note: The “site_id” value at the end of the path can be found in the “id” value in the site object that makes up each element of the array returned from Site List.

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.
 

In this article: