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.
- For assistance using any API version please contact support@kentik.com.

The Kentik V5 Admin APIs offer "customization" APIs for programmatically managing settings under "Customize" in the Admin section of the Kentik portal. Available APIs include:

• Custom Dimensions: Managed via the Custom Dimension API, mirroring the Custom Dimensions portal settings.
• Saved Filters: Managed via the Saved Filter API, mirroring the Saved Filters portal settings.
• Flow Tags: Managed via the Tag API, mirroring the Flow Tags portal settings.

Note: Interface Classification and Network Classification are not supported via APIs.

The Tag API allows programmatic management of your organization’s tags in Kentik. The methods for managing tags are detailed 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.
- The V5 API tester was discontinued in January 2025.

Calls to the Tag API return an HTTP response with a JSON "tag" object, or an array of such objects for the Tag List call. The object contains fields as 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: The returned object may not include all fields, depending on which fields are defined.

Each tag object contains fields with information about an individual tag registered with your organization. These fields are described in the following table:

Notes:
- The Portal field column shows the corresponding setting name on the Add Tag or Edit Tag page in the portal (see Add or Edit Tags).
- Commas are only valid as delimiters in comma-delimited lists within field values.
- For more details on validations for the above field values, see Tag Field Validation.

The Tag List GET method retrieves a list of your Kentik tags as a JSON array, with each element representing an individual tag.

Note: The "id" value in a tag’s structure can be used in subsequent calls to retrieve, 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 from the Tag List method includes the following elements:

• Response headers
• HTTP response code
• A response body with a JSON tag array with an element containing information for each of your tags.

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

The Tag Info GET method fetches details of a specific tag by ID from your list of Kentik tags.

HTTP Request

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

Notes:
- The "tag_id" in the path corresponds to the "id" value in each tag object from the Tag List array.
- 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 from the Tag Info method includes the following elements:

• Response headers
• HTTP response code
• A single JSON tag object with details about a tag specified by tag_id.

Note: For details on the JSON name/value pairs in a tag object, see Tag JSON.

The Tag Create POST method adds a new tag to your Kentik tags.

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.

To create a tag, specify the tag name using the flow_tag parameter and at least one additional tag attribute parameter for matching with incoming flow fields. The following parameters can be included in a JSON object in the request body:

HTTP Response

A successful response from the Tag Create method includes the following elements:

• Response headers
• HTTP response code
• A JSON tag object detailing the newly-added tag, with elements based on specified optional tag fields.

Note: For details on the JSON name/value pairs in a tag object, see Tag JSON.

The Tag Update PUT method modifies an existing tag, identified by ID, with new values for one or more fields.

HTTP Request

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

Notes:
- The "tag_id" in the path corresponds to the "id" value in each tag object from the Tag List array.
- If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

Parameters to be updated are included in a JSON tag object with only the fields to be changed. The following example shows an update to the port field:

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

HTTP Response

A successful response from the Tag Update method includes the following elements:

• Response headers
• HTTP response code
• A single JSON tag object with details about the newly-updated tag.

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

The Tag Delete method removes a specific tag, identified by its ID, from your collection of Kentik tags.

HTTP Request

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

Notes:
- The "tag_id" in the path corresponds to the "id" value in each tag object from the Tag List array.
- 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 from the Tag Delete method includes the following elements:

• Response headers
• HTTP response code 204 (no content)

The Custom Dimension API allows for programmatic management of your organization's custom dimensions in Kentik. The available methods 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 return an HTTP response body with a JSON customDimension object, or an array of such objects for the Custom Dimension List call. The object includes fields as 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”
  }
}

Each customDimension object contains fields with information about an individual custom dimension registered with Kentik. These fields are described in the following table:

Note: When a custom dimension is deleted, the name cannot be reused until the longest data retention period of any of your Kentik plans (see About Plans) has passed. For example, if your plan retains the Fast dataseries for one year, the deleted dimension’s name cannot be reused for one year.

The Custom Dimension List GET method retrieves a JSON array of your Kentik custom dimensions, where each element represents an individual custom dimension.

