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

The Kentik V5 APIs enable programmatic management of Kentik Detect. 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 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.

API calls (requests to API endpoints) are rate-limited to enable fair distribution of server resources to all Kentik Detect 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:

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.

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

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

Notes:
- 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 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 portal dimensions (and underlying KDE main table columns) corresponding to the JSON name:value pairs used by the V5 APIs, see Dimension Reference.