Kentik Devices API (v6)
Register and manage the network devices (routers, hosts, agents) exporting telemetry to Kentik.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Device API",
"description": "# Overview\nThe Device API provides programmatic access to configuration of devices",
"version": "v202504beta2",
"contact": {
"name": "Kentik API Engineering",
"url": "https://github.com/kentik/api-schema-public"
}
},
"tags": [
{
"name": "DeviceService"
}
],
"paths": {
"/device/v202504beta2/device": {
"get": {
"summary": "List all devices.",
"description": "Returns list of configured devices. Use the 'view' parameter to control response detail: FULL (default), BASIC (id, name, status), or ID_ONLY (id only). See [About Devices](https://kb.kentik.com/v4/Cb01.htm).",
"operationId": "ListDevices",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2ListDevicesResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "query.noCustomColumns",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "view",
"description": "Controls the amount of detail returned for each device. Defaults to FULL.\n\n - DEVICE_VIEW_UNSPECIFIED: When unspecified, defaults to FULL for backward compatibility.\n - DEVICE_VIEW_FULL: Returns the full device configuration with all fields populated.\n - DEVICE_VIEW_BASIC: Returns only basic device information: id, device_name, device_status.\n - DEVICE_VIEW_ID_ONLY: Returns only device IDs.",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"DEVICE_VIEW_UNSPECIFIED",
"DEVICE_VIEW_FULL",
"DEVICE_VIEW_BASIC",
"DEVICE_VIEW_ID_ONLY"
],
"default": "DEVICE_VIEW_UNSPECIFIED"
}
}
],
"tags": [
"DeviceService"
]
},
"post": {
"summary": "Configure a new device.",
"description": "Create configuration for a new device. Returns the newly created configuration (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "CreateDevice",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2CreateDeviceResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2CreateDeviceRequest"
}
}
},
"required": true
},
"tags": [
"DeviceService"
]
}
},
"/device/v202504beta2/device/batch_create": {
"post": {
"summary": "Configure multiple devices (max 100).",
"description": "Create configuration for multiple devices. Returns the newly created configurations (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "CreateDevices",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2CreateDevicesResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2CreateDevicesRequest"
}
}
},
"required": true
},
"tags": [
"DeviceService"
]
}
},
"/device/v202504beta2/device/batch_delete": {
"post": {
"summary": "Delete configuration of multiple devices.",
"description": "Deletes configuration of multiple devices with specific IDs (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "DeleteDevices",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2DeleteDevicesResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2DeleteDevicesRequest"
}
}
},
"required": true
},
"tags": [
"DeviceService"
]
}
},
"/device/v202504beta2/device/batch_update": {
"put": {
"summary": "Updates configuration of multiple devices (max 100).",
"description": "Replaces configuration of multiple devices with attributes in the request. Returns the updated configurations (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "UpdateDevices",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2UpdateDevicesResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2UpdateDevicesRequest"
}
}
},
"required": true
},
"tags": [
"DeviceService"
]
}
},
"/device/v202504beta2/device/name/{deviceName}": {
"get": {
"summary": "Retrieve configuration of a device by name.",
"description": "Returns configuration of a device specified by name (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "GetDeviceByName",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2GetDeviceByNameResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "deviceName",
"description": "Name of the requested device",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "query.noCustomColumns",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"tags": [
"DeviceService"
]
}
},
"/device/v202504beta2/device/{device.id}": {
"put": {
"summary": "Updates configuration of a device.",
"description": "Replaces configuration of a device with attributes in the request. Returns the updated configuration (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "UpdateDevice",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2UpdateDeviceResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "device.id",
"description": "System generated unique identifier",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceServiceUpdateDeviceBody"
}
}
},
"required": true
},
"tags": [
"DeviceService"
]
},
"get": {
"summary": "Retrieve configuration of a device.",
"description": "Returns configuration of a device specified by ID (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "GetDevice",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2GetDeviceResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "device.id",
"description": "ID of the requested device",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "query.noCustomColumns",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"tags": [
"DeviceService"
]
},
"delete": {
"summary": "Delete configuration of a device.",
"description": "Deletes configuration of a device with specific ID (see [About Devices](https://kb.kentik.com/v4/Cb01.htm)).",
"operationId": "DeleteDevice",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2DeleteDeviceResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "device.id",
"description": "ID of the device to be deleted",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"DeviceService"
]
}
},
"/device/v202504beta2/device/{id}/labels": {
"put": {
"summary": "Updates labels of a device.",
"description": "Removes all existing labels from the device and applies the device labels (see [About Device Labels](https://kb.kentik.com/v4/Cb16.htm)) specified by id. Returns the updated configuration.",
"operationId": "UpdateDeviceLabels",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202504beta2UpdateDeviceLabelsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "ID of the device to be updated",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceServiceUpdateDeviceLabelsBody"
}
}
},
"required": true
},
"tags": [
"DeviceService"
]
}
}
},
"security": [
{
"email": [],
"token": []
}
],
"externalDocs": {
"description": "General information about Kentik APIs",
"url": "https://kb.kentik.com/v0/Ab09.htm#Ab09-APIs_Overview"
},
"components": {
"securitySchemes": {
"email": {
"type": "apiKey",
"name": "X-CH-Auth-Email",
"in": "header"
},
"token": {
"type": "apiKey",
"name": "X-CH-Auth-API-Token",
"in": "header"
}
},
"schemas": {
"DeviceServiceUpdateDeviceBody": {
"type": "object",
"properties": {
"device": {
"type": "object",
"properties": {
"deviceName": {
"type": "string",
"description": "Device name (device_name) - The name of the device. Valid characters: alphanumeric and underscores. Length: min=4, max=60."
},
"deviceSubtype": {
"type": "string",
"description": "Device subtype (device_subtype) - The device subtype."
},
"cdnAttr": {
"type": "string",
"description": "CDN attributes (cdn_attr) - If this is a DNS server, you can contribute its queries to Kentik's CDN attribution database. Valid values: \"Y\" or \"N\". ** cdn_attr is required when the device subtype's parent type is \"host-nprobe-dns-www\""
},
"deviceDescription": {
"type": "string",
"description": "Description (device_description) - The device description. Valid characters: any. Length: max=128."
},
"sendingIps": {
"type": "array",
"items": {
"type": "string"
},
"description": "Device ip (sending_ips) - Array containing one or more IP address(es), from which the device is sending flow. ** sending_ips is required when the device subtype's parent type is \"router\""
},
"deviceSampleRate": {
"type": "number",
"format": "double",
"description": "Sample rate (device_sample_rate) - The rate at which the device is sampling flows. Valid values: integer bigger than 1. Recommended rate varies depending on flow volume; see https://kb.kentik.com/Ab02.htm#Ab02-Flow_Sampling. ** device_sample_rate is required when the device subtype's parent type is \"router\""
},
"planId": {
"type": "integer",
"format": "int64",
"description": "Plan (plan_id) - The ID of the plan to which this device is assigned. Available plan(s) can be found via the Plans API. Valid value: integer."
},
"siteId": {
"type": "integer",
"format": "int64",
"description": "Site (site_id) - The ID of the site (if any) to which this device is assigned. Site IDs are system generated when a site is created. Valid value: integer."
},
"minimizeSnmp": {
"type": "boolean",
"description": "SNMP polling (minimize_snmp) - The interval at which SNMP will be polled. If \"false\" (Standard), interface counter will be polled every 10 minutes and interface description every 30 minutes. If \"true\" (Minimum) (Minimum), interface counter won't be polled and interface description will be polled every 6 hours. ** minimize_snmp is required when the device subtype's parent type is \"router\""
},
"deviceSnmpIp": {
"type": "string",
"description": "Device SNMP IP (device_snmp_ip) - The SNMP IP to use when polling the device. device_snmp_ip is ignored unless the device subtype's parent type is \"router\""
},
"deviceSnmpCommunity": {
"type": "string",
"description": "SNMP community (device_snmp_community) - The SNMP community to use when polling the device. device_snmp_community is ignored unless the device subtype's parent type is \"router\""
},
"deviceSnmpV3Conf": {
"$ref": "#/components/schemas/v202504beta2DeviceSnmpV3Conf"
},
"deviceBgpType": {
"type": "string",
"description": "BGP (device_bgp_type) - Device bgp type. Valid values: \"none\" (use generic IP/ASN mapping), \"device\" (peer with the device itself), \"other_device\" (share routing table of existing peered device)"
},
"deviceBgpNeighborIp": {
"type": "string",
"description": "Your IPv4 peering address (device_bgp_neighbor_ip) - A valid IPv4 address to use for peering with the device. ** An IPv4 and/or IPv6 peering address is required when device_bgp_type is set to \"device\""
},
"deviceBgpNeighborIp6": {
"type": "string",
"description": "Your IPv6 peering address (device_bgp_neighbor_ip6) - A valid IPv6 address to use for peering with the device. ** An IPv4 and/or IPv6 peering address is required when device_bgp_type is set to \"device\""
},
"deviceBgpNeighborAsn": {
"type": "string",
"description": "Your ASN (device_bgp_neighbor_asn) - The valid AS number (ASN) of the autonomous system that this device belongs to. ** device_bgp_neighbor_asn is required when device_bgp_type is set to \"device\""
},
"deviceBgpPassword": {
"type": "string",
"description": "BGP md5 password (device_bgp_password) - Optional BGP MD5 password (shared authentication password for BGP peering). Valid characters: printable ASCII excluding space and question mark. Length: 32. device_bgp_password is optional when device_bgp_type is set to \"device\""
},
"useBgpDeviceId": {
"type": "string",
"description": "Select master BGP device (use_bgp_device_id) - The ID of the device whose BGP table should be shared with this device. ** use_bgp_device_id is required when device_bgp_type is set to \"other_device\"). Valid value: a system-generated device_id"
},
"deviceBgpFlowspec": {
"type": "boolean",
"description": "BGP Flowspec Compatibility (device_bgp_flowspec) - Toggle BGP Flowspec Compatibility for device."
},
"nms": {
"$ref": "#/components/schemas/v202504beta2DeviceNmsConfig"
},
"deviceBgpCredentialName": {
"type": "string",
"description": "BGP Credential Name (device_bgp_credential_name) - Unsupported Field. Use device_bgp_password instead."
},
"flowSnmpCredentialName": {
"type": "string",
"description": "Snmp Credential Name (flow_snmp_credential_name) - Optional Credential Name (Credential for Flow Snmp peering). Valid characters: alphanumeric. Length: 32."
},
"monitoringTemplateId": {
"type": "integer",
"format": "int64",
"description": "Monitoring template - The ID of the monitoring template assigned to this device."
},
"deviceAlert": {
"type": "string",
"description": "Device alert - The device alert endpoint URL."
}
},
"title": "DeviceConcise"
}
},
"title": "UpdateDeviceRequest",
"required": [
"device"
]
},
"DeviceServiceUpdateDeviceLabelsBody": {
"type": "object",
"properties": {
"labels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/v202504beta2LabelConcise"
},
"description": "List of labels to be added to the device"
}
},
"title": "UpdateDeviceLabelsRequest",
"required": [
"labels"
]
},
"devicev202504beta2Label": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Label ID"
},
"name": {
"type": "string",
"description": "Label name"
},
"description": {
"type": "string",
"description": "Label description"
},
"edate": {
"type": "string",
"format": "date-time",
"description": "Label end date (UTC)"
},
"cdate": {
"type": "string",
"format": "date-time",
"description": "Label creation date (UTC)"
},
"userId": {
"type": "string",
"description": "User ID"
},
"companyId": {
"type": "string",
"description": "Company ID"
},
"color": {
"type": "string",
"description": "Label color"
},
"order": {
"type": "string",
"description": "Label order"
},
"pivotDeviceId": {
"type": "string",
"description": "Pivot device ID"
},
"pivotLabelId": {
"type": "string",
"description": "Pivot label ID"
}
},
"title": "Label"
},
"protobufAny": {
"type": "object",
"properties": {
"@type": {
"type": "string"
}
},
"a
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kentik/refs/heads/main/openapi/kentik-device-openapi.json