In this article:

Contents Search
   

 

Customization APIs

The “customization” 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 assistance using any API version please contact support@Kentik.com.

 

 
 top

About Customization APIs

The Kentik V5 Admin APIs include a set of “customization” APIs that enable programmatic management of the settings listed under “Customize” in the sidebar of the Admin section of the Kentik Detect portal. The following APIs are available in this category:

  • Custom Dimensions: Supported via the Custom Dimension API; which provides functionality equivalent to the portal settings covered in Custom Dimensions.
  • Saved Filters: Supported via the Saved Filter API; which provides functionality equivalent to the portal settings covered in Saved Filters.
  • Flow Tags: Supported via the Tag API; which provides functionality equivalent to the portal settings covered in Flow Tags.

Note: Interface Classification and Network Classification are not yet supported with APIs.

 

 
 top

Tag API

Note: Users whose level is Member have access only to the GET methods of this API.

The Tag API enables programmatic management of your company’s tags in Kentik Detect. The methods available to manage tags are covered in the following topics:

Notes:
-
For information on adding and managing tags via the Kentik Detect portal, see Flow Tags.
- To make calls to this API using cURL, see API Access Via cURL.

 

 
 top  |  section

Tag JSON

Calls to the Tag API each return an HTTP response body containing a “tag” object in JSON (or, in the case of the Tag List call, an array of such objects). The object is made up of the fields (name:value pairs) shown in the following example:

{
  "tag": {
    "id": 664,
    "flow_tag": "INTF_NAME_TEST",
    "device_name": "",
    "interface_name": "",
    "addr": "",
    "port": "700",
    "tcp_flags": "",
    "protocol": "",
    "asn": "",
    "nexthop_asn": "",
    "bgp_aspath": "",
    "bgp_community": "",
    "user": "3584",
    "created_date": "2015-07-14T18:02:40.469Z",
    "updated_date": "2015-10-20T00:47:03.509Z",
    "company_id": "1289"
  }
}

Note: Depending on which fields are defined in a tag object, the returned object may not include all of the fields shown above.

The fields of each tag object contain information on an individual tag registered with a given Kentik customer (company). These fields are described in the following table:

JSON name Type Description Portal field
id number The system-assigned ID of the tag. Tag ID
flow_tag string Required: A name for the tag. When a match for any of the other tag parameters is found in the flow from a given device, this string will be added to the src_flow_tags and/or dst_flow_tags column in that device’s KDE main table.
- Length: min=2, max=20.
- Valid characters: alphanumeric, hyphen, or underscores (no spaces).
Tag name
device_name string A match results when the device_name associated with a device sending flow data contains this string. Device name
device_type string A comma-delimited list of device types or regular expressions. A match results when any specified device type matches the device_type associated with a device sending flow data. Device type
site string A comma-separated list of sites or regular expressions. A match results when any specified site matches the site associated with a device sending flow data. Site
interface_name string A match results when the name or description of an interface sending flow data contains this string. Interface name
addr string A range of IP addresses, expressed in CIDR notation (e.g. 38.12.34.0/24). A match results when this value corresponds to a range of IP addresses in incoming flow. IP address
port string A port number, either source (SRC Port) or destination DST Port). A match results when this value appears within a port number in incoming flow. Port
tcp_flags string An integer number between 0 and 255 representing an 8-bit binary bit pattern corresponding to TCP flags. A match will result if the value in both the flow bit pattern and the bitmask is 1 at any of the eight places. TCP flag
protocol string The protocol of traffic represented by a flow. The protocol of TCP is 6, and of UDP is 17. A match results when this value is the same as the protocol of the traffic represented by the flow. Protocol name/number
asn string A comma-delimited list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the last-hop router based on AS-PATH. Last-hop (origin) ASN
lasthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name represents the name corresponding to the last ASN in the path in the routing table for either the source (SRC IP) or destination (DST IP). Last-hop (origin) AS Name
nexthop_asn string A comma-delimited list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the next-hop router based on AS-PATH. Next-hop ASN
nexthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name corresponds to the AS name of the next hop router based on AS path. Next-hop AS Name
nexthop string A comma-separated list of IPv4 and/or IPv6 CIDRs. If a CIDR grouping (IPv4 or IPv6) is specified, a match can be on any address within that grouping. If no CIDR grouping is specified a match requires an exact IP.
- CIDRs may be expressed in “short form” (e.g. 1::2/127).
Next-hop IP
bgp_aspath string A comma-delimited list of numbers or regular expressions representing BGP AS path. A match results when this value is the same as the BGP AS-PATH in the route.
- Permitted characters []*:_^$.0123456789()+?,space-
- Example: “^3737 1212,_7801_,2906$” would look for any of those 3 combinations in the AS path.
BGP AS path
bgp_community string A comma-delimited list of numbers or regular expression representing BGP community (i.e. 2096:2212). A match results when this value is the same as the BGP community of the BGP route associated with incoming flow data.
- Permitted characters []*:_^$.0123456789()+?,space-
BGP community
mac string A comma-separated list of MAC Addresses. Results in a match if this value matches source or destination Ethernet (L2) address. MAC Address
country string A comma-separated list of two-character country codes. Results in a match if this value includes a two-letter country code associated with the source or destination IP of the flow. Country
user string The system-assigned ID of the user who created the tag. N.A.
created_date string Date-time of tag creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z N.A.
updated_date string Date-time of most-recent tag edit, in UTC, e.g. 2015-01-27T01:39:17.186Z N.A.
company_id number The system-assigned ID of the customer. N.A.

Notes:
- The Portal field column indicates the name of the corresponding setting on the Add Tag or Edit Tag page in the portal (see Add or Edit Tags).
- Commas are valid in field values only as delimiters in comma-delimited lists.
- For further information about validations applied to values submitted for the above fields, see Tag Field Validation.

 

 
 top  |  section

Tag List

This GET method retrieves a list of a customer’s Kentik Detect tags. The list is a JSON array whose elements each correspond to an individual tag.

Notes:
- To try this call, go to the V5 API Tester.
- The “id” value in the structure corresponding to a given tag can be used in subsequent calls to get information about, update, or delete that tag.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italics):

URL https://api.kentik.com/api/v5/tags
Request GET /api/v5/tags 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

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A response body containing a tag array in JSON. The array contains an element for each of the company’s tags; each element contains information about that tag.

Note: For a description of the JSON name:value pairs in a tag object see Tag JSON.

 

 
 top  |  section

Tag Info

This GET method retrieves information about a single tag, identified by ID, in the list of a customer’s Kentik Detect tags.

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/tag/tag_id
Request GET /api/v5/tag/tag_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

Note: The “tag_id” value at the end of the path can be found in the “id” value in the tag object that makes up element of the array returned from Tag List.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON tag object containing information about the tag specified with tag_id.

Note: For a description of the JSON name:value pairs in a tag object see Tag JSON.

 

 
 top  |  section

Tag Create

This POST method adds a new tag to a customer’s Kentik Detect tags.

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/tag
Request POST /api/v5/tag 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

Creating a tag requires specifying the text of the tag itself (effectively the name of the tag) with the flow_tag parameter, and also specifying at least one additional tag attribute parameter that will be evaluated for a match with fields in the incoming flow (or with values derived from fields in the flow). The following parameters may be passed in a JSON object in the request body:

Parameter Type Description
flow_tag string Required: A name for the tag. When a match for any of the other tag parameters is found in the flow from a given device, this string will be added to the src_flow_tags and/or dst_flow_tags column in that device’s KDE main table.
device_name string A match results when the device_name associated with a device sending flow data contains this string.
device_type string A comma-delimited list of device types or regular expressions. A match results when any specified device type matches the device_type associated with a device sending flow data.
site string A comma-separated list of sites or regular expressions. A match results when any specified site matches the site associated with a device sending flow data.
interface_name string A match results when the name or description of an interface sending flow data contains this string.
addr string A range of IP addresses, expressed in CIDR notation (e.g. 38.12.34.0/24). A match results when this value corresponds to a range of IP addresses in incoming flow.
Note: This field can contain up to 249 IP/CIDR items in a comma-delimited list.
port string A port number, either source (SRC Port) or destination DST Port). A match results when this value appears within a port number in incoming flow.
tcp_flags string An integer number between 0 and 255 representing an 8-bit binary bit pattern corresponding to TCP flags. A match will result if the value in both the flow bit pattern and the bitmask is 1 at any of the eight places.
protocol string The protocol of traffic represented by a flow. The protocol of TCP is 6, and of UDP is 17. A match results when this value is the same as the protocol of the traffic represented by the flow.
asn string A comma-separated list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the last-hop router based on AS-PATH.
lasthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name represents the name corresponding to the last ASN in the path in the routing table for either the source (SRC IP) or destination (DST IP).
nexthop_asn string A comma-separated list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the next-hop router based on AS-PATH.
nexthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name corresponds to the AS name of the next hop router based on AS path.
nexthop string A comma-separated list of IPv4 and/or IPv6 CIDRs. If a CIDR grouping (IPv4 or IPv6) is specified, a match can be on any address within that grouping. If no CIDR grouping is specified a match requires an exact IP.
- CIDRs may be expressed in “short form” (e.g. 1::2/127).
bgp_aspath string A comma-separated list of numbers or regular expressions representing BGP AS path. A match results when this value is the same as the BGP AS-PATH in the route.
- Permitted characters []*:_^$.0123456789()+?,space-
- Example: “^3737 1212,_7801_,2906$” would look for any of those 3 combinations in the AS path.
bgp_community string A comma-separated list of numbers or regular expression representing BGP community (i.e. 2096:2212). A match results when this value is the same as the BGP community of the BGP route associated with incoming flow data.
- Permitted characters []*:_^$.0123456789()+?,space-
mac string A comma-separated list of MAC Addresses. Results in a match if this value matches source or destination Ethernet (L2) address.
country string A comma-separated list of two-character country codes. Results in a match if this value includes a two-letter country code associated with the source or destination IP of the flow.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON tag object containing information about the newly added tag. The elements included in the returned tag object depend on which of the optional tag field parameters are specified in the call.

Note: For a description of the JSON name:value pairs in a tag object see Tag JSON.

 

 
 top  |  section

Tag Update

This PUT method updates an existing tag, identified by ID, with new values for one or more of that tag’s fields.

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/tag/tag_id
Request PUT /api/v5/tag/tag_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

Note: The “tag_id” value at the end of the path can be found in the “id” value in the tag object that makes up element of the array returned from Tag List.

The parameters to be changed are passed into the call with a JSON tag object that contains only the fields (name:value pairs) that are to be updated. The following example shows the tag object that would be used to update the port that the tag tries to match:

{
  "tag": {
    "port": "700"
  }
}

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON tag object containing information about the newly updated tag.

Note: For a description of the JSON name:value pairs in a tag object see Tag JSON.

 

 
 top  |  section

Tag Delete

This DELETE method removes one tag, identified by ID, from a customer’s collection of Kentik Detect tags.

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/tag/tag_id
Request DELETE /api/v5/tag/tag_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

Note: The “tag_id” value at the end of the path can be found in the “id” value in the tag object that makes up element of the array returned from Tag List.

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.

 

 
 top

Custom Dimension API

Note: Users whose level is Member have access only to the GET methods of this API.

The Custom Dimension API enables programmatic management of your company’s custom dimensions in Kentik Detect. The methods available to manage custom dimensions are covered in the following topics:

Notes:
- For an overview explanation of custom dimensions and their associated populators, see Dimensions and Populators.
- To make calls to this API using cURL, see API Access Via cURL.

 

 
 top  |  section

Custom Dimension JSON

Calls to the Custom Dimension API each return an HTTP response body containing a customDimension object in JSON (or, in the case of the Custom Dimension List call, an array of such objects). The object is made up of the fields (name:value pairs) shown in the following example:

{
  "customDimension": {
    "id": 9,
    "display_name": "Mikes int column",
    "name": "c_mh_test",
    "type": "uint32",
    "populators": [
      {
        "id": 2600,
        "dimension_id": 9,
        "value": "1234",
        "direction": "src",
        "device_name": "My_device",
        "user": "6762",
        "created_date": "2016-08-24T11:27:04.452Z",
        "updated_date": "2016-08-24T11:27:04.452Z",
        "company_id": "1289"
      }
    ],
    "created_date": "2016-08-24T11:25:57.497Z",
    "updated_date": "2016-08-27T00:45:22.725Z",
    "company_id": "1289"
  }
}

The fields of each customDimension object contain information on an individual custom dimension 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 custom dimension (router or host).
name string The name of the custom dimension (used by system and in SQL):
- Must start with “c_”.
- Valid characters: alphanumeric, underscores.
- Length: min=1, max=20.
type string The type of the custom dimension.
- Valid values: “string” or “uint32”.
display_name string User-supplied name string for the custom dimension.
- Valid characters: alphanumeric, spaces, dashes, underscores.
- Length: min=2, max=30.
populators array of strings An array of the populators currently assigned to the custom dimension.
Note: for a description of populator fields, see Populator JSON.
created_date string Date-time of registration of the custom dimension in Kentik Detect creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
updated_date string Date-time of most-recent edit to the custom dimension, in UTC, e.g. 2015-01-27T01:39:17.186Z
company_id number The system-assigned ID of the customer.

Note: If a custom dimension is deleted, the name of that dimension cannot be reused for a period starting at the time of deletion and equal to the longest data retention period of any of your company’s Kentik Detect plans (see About Plans). For example, if your company has a plan that includes retention of the Fast dataseries on certain devices for one year, then if any custom dimension is deleted that dimension’s name cannot be reused for one year.

 

 
 top  |  section

Custom Dimension List

This GET method retrieves a list of a customer’s Kentik Detect custom dimensions. The list is a JSON array whose elements each correspond to an individual custom dimension.

Notes:
- The “id” value in the customDimension object for each custom dimension can be used in subsequent calls to get information about, update, or delete that custom dimension.
- 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/customdimensions
Request GET /api/v5/customdimensions 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

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A response body containing a custom dimension array in JSON. The array contains an element for each of the company’s custom dimensions; each element is a customDimension object containing information about one custom dimension.

Note: For a description of the JSON name:value pairs in a customDimension object, see Custom Dimension JSON.

 

 
 top  |  section

Custom Dimension Info

This GET method retrieves information about a single custom dimension, identified by ID, in the list of a customer’s Kentik Detect custom dimensions.

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/customdimension/dimension_id
Request GET /api/v5/customdimension/dimension_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

Note: The dimension_id value at the end of the path can be found in the id value in the customDimension object that makes up each element of the array returned from Custom Dimension List.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON customDimension object containing information about the custom dimension specified with dimension_id.

Note: For a description of the JSON name:value pairs in a custom dimension object see Custom Dimension JSON.

 

 
 top  |  section

Custom Dimension Create

This POST method adds a new custom dimension to a customer’s collection of custom dimensions.

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/customdimension
Request POST /api/v5/customdimension 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

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

JSON name Type Description
name string Required: The name of the custom dimension (used by system and in SQL).
- Must start with “c_”.
- Valid characters: alphanumeric, dashes, underscores.
- Length: min=1, max=20.
type string Required: The type of the custom dimension.
- Valid values: “string” or “uint32”.
display_name string Required: A name string for the custom dimension (used in portal for group-by dimensions and filters).
- Valid characters: alphanumeric, spaces, dashes, underscores.
- Length: min=2, max=30.

Note: If a custom dimension is deleted, the name of that dimension cannot be reused for a period starting at the time of deletion and equal to the longest data retention period of any of your company’s Kentik Detect plans. For example, if your company has a plan that includes retention of the Fast dataseries on certain devices for one year, then if any custom dimension is deleted that dimension’s name cannot be reused for one year.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON customDimension object containing information about the newly added custom dimension.

Note: For a description of the JSON name:value pairs in a customDimension object see Custom Dimension JSON.

 

 
 top  |  section

Custom Dimension Update

This PUT method updates system data about one custom dimension, identified by ID, in a customer’s collection of custom dimensions.

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/customdimension/dimension_id
Request PUT /api/v5/customdimension/dimension_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

Note: The “dimension_id” value at the end of the path can be found in the “id” value in the customDimension object that makes up each element of the array returned from Custom Dimension List.

The parameters to be changed are passed into the call with a JSON customDimension object that contains only the fields (name:value pairs) that are to be updated. The following example shows the customDimension object that would be used to update the custom dimension’s display name:

{
  "custom dimension": {
    "display_name": "The 4th dimension"
  }
}

Note: The only value that can be changed with a custom dimension update is the display name.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON customDimension object containing information about the newly updated custom dimension. The returned object will not include a populators array.

Note: For a description of the JSON name:value pairs in a customDimension object see Custom Dimension JSON.

 

 
 top  |  section

Custom Dimension Delete

This DELETE method removes one custom dimension, identified by ID, from a customer’s collection of custom dimensions.

Notes:
- If a custom dimension is deleted, the name of that dimension cannot be reused for a period starting at the time of deletion and equal to the longest data retention period of any of your company’s Kentik Detect plans. For example, if your company has a plan that includes retention of the Fast dataseries on certain devices for one year, then if any custom dimension is deleted that dimension’s name cannot be reused for one year.
- 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/customdimension/dimension_id
Request DELETE /api/v5/customdimension/dimension_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

Note: The “custom dimension_id” value at the end of the path can be found in the “id” value in the customDimension object that makes up each element of the array returned from Custom Dimension List.

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.

 

 
 top  |  section

Populator JSON

The Custom Dimensions API includes populator objects that determine when the KDE main table field (see KDE Tables) that corresponds to a custom dimension is populated for a given row in the table (see Dimensions and Populators). The populators assigned to a given custom dimension are found within the populators array of the customDimension object that is returned in an HTTP response body from a Custom Dimension List or Custom Dimension Info call. The populator object is made up of the fields (name:value pairs) shown in the following example:

{
  "populator": {
    "id": 2600,
    "dimension_id": 9,
    "value": "1234",
    "direction": "dst",
    "device_name": "my_device1",
    "interface_name": "a great interface",
    "addr": "192.168.2.1/32",
    "port": "800",
    "tcp_flags": "254",
    "protocol": "7",
    "asn": "1235",
    "nexthop_asn": "5437",
    "bgp_aspath": "1212",
    "bgp_community": "2096:2212",
    "user": "2345",
    "created_date": "2016-08-24T11:27:04.452Z",
    "updated_date": "2016-10-12T22:37:19.251Z",
    "company_id": "1289"
  }
}

Note: Depending on which fields are defined in a populator object, the returned object may not include all of the fields shown above.

The fields of each populator object contain information on an individual populator assigned to a given custom dimension. These fields are described in the following table:

JSON name Type Description Portal field
id number The system-assigned ID of the populator. Populator ID
dimension_id number Required: the ID of the custom dimension to which the populator is assigned. N.A.
value string Required: The value placed in the custom column when there’s a match with the ANDed populator parameters below.
• When custom dimension type is “string”:
- Valid characters: alphanumeric, spaces, dashes, underscores.
- Length: min=1, max=128.
• When the custom dimension’s type is “uint32”
- Valid values: min=0, max=4294967295.
Dimension value
direction string The direction (src or dst) of the flow fields in which to look for a match with the populator parameters below. Direction
device_name string A match results when the device_name associated with a device sending flow data contains this string. Device name
device_type string A comma-delimited list of device types or regular expressions. A match results when any specified device type matches the device_type associated with a device sending flow data. Device type
site string A comma-separated list of sites or regular expressions. A match results when any specified site matches the site associated with a device sending flow data. Site
interface_name string A match results when the name or description of an interface sending flow data contains this string. Interface name/description
addr string A range of IP addresses, expressed in CIDR notation (e.g. 38.12.34.0/24). A match results when this value corresponds to a range of IP addresses in incoming flow. IP address
port string A port number, either source (SRC Port) or destination DST Port). A match results when this value appears within a port number in incoming flow. Port
tcp_flags string An integer number between 0 and 255 representing an 8-bit binary bit pattern corresponding to TCP flags. A match will result if the value in both the flow bit pattern and the bitmask is 1 at any of the eight places. TCP flag
protocol string The protocol of traffic represented by a flow. The protocol of TCP is 6, and of UDP is 17. A match results when this value is the same as the protocol of the traffic represented by the flow. Protocol name/number
asn string A comma-separated list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the last-hop router based on AS-PATH. Last-hop (origin) ASN
lasthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name represents the name corresponding to the last ASN in the path in the routing table for either the source (SRC IP) or destination (DST IP). Last-hop (origin) AS Name
nexthop_asn string A comma-separated list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the next-hop router based on AS-PATH. Next-hop ASN
nexthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name corresponds to the AS name of the next hop router based on AS path. Next-hop AS Name
nexthop string A comma-separated list of IPv4 and/or IPv6 CIDRs. If a CIDR grouping (IPv4 or IPv6) is specified, a match can be on any address within that grouping. If no CIDR grouping is specified a match requires an exact IP.
- CIDRs may be expressed in “short form” (e.g. 1::2/127).
Next-hop IP
bgp_aspath string A comma-separated list of numbers or regular expressions representing BGP AS path. A match results when this value is the same as the BGP AS-PATH in the route.
- Permitted characters []*:_^$.0123456789()+?,space-
- Example: “^3737 1212,_7801_,2906$” would look for any of those 3 combinations in the AS path.
BGP AS path
bgp_community string A comma-separated list of numbers or regular expression representing BGP community (i.e. 2096:2212). A match results when this value is the same as the BGP community of the BGP route associated with incoming flow data.
- Permitted characters []*:_^$.0123456789()+?,space-
BGP community
mac string A comma-separated list of MAC Addresses. Results in a match if this value matches source or destination Ethernet (L2) address. MAC Address
country string A comma-separated list of two-character country codes. Results in a match if this value includes a two-letter country code associated with the source or destination IP of the flow. Country
user number The system-assigned ID of the user who created the populator. N.A.
created_date string Date-time of populator creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z N.A.
updated_date string Date-time of most-recent populator edit, in UTC, e.g. 2015-01-27T01:39:17.186Z N.A.
company_id number The system-assigned ID of the customer. N.A.

Notes:
- The Portal field column indicates the name of the corresponding setting on the Add Populator or Edit Populator page in the portal (see Add or Edit Populators).
- Commas are valid in field values only as delimiters in comma-delimited lists.
- For further information about validations applied to values specified for the above fields, see Populator Field Validation.

 

 
 top  |  section

Populator Create

This POST method adds a new populator to a customer’s Kentik Detect populators.

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 api.kentik.com/api/v5/customdimension/dimension_id/populator
Request POST /api/v5/customdimension/dimension_id/populator 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: The dimension_id in the above URL is the ID of the custom dimension to which the populator is to be assigned. This ID can be found in the id value in the customDimension object that makes up each element of the array returned from Custom Dimension List.

The following parameters are passed in a JSON object in the request body. At least one of the non-required parameters must be specified for the populator to work:

JSON name Type Description
dimension_id number Required: the ID of the custom dimension to which the populator is assigned.
value string Required: The value placed in the custom column when there’s a match with the ANDed populator parameters below.
• When custom dimension type is “string”:
- Valid characters: alphanumeric, spaces, dashes, underscores.
- Length: min=1, max=128.
• When the custom dimension’s type is “uint32”
- Valid values: min=0, max=4294967295.
direction string Required: The direction (src or dst) of the flow fields in which to look for a match with the populator parameters below.
device_name string A match results when the device_name associated with a device sending flow data contains this string.
interface_name string A match results when the name or description of an interface sending flow data contains this string.
addr string A range of IP addresses, expressed in CIDR notation (e.g. 38.12.34.0/24). A match results when this value corresponds to a range of IP addresses in incoming flow.
port string A port number, either source (SRC Port) or destination DST Port). A match results when this value appears within a port number in incoming flow.
tcp_flags string An integer number between 0 and 255 representing an 8-bit binary bit pattern corresponding to TCP flags. A match will result if the value in both the flow bit pattern and the bitmask is 1 at any of the eight places.
protocol string The protocol of traffic represented by a flow. The protocol of TCP is 6, and of UDP is 17. A match results when this value is the same as the protocol of the traffic represented by the flow.
asn string A comma-separated list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the last-hop router based on AS-PATH. Both 16- and 32-bit ASNs are valid.
lasthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name represents the name corresponding to the last ASN in the path in the routing table for either the source (SRC IP) or destination (DST IP).
nexthop_asn string A comma-separated list of ASNs (16- or 32-bit). A match results when any specified ASN is the same as the ASN of the next-hop router based on AS-PATH. Both 16- and 32-bit ASNs are valid.
nexthop_as_name string A comma-separated list of AS names or regular expressions. A match results when any specified AS name corresponds to the AS name of the next hop router based on AS path.
nexthop string A comma-separated list of IPv4 and/or IPv6 CIDRs. If a CIDR grouping (IPv4 or IPv6) is specified, a match can be on any address within that grouping. If no CIDR grouping is specified a match requires an exact IP.
- CIDRs may be expressed in “short form” (e.g. 1::2/127).
bgp_aspath string A comma-separated list of numbers or regular expressions representing BGP AS path. A match results when this value is the same as the BGP AS-PATH in the route.
- Permitted characters []*:_^$.0123456789()+?,space-
- Example: “^3737 1212,_7801_,2906$” would look for any of those 3 combinations in the AS path.
bgp_community string A comma-separated list of numbers or regular expression representing BGP community (i.e. 2096:2212). A match results when this value is the same as the BGP community of the BGP route associated with incoming flow data.
- Permitted characters []*:_^$.0123456789()+?,space-
mac string A comma-separated list of MAC Addresses. Results in a match if this value matches source or destination Ethernet (L2) address.
country string A comma-separated list of two-character country codes. Results in a match if this value includes a two-letter country code associated with the source or destination IP of the flow.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON populator object containing information about the specified parameters of the newly added populator.

Note: For a description of the JSON name:value pairs in a populator object see Populator JSON.

 

 
 top  |  section

Populator Update

This PUT method updates system data about one populator, identified by ID, in a customer’s list of existing Kentik Detect populators.

Notes:
- To identify (and find the ID of) the populator that you wish to update, use the Custom Dimension Info call to see a list of all populators assigned to a given custom dimension.
- 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 api.kentik.com/api/v5/customdimension/dimension_id/populator/populator_id
Request PUT /api/v5/customdimension/dimension_id/populator/populator_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

Note: The dimension_id in the above URL is the ID of the custom dimension to which the populator is to be assigned. This ID can be found in the id value in the customDimension object that makes up each element of the array returned from Custom Dimension List.

The parameters to be changed are passed into the call with a JSON populator object that contains only the fields (name:value pairs) that are to be updated. The following example shows the populator object that would be used to update the port that the populator should look to match:

{
  "populator": {
    "port": "700"
  }
}

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON populator object containing information about the specified parameters of the newly updated populator.

Note: For a description of the JSON name:value pairs in a populator object see Populator JSON.

 

 
 top  |  section

Populator Delete

This DELETE method removes one populator, identified by ID, from a customer’s collection of Kentik Detect populators.

Notes:
- When a populator for a custom dimension is deleted, the KDE main table rows that were previously matched by that populator will no longer be filterable by the populator’s value.
- To identify (and find the ID of) the populator that you wish to delete, use the Custom Dimension Info call to see a list of all populators assigned to a given custom dimension.
- 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 api.kentik.com/api/v5/customdimension/dimension_id/populator/populator_id
Request DELETE /api/v5/populator/populator_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

Note: The dimension_id in the above URL is the ID of the custom dimension to which the populator is to be assigned. This ID can be found in the id value in the customDimension object that makes up each element of the array returned from Custom Dimension List.

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.

 

 
 top

Saved Filter API

Note: Users whose level is Member have access only to the GET methods of this API.

The Saved Filter API enables programmatic management of the custom filters saved in Kentik Detect by your organization’s users (see About Company Filters). The methods available to manage custom filters are covered in the following topics:

Notes:
-
For information on adding and managing saved filters via the Kentik Detect portal, see About Company Filters.
- To make calls to this API using cURL, see API Access Via cURL.

 

 
 top  |  section