Note: The "id" in the customDimension object can be used in subsequent calls to retrieve, update, or delete that custom dimension.

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 from the Custom Dimension List method includes the following elements:

• Response headers
• HTTP response code
• A response body with a JSON custom dimension array, with a customDimension object containing information about each custom dimension.

Note: For details on the JSON name/value pairs in a customDimension object, see Custom Dimension JSON.

The Custom Dimension Info GET method fetches details of a specific custom dimension by its ID from your list of Kentik custom dimensions.

HTTP Request

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

Notes:
- The dimension_id in the path corresponds to the id value in the customDimension object from the Custom Dimension List array.
- 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 from the Custom Dimension Info method includes the following elements:

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

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

The Custom Dimension Create POST method adds a new custom dimension to your collection of custom dimensions.

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: When a custom dimension is deleted, its name cannot be reused until the longest data retention period of any of your Kentik plans has passed. For example, if your plan includes retention of the Fast dataseries for one year, then that dimension's name cannot be reused for one year.

HTTP Response

A successful response from the Custom Dimension Create method includes the following elements:

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

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

The Custom Dimension Update PUT method modifies a specific custom dimension, identified by its ID, within your collection of custom dimensions. The only attribute that can be updated is the display name.

HTTP Request

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

Notes:
- The "dimension_id" in the path corresponds to the "id" in the customDimension object from the Custom Dimension List array.
- 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 updated are included in a JSON customDimension object with only the fields to be changed. The following example shows an update to the custom dimension’s display name:

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

Note: Only the display name can be changed when updating a custom dimension.

HTTP Response

A successful response from the Custom Dimension Update method includes the following elements:

• Response headers
• HTTP response code
• A JSON customDimension object with details of the updated custom dimension, excluding the populators array.

Note: For details on the JSON name/value pairs in a customDimension object, see Custom Dimension JSON.

The Custom Dimension Delete method removes a specific custom dimension, identified by its ID, from a customer's collection.

Note: When a custom dimension is deleted, its name cannot be reused until the longest data retention period of any of your Kentik plans has passed. For example, if your plan retains the Fast dataseries for one year, the deleted dimension's name cannot be reused for one year.

HTTP Request

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

Notes:
- The "custom dimension_id" in the path corresponds to the "id" in the customDimension object from the Custom Dimension List array.
- 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 from the Custom Dimension Delete method includes the following elements:

• Response headers
• HTTP response code 204 (no content)

The Custom Dimensions API uses populator objects to decide when the KDE main table field (see KDE Tables), corresponding to a custom dimension, is populated for a specific row (see Dimensions and Populators). These populators are located in the populators array of the customDimension object, which is returned in an HTTP response from a Custom Dimension List or Custom Dimension Info call. A populator object consists of the fields 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: The returned populator object may not include all fields, as it depends on which fields are defined in the object.

The fields of each populator object provide information about an individual populator assigned to a specific custom dimension. These fields are described in the following table:

Notes:
- The Portal field column shows the corresponding setting name in the Populator Settings Dialog in the portal.
- Commas are used only as delimiters in comma-delimited lists.
- For more on field value validations, see Populator Field Validation.

The Populator Create POST method adds a new populator to your Kentik populators.

HTTP Request

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

Notes:
- The dimension_id in the path corresponds to the id value in the customDimension object from the Custom Dimension List array.
- 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 from the Populator Create method includes the following elements:

• Response headers
• HTTP response code
• A JSON populator object with details of the newly added populator’s parameters.

Note: For details on the JSON name/value pairs in a populator object, see Populator JSON.

The Populator Update PUT method updates data for a specific populator, identified by its ID, in your list of existing Kentik populators.

Note: Use the Custom Dimension Info call to find the ID of the populator you want to update.

HTTP Request

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

Notes:
- The dimension_id in the path corresponds to the id value in the customDimension object from the Custom Dimension List array.
- 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 updated are included in a JSON populator object with only the fields to be changed. The following example shows an update to the port number:

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

