CH logo® Knowledge Base
Contents Search
   

 

APIs Overview

The Kentik APIs enable programmatic control of Kentik Detect, including both the management of your company’s administrative settings and the querying of stored network data. Kentik APIs are covered in the following topics:

Note: For assistance using a Kentik API, please email support@Kentik.com.

 

 
 top

About Kentik APIs

Kentik APIs enable programmatic control over Kentik Detect setup (administrative functions) as well as querying of network data stored in Kentik Detect. Kentik currently has the API versions shown below.

 

Current API Version

V5 APIs: An updated set of Kentik APIs that covers both administrative and querying functionality:

 

Discontinued API Versions

The following API versions are now discontinued (endpoints are no longer available):

  • V1 APIs: Original Kentik APIs, which supported both admin and querying. Discontinued as of May 8, 2017.
  • V4 APIs: Kentik APIs for modeling the Data Explorer functionality of the Kentik portal to output graphs and tables. Discontinued as of May 8, 2017.

 

 
 top

About the V5 APIs

The Kentik V5 APIs enable programmatic management of your company’s Kentik Detect admin settings and the querying of network data in Kentik Detect. The V5 APIs are divided into two main categories, which are covered in the following topics:

  • V5 Admin APIs: The Kentik V5 Admin APIs enable programmatic management of your company’s Kentik Detect settings. The interfaces support methods that write to or read from backend information, maintained by Kentik for each company, in areas such as users, devices, sites, and tags. Calls that return information do so in key:value pairs in a JSON structure within an HTTP response body. For documentation on APIs for administrative functions, start with V5 Admin APIs.
  • V5 Query API: The Kentik V5 Query API enables programmatic querying of your company’s network data stored in Kentik Detect. Queries can return data or visualizations in graphics files. V5 Query API is documented in V5 Query API.

 

 
 top

API Access Via cURL

The Kentik V5 APIs may be accessed using cURL (https://curl.haxx.se/) to generate HTTP requests to the Kentik API server. The use of cURL with the V5 API is covered in the following topics:

 

 
 top  |  section

API V5 cURL Structure

The structure of an HTTP request to Kentik Detect via cURL is made up of the elements shown in the following table, which illustrates a call to the V5 User API:

Element Example Description
Command
declaration
curl Declares the following string as a cURL command.
Method -X PUT HTTP method of the call, e.g. GET, PUT, POST, DELETE
Authorization:
API token
-H ‘X-CH-Auth-API-Token: user_api_token Header: used to pass the API Token that is associated with the user in the Kentik system.
Authorization:
User email
-H ‘X-CH-Auth-Email: user@domain.suffix Header: used to pass the email address that is associated with the user in the Kentik system.
Content-Type declaration Content-Type: application/json Header: specifies the content type of the
Data -d ‘{
  “user”: {
    “email_service”: true,
  }
}’
Data (JSON): If creating or updating, a JSON object containing data fields (name:value pairs):
- If creating (POST), include all required fields.
- If updating (PUT), include only the fields that you wish to update. In the example at left, the email_service field will be updated; all other fields retain their existing values.
URL https://api.kentik.com/api/v5/user/user_id Path to the endpoint on the Kentik V5 API query server.
Formatter | python -m json.tool Optional: added to the end of the cURL command to have the JSON response body returned in “pretty” layout.

 

 
 top  |  section

API V5 cURL Command

When assembled, the above syntax elements become a cURL command like the following example (with placeholders highlighted), which creates a new user (the backslashes break the command into multiple lines for improved readability):

curl -X POST \
-H 'X-CH-Auth-Email: user@domain.suffix' \
-H 'X-CH-Auth-API-Token: user_api_token' \
-H 'Content-Type: application/json' \
-d '{
  "user": {
    "user_name": "New_Username",
    "user_full_name": "New Username",
    "user_email": "new_user@domain.suffix",
    "user_password": "newUser_password",
    "role": "Member",
    "email_service": true,
    "email_product": true
  }
}' \
https://api.kentik.com/api/v5/user | python -m json.tool

Note: A user’s API token may be found at the bottom of the User Information pane of the User Profile page in the Kentik portal (access via the link on the username at the right of the main navbar).

Using a single data (-d) parameter in cURL to pass a JSON object, as shown above, makes it easy to pass field values to Kentik Detect:

  • For the Create call of each API (User, Device, etc.), the -d parameter will take the entire JSON object corresponding to that API (e.g. the user object for the User API).
  • For the Update call of each API, the -d parameter will take the JSON structure corresponding to that API, but only the fields that are to be updated will be included in the structure.

Notes:
- Depending on the programmatic context, a data (-d) parameter that contains single quotes may cause a call to fail. To escape these quotes in cURL, replace single quotes with the Unicode equivalent \u0027.
- An example of the JSON object that is returned from each of the V5 APIs is illustrated in the topics covering those APIs (see V5 Admin APIs and V5 Query API).
- For a description of the KDE main table columns corresponding to the JSON name:value pairs used by the V5 APIs, see Main Table Schema.

 

In this article: