Customization APIs

The "customization" APIs of the Kentik V5 Admin APIs are covered in the following topics:

• About Customization APIs
• Tag API
• Custom Dimension API
• Batch API
• Saved Filter API
• Custom Application API

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.

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.

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:

• Tag JSON
• Tag List
• Tag Info
• Tag Create
• Tag Update
• Tag Delete

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.

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:

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.

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

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.

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

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.

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

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:

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.

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

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.

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

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.

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:

• Custom Dimension JSON
• Custom Dimension List
• Custom Dimension Info
• Custom Dimension Create
• Custom Dimension Update
• Custom Dimension Delete
• Populator JSON
• Populator Create
• Populator Update
• Populator Delete

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.

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:

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.

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

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.

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

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.

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

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:

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.

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

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.

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

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.

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:

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.

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

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:

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.

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

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.

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

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.

The Batch API is covered in the following topics:

• About the Batch API
• Using the Batch API
• Batch Request
• Batch Response
• Batch Status Request
• Batch Status Response

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.

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.

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.

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.

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.

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.

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

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

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.

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"
    }
  ]
}

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:

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.

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.

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.

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

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.

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.

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.

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

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:

• Saved Filter JSON
• Saved Filter List
• Saved Filter Info
• Saved Filter Create
• Saved Filter Update
• Saved Filter Delete

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.

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.

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

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

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

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

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.

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

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.

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

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.

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

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:

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.

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

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.

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

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.

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

• US V5 API tester
• EU V5 API tester

More information is coming soon.