Site and Plan 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.

 

About Site and Plan APIs

The Kentik V5 Admin APIs include APIs that enable programmatic management of settings found in the Admin section of the Kentik portal. This includes the following APIs:

  • Sites: Supported via the Site API; which provides functionality equivalent to the portal settings covered in Site Admin Dialogs.
  • Plans: Supported via the Plan API; which provides access to the information found on the portal’s Plans Page.
 

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

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

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

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:

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

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

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

Plan API

The Plan API, which enables programmatic management of your organization’s Kentik 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 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_subtype": "router"
        },
        {
          "device_subtype": "host-nprobe-basic"
        },
        {
          "device_subtype": "host-nprobe-dns-www"
        }
      ],
      "devices": [
        {
          "device_name": "superx4",
          "device_subtype": "router",
          "id": "1206"
        },
        {
          "device_name": "superx2_readnews_com",
          "device_subtype": "router",
          "id": "4806"
        },
        {
          "device_name": "host_nprobe_basic",
          "device_subtype": "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 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 under this plan.
max_fps number Per device limit on flow records per second that can be sent to Kentik (excess FPS may trigger rate-limiting).
bgp_enabled boolean Indicates whether or not devices on this plan may be peered to enable Kentik 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 for Plans.

DeviceTypes Array

JSON name Type Description
device_subtype string A type of device that sends flow records to Kentik.
- Valid values: see Device Subtypes.

Devices Array for Plans

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

JSON name Type Description
device_name string The user-assigned name of a device associated with this plan.
device_subtype string A type of device that sends flow records to Kentik.
- Valid values: see Device Subtypes.
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

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

© 2014- Kentik

In this article: