Kentik BGP Monitoring API (v6)
Configure BGP monitors and query route and prefix visibility across the internet.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "BGP Monitoring API",
"description": "# Overview\nThe BGP Monitoring API provides programmatic access to Kentik's BGP monitoring system. The APIs handle two distinct functions:\n* **Admin service**: manages monitoring of advertised BGP prefixes as collected from global vantage points.\n* **Data service**: handles retrieval of two classes of data for any IP prefix:\n - metrics for reachability and path changes, which provide a time series for a specified interval;\n - routes, which provide a snapshot of routing information for particular timestamp.\n\nThe services described above use the following endpoints:\n| Endpoint | Purpose |\n|-----------|---------|\n| BgpMonitoringAdminService | CRUD operations for BGP monitors |\n| BgpMonitoringDataService | Retrieval of BGP monitoring data |\n\nBoth REST endpoints and gRPC RPCs are provided.\n### Known Limitations\nThe API currently does not support retrieval of BGP event history.\n# BGP Monitoring Data\n\nKentik's BGP monitoring API provides the following information about network prefixes:\n* **Reachability**: expressed as the percentage of vantage points reporting the prefix\n* **Path changes**: the number of changes in a given time range\n* **Routes**: AS Path, next hop\n### Data Retrieval Limitations\n\nThe following considerations apply to data retrieval using these APIs:\n* BGP metrics and routes can be retrieved for any prefix with prefix length greater than 14 and any time interval. Prefixes with smaller length must be split into subnets (sub-prefixes) and requested individually.\n* Requests for BGP metrics can can specify one or more metric types to be retrieved for a single prefix. Observed data are returned as a sequence of messages, one for each metric type and observation time.\n* Route requests retrieve snapshot of information for specified prefix and time. Responses contain also mapping of ASNs to AS names for convenience.\n# Working with BGP Monitoring\n\nThe topics below cover important information related to using Kentik's BGP monitoring APIs.\n### BGP Prefixes\n\nThese APIs represent BGP prefixes using NLRI (Network Layer Reachability Information) objects. While NLRI objects allow representation of any type of network address, the system currently supports only IPv4 and IPv6 unicast in standard textual representation:\n* **IPv4**: dotted-decimal notation\n* **IPv6**: [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952) syntax\n### BGP Monitor Tests\n\nBGP Monitors enable the generation of alerts for group network prefixes (IPv4 or IPv6) based on the following factors:\n* Visibility/reachability of prefixes\n* Mismatch of originating ASNs with a specified list of valid originators\n* Validity of advertisements with respect to RPKI (Resource Public Key Infrastructure)\n\n### Configuration Limitations \n\nThe following considerations apply when configuring a BGP monitor test:\n* Each BGP monitor instance can monitor up to 10 prefixes.\n* The length of each monitored (IPv4 or IPv6) prefix must be greater than 14. Prefixes with smaller length must be split into subnets (sub-prefixes).",
"version": "v202210",
"contact": {
"name": "Kentik API Engineering",
"url": "https://github.com/kentik/api-schema-public"
}
},
"tags": [
{
"name": "BgpMonitoringAdminService"
},
{
"name": "BgpMonitoringDataService"
}
],
"paths": {
"/bgp_monitoring/v202210/metrics": {
"post": {
"summary": "Get metrics for a BGP prefix.",
"description": "Retrieve metric data for single BGP prefix and time interval.",
"operationId": "GetMetricsForTarget",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210GetMetricsForTargetResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210GetMetricsForTargetRequest"
}
}
},
"required": true
},
"tags": [
"BgpMonitoringDataService"
]
}
},
"/bgp_monitoring/v202210/monitors": {
"get": {
"summary": "List BGP Monitors.",
"description": "Returns list of all BGP monitors present in the account.",
"operationId": "ListMonitors",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210ListMonitorsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"tags": [
"BgpMonitoringAdminService"
]
},
"post": {
"summary": "Create new BGP Monitor instance.",
"description": "Creates new BGP Monitor and if successful returns its configuration.",
"operationId": "CreateMonitor",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210CreateMonitorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210CreateMonitorRequest"
}
}
},
"required": true
},
"tags": [
"BgpMonitoringAdminService"
]
}
},
"/bgp_monitoring/v202210/monitors/{id}": {
"get": {
"summary": "Get BGP Monitor configuration.",
"description": "Returns configuration of existing BGP monitor with specific ID.",
"operationId": "GetMonitor",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210GetMonitorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "ID of the BGP monitor to be retrieved",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"BgpMonitoringAdminService"
]
},
"delete": {
"summary": "Delete existing BGP Monitor.",
"description": "Delete BGP monitor with with specific ID.",
"operationId": "DeleteMonitor",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210DeleteMonitorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "ID of the BGP monitor to be deleted",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"BgpMonitoringAdminService"
]
},
"put": {
"summary": "Update configuration of a BGP monitor.",
"description": "Updates configuration of BGP monitor with specific ID and returns updated configuration.",
"operationId": "UpdateMonitor",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210UpdateMonitorResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "System generated unique identifier",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BgpMonitoringAdminServiceUpdateMonitorBody"
}
}
},
"required": true
},
"tags": [
"BgpMonitoringAdminService"
]
}
},
"/bgp_monitoring/v202210/monitors/{id}/status": {
"put": {
"summary": "Sets administrative status of a BGP monitor.",
"description": "Sets administrative status of BGP monitor with specific ID.",
"operationId": "SetMonitorStatus",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210SetMonitorStatusResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "ID of the BGP monitor whose status is to be modified",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BgpMonitoringAdminServiceSetMonitorStatusBody"
}
}
},
"required": true
},
"tags": [
"BgpMonitoringAdminService"
]
}
},
"/bgp_monitoring/v202210/routes": {
"post": {
"summary": "Get routes for a BGP prefix.",
"description": "Retrieve snapshot of route information for single BGP prefix at specific time.",
"operationId": "GetRoutesForTarget",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210GetRoutesForTargetResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202210GetRoutesForTargetRequest"
}
}
},
"required": true
},
"tags": [
"BgpMonitoringDataService"
]
}
}
},
"security": [
{
"email": [],
"token": []
}
],
"externalDocs": {
"description": "More about Kentik BGP monitoring",
"url": "https://kb.kentik.com/v4/Ma03.htm#Ma03-BGP_Monitor_Details_Page"
},
"components": {
"securitySchemes": {
"email": {
"type": "apiKey",
"name": "X-CH-Auth-Email",
"in": "header"
},
"token": {
"type": "apiKey",
"name": "X-CH-Auth-API-Token",
"in": "header"
}
},
"schemas": {
"BgpMonitoringAdminServiceSetMonitorStatusBody": {
"type": "object",
"properties": {
"status": {
"$ref": "#/components/schemas/v202210BgpMonitorStatus"
}
},
"title": "SetMonitorStatusRequest",
"required": [
"status"
]
},
"BgpMonitoringAdminServiceUpdateMonitorBody": {
"type": "object",
"properties": {
"monitor": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "User selected name of the monitor"
},
"status": {
"$ref": "#/components/schemas/v202210BgpMonitorStatus"
},
"settings": {
"$ref": "#/components/schemas/v202210BgpMonitorSettings"
},
"cdate": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (UTC)",
"readOnly": true
},
"edate": {
"type": "string",
"format": "date-time",
"description": "Last modification timestamp (UTC)",
"readOnly": true
},
"createdBy": {
"$ref": "#/components/schemas/v202303UserInfo"
},
"lastUpdatedBy": {
"$ref": "#/components/schemas/v202303UserInfo"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
}
},
"title": "BgpMonitor"
}
},
"title": "UpdateMonitorRequest",
"required": [
"name",
"monitor"
]
},
"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"
}
}
}
},
"v202210BgpHealthSettings": {
"type": "object",
"properties": {
"reachabilityWarning": {
"type": "number",
"format": "float",
"description": "Threshold (in percents) for triggering warning level alert"
},
"reachabilityCritical": {
"type": "number",
"format": "float",
"description": "Threshold (in percents) for triggering critical level alert"
}
},
"title": "BgpHealthSettings"
},
"v202210BgpMetric": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "UTC time of the observation",
"readOnly": true
},
"nlri": {
"$ref": "#/components/schemas/v202210Nlri"
},
"reachability": {
"type": "number",
"format": "float",
"description": "Percentage of vantage points reporting the prefix reachable",
"readOnly": true
},
"pathChanges": {
"type": "integer",
"format": "int64",
"description": "Number of AS path changes for the prefix across all vantage points in the queried time interval",
"readOnly": true
}
},
"title": "BgpMetric"
},
"v202210BgpMetricType": {
"type": "string",
"enum": [
"BGP_METRIC_TYPE_UNSPECIFIED",
"BGP_METRIC_TYPE_REACHABILITY",
"BGP_METRIC_TYPE_PATH_CHANGES"
],
"default": "BGP_METRIC_TYPE_UNSPECIFIED",
"description": "- BGP_METRIC_TYPE_UNSPECIFIED: Invalid value.\n - BGP_METRIC_TYPE_REACHABILITY: Reachability metric in percents\n - BGP_METRIC_TYPE_PATH_CHANGES: Number of path changes over time interval",
"title": "BgpMetricType"
},
"v202210BgpMonitor": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "System generated unique identifier",
"readOnly": true
},
"name": {
"type": "string",
"description": "User selected name of the monitor"
},
"status": {
"$ref": "#/components/schemas/v202210BgpMonitorStatus"
},
"settings": {
"$ref": "#/components/schemas/v202210BgpMonitorSettings"
},
"cdate": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (UTC)",
"readOnly": true
},
"edate": {
"type": "string",
"format": "date-time",
"description": "Last modification timestamp (UTC)",
"readOnly": true
},
"createdBy": {
"$ref": "#/components/schemas/v202303UserInfo"
},
"lastUpdatedBy": {
"$ref": "#/components/schemas/v202303UserInfo"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
}
},
"title": "BgpMonitor",
"required": [
"name"
]
},
"v202210BgpMonitorSettings": {
"type": "object",
"properties": {
"allowedAsns": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "List of ASNs that are valid originators of monitored prefixes"
},
"targets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/v202210Nlri"
},
"description": "List of prefixes to monitor"
},
"checkRpki": {
"type": "boolean",
"description": "Enable verification of validity of advertisements of monitored prefixes with respect to RPKI"
},
"includeCoveredPrefixes": {
"type": "boolean",
"description": "Include advertised subnets (sub-prefixes) of monitored prefixes"
},
"healthSettings": {
"$ref": "#/components/schemas/v202210BgpHealthSettings"
},
"notificationChannels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of IDs of notification channels for delivery of alerts"
},
"notes": {
"type": "string",
"description": "Free form notes documenting the monitor"
},
"allowedUpstreams": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "List of ASNs that are expected to propagate monitored prefixes"
}
},
"title": "BgpMonitorSettings",
"required": [
"targets"
]
},
"v202210BgpMonitorStatus": {
"type": "string",
"enum": [
"BGP_MONITOR_STATUS_UNSPECIFIED",
"BGP_MONITOR_STATUS_ACTIVE",
"BGP_MONITOR_STATUS_PAUSED",
"BGP_MONITOR_STATUS_DELETED"
],
"default": "BGP_MONITOR_STATUS_UNSPECIFIED",
"description": "- BGP_MONITOR_STATUS_UNSPECIFIED: Invalid value.\n - BGP_MONITOR_STATUS_ACTIVE: Monitor is active.\n - BGP_MONITOR_STATUS_PAUSED: Monitor is paused.\n - BGP_MONITOR_STATUS_DELETED: Monitor is deleted. Not user settable",
"title": "BgpMonitorStatus"
},
"v202210CreateMonitorRequest": {
"type": "object",
"properties": {
"monitor": {
"$ref": "#/components/schemas/v202210BgpMonitor"
}
},
"title": "CreateMonitorRequest",
"required": [
"monitor"
]
},
"v202210CreateMonitorResponse": {
"type": "object",
"properties": {
"monitor": {
"$ref": "#/components/schemas/v202210BgpMonitor"
}
},
"title": "CreateMonitorResponse"
},
"v202210DeleteMonitorResponse": {
"type": "object",
"title": "DeleteMonitorResponse"
},
"v202210GetMetricsForTargetRequest": {
"type": "object",
"properties": {
"startTime": {
"type": "string",
"format": "date-time",
"description": "UTC timestamp of the beginning of queried interval"
},
"endTime": {
"type": "string",
"format": "date-time",
"description": "UTC timestamp of the end of queried interval"
},
"target": {
"$ref": "#/components/schemas/v202210Nlri"
},
"includeCovered": {
"type": "boolean",
"description": "Return metrics for subnets (sub-prefixes) of the target prefix (default: false)"
},
"metrics": {
"type": "array",
"items": {
"$ref": "#/components/schemas/v202210BgpMetricType"
},
"description": "List of one or more BGP metric types to return"
}
},
"title": "GetMetricsForTargetRequest",
"required": [
"startTime",
"endTime",
"target",
"metrics"
]
},
"v202210GetMetricsForTargetResponse": {
"type": "object",
"properties": {
"metrics": {
"type": "array",
"items": {
"$ref": "#/components/schemas/v202210BgpMetric"
},
"description": "List of observations (metric values)",
"readOnly": true
}
},
"title": "GetMetricsForTargetResponse"
},
"v202210GetMonitorResponse": {
"type": "object",
"properties": {
"monitor": {
"$ref": "#/components/schemas/v202210BgpMonitor"
}
},
"title": "GetMonitorResponse"
},
"v202210GetRoutesForTargetRequest": {
"type": "object",
"properties": {
"time": {
"type": "string",
"format": "date-time",
"description": "Reference UTC time for the route information snapshot"
},
"target": {
"$ref": "#/components/schemas/v202210Nlri"
},
"includeCovered": {
"type": "boolean",
"description
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kentik/refs/heads/main/openapi/kentik-bgp-monitoring-openapi.json