HTTP Response

A successful response from the Populator Update method includes the following elements:

• Response headers
• HTTP response code
• A JSON populator object with the updated populator’s parameters.

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

This Populator Delete method removes one populator, identified by its ID, from your collection of Kentik populators.

Notes:
- Deleting a populator for a custom dimension makes previously matched KDE main table rows unfilterable by that populator's value.
- Use the Custom Dimension Info call to identify the ID of the populator you wish to delete.

HTTP Request

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

Notes:
- The dimension_id in the path corresponds to the id value in the customDimension object from the Custom Dimension List array.
- 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 from the Populator Delete method includes the following elements:

• Response headers
• HTTP response code 204 (no content)

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:
- A Python integration is available for making calls to this API. See our Hypertagging API project on 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 allows programmatic management of your organization’s flow tags (see About Flow Tags) and custom dimension populators (see Dimensions and Populators) in Kentik. It supports:

• Adding a batch of tags or populators
• Modifying existing tags or populators
• Removing existing tags or populators
• Retrieving status updates on batch operation progress

Note: The Batch API complements, but does not replace, our APIs for managing flow tags and custom dimension populators. See Tag API and Custom Dimension API.

The Batch API differs from other Kentik V5 APIs by using a single POST method (see Batch Request) for creating, updating, and deleting objects, with actions determined by parameter values. It also provides a separate GET method (see Batch Status Request) to retrieve status information.

For the create/update/delete method, multiple requests, known as “parts”, can be included in a single batch operation, with each part having a 4MB payload limit. The multi-part process involves:

• Step 1: POST the request JSON for the first part to the appropriate endpoint (tags or populators). Set the complete parameter to false to indicate more parts will follow.
• Step 2: An HTTP response with status 202 (Accepted) confirms receipt, queueing the request for offline processing. The response includes a GUID (Globally Unique Identifier), which is used to:
  - Identify subsequent requests as part of the same batch operation.
  - Request the batch operation status in a Batch Status Request.
• Step 3: POST the request JSON for additional parts, using the same GUID. In the final request, set the complete parameter (see Batch Request JSON Fields) to true.

Note: The creation or updating of flow tags or custom dimension populators starts with the first request, but deletion of unneeded tags or populators occurs only after all batch operation parts are received.

The Batch Request POST method is used to manage either:

• All your flow tags
• The populators for a single custom dimension

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

• Criteria: An array of criteria to evaluate each flow record for a match at ingest, including:
  - Direction: Specifies the direction (source, destination, or either) of fields like SRC IP or SRC port
  - Field: The field name and value to match, e.g., "addr": ["1.2.3.4"] for matching the IP address "1.2.3.4.".
• Value:
  - Tags: The tag name to be entered into the src_flow_tags or dst_flow_tags column (see Populating Tag Columns) if criteria match.
  - Populators: The text to be inserted into the custom dimension field if criteria match (see Dimensions and Populators).

The JSON allows multiple criteria sets for each value, with each unique criteria-value combination defining a tag or populator, depending on the endpoint.

Note: A single set of criteria can define multiple values, leading to multiple tags/populators matching the same criteria:
- Tags: The flow record field (src_flow_tags or dst_flow_tags) will include all matching tag names.
- Populators: A random value from the matching criteria will be selected for the custom dimension field.

The Batch API uses the criteria and value parameters based on context to determine the action taken on the flow tag:

• Upserts: An array for update or insert operations:
  - Update: Modify the value if the criterion is already specified for the tag.
  - Insert: Add the criterion and set it to the provided value if not already specified for the tag.
  Note: Users don’t need to know if a criterion is already specified.
• Deletes: An array for delete operations where each value parameter leads to the deletion of the corresponding tag or populator.
  Note: Deletions do not require a criteria parameter.

Note: The API allows updates without needing the ID of each tag or populator, which may sometimes change the ID during an update.

The batch request path varies based on whether you’re 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 following example JSON is used in a single-part request to the Custom Dimension endpoint to:

• Create or update three populators with the value "service_abc", based on specified direction and IP address criteria.
• Delete two populators as specified in 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"
    }
  ]
}

Parameters in a JSON request body can be categorized as follows:

• Batch-related parameters: Settings and structures for batch operations. See table below.
• Match fields: Included in the criteria array, either:
  - Tag-related parameters: See the table in Tag Create.
  - Populator-related parameters: See the table in Populator Create.

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

A successful response from the Batch Request method includes the following elements:

• Response headers
• HTTP response code 202 (accepted)
• A JSON structure with status information for the operation identified in the Batch Status Request

The following 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:

• Identify subsequent batches as part of the same operation.
• Request the status of a batch operation via a Batch Status Request.

The Batch Status Request GET method allows you to check the status of a batch operation initiated with a Batch Request. The operation is identified by the GUID from the original batch request, and is included in the status request URL 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 from the Batch Status Request method includes the following elements:

• Response headers
• HTTP response code 200 (OK)
• A JSON structure with the operation’s status information

Each call to the Batch Status endpoint returns a JSON object with the fields (name/value pairs) as 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 is excluded when the batch operation status requested pertains to tags instead of custom dimension populators.

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

The Saved Filter API allows programmatic management of custom filters saved in Kentik by your organization’s users (see Company Saved Filters). The available methods 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 return a JSON “saved filter” object, or an array of such objects for the Saved Filter List call. For example, this Saved Filter List call returns an array with two objects:

• The first object (ID 001) was created via the API
• The second object (ID 002) was saved from the Kentik portal and includes additional internal fields not present 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: The returned JSON may not include all fields shown above, depending on the defined filter groups and individual filters.

Each saved filter object provides details on a custom filter saved by a user in your organization. The components of 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 more details on how the name/value pairs correspond to custom filters saved via the Kentik portal, see Filter Groups Interface.

The Saved Filter List GET method fetches JSON array of custom filters saved by users in your organization, with each element representing an individual custom filter.

Note: The "id" for each individual custom filter can be used in subsequent calls to retrieve, 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 from the Saved Filter List method includes the following elements:

• Response headers
• HTTP response code
• A response body with a JSON array containing elements for each saved custom filter in your organization, with details about each filter.

Note: For details of the JSON name/value pairs in an array element, see Saved Filter JSON.

The Saved Filter Info GET method fetches details of a specific custom filter, identified by its ID, from the collection of filters saved in Kentik by your organization’s users.

HTTP Request

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

Notes:
- The "filter_id" in the path corresponds to the "id" of an array element 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 from the Saved Filter Info method includes the following elements:

• Response headers
• HTTP response code
• A JSON saved filter object with details of the custom filter specified by filter_id.

Note: For details of the JSON name/value pairs in the returned saved filter object, see Saved Filter JSON.

The Saved Filter Create POST method adds a new custom filter to your collection of saved filters.

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 table below lists the fields with values defined in the saved filter JSON included in the request body:

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

HTTP Response

A successful response from the Saved Filter Create method includes the following elements:

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

Note: For details of the JSON name/value pairs in the returned filter object, see Saved Filter JSON.

The Saved Filter Update PUT method modifies a saved custom filter, identified by its ID, by updating one or more of its field values.

HTTP Request

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

Notes:
- The "filter_id" in the path corresponds to the "id" of an array element 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 in the request body must include all fields from Saved Filter Create, even those you don't wish to change. The specified values in this object will become the updated filter’s values.

HTTP Response

A successful response from the Saved Filter Update method includes the following elements:

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

Note: For details of the JSON name/value pairs in the returned filter object, see Saved Filter JSON.

The Saved Filter Delete method removes a specific custom filter, identified by its ID, from your collection of saved custom filters.

HTTP Request

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

Notes:
- The "filter_id" in the path corresponds to the "id" in each of the array elements 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 from the Saved Filter Delete method includes the following elements:

• Response headers
• HTTP response code 204 (no content)

The Custom Application API allows programmatic management of your organization's custom applications (see About Applications).

More information is coming soon.