Kentik Alerting API (v6)
List, acknowledge, comment on, and manage alerts raised by policies across flow, BGP, and NMS.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Alerting Alert API",
"description": "# Overview\nThe Alerts API provides programmatic access to Kentik's Alerts, which allows the retrieval and basic manual control of alerts.",
"version": "v202505",
"contact": {
"name": "Kentik API Engineering",
"url": "https://github.com/kentik/api-schema-public"
}
},
"tags": [
{
"name": "AlertService"
}
],
"paths": {
"/v202505/alerts": {
"post": {
"summary": "List Alerts",
"description": "Returns an array of alert objects that contain information about individual alerts.",
"operationId": "List",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceListResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceListRequest"
}
}
},
"required": true
},
"tags": [
"AlertService"
]
}
},
"/v202505/alerts/clear": {
"post": {
"summary": "Clear Alerts",
"description": "Clears alerts.",
"operationId": "Clear",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceClearResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceClearRequest"
}
}
},
"required": true
},
"tags": [
"AlertService"
]
}
},
"/v202505/alerts/{alertId}/comments": {
"get": {
"summary": "List Alert Comments",
"description": "Returns all comments for an alert.",
"operationId": "ListComments",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceListCommentsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "alertId",
"description": "The ID of the alert to list comments for.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"AlertService"
]
},
"post": {
"summary": "Add Alert Comment",
"description": "Adds a comment to an alert.",
"operationId": "AddComment",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceAddCommentResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "alertId",
"description": "The ID of the alert to add the comment to.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertServiceAddCommentBody"
}
}
},
"required": true
},
"tags": [
"AlertService"
]
}
},
"/v202505/alerts/{alertId}/external-context": {
"put": {
"summary": "Set External Context for Alert",
"description": "Add or replace external context",
"operationId": "SetExternalContext",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceSetExternalContextResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "alertId",
"description": "The ID of the alert to add or replace external context.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertServiceSetExternalContextBody"
}
}
},
"required": true
},
"tags": [
"AlertService"
]
}
},
"/v202505/alerts/{id}": {
"get": {
"summary": "Get Alert",
"description": "Returns an alert object that contains information about an individual alert.",
"operationId": "Get",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceGetResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "The ID of the alert to get.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"AlertService"
]
}
},
"/v202505/alerts/{id}/ack": {
"post": {
"summary": "Ack Alert",
"description": "Acknowledges an alert.",
"operationId": "Ack",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceAckResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "The ID of the alert to acknowledge.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertServiceAckBody"
}
}
},
"required": true
},
"tags": [
"AlertService"
]
}
},
"/v202505/alerts/{id}/unack": {
"post": {
"summary": "UnAck Alert",
"description": "Unacknowledges an alert (removes the acknowledgement).",
"operationId": "UnAck",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202505AlertServiceUnAckResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "The ID of the alert to remove the acknowledgement from.",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertServiceUnAckBody"
}
}
},
"required": true
},
"tags": [
"AlertService"
]
}
}
},
"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": {
"AlertAcknowledgement": {
"type": "object",
"properties": {
"state": {
"$ref": "#/components/schemas/v202505AlertAcknowledgement"
},
"ackedByUser": {
"type": "string",
"description": "The user ID of the user who acknowledged the alert. Present only if the alert has been acknowledged manually.",
"readOnly": true
},
"autoAckId": {
"type": "string",
"description": "The ID of the auto-ack that acknowledged the alert. Present only if the alert has been auto-acknowledged.",
"readOnly": true
},
"ackedAt": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the acknowledgement.",
"readOnly": true
}
}
},
"AlertServiceAckBody": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"description": "The comment to add to the acknowledgement."
}
}
},
"AlertServiceAddCommentBody": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The text content of the comment. Maximum length is 5000 characters.",
"maxLength": 5000
}
},
"required": [
"text"
]
},
"AlertServiceSetExternalContextBody": {
"type": "object",
"properties": {
"context": {
"$ref": "#/components/schemas/v202505ExternalContext"
}
},
"required": [
"context"
]
},
"AlertServiceUnAckBody": {
"type": "object"
},
"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"
},
"FlowContextActivationStatus": {
"type": "string",
"enum": [
"ACTIVATION_STATUS_UNSPECIFIED",
"ACTIVATION_STATUS_NOT_USED_BASELINE",
"ACTIVATION_STATUS_BASELINE_MISSING_SKIP",
"ACTIVATION_STATUS_BASELINE_MISSING_TRIGGER",
"ACTIVATION_STATUS_BASELINE_USED_FOUND",
"ACTIVATION_STATUS_BASELINE_MISSING_DEFAULT",
"ACTIVATION_STATUS_BASELINE_MISSING_LOWEST",
"ACTIVATION_STATUS_BASELINE_MISSING_HIGHEST",
"ACTIVATION_STATUS_BASELINE_NOT_FOUND_EXISTS",
"ACTIVATION_STATUS_CURRENT_MISSING_SKIP",
"ACTIVATION_STATUS_CURRENT_MISSING_TRIGGER",
"ACTIVATION_STATUS_CURRENT_USED_FOUND",
"ACTIVATION_STATUS_CURRENT_MISSING_DEFAULT",
"ACTIVATION_STATUS_CURRENT_MISSING_LOWEST",
"ACTIVATION_STATUS_CURRENT_MISSING_HIGHEST",
"ACTIVATION_STATUS_CURRENT_NOT_FOUND_EXISTS",
"ACTIVATION_STATUS_BASELINE_MISSING_DEFAULT_INSTEAD_OF_LOWEST",
"ACTIVATION_STATUS_BASELINE_MISSING_DEFAULT_INSTEAD_OF_HIGHEST",
"ACTIVATION_STATUS_CURRENT_MISSING_DEFAULT_INSTEAD_OF_LOWEST",
"ACTIVATION_STATUS_CURRENT_MISSING_DEFAULT_INSTEAD_OF_HIGHEST"
],
"default": "ACTIVATION_STATUS_UNSPECIFIED",
"title": "- ACTIVATION_STATUS_NOT_USED_BASELINE: baseline for this alert key was not used (e.g. policy configuration is not using baseline)\n - ACTIVATION_STATUS_BASELINE_MISSING_SKIP: baseline for this alert key was missing, and the fallback is to just skip\n - ACTIVATION_STATUS_BASELINE_MISSING_TRIGGER: baseline for this alert key was missing, and the fallback is to trigger the alert\n - ACTIVATION_STATUS_BASELINE_USED_FOUND: baseline for this alert key was valid and hence used\n - ACTIVATION_STATUS_BASELINE_MISSING_DEFAULT: baseline for this alert key was missing and default value was used\n - ACTIVATION_STATUS_BASELINE_MISSING_LOWEST: baseline for this alert key was missing and lowest baseline value was used\n - ACTIVATION_STATUS_BASELINE_MISSING_HIGHEST: baseline for this alert key was missing and highest baseline value was used\n - ACTIVATION_STATUS_BASELINE_NOT_FOUND_EXISTS: baseline for this alert key was missing and this policy wants to trigger the alert in such case\n - ACTIVATION_STATUS_CURRENT_MISSING_SKIP: current value for this alert key was missing, and the fallback is to just skip\n - ACTIVATION_STATUS_CURRENT_MISSING_TRIGGER: current value for this alert key was missing, and the fallback is to trigger the alert\n - ACTIVATION_STATUS_CURRENT_USED_FOUND: current value for this alert key was valid and hence used\n - ACTIVATION_STATUS_CURRENT_MISSING_DEFAULT: current value for this alert key was missing and default value was used\n - ACTIVATION_STATUS_CURRENT_MISSING_LOWEST: current value for this alert key was missing and lowest current traffic value was used\n - ACTIVATION_STATUS_CURRENT_MISSING_HIGHEST: current value for this alert key was missing and highest current traffic value was used\n - ACTIVATION_STATUS_CURRENT_NOT_FOUND_EXISTS: current value for this alert key was missing and this policy wants to trigger the alert in such case\n - ACTIVATION_STATUS_BASELINE_MISSING_DEFAULT_INSTEAD_OF_LOWEST: baseline for this alert key was missing and no other value was found, so default value was used instead of lowest baseline value\n - ACTIVATION_STATUS_BASELINE_MISSING_DEFAULT_INSTEAD_OF_HIGHEST: baseline for this alert key was missing and no other value was found, so default value was used instead of highest baseline value\n - ACTIVATION_STATUS_CURRENT_MISSING_DEFAULT_INSTEAD_OF_LOWEST: current value for this alert key was missing and no other value was found, so default value was used instead of lowest current traffic value\n - ACTIVATION_STATUS_CURRENT_MISSING_DEFAULT_INSTEAD_OF_HIGHEST: current value for this alert key was missing and no other value was found, so default value was used instead of highest current traffic value"
},
"FlowContextAlertKeyDetails": {
"type": "object",
"properties": {
"device": {
"$ref": "#/components/schemas/FlowContextDeviceDetails"
},
"interface": {
"$ref": "#/components/schemas/FlowContextInterfaceDetails"
},
"site": {
"$ref": "#/components/schemas/FlowContextSiteDetails"
},
"extendedValue": {
"type": "string",
"description": "The extended value of the alert key.",
"readOnly": true
}
}
},
"FlowContextDeviceDetails": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the device.",
"readOnly": true
},
"name": {
"type": "string",
"description": "The name of the device.",
"readOnly": true
},
"type": {
"type": "string",
"description": "The type of the device (e.g. 'router').",
"readOnly": true
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "The labels associated with the device.",
"readOnly": true
}
}
},
"FlowContextInterfaceDetails": {
"type": "object",
"properties": {
"snmpId": {
"type": "string",
"description": "The SNMP ID of the interface.",
"readOnly": true
},
"snmpAlias": {
"type": "string",
"description": "The SNMP alias of the interface (e.g. 'eth0').",
"readOnly": true
},
"description": {
"type": "string",
"description": "The description of the interface.",
"readOnly": true
},
"snmpSpeedMbps": {
"type": "string",
"format": "int64",
"description": "The SNMP speed of the interface in Mbps.",
"readOnly": true
}
}
},
"FlowContextMetricValue": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the metric value (e.g. 'bytes_in', 'bytes_out', 'packets_in', 'packets_out', etc.).",
"readOnly": true
},
"value": {
"type": "number",
"format": "double",
"description": "The value of the given metric.",
"readOnly": true
}
}
},
"FlowContextSiteDetails": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the site.",
"readOnly": true
},
"name": {
"type": "string",
"description": "The name of the site.",
"readOnly": true
},
"latitude": {
"type": "string",
"description": "The geographic latitude of the site."
},
"longitude": {
"type": "string",
"description": "The geographic longitude of the site.",
"readOnly": true
},
"location": {
"type": "string",
"description": "The location of the site (e.g. 'New York, NY').",
"readOnly": true
},
"country": {
"type": "string",
"description": "The country of the site (e.g. 'United States').",
"readOnly": true
}
}
},
"NmsContextActivationInfo": {
"type": "object",
"properties": {
"activate": {
"$ref": "#/components/schemas/v202505NmsActivateOrClearConditions"
},
"severity": {
"$ref": "#/components/schemas/v202303Severity"
},
"clearManual": {
"type": "boolean"
},
"clearUnlessActivated": {
"type": "boolean"
}
}
},
"NmsContextAlarmMetricMap": {
"type": "object",
"properties": {
"metrics": {
"type": "object",
"additionalProperties": {
"type": "number",
"format": "double"
}
}
}
},
"NmsContextAlarmTarget": {
"type": "object",
"properties": {
"fields": {
"type": "object",
"additionalProperties": {
"type": "number",
"format": "double"
}
},
"tags": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"NmsContextDatasetInfo": {
"type": "object",
"properties": {
"customType": {
"type": "boolean"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
}
},
"entityType": {
"type": "string"
},
"measurements": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"SortingConfigField": {
"type": "object",
"properties": {
"by": {
"$ref": "#/components/schemas/FieldBy"
},
"order": {
"$ref": "#/components/schemas/SortingConfigOrder"
}
}
},
"SortingConfigOrder": {
"type": "string",
"enum": [
"ORDER_UNSPECIFIED",
"ORDER_ASCENDING",
"ORDER_DESCENDING"
],
"default": "ORDER_UNSPECIFIED"
},
"protobufAny": {
"type": "object",
"properties": {
"@type": {
"type": "string"
}
},
"additionalProperties": {}
},
"rpcStatus": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
},
"details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/protobufAny"
}
}
}
},
"typesv202506PaginationConfig": {
"type": "object",
"properties": {
"limit": {
"type": "string",
"format": "uint64",
"title": "limit is how many items to return at most"
},
"offset": {
"type": "string",
"format": "uint64",
"title": "offset is the offset into the list of items"
},
"includeTotalCount": {
"type": "boolean",
"title": "include_total_count is a flag to enforce API service to include the total count of items in the response,\nwhich in some cases may be very expensive to fetch"
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kentik/refs/heads/main/openapi/kentik-alerting-openapi.json