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

 

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

 

Tag API

Notes:
- This API is deprecated in favor of the v6 Flow Tag APIs.
- 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. The methods available to manage tags are covered in the following topics:

Notes:
-
For information on adding and managing tags via the Kentik 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
vlans string A comma-separated list of VLAN IDs. Results in a match if this value includes a VLAN ID associated with the source or destination IP of the flow. VLAN(s)
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 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

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

Notes:
- 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.
- 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 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 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

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.

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.
VLAN(s) string A comma-separated list of VLAN IDs. Results in a match if this value includes a VLAN ID 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

Notes:
- 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.
- 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 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 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

Notes:
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.
- 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.
 

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

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

Notes:
- 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.
- 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 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

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:

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

Notes:
- 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.
- 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 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 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

Notes:
- 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.
- 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.
 
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 (source, destination, or either) 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
vlans string A comma-separated list of VLAN IDs. Results in a match if this value includes a VLAN ID associated with the source or destination IP of the flow. VLAN(s)
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 in the Populator Settings Dialog in the portal.
- 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 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

Notes:
- 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.
- 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. 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 (source, destination, or either) 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.
vlans string A comma-separated list of VLAN IDs. Results in a match if this value includes a VLAN ID 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 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

Notes:
- 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.
- 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 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 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

Notes:
- 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.
- 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.
 

Batch API

Note: Users whose level is Member do not have access to this API.

The Batch API is covered in the following topics:

Notes:
- We’ve developed a Python integration enabling you to make calls to this API; see our Hypertagging API project in GitHub.
- To make calls to this API using cURL, see API Access Via cURL.
-
For information on adding and managing tags via the Kentik portal, see Flow Tags.
-
For information on adding and managing custom dimensions via the portal, see Dimensions and Populators.

 
top  |  section

About the Batch API

The Batch API enables programmatic management of your company's flow tags (see About Flow Tags) and the populators of your custom dimensions (see Dimensions and Populators) in Kentik. The batch method can be used for any of the following tasks:

  • Add a batch of tags or populators.
  • Make changes to existing tags or populators.
  • Remove existing tags or populators.
  • Get status updates on the progress of batch operations.

Note: The Batch API supplements rather than replaces our existing APIs for management of flow tags and custom dimension populators. See Tag API and Custom Dimension API.

 
top  |  section

Using the Batch API

Unlike the other Kentik V5 APIs, which use different methods to create and update objects and settings, the Batch API uses a single POST method (see Batch Request) to create, update, and delete; the action of an individual call depends on the value of its parameters. The Batch API also includes a separate GET method (see Batch Status Request) to return status information.

For the create/update/delete method, multiple requests — each referred to as a "part" — are supported within one batch operation. Each individual request/part is limited to a payload of 4MB. A multi-part process involves the following steps:

  • HTTP POST the Request JSON for the first part to the appropriate endpoint (depends on tags vs. populators). Specify the complete parameter as false to indicate that additional parts will be coming.
  • An HTTP response is returned with status 202 (Accepted) to acknowledge receipt (the JSON passed with the request will be queued for offline processing). The response also includes a GUID (Globally Unique Identifier), which is used to:
    - Include in subsequent requests to identify them as being part of the same overall batch operation.
    - Include in a Batch Status Request to get the status of the batch operation.
  • POST the Request JSON for additional parts, each identified with the same GUID. In the final request of the series, specify the complete parameter (see Batch Request JSON Fields) as true.

Note: The creation and/or updating of flow tags or custom dimension populators begins when the first request is received, but the deletion of unneeded tags or populators is not executed until all parts of the batch operation are received.

 
top  |  section

Batch Request

This POST method is used to manage (create, update, or delete) one or the other of the following:

  • All of your flow tags.
  • The populators for one individual custom dimension.

Criteria and Value

Managing tags or populators with the Batch Request method requires specifying the following:

  • Criteria: An array of one or more criterion against which each flow record will be evaluated for a match at ingest. Each element of the array passes the following:
    - Direction: The direction (source, destination, or either) of the direction-specific fields in the flow record (e.g. SRC IP, SRC port, etc.) that will be evaluated for a match.
    - Field: The name of the field to evaluate, and the value to look for in that field (e.g. "addr": ["1.2.3.4"] means that the addr field of the flow record should be evaluated for a match on the IP address "1.2.3.4."
  • Value:
    - For Tags: The text of the tag itself (effectively the name of the tag). If the criteria are matched, this value will be entered into either the src_flow_tags or dst_flow_tags column (depending on the direction of flow) of the ingested flow record (see Populating Tag Columns).
    - For Populators: The text that will be inserted into the custom dimension field (custom column) of each ingested flow record for which the criteria are matched (see Dimensions and Populators).

The JSON is structured so that multiple sets of criteria may be specified for each value, with each unique combination of criteria and value defining a single tag or populator (depending on endpoint).

Note: A set of criteria used in the definition of one value may also be used in the definition of any other values, resulting in multiple tags/populators that match on the same criteria:
- For tags, the flow record field corresponding to the direction (src_flow_tags or dst_flow_tags) will be populated with the values (delimited tag names) associated with all matching criteria.
- For populators, one of the values associated with matching criteria will be randomly selected for inclusion in the corresponding custom dimension field.

Upserts and Deletes

The way that the Batch API uses the criteria and value parameters described above depends on the context, which determines the action taken on the flow tag:

  • Upserts: An array of information used for update or insert operations:
    - Update: If the value of a criterion has already been specified for this tag, change it to the provided value.
    - Insert: If the value of a criterion has not already been specified for this tag, add the criterion and set it to the provided value.
    Note: The user need not know in advance if a given criterion has already been specified for this tag.
  • Deletes: An array of information used for delete operations in which each provided value parameter will result in the deletion of the corresponding tag or populator.
    Note: Deletions do not require a criteria parameter.

Note: The API has been designed to allow updating without requiring you to retain and provide the ID of each tag or populator that you wish to update. One consequence of this design is that in some cases an update operation may result in a change of ID.

Batch Request Paths

The path to use for a batch request depends on whether you are managing flow tags or populators:

  • Flow Tags: The following table shows the path and HTTP request for a tag-related request (placeholders in italic):

URL https://api.kentik.com/api/v5/batch/tags
Request POST /api/v5/batch/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
  • Populators: The following table shows the path and HTTP request for a populator-related request (placeholders in italic):

URL https://api.kentik.com/api/v5/batch/customdimensions/dimension_name/populators
Request POST /api/v5/batch/customdimensions/dimension_name/populators 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: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URLs above.

Sample Batch Request JSON

The example below shows the structure of request JSON that would be passed in the body of a single-part request to the Custom Dimension endpoint. The actions resulting from the parameters specified in this structure would be to:

  • Create or update (depending on whether they already exist) three populators whose value is (or will be, if they don't already exist) "service_abc" and whose direction and IP address are specified with the objects of the criteria array.
  • Delete the two populators whose value is specified with the objects of the deletes array.

{
  "replace_all": false,
  "complete": true,
  "upserts": [
    {
      "value": "service_abc",
      "criteria": [
        {
          "direction": "dst",
          "addr": ["91.221.37.160"]
        },
        {
          "direction": "src",
          "addr": ["94.74.74.192"]
        },
        {
          "direction": "dst",
          "addr": ["1.2.3.4"]
        }
      ]
    }
  ],
  "deletes": [
    {
      "value": "324234"
    },
    {
      "value": "test4"
    }
  ]
}

Batch Request JSON Fields

The parameters that may be passed in a JSON object in the request body fall into one of the following categories:

  • Batch-related parameters: Settings and structures for batch operations. See table below.
  • Match fields: One or the other of the following, which may be included in the objects of the criteria array:
    - Tag-related parameters: See the table of parameters in Tag Create.
    - Populator-related parameters: See the table of parameters in Populator Create.

The following batch-related parameters may be passed in the request body:

Parameter Type Description
replace_all Boolean Required:
- If false, all tags or populators that are not included in the upserts array will be left unchanged.
- If true, all tags or populators that are not included in the upserts array will be deleted.
complete Boolean Required:
- If false, this is a multi-part operation and this is not the last part (additional parts will be sent in subsequent requests).
- If true, this is the last part of the operation (which may also be the only part).
upserts array An array of objects that each contain a value (the name of one or more tags or populators) and a criteria array in which each element represents a tag or populator (depending on endpoint).
upserts.value string Required if there are upserts:
- For tags, the name of the tag.
- For populators, the populator's "value" property.
upserts.criteria string An array of objects that each contain the information needed to update or insert match criteria for one tag or populator.
upserts.criteria.direction string The direction (src, dst, or either) of the direction-specific fields in the flow record (e.g. SRC IP, SRC port, etc.) that will be evaluated for a match.
Note: The default for populators is “either.” For tags this parameter is ignored.
deletes array An array of objects that each contain the information needed to identify items for deletion. All items (tags or populators, depending on endpoint) matching one of the values specified in the array will be deleted.
deletes.value string Required if there are deletes:
- For tags, the name of the tag.
- For populators, the populator's "value" property.

 
top  |  section

Batch Response

A successful response to a batch request includes the following elements:

  • The response headers.
  • The HTTP response code 202 (accepted).
  • A JSON structure containing information about the status of the operation identified in the Batch Status Request.

Batch Response JSON

The following code shows the JSON returned in the batch response:

{
  "message": "Successfully stored request. Batch queued for processing.",
  "guid": "batch_operation_guid"
}

The GUID is used to:

  • Include in subsequent batches to identify them as being part of the same overall batch operation.
  • Include in a Batch Status Request to get the status of a batch operation.
 
top  |  section

Batch Status Request

This GET method enables you to return the status of a batch operation that was initiated with a Batch Request. The operation for which to return status information is identified by the GUID returned in the original batch request, which is included in the URL of the status request as shown in Batch Status HTTP Request.

Batch Status HTTP Request

The HTTP request for a batch status request is as shown in the following table:

URL https://api.kentik.com/api/v5/batch/batch_operation_guid/status
Request GET /api/v5/batch/batch_operation_guid/status 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: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

 
top  |  section

Batch Status Response

A successful response to a batch status request includes the following elements:

  • The response headers.
  • The HTTP response code 200 (OK).
  • A JSON structure containing information about the status of the operation identified in the Batch Status Request.

Sample Batch Status Response JSON

Calls to the Batch Status endpoint each return an HTTP response body containing JSON. The object is made up of the fields (name:value pairs) shown in the following example:

{
  "custom_dimension": {
    "id": 98,
    "name": "MY_FAVE_DIM"
  },
  "guid": "kentik_assigned_batch_id",
  "is_multipart": false,
  "is_pending": false,
  "is_complete": true,
  "number_of_parts": 1,
  "user": {
    "id": 2233,
    "email": "username@domain.com"
  },
  "upserts": {
    "total": 9955,
    "applied": 9898,
    "invalid": 0,
    "unchanged": 0,
    "over_limit": 57
  },
  "deletes": {
    "total": 0,
    "applied": 0,
    "unchanged": 0,
    "invalid": 0
  },
  "replace_all": {
    "requested": true,
    "deletes_performed": 0,
    "successful": true
  },
  "batch_date": "2018-09-25T21:41:18.88816Z"
}

Note: The custom_dimension object shown above is not included when the batch operation whose status has been requested is for tags rather than for the populators of a custom dimension.

Batch Status Response JSON Fields

The table below describes the elements of the JSON returned with the status response.

JSON name Type Description
custom_dimension object An object containing ID and name information identifying the custom dimension whose populators are being managed by this batch operation.
Note: Included only when the batch operation is for a custom dimension.
custom_dimension.id number The unique ID of the custom dimension (Kentik assigned).
custom_dimension.name string The name specified when the custom dimension was created (see Dimension General Properties).
Guid string A unique identifier for this batch operation. Used for additional batch requests (if the batch operation is multipart) and batch status requests related to the operation.
Is_multipart Boolean Indicates whether this batch operation is made up of multiple batches.
Is_complete Boolean - If true, all batches in the batch operation have been received and processed.
- If false, remaining batches in the operation have not yet been received or processed.
Number_of_parts number The total number of batches received so far in the batch operation.
User object Container for information about the user who initiated the batch operation.
User.id number The unique Kentik ID of the user.
User.email string The email address associated with the user.
Upserts object Container for information about upserts processed so far in this batch operation.
Upserts.total number The sum of the remaining four parameters in the upserts object.
Upserts.applied number The number of values so far that have been applied.
Upserts.invalid number The number of values so far that were determined to be invalid.
Upserts.unchanged number The number of values so far that resulted in no change to an existing value.
Upserts.over_limit number The number of values so far that were ignored because updating or inserting them would result in excess populators (over contractual limits).
Deletes object Container for information about deletes processed so far in this batch operation.
Deletes.total number The sum of the remaining four parameters in the deletes object.
Deletes.applied number The number of values so far that have been deleted.
Deletes.unchanged number The number of values so far that resulted in no deletion.
Deletes.invalid number The number of values so far for which the deletion request was determined to be invalid.
Replace_all object Container for information about changes made so far in this batch operation due to the replace_all setting in the batch operation request.
Replace_all.requested Boolean Indicates whether replace_all was or was not requested.
Replace_all.deletes_performed number The number of values deleted because they were not included in the request.
Replace_all.successful Boolean True unless an issue has been encountered that would prevent deletion of any values that would otherwise be deleted.
Batch_date string The date-time at which the batch request with this GUID was initially received by the server.

 

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 by your organization’s users (see Company Saved 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 portal, see Saved 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 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 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 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 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 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 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

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

Notes:
- 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.
- 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 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

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

Notes:
- 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.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

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

Notes:
- 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.
- 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.
 

Custom Application API

The Custom Application API enables programmatic management of your company's custom applications (see About Applications). A tester for the methods available to manage custom applications is available at one of the following URLs (choose based on the region in which your organization is registered with Kentik):

More information is coming soon.

© 2014- Kentik
In this article:
×