Kentik Alert Policies API (v6)
Create and manage alert policies, thresholds, baselines, and their datasources and filters.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Alerting Policies API",
"description": "# Overview\nThe Alerting Policies API provides programmatic access to Kentik's configuration of the policies that define how, when, and to whom alerts are triggered.",
"version": "v202505",
"contact": {
"name": "Kentik API Engineering",
"url": "https://github.com/kentik/api-schema-public"
}
},
"tags": [
{
"name": "PolicyService"
}
],
"paths": {
"/v202505/policies/list": {
"post": {
"summary": "List Policies",
"description": "Returns a list of alerting policies.",
"operationId": "List",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505PolicyServiceListResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505PolicyServiceListRequest"
}
}
},
"required": true
},
"tags": [
"PolicyService"
]
}
},
"/v202505/policies/{policyType}/{id}": {
"get": {
"summary": "Get Policy",
"description": "Returns an alerting policy.",
"operationId": "Get",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505PolicyServiceGetResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "policyType",
"description": "The type of policy to get.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"POLICY_TYPE_UNSPECIFIED",
"POLICY_TYPE_AGENT",
"POLICY_TYPE_COMPONENT",
"POLICY_TYPE_DEVICE",
"POLICY_TYPE_EVENT",
"POLICY_TYPE_INTERFACE",
"POLICY_TYPE_CUSTOM",
"POLICY_TYPE_CLOUD",
"POLICY_TYPE_PROTECT",
"POLICY_TYPE_TRAFFIC",
"POLICY_TYPE_KMETRICS"
]
}
},
{
"name": "id",
"description": "The ID of the policy to get.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"PolicyService"
]
}
},
"/v202505/policies/{policyType}/{id}/disable": {
"post": {
"summary": "Disable Policy",
"description": "Disables an alerting policy.",
"operationId": "Disable",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505PolicyServiceDisableResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "policyType",
"description": "The type of policy to disable.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"POLICY_TYPE_UNSPECIFIED",
"POLICY_TYPE_AGENT",
"POLICY_TYPE_COMPONENT",
"POLICY_TYPE_DEVICE",
"POLICY_TYPE_EVENT",
"POLICY_TYPE_INTERFACE",
"POLICY_TYPE_CUSTOM",
"POLICY_TYPE_CLOUD",
"POLICY_TYPE_PROTECT",
"POLICY_TYPE_TRAFFIC",
"POLICY_TYPE_KMETRICS"
]
}
},
{
"name": "id",
"description": "The ID of the policy to disable.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyServiceDisableBody"
}
}
},
"required": true
},
"tags": [
"PolicyService"
]
}
},
"/v202505/policies/{policyType}/{id}/enable": {
"post": {
"summary": "Enable Policy",
"description": "Enables an alerting policy.",
"operationId": "Enable",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505PolicyServiceEnableResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "policyType",
"description": "The type of policy to enable.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"POLICY_TYPE_UNSPECIFIED",
"POLICY_TYPE_AGENT",
"POLICY_TYPE_COMPONENT",
"POLICY_TYPE_DEVICE",
"POLICY_TYPE_EVENT",
"POLICY_TYPE_INTERFACE",
"POLICY_TYPE_CUSTOM",
"POLICY_TYPE_CLOUD",
"POLICY_TYPE_PROTECT",
"POLICY_TYPE_TRAFFIC",
"POLICY_TYPE_KMETRICS"
]
}
},
{
"name": "id",
"description": "The ID of the policy to enable.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyServiceEnableBody"
}
}
},
"required": true
},
"tags": [
"PolicyService"
]
}
}
},
"security": [
{
"email": [],
"token": []
}
],
"externalDocs": {
"description": "Kentik Alerts documentation",
"url": "https://kb.kentik.com/docs/alerting"
},
"components": {
"securitySchemes": {
"email": {
"type": "apiKey",
"name": "X-CH-Auth-Email",
"in": "header"
},
"token": {
"type": "apiKey",
"name": "X-CH-Auth-API-Token",
"in": "header"
}
},
"schemas": {
"BaselineConditionDeltaType": {
"type": "string",
"enum": [
"DELTA_TYPE_UNSPECIFIED",
"DELTA_TYPE_ABOVE",
"DELTA_TYPE_BELOW"
],
"default": "DELTA_TYPE_UNSPECIFIED",
"title": "- DELTA_TYPE_ABOVE: the traffic value must be above the baseline value\n - DELTA_TYPE_BELOW: the traffic value must be below the baseline value"
},
"BaselineConfigCompareMode": {
"type": "string",
"enum": [
"COMPARE_MODE_UNSPECIFIED",
"COMPARE_MODE_PREVIOUS_HOURS",
"COMPARE_MODE_PREVIOUS_DAYS",
"COMPARE_MODE_PREVIOUS_DAYS_DISTINGUISH_WEEKENDS",
"COMPARE_MODE_PREVIOUS_WEEKS"
],
"default": "COMPARE_MODE_UNSPECIFIED",
"title": "- COMPARE_MODE_PREVIOUS_HOURS: pick all previous hours baseline values\n - COMPARE_MODE_PREVIOUS_DAYS: pick all previous days baseline values\n - COMPARE_MODE_PREVIOUS_DAYS_DISTINGUISH_WEEKENDS: pick previous days baseline values but distinguish weekend days from weekdays\n - COMPARE_MODE_PREVIOUS_WEEKS: pick all previous weeks baseline values"
},
"ConditionsBaselineCondition": {
"type": "object",
"properties": {
"absolute": {
"type": "number",
"format": "double",
"description": "The absolute value used for the policy level condition."
},
"percentage": {
"type": "string",
"format": "int64",
"description": "The percentage value used for the policy level condition."
},
"delta": {
"$ref": "#/components/schemas/BaselineConditionDeltaType"
},
"useLowest": {
"type": "boolean",
"description": "Use the lowest value for the policy level condition if valid baseline value is missing."
},
"useHighest": {
"type": "boolean",
"description": "Use the highest value for the policy level condition if valid baseline value is missing."
},
"useTrigger": {
"type": "boolean",
"description": "Use the trigger value for the policy level condition if valid baseline value is missing."
},
"skip": {
"type": "boolean",
"description": "Skip the current traffic value if valid baseline value is missing."
},
"useValue": {
"type": "string",
"format": "int64",
"description": "Use the given value for the policy level condition if valid baseline value is missing."
}
},
"required": [
"delta"
]
},
"ConditionsForecastCondition": {
"type": "object",
"properties": {
"operator": {
"$ref": "#/components/schemas/FlowPolicyLevelSettingsConditionsOperator"
},
"percentageValue": {
"type": "string",
"format": "int64"
}
}
},
"ConditionsInterfaceCapacityCondition": {
"type": "object",
"properties": {
"absolute": {
"type": "number",
"format": "double",
"description": "The absolute value used for the policy level condition."
},
"percentage": {
"type": "string",
"format": "int64",
"description": "The percentage value used for the policy level condition."
}
}
},
"ConditionsRatioCondition": {
"type": "object",
"properties": {
"lhsMetric": {
"type": "string",
"description": "The left hand side metric used for the policy level condition."
},
"rhsMetric": {
"type": "string",
"description": "The right hand side metric used for the policy level condition."
},
"lhsProportion": {
"type": "integer",
"format": "int64",
"description": "The left hand side proportion used for the policy level condition."
},
"rhsProportion": {
"type": "integer",
"format": "int64",
"description": "The right hand side proportion used for the policy level condition."
},
"margin": {
"type": "number",
"format": "double",
"description": "The margin used for the policy level condition."
},
"direction": {
"$ref": "#/components/schemas/RatioConditionDirection"
}
},
"required": [
"lhsMetric",
"rhsMetric",
"lhsProportion",
"rhsProportion",
"margin",
"direction"
]
},
"ConditionsStaticCondition": {
"type": "object",
"properties": {
"metric": {
"type": "string",
"description": "The metric used for the policy level condition."
},
"operator": {
"$ref": "#/components/schemas/FlowPolicyLevelSettingsConditionsOperator"
},
"value": {
"type": "number",
"format": "double",
"description": "The value used for the policy level condition."
}
},
"required": [
"metric",
"operator",
"value"
]
},
"ConditionsTopKeysCondition": {
"type": "object",
"properties": {
"event": {
"$ref": "#/components/schemas/TopKeysConditionTopKeysEvent"
},
"count": {
"type": "string",
"format": "int64",
"description": "The count of the top keys used for the policy level condition."
}
},
"required": [
"event",
"count"
]
},
"EventPolicySettingsEventType": {
"type": "string",
"enum": [
"EVENT_TYPE_UNSPECIFIED",
"EVENT_TYPE_SYSLOG",
"EVENT_TYPE_SNMP_TRAP"
],
"default": "EVENT_TYPE_UNSPECIFIED",
"title": "- EVENT_TYPE_SYSLOG: Syslog event\n - EVENT_TYPE_SNMP_TRAP: SNMP trap event"
},
"FieldBy": {
"type": "string",
"enum": [
"BY_UNSPECIFIED",
"BY_ID",
"BY_NAME",
"BY_CREATED_AT",
"BY_UPDATED_AT",
"BY_SEVERITY",
"BY_STATUS",
"BY_POLICY_TYPE",
"BY_START_TIME",
"BY_END_TIME",
"BY_ALARM_STATE",
"BY_ALARM_POLICY_NAME",
"BY_ALARM_PRIMARY_DIMENSION"
],
"default": "BY_UNSPECIFIED"
},
"FlowPolicyLevelSettingsActivationSettings": {
"type": "object",
"properties": {
"matchTimes": {
"type": "string",
"format": "int64",
"description": "The number of times the policy level conditions must be met within the match window to activate the alert."
},
"matchWindow": {
"type": "string",
"description": "The window of time within which the policy level conditions must be met to activate the alert."
},
"resetCountWindow": {
"type": "string",
"description": "The window of time within which the level conditions must not be met again to reset the match count."
}
},
"required": [
"matchTimes",
"matchWindow",
"resetCountWindow"
]
},
"FlowPolicyLevelSettingsConditions": {
"type": "object",
"properties": {
"static": {
"$ref": "#/components/schemas/ConditionsStaticCondition"
},
"baseline": {
"$ref": "#/components/schemas/ConditionsBaselineCondition"
},
"topKeys": {
"$ref": "#/components/schemas/ConditionsTopKeysCondition"
},
"interfaceCapacity": {
"$ref": "#/components/schemas/ConditionsInterfaceCapacityCondition"
},
"ratio": {
"$ref": "#/components/schemas/ConditionsRatioCondition"
},
"forecast": {
"$ref": "#/components/schemas/ConditionsForecastCondition"
}
}
},
"FlowPolicyLevelSettingsConditionsOperator": {
"type": "string",
"enum": [
"OPERATOR_UNSPECIFIED",
"OPERATOR_GREATER_THAN_OR_EQUALS",
"OPERATOR_GREATER_THAN",
"OPERATOR_EQUALS",
"OPERATOR_NOT_EQUALS",
"OPERATOR_LESS_THAN",
"OPERATOR_LESS_THAN_OR_EQUALS",
"OPERATOR_IN_SET",
"OPERATOR_NOT_IN_SET"
],
"default": "OPERATOR_UNSPECIFIED"
},
"FlowPolicyLevelSettingsMitigationAssociation": {
"type": "object",
"properties": {
"platformId": {
"type": "string",
"description": "The platform ID of the mitigation association."
},
"methodId": {
"type": "string",
"description": "The method ID of the mitigation association."
}
},
"required": [
"platformId",
"methodId"
]
},
"FlowPolicySettingsBaselineConfig": {
"type": "object",
"properties": {
"storedKeyCount": {
"type": "string",
"format": "int64",
"default": "25",
"description": "The number of alert keys stored in the baseline per policy window.",
"title": "not exposing completeness duration as this does not work"
},
"windowLength": {
"type": "string",
"default": "2419200s",
"description": "The length of the entire policy baseline window."
},
"windowStartOffset": {
"type": "string",
"default": "86400s",
"description": "The start offset from now used when calculating the baseline value."
},
"rollupAggregation": {
"$ref": "#/components/schemas/v202505AggregationType"
},
"compareMode": {
"$ref": "#/components/schemas/BaselineConfigCompareMode"
},
"neighbourhoodRadius": {
"type": "string",
"description": "The neighbourhood radius used to calculate the neighbourhood value. This is the number of hours before and after the current hour to include in the neighbourhood value calculation."
},
"neighbourhoodAggregation": {
"$ref": "#/components/schemas/v202505AggregationType"
},
"finalAggregation": {
"$ref": "#/components/schemas/v202505AggregationType"
}
},
"required": [
"storedKeyCount",
"windowLength",
"windowStartOffset",
"rollupAggregation",
"compareMode",
"neighbourhoodRadius",
"neighbourhoodAggregation",
"finalAggregation"
]
},
"NmsPolicyLevelSettingsClearType": {
"type": "string",
"enum": [
"CLEAR_TYPE_UNSPECIFIED",
"CLEAR_TYPE_CLEAR_MANUAL",
"CLEAR_TYPE_CLEAR_UNLESS_ACTIVATED"
],
"default": "CLEAR_TYPE_UNSPECIFIED",
"title": "- CLEAR_TYPE_UNSPECIFIED: assumed CLEAR_TYPE_CLEAR_UNLESS_ACTIVATED if not specified\n - CLEAR_TYPE_CLEAR_MANUAL: CLEAR_TYPE_CONDITIONAL = 1; we don't want to expose this yet, not implemented"
},
"PolicyDataSourcesDeviceTag": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the device tag to include in the policy."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"description": "The values of the device tag to include in the policy. Has to contain at least one value.",
"minItems": 1
}
}
},
"PolicyDimensionFiltersConjunction": {
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PolicyDimensionFiltersEntry"
},
"description": "The entries of the conjunction."
}
}
},
"PolicyDimensionFiltersEntry": {
"type": "object",
"properties": {
"not": {
"type": "boolean",
"description": "If true, the entry will be negated."
},
"dimension": {
"type": "string",
"description": "The dimension the filter entry is applied to."
},
"equalsAny": {
"$ref": "#/components/schemas/PolicyDimensionFiltersEntryStringArray"
},
"matchesAny": {
"$ref": "#/components/schemas/PolicyDimensionFiltersEntryStringArray"
}
}
},
"PolicyDimensionFiltersEntryStringArray": {
"type": "object",
"properties": {
"values": {
"type": "array",
"items": {
"type": "string"
},
"description": "The values of the string array."
}
}
},
"PolicyFiltersFieldFilter": {
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "The field the filter is applied to."
},
"operator": {
"$ref": "#/components/schemas/v202505PolicyFiltersOperator"
},
"value": {
"type": "string",
"description": "The right-hand value used for the filter operation."
}
}
},
"PolicyFiltersFilterConnector": {
"type": "string",
"enum": [
"FILTER_CONNECTOR_UNSPECIFIED",
"FILTER_CONNECTOR_AND",
"FILTER_CONNECTOR_OR"
],
"default": "FILTER_CONNECTOR_UNSPECIFIED",
"title": "- FILTER_CONNECTOR_AND: All of the conditions must be true\n - FILTER_CONNECTOR_OR: Any of the conditions must be true"
},
"PolicyFiltersSavedFilter": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the saved filter. Saved filters are pre-defined filters that can be used in the policy."
},
"not": {
"type": "boolean",
"description": "If true, the saved filter will be negated."
}
}
},
"PolicyPolicyErrorInfo": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp when the error occurred."
},
"description": {
"type": "string",
"description": "The description of the error."
}
}
},
"PolicyPolicyLevel": {
"type": "object",
"properties": {
"severity": {
"$ref": "#/components/schemas/v202303Severity"
},
"description": {
"type": "string",
"description": "The description of the policy level."
},
"ackRequired": {
"type": "boolean",
"description": "Whether acknowledgment is required for alerts that match this policy level."
},
"nms": {
"$ref": "#/components/schemas/v202505NmsPolicyLevelSettings"
},
"flow": {
"$ref": "#/components/schemas/v202505FlowPolicyLevelSettings"
},
"event": {
"$ref": "#/components/schemas/v202505EventPolicyLevelSettings"
},
"notifications": {
"type": "array",
"items": {
"$ref": "#/components/schemas/v202505NotificationChannelAssociation"
},
"description": "The notification channel associations for this policy level. When the alert is triggered at this level, the channels are used to send the alert notification."
}
}
},
"PolicyServiceDisableBody": {
"type": "object"
},
"PolicyServiceEnableBody": {
"type": "object"
},
"RatioConditionDirection": {
"type": "string",
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kentik/refs/heads/main/openapi/kentik-alert-policy-openapi.json