Site and Plan APIs

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

• About Site and Plan APIs
• Site API
• Plan API

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

The Kentik V5 Admin APIs include 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 Settings.
• Plans: Supported via the Plan API; which provides access to the information found on the portal's Licenses Page.

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:

• Site JSON
• Site List
• Site Info
• Site Create
• Site Update
• Site Delete

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

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:

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

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

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.

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

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.

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

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

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

HTTP Response

A successful response to this call includes the following elements:

• The response headers.
• The HTTP response code.
• A single JSON 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.

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

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.

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

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.

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

• Plan JSON
• Plan List

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

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.

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

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.

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

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.