Saved Filter JSON

Calls to the Saved Filter API each return an HTTP response body containing a “saved filter” object in JSON (or, in the case of the Saved Filter List call, an array of such objects). In the following example, the array returned from a Saved Filter List call contains two such objects:

  • The first object, with ID of 001 was created with the Saved Filter API.
  • The object with ID of 002 was saved from the Kentik Detect portal. Saved filters originating in the portal include some additional fields, used internally, that are not included in API-created filters.

[
  {
    "cdate": "2016-10-26T06:00:08.574Z",
    "company_id": "1223",
    "edate": "2016-10-26T06:00:08.574Z",
    "filter_description": "zzz",
    "filter_level": "company",
    "filter_name": "zzz",
    "filters": {
      "connector": "any",
      "custom": true,
      "filterGroups": [
        {
          "connector": "All",
          "filters": [
            {
              "filterField": "dst_as",
              "filterValue": "17",
              "operator": "="
            },
            {
              "filterField": "src_geo",
              "filterValue": "us",
              "operator": "="
            }
          ],
          "not": true
        }
      ]
    },
    "id": 001
  },
  {
    "cdate": "2016-12-09T21:03:12.738Z",
    "company_id": "1223",
    "edate": "2016-12-09T21:03:12.738Z",
    "filter_description": "Source IP address is within RFC1918 address space: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16",
    "filter_level": "company",
    "filter_name": "RFC1918_SRC Copy 0.7142274979608774",
    "filters": {
      "connector": "All",
      "custom": false,
      "filterGroups": [
        {
          "connector": "Any",
          "filterString": "( ( (inet_src_addr ILIKE '10.0.0.0/8') ) OR ( (inet_src_addr ILIKE '172.16.0.0/12') ) OR ( (inet_src_addr ILIKE '192.168.0.0/16') )) ",
          "filters": [
            {
              "filterField": "inet_src_addr",
              "filterValue": "10.0.0.0/8",
              "id": "c115",
              "operator": "ILIKE"
            },
            {
              "filterField": "inet_src_addr",
              "filterValue": "192.168.0.0/16",
              "id": "c117",
              "operator": "ILIKE"
            }
          ],
          "id": "c118",
          "metric": null,
          "not": false
        }
      ],
      "filterString": "(( ( (inet_src_addr ILIKE '10.0.0.0/8') ) OR ( (inet_src_addr ILIKE '172.16.0.0/12') ) OR ( (inet_src_addr ILIKE '192.168.0.0/16') )))"
    },
    "id": 002
  }
]

Note: Depending on which filter groups and individual filters are defined in a saved filter, the returned JSON may not include all of the fields shown above.

Each saved filter object contains information on an individual custom filter saved by a user in your organization. The structures that make up the object are described in the following topics.

 

Saved Filter Object

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

JSON name Type Description
cdate string The system-assigned date-time of filter creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
company_id number The system-assigned ID of the customer.
edate string The system-assigned date-time of most-recent modification, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z
filter_description string An optional description of the saved filter.
filter_level string The scope across which the shared filter is available: user (personal only), company (organization-wide), or global (Kentik-provided preset).
Note: User and global saved filters are not yet implemented in the API.
filter_name string A unique name for the saved filter.
filters object An object representing a set of filter groups that make up a saved filter.
See Filters Object.
id number The system-assigned ID of the saved filter.

 

Filters Object

A set of one or more filter groups, each made up of the name:value pairs shown in the following table:

JSON name Type Description
connector string Sets the conjunctive operator (“and” or “or”) that will join all filter groups in this filter set.
custom boolean Reserved for internal use.
filterGroups array An array of filter groups that make up this saved filter. See FilterGroups Array.
filterString string Reserved for internal use.
Note: Present only if the filter was saved from the Kentik Detect portal.

 

FilterGroups Array

An array of filter groups, each made up of the name:value pairs shown in the following table:

JSON name Type Description
connector string Sets the conjunctive operator (“and” or “or”) that will join all filters in this filter group.
filterString string Reserved for internal use.
Note: Present only if the filter was saved from the Kentik Detect portal.
filters array An array of filters that make up this filter group. See Filters Array.
id string The system-assigned unique ID identifying an individual filter group.
Note: Present only if the filter was saved from the Kentik Detect portal.
metric string Reserved for internal use.
not boolean Sets whether traffic matching the filter group is included (false) or excluded (true).

 

Filters Array

An array of individual filters, each made up of the name:value pairs shown in the following table:

JSON name Type Description
filterField string The dimension to filter on.
- Valid values: src_geo, src_geo_region, src_geo_city, src_as, src_flow_tags, l4_src_port, vlan_in, src_eth_mac, inet_src_addr, input_port, i_input_snmp_alias, i_input_interface_description, ipv4_src_route_prefix, src_route_length, src_bgp_aspath, src_bgp_community, ipv4_src_next_hop, src_nexthop_as, src_second_asn, src_third_asn, dst_geo, dst_geo_region, dst_geo_city, dst_as, dst_flow_tags, l4_dst_port, vlan_out, dst_eth_mac, inet_dst_addr, output_port, i_output_snmp_alias, i_output_interface_description, ipv4_dst_route_prefix, dst_route_length, dst_bgp_aspath, dst_bgp_community, ipv4_dst_next_hop, dst_nexthop_as, dst_second_asn, dst_third_asn, tcp_flags, tcp_flags_raw, protocol, i_device_name, both_pkts, tcp_retransmit, or tos
id string The system-assigned unique ID identifying an individual filter.
Note: Present only if the filter was saved from the Kentik Detect portal.
filterValue string The filterField value to match.
operator string The operator to apply in the filter.
- Valid value: “=“,”<>“,”ILIKE”,”NOT ILIKE”,”�”,”!�”,”>“,”<“,”&”

Note: For further information about how the settings represented by the name:value pairs above correspond to custom filters saved via the Kentik Detect portal, see Filter Groups Interface.

 

 
 top  |  section

Saved Filter List

This GET method retrieves a list of the custom filters that have been saved by users in your organization. The list is a JSON array whose elements each correspond to an individual custom filter.

Notes:
- To try this call, go to the V5 API Tester.
-
The “id” value in the structure corresponding to each individual custom filter can be used in subsequent calls to get information about, update, or delete that custom filter.

HTTP Request

The following table shows the path and HTTP request for this call (placeholders in italics):

URL https://api.kentik.com/api/v5/saved-filters/custom
Request GET /api/v5/saved-filters/custom 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

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 custom filters; each element contains information about that custom filter.

Note: For a description of the JSON name:value pairs in an individual element of the array see Saved Filter JSON.

 

 
 top  |  section

Saved Filter Info

This GET method retrieves information about a single custom filter, identified by ID, in the collection of custom filters saved to Kentik Detect by users in your organization.

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/saved-filter/custom/filter_id
Request GET /api/v5/saved-filter/custom/filter_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

Note: The “filter_id” value at the end of the path can be found in the “id” value of each of the elements of the array returned from Saved Filter List.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON saved filter object containing information about the custom filter specified with filter_id.

Note: For a description of the JSON name:value pairs in the returned saved filter object see Saved Filter JSON.

 

 
 top  |  section

Saved Filter Create

This POST method adds a new custom filter to a customer’s collection of saved filters.

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/saved-filter/custom
Request POST /api/v5/saved-filter/custom 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

The following table lists the fields whose values are defined in the saved filter JSON that is passed in the request body:

Parameter Structure Type Description
filter_name Saved Filter Object string Required: A unique name for the custom filter.
filter_description Saved Filter Object string An optional description for the custom filter.
connector Filters Object string Required: The conjunctive operator (“and” or “or”) that will join all filter groups in this filter set.
connector FilterGroups Array string Required: The conjunctive operator (“and” or “or”) that will join all filters in this filter group.
not FilterGroups Array boolean Required: Sets whether traffic matching the filter group is included (false) or excluded (true).
filterField Filters Array string The dimension to filter on.
operator Filters Array string The operator to apply in the filter.
filterValue Filters Array string The filterField value to match.

Note: For more information on a parameter in the table above, refer to the topic on the structure to which the parameter belongs.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON saved filter object containing information about the newly added custom filter.

Note: For a description of the JSON name:value pairs in the returned filter object see Saved Filter JSON.

 

 
 top  |  section

Saved Filter Update

This PUT method updates a saved custom filter, identified by ID, with new values for one or more of that filter’s fields.

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/saved-filter/custom/filter_id
Request PUT /api/v5/saved-filter/custom/filter_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

Note: The “filter_id” value at the end of the path can be found in the “id” value of each of the elements of the array returned from Saved Filter List.

When updating a saved filter, the saved filter object passed in with the request body includes all of the fields shown in Saved Filter Create — including the fields that you don’t wish to change — and the values specified in that object become the values of the updated filter.

HTTP Response

A successful response to this call includes the following elements:

  • The response headers.
  • The HTTP response code.
  • A single JSON saved filter object containing information about the newly updated custom filter.

Note: For a description of the JSON name:value pairs in the returned filter object see Saved Filter JSON.

 

 
 top  |  section

Saved Filter Delete

This DELETE method removes one custom filter, identified by ID, from a customer’s collection of saved custom filters.

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/saved-filter/custom/filter_id
Request DELETE /api/v5/saved-filter/custom/filter_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

Note: The “filter_id” value at the end of the path can be found in the “id” value of each of the elements of the array returned from Saved Filter List.

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.