The Kentik APIs, which enable programmatic control of Kentik, are covered in the following topics:
- About Kentik APIs
- About the V6 APIs
- About the V5 APIs
- API Rate Limiting
- API Access Via cURL
- API Access Via Swagger
Note: For assistance using a Kentik API, please contact Customer Support.
About Kentik APIs
Kentik APIs enable programmatic control over Kentik setup (administrative functions) and the querying of network data stored in Kentik, as well as alerting (notification) and mitigation in response to user-defined conditions. Kentik currently has the API versions shown below.
Current API Versions
Kentik currently supports two API versions:
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.
About the V6 APIs
The V6 APIs, provided for both REST endpoints and gRPC RPCs, serve two main purposes:
- Provide functionality that's not covered by the V5 APIs.
- Provide a foundation for ongoing expansion of capabilities, including in some areas that are already covered by the V5 APIs (e.g. Users and Sites).
The following v6 APIs are currently available:
V6 API Tester
The V6 API tester enables you to test the V6 API by calling its methods using data from your own Kentik account. The tester is built into the Kentik portal at the following URL: https://portal.kentik.com/v4/core/api-tester.
About the V5 APIs
The Kentik V5 APIs enable programmatic management of Kentik. The V5 APIs are divided into the following main categories:
- V5 Admin APIs: The Kentik V5 Admin APIs enable programmatic management of your company's Kentik 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 (users, devices, tags, etc.), start with V5 Admin APIs. For a list, see V5 Admin Methods.
- V5 Query API: The Kentik V5 Query API enables programmatic querying of your company's network data stored in Kentik. Queries can return data or visualizations in graphics files. V5 Query API is documented in V5 Query API. For a list, see V5 Query Methods.
- V5 Alerting APIs: The Kentik V5 Alerting APIs provide programmatic notification of anomalous conditions (DDoS attacks, blocked routes, etc.) on network infrastructure monitored with Kentik, and enable the initiation and management of mitigation. Methods can return data on current or baseline (historical) conditions that deviate from your specified norms. V5 Alerting APIs are documented in V5 Alerting API. For a list, see V5 Alerting Methods.
Note: The V5 APIs fully supersede all earlier API versions (see Discontinued API Versions).
V5 API Tester
In addition to testing the V5 APIs with cURL (see API Access Via cURL) you can also use our V5 API tester, which is in ioDocs. The tester is available at the following URLs (choose based on the region in which your organization is registered with Kentik):
Note: The v5 Alerting API is not included on the above tester pages. To test the v5 Alerting API, see API Access Via Swagger.
API Rate Limiting
API calls (requests to API endpoints) are rate-limited to enable fair distribution of server resources to all Kentik customers. The limits are structured to permit reasonable bursts of activity and to avoid sudden brick-wall failure. When developing code that uses the APIs, please be aware of the following key points:
- Requests from the V5 Query API and the V5 Admin APIs are counted separately and have different limits.
- Rate limits are based on a rolling minute and a rolling hour, which means that each request received by the server is included in the per-minute count for 60 seconds from time of receipt, and in the per-hour count for 3600 seconds from time of receipt.
- A server response delay is applied to every request received while the per-minute count is greater than the soft limit given in the table below.
- An HTTP 429 error may be generated by every request received while either the per-minute count is greater than the hard limit or the per-hour count is greater than the hourly limit.
- If the maximum concurrent request limit is respected then the per-minute count will never exceed the hard limit (nor will the hourly limit be exceeded for non-query APIs).
The following table shows the limits for query and non-query API calls.
|Per-customer limit||Non-query APIs||Query API||Description|
|Maximum concurrent requests||1||4||A request is concurrent if received before the server has responded to the previous request.|
|Soft limit (per minute)||20||30||Maximum requests per rolling minute without triggering server response delay.|
|Server response delay (seconds)||1.5||1||Delay in server response that will be applied to requests received while per-minute count exceeds soft limit.|
|Hard limit (per minute)||60||100||Maximum requests per rolling minute without triggering HTTP 429 error.
Note: Occurs only if concurrent requests exceed maximum.
|Hourly limit||3750||1000||Maximum requests per rolling hour without triggering HTTP 429 error.|
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:
API V5 cURL Structure
The structure of an HTTP request to Kentik via cURL is made up of the elements shown in the following table, which illustrates a call to the V5 User API:
|curl||Declares the following string as a cURL command.|
|Method||-X PUT||HTTP method of the call, e.g. GET, PUT, POST, DELETE|
|-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.|
|-H 'X-CH-Auth-Email: email@example.com'||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.|
|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 (US)||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.|
Note: For organizations that are registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the API v5 URL shown above.
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: firstname.lastname@example.org' \
-H 'X-CH-Auth-API-Token: user_api_token' \
-H 'Content-Type: application/json' \
"user_full_name": "New Username",
https://api.kentik.com/api/v5/user | python -m json.tool
- 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).
- For organizations that are registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the API v5 URL shown above.
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:
- 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.
- 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 portal dimensions (and underlying KDE main table columns) corresponding to the JSON name:value pairs used by the V5 APIs, see Dimensions Reference.
API Access Via Swagger
Access to Kentik APIs via Swagger is covered in the following topics:
Kentik APIs in Swagger
As of Q3 2020, Kentik is moving away from ioDocs as a platform for testing API methods, and will be using Swagger instead. The first API to be affected by this change is our Alerting API. This change has the following impact on the way that Kentik APIs are documented and tested:
- New APIs will not appear on the ioDocs API tester page (see V5 API Tester).
- The primary tool for seeing the details of all available parameters for API methods will initially be Swagger Editor (see Viewing APIs With Swagger).
- APIs will still be documented at a high level in the Knowledge Base, but not down to the parameter level (view details in Swagger Editor instead).
- Testing via Swagger is not yet implemented for Kentik's EU cluster. Customers using our EU cluster should test via cURL instead (see API Access Via cURL).
- You must be an Admin-level user to perform the setup procedures described below.
Swagger Access Control
Using the Swagger Editor to test calls involving actual Kentik data requires that Kentik be set to grant access to the client from which you make those calls. Unless your organization's API access is set to Allow All, you enable access by adding the client to your API whitelist:
- In the Kentik portal, choose Settings from the main navbar menu.
- On the Settings landing page, choose Access Control from the Access & Security card in the right sidebar.
- On the Access Control page, if the API pane is set to Allow All then do nothing, but if the API pane is set to Deny All Except then:
- Click the Add Exception Group button. A new Exception card will be added.
- Click the Edit (pencil) icon. The card will expand to show the Exception Name and IP Addresses fields.
- Enter a name for the exception group (e.g. "Swagger access") and one or more public IP addresses from which a client running the Swagger Editor will access the Kentik APIs.
Note: To determine your client's public IP address, go to https://ipinfo.io/ip.
- Click the Save button to save the new exception group and collapse the card.
- The above procedure is not required to view the details of methods and parameters in Swagger.
- Calls from the Swagger Editor to Kentik data are currently supported for Kentik's US cluster. EU customers should test via cURL instead (see API Access Via cURL).
Getting a Swagger File
Viewing a Kentik API in Swagger involves getting the swagger.json file for that file, which you can do as described in the topics below.
Getting Swagger via cURL
Using cURL you can directly download the swagger.json file that matches your deployed API version. Below is a cURL example for downloading the Alerting API (alerting.swagger.json).
|curl -sv \
-H 'X-CH-Auth-API-Token:api_token_from_portal_profile’ \
-H 'X-CH-Auth-Email:email@example.com’ \
-H 'Content-Type:application/json' \
Getting Swagger from GitHub
Assuming that you have read access to Kentik on GitHub, you can download the swagger.json file from there. the following URL shows the repo for the Alerting API:
Viewing APIs With Swagger
Kentik APIs that support Swagger may be viewed in the Swagger Editor. To open the editor and view an API:
- Go to Swagger Editor at https://editor.swagger.io/
- Choose Import File from the File menu in the navbar.
- In the resulting dialog, choose a swagger.json file, e.g. alerting.swagger.json, then click the Open button. the dialog will close and the file will open in the Swagger Editor.
- The left-side pane of the editor will display the JSON code while the left side displays the Swagger output. To make more room for the output, click on the center divider (thick gray line) and drag it to the left.
Swagger API Authorization
Once the swagger.json file is imported into the Swagger Editor you'll be able to view all the methods and properties defined in the file (for more info, see https://swagger.io/tools/swagger-ui/). In order to test a method using the Swagger Try it out button (visible when you click on a method to expand it) you'll first need to configure authorization using your Kentik API authentication credentials:
- In a new tab, go to the Kentik portal and choose Profile from the drop-down user menu at the far right of the main navbar.
- From the sidebar at left, choose Authentication.
- In the API Token pane at bottom, select and copy the API token to the clipboard.
- Back in the Swagger Editor tab, the Authorize button in the right-side pane (at the top of the Swagger output) will include an open lock icon. Click the button.
- In the resulting Available Authorizations dialog, enter your Kentik-registered email address in the email field and click the corresponding Authorize button.
- Paste the API token from the clipboard into the token field and click the corresponding Authorize button.
- Click one of the Close buttons to close the dialog. Assuming that authorization was successful, the icon in the Authorize button will now be a closed lock.
Note: Calls from the Swagger Editor to Kentik data are currently supported for Kentik's US cluster. EU customers should test via cURL instead (see API Access Via cURL).