---
title: "Network Assets APIs"
slug: "network-assets-apis"
description: "Explore Kentik V5 Admin APIs for managing network assets, devices, and interfaces programmatically with detailed JSON responses and cURL integration."
updated: 2025-08-26T23:40:23Z
published: 2025-08-26T23:40:23Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.kentik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Assets APIs

This article discusses the network assets APIs of the Kentik V5 Admin APIs.

> [!NOTE]
> **Notes:**
> 
> - For an overview of all Kentik APIs, see [**Kentik APIs**](/v1/docs/apis-overview).
> - For information on using APIs with cURL, see [**API Access Via cURL**](/v1/docs/apis-overview#api-access-via-curl)
> - For help using any API version, contact [**support@kentik.com**](mailto:support@kentik.com).

## About Network Assets APIs

The Kentik V5 Admin APIs offer "network assets" APIs for programmatically managing settings in the Admin section of the Kentik portal, including the following:

- **Devices and interfaces**: Managed via the [**Device API**](/v1/docs/network-assets-apis#device-api), offering similar functionality to the portal’s [**Device Settings Dialog**](/v1/docs/network-devices#device-settings-dialog).
- **Device labels**: Managed via the [**Device Label API**](/v1/docs/network-assets-apis#device-label-api), provides functionality equivalent to the portal’s [**Labels Page**](/v1/docs/labels#labels-page).

## Device API

The Device API allows you to manage your organization's devices in Kentik.

> [!NOTE]
> **Notes:**
> 
> - Member-level users only have access to the GET methods of this API.
> - For information on adding and managing devices via the Kentik portal, see [**Manage Devices**](/v1/docs/network-devices#manage-devices).
> - To make calls to this API using cURL, see [**API Access Via cURL**](/v1/docs/apis-overview#api-access-via-curl).
> - The V5 API tester was discontinued in January 2025.

### Device JSON

Device API calls return an HTTP response with a JSON device object, or, an array of such objects for the Device List call. The object contains the fields (name/value pairs) shown in the following example:

```json
{
"device": {
"id": "9623",
     "company_id": "1289",
     "device_name": "pd_router",
     "device_subtype": "router",
     "device_description": "test of device settings",
     "plan_id": 123,
     "site_id": 394,
     "device_flow_type": "netflow.v5",
     "device_sample_rate": "1024",
     "sending_ips": [
       "142.254.47.216"
    ],
    "device_snmp_ip": "142.254.47.216",
     "device_snmp_community": "",
     "minimize_snmp": false,
     "device_bgp_type": "device",
     "device_bgp_neighbor_ip": "142.254.47.216",
     "device_bgp_neighbor_asn": "5001",
     "device_bgp_password": null,
     "use_bgp_device_id": null,
     "custom_columns": null,
     "created_date": "2016-09-09T17:27:18.080Z",
     "updated_date": "2016-09-09T17:27:18.080Z"
     "device_snmp_v3_conf": {
       "UserName": "eenie",
       "AuthenticationProtocol": "MD5",
       "AuthenticationPassphrase": "meenie",
       "PrivacyProtocol": "DES",
       "PrivacyPassphrase": "minie"
     },
   }
 }
```

Each device object contains fields with information about an individual device registered in Kentik to your organization. These fields are detailed in the following tables.

#### Device Object

| JSON name | Type | Description |
| --- | --- | --- |
| id | number | The system-assigned device ID. |
| company_id | number | The system-assigned ID of the company (organization). |
| device_name | string | User-supplied device name. |
| device_subtype | string | The subtype of the device, see [**Device Subtypes**](/v1/docs/network-assets-apis#device-subtypes). |
| device_description | string | User-supplied device description. |
| plan_id | number | The ID of the plan to which this device is assigned. Available plans can be found via the Plans API. - Valid value: integer. |
| site_id | number | The system-assigned ID of the site, if any, to which this device is assigned. |
| device_flow_type | string | For routers, the flow type sent to Kentik (NetFlow v5, NetFlow v9, sFlow, or IPFIX). For hosts, it’s IPFIX, the flow type sent from the Kentik nProbe host agent. > [!NOTE] > **Note:** Kentik auto-detects flow type. |
| device_sample_rate | string | Total packets transiting the device for each packet processed for flow data (see [**Flow Sampling**](/v1/docs/flow-overview#flow-sampling)). |
| sending_ips | array of strings | IPs from which the device will send flow to Kentik. |
| device_snmp_ip | string | The IP address for polling the device (router). |
| device_snmp_community | string | The SNMP community for polling the device (router). |
| minimize_snmp | boolean | - The SNMP polling interval - If false (standard), interface counter is polled every 5 minutes and interface description every 30 minutes. - If true (minimized), interface counter is not polled, and interface description is polled every 6 hours. |
| device_bgp_type | string | Reserved for internal use. |
| device_bgp_neighbor_ip | string | BGP Neighbor IP |
| device_bgp_neighbor_asn | string | BGP Neighbor ASN (16- or 32-bit) |
| device_bgp_password | string | BGP Password |
| use_bgp_device_id | string | Use this device's BGP table instead of creating a new BGP session. |
| custom_columns | N.A. | Internal use only. |
| created_date | string | Date-time of registration of the device in Kentik creation, in UTC (ISO 8601), e.g., 2015-01-27T01:39:17.186Z |
| updated_date | string | Date-time of last edit to the device in UTC, e.g., 2015-01-27T01:39:17.186Z |
| device_snmp_v3_conf | object | See [**Device_snmp_v3_conf Object**](/v1/docs/network-assets-apis#devicesnmpv3conf-object) |

> [!NOTE]
> **Note:** For more details about the settings indicated by the name/value pairs, see [**Device Settings Dialog**](/v1/docs/network-devices#device-settings-dialog).

#### Device Subtypes

Kentik supports the device subtypes found in the Subtype column of the table in [**Supported Device Types**](/v1/docs/network-devices#supported-device-types).

#### Device_snmp_v3_conf Object

| JSON name | Type | Description |
| --- | --- | --- |
| UserName | string | The user name for SNMP v3 authentication. > [!NOTE] > **Note:** Required if AuthenticationProtocol is MD5 or SHA, or if PrivacyProtocol is DES or AES-128. |
| AuthenticationProtocol | string | SNMP v3 authentication protocol. - Valid values: NoAuth (none), MD5, SHA. |
| AuthenticationPassphrase | string | Password for SNMP V3 authentication. > [!NOTE] > **Note:** Required if AuthenticationProtocol is MD5 or SHA. |
| PrivacyProtocol | string | The SNMP V3 privacy type: - Valid values: NoPriv (none), DES (56-bit DES encryption), AES-128. |
| PrivacyPassphrase | string | Password for SNMP V3 privacy. > [!NOTE] > **Note:** Required if PrivacyProtocol is DES or AES-128. |

  

### Device List

The Device List `GET` method fetches JSON array of your Kentik devices, with each element representing an individual device.

> [!NOTE]
> **Note:** The “id” value in each device object can be used in subsequent calls to retrieve, update, or delete that specific device.

**HTTP Request**

The following table shows the path and HTTP request for this call:

| **URL** | https://api.kentik.com/api/v5/devices |
| --- | --- |
| **Request** | GET /api/v5/devices HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **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 Device List method includes the following elements:

- Response headers
- HTTP response code
- Response body with a JSON device array, where each element is a device object containing device information.

> [!NOTE]
> **Note:** For details on the JSON name/value pairs in a device object, see [**Device JSON**](/v1/docs/network-assets-apis#device-json).

### Device Info

The Device Info `GET` method fetches details of a single device, identified by its ID, from your Kentik devices list.

**HTTP Request**

The following table shows the path and HTTP request for this call:

| **URL** | https://api.kentik.com/api/v5/device/device_id |
| --- | --- |
| **Request** | GET /api/v5/device/device_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes:**
> 
> - The “device_id” in the path corresponds to the “id” value in each `device` object from the [**Device List**](/v1/docs/network-assets-apis#device-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 Device Info method includes the following elements:

- Response headers
- HTTP response code
- A single JSON `device` object with details about the device specified by `device_id`.

> [!NOTE]
> **Note:** For details on the JSON name/value pairs in a `device` object, see [**Device JSON**](/v1/docs/network-assets-apis#device-json).

### Device Create

The Device Create `POST` method adds a new device to Kentik.

**HTTP Request**

The following table shows the path and HTTP request for this call:

| **URL** | https://api.kentik.com/api/v5/device |
| --- | --- |
| **Request** | POST /api/v5/device HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **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 request body includes the following parameters in a JSON object:

| Parameter | Type | Description |
| --- | --- | --- |
| device_name | string | Required: The name of the device: - Valid characters: alphanumeric and underscores. - Length: min=4, max=60. |
| Device_subtype | string | Required: The type of device: - Valid values: see [**Device Subtypes**](/docs/network-assets-apis#Ec05-Device_Subtypes). |
| Device_description | string | A description of this device: - Valid characters: any. - Length: max=128. |
| Plan_id | number | Required: The ID of the plan to which this device is assigned. Available plans can be found via the Plans API. - Valid value: integer. |
| Site_id | number | The ID of the site, if any, to which this device will be assigned. Site IDs are system-generated upon site creation. - Valid value: integer. |
| Device_sample_rate | string | Required: Total packets transiting the device for each packet processed for flow data. |
| Sending_ips | array of strings | Required: The IP(s) from which flow is sent. > [!NOTE] > **Note:** The IP must not already be sending flow to another device registered in Kentik. |
| Device_snmp_ip | string | The SNMP IP for polling the device. > [!NOTE] > **Note:** Ignored unless device_subtype is set to router. |
| Device_snmp_community | string | The SNMP community for polling the device. > [!NOTE] > **Note:** Ignored unless device_subtype is set to router. |
| Minimize_snmp | boolean | Required when device type is router: The interval at which SNMP will be polled: - If false (standard), interface counter is polled every 5 minutes and interface description every 3 hours. - If true (minimized), interface counter is not polled and interface description is polled every 6 hours. |
| Device_snmp_v3_conf | object | See [**Setting device_snmp_v3_conf**](/v1/docs/network-assets-apis#setting-devicesnmpv3conf). > [!NOTE] > **Note:** If included, Kentik will poll this router with SNMP V3. |
| Device_bgp_type | string | Required: 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) |
| device_bgp_neighbor_ip | string | A valid IPv4 address for peering with this device. > [!NOTE] > **Notes:** > > - Either this or its IPv6 equivalent is required when device_bgp_type is set to “device.” > - IP must not already be peering with another Kentik device. |
| Device_bgp_neighbor_ip6 | string | A valid IPv6 address for peering with this device. > [!NOTE] > **Notes:** > > - Either this or its IPv4 equivalent is required when device_bgp_type is set to “device.” > - IP must not already be peering with another Kentik device. |
| Device_bgp_neighbor_asn | string | The valid ASN (16 or 32-bit) of the autonomous system to which this device belongs. > [!NOTE] > **Note:** Required when device_bgp_type is set to “device.” |
| Device_bgp_password | string | Optional BGP MD5 password (shared authentication password for BGP peering). Valid characters: alphanumeric. Length: 32. > [!NOTE] > **Note:** Required when device_bgp_type is set to “device.” |
| Use_bgp_device_id | string | The ID of the device whose BGP table will be shared with this device. > [!NOTE] > **Note:** Required when device_bgp_type is set to “other_device”). > > - Valid value: a system-generated device_id. |

#### Setting device_snmp_v3_conf

The `device_snmp_v3_conf` object is included in request JSON to use SNMP V3 for router polling. If omitted, Kentik will assume SNMP V3 is intended.

| Parameter | Type | Description |
| --- | --- | --- |
| UserName | string | The username for SNMP v3 authentication. > [!NOTE] > **Note:** Required if AuthenticationProtocol is MD5 or SHA, or if PrivacyProtocol is DES or AES-128. |
| AuthenticationProtocol | string | SNMP v3 authentication protocol. - Valid values: NoAuth (none), MD5, SHA. |
| AuthenticationPassphrase | string | Password for SNMP V3 authentication. > [!NOTE] > **Note:** Required if AuthenticationProtocol is MD5 or SHA. |
| PrivacyProtocol | string | The SNMP V3 privacy type: - Valid values: NoPriv (none), DES (56-bit DES encryption), AES-128. |
| PrivacyPassphrase | string | Password for SNMP V3 privacy. > [!NOTE] > **Note:** Required if PrivacyProtocol is DES or AES-128. |

> [!NOTE]
> **Note:** SNMP V3 authentication and privacy settings are independent. To disable both, set AuthenticationProtocol to NoAuth and PrivacyProtocol to NoPriv.

**HTTP Response**

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

- Response headers
- HTTP response code
- A single JSON `device` object with details about the newly-added device

> [!NOTE]
> **Note:** For details on the JSON name/value pairs in a `device` object, see [**Device JSON**](/v1/docs/network-assets-apis-1#device-json).

### Device Update

The Device Update `PUT` method updates data for a specific device, identified by ID, in your Kentik devices list.

**HTTP Request**

The following table shows the path and HTTP request for this call:

| **URL** | https://api.kentik.com/api/v5/device/device_id |
| --- | --- |
| **Request** | PUT /api/v5/device/device_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes:**
> 
> - The “device_id” in the path corresponds to the “id” in each device object from the [**Device List**](/v1/docs/network-assets-apis#device-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.

Pass the parameters to be updated in a JSON `device` object containing only the fields to be changed. Here’s an example for updating a device’s description:

```json
{
“device”: {
     “device_description”: “This is a really wonderful device.”
   }
 }
```

**HTTP Response**

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

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

> [!NOTE]
> **Note:** For details on the JSON name/value pairs in a `device` object, see [**Device JSON**](/v1/docs/network-assets-apis#device-json).

### Device Apply Labels

The Device Apply Labels PUT method removes all existing labels (see [**Labels**](/v1/docs/labels)) from the specified device and applies the specified new labels.

> [!NOTE]
> **Notes:**
> 
> - If no labels are specified, this method will still remove all existing labels from the specified device.
> - To create and manage device labels via API, see [**Device Label API**](/v1/docs/network-assets-apis#device-label-api).

**HTTP Request**

The following table shows the path and HTTP request for this call:

| **URL** | api.kentik.com/api/v5/devices/device_id/labels |
| --- | --- |
| **Request** | POST /api/v5/devices/device_id/labels HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **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:

| Parameter | Type | Description |
| --- | --- | --- |
| labels | array | An array of id objects. > [!NOTE] > **Note:** Omitting the labels array in the request body will result in the removal of all existing labels without adding new ones. |
| id | integer | The id of a label to apply to the device. |

The example below shows a request body for adding two labels to a device.

```json
{
"labels": [
    {
      "id": 1096
    },
    {
      "id": 32
    }
  ]
 }
```

**HTTP Response**

A successful response from the Device Apply Labels method includes the following elements:

- Response headers
- HTTP response code
- A single JSON device object with a labels array showing the labels assigned to the device post-operation. An example of a successful label application is provided below.

```json
{
"id": "device_id",
"device_name": "device_name",
"labels": [
    {
      "id": label_id,
      "name": "label_name",
      "edate": "2019-03-07T00:53:51.759Z",
      "cdate": "2019-03-07T00:53:51.759Z",
      "user_id": "#####",
      "company_id": "####",
      "color": "#800000",
    }
  ]
 }
```

> [!NOTE]
> **Note:** For details on the JSON name/value pairs in an individual labels object, see [**Device Label Object**](/v1/docs/network-assets-apis#device-label-object).

### Device Delete

The Device Delete method removes one device, identified by ID, from your collection of Kentik devices.

**HTTP Request**

The following table shows the path and HTTP request for this call:

| **URL** | https://api.kentik.com/api/v5/device/device_id |
| --- | --- |
| **Request** | DELETE /api/v5/device/device_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes:**
> 
> - The “device_id” in the path corresponds to the “id” in each `device` object from the [**Device List**](/v1/docs/network-assets-apis#device-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 Device Delete method includes the following elements:

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

### Interface JSON

The interface methods of the Device API return an HTTP response body with an "interface" JSON object (or an array of objects for the Interface List call). The object includes name/value pairs as shown in the following example:

```json
{
"id": "9201304925",
"company_id": "1289",
"device_id": "2951",
"snmp_id": "150",
"snmp_speed": "1000",
"snmp_type": 6,
"snmp_type": 53,
"snmp_alias": "irs",
"interface_ip": "198.186.192.33",
"interface_description": "Vlan350",
"interface_kvs": "\"updated\"=>\"1\"",
"interface_tags": "",
"interface_status": "V",
"cdate": "2017-04-19T00:40:01.145Z",
"edate": "2017-05-03T03:20:27.303Z",
"initial_snmp_id": "150",
"initial_snmp_alias": "irs",
"initial_interface_description": "Vlan350",
"initial_snmp_speed": "1000",
"interface_ip_netmask": "255.255.255.224",
"secondary_ips": [
    {
      "address": "198.186.193.51",
      "netmask": "255.255.255.240"
    }
  ],
"connectivity_type": "",
"network_boundary": "",
"initial_connectivity_type": "",
"initial_network_boundary": ""
"top_nexthop_asns": null,
"provider":"",  
"initial_provider": "",
"vrf_id": ####
"vrf": {
     "name" : "test_vrf",
     "description" : "This is still a test",
     "route_distinguisher" : "11.121.111.13:3254",
     "ext_route_distinguisher" : 296507164417724,
     "route_target" : "101:100"
   }
 }
```

Each interface object contains fields with information about an individual interface on a Kentik-registered device. These fields are described in the following tables.

> [!NOTE]
> **Note:** For details on the settings represented by the name/value pairs (see [**Interfaces Page**](/v1/docs/interfaces#interfaces-page)).

#### Interface Object

An `interface` object contains all the information about an individual interface of a device registered with Kentik.

| JSON name | Type | Description |
| --- | --- | --- |
| id | string | The system-assigned ID of the interface. |
| Company_id | string | The system-assigned ID of the customer. |
| Device_id | string | The system-assigned ID of the device to which this interface belongs. |
| Snmp_id | string | The interface index (ifIndex) as defined in the device and retrieved via SNMP. Same as initial_snmp_id unless manually overridden when device is created or updated in Kentik. |
| Snmp_speed | number | The capacity of the interface in Mbps. Same as initial_snmp_speed unless manually overridden when device is created or updated in Kentik. |
| Snmp_type | integer | Reserved for internal use. |
| Snmp_alias | string | User-specified text used by Kentik as the description of the interface. Same as initial_interface_description unless manually overridden when device is created or updated in Kentik. |
| Interface_ip | string | The IP address assigned to the interface. |
| Interface_description | string | User-specified text used by Kentik as the name of the interface. Same as initial_snmp_alias unless manually overridden when device is created or updated in Kentik. |
| Interface_kvs | number | Reserved for internal use. |
| Interface_tags | number | Reserved for internal use. |
| Interface_status |  | Reserved for internal use. |
| Cdate | string | Date-time of registration of the interface in Kentik creation, in UTC (ISO 8601), e.g. 2015-01-27T01:39:17.186Z |
| edate | string | Date-time of last edit to the interface, in UTC, e.g. 2015-01-27T01:39:17.186Z |
| initial_snmp_id | string | Last SNMP-polled SNMP ID of the interface on its device. |
| Initial_snmp_alias | string | Last SNMP-polled interface description. |
| Initial_interface_description | string | Last SNMP-polled interface name. |
| initial_snmp_speed | string | Last SNMP-polled interface capacity (Mbps). |
| Interface_ip_netmask | string | The netmask configured for the interface (applies to Ipv4 interfaces only). |
| Secondary_ips | array | See [**secondary_ips Array**](/v1/docs/network-assets-apis#secondaryips-array). |
| Connectivity_type | string | Reserved for internal use. |
| Network_boundary | string | Reserved for internal use. |
| Initial_connectivity_type | string | Same as connectivity_type. |
| Initial_network_boundary | string | Same as network_boundary. |
| Top_nexthop_asns | array | An array of ASNs, see [**Top Next Hop ASNs**](/v1/docs/network-assets-apis#top-next-hop-asns). |
| Provider | object | The provider, as determined by provider classification, via which traffic from a given externally facing interface reaches the Internet; see [**Provider Classification**](/v1/docs/interface-classification#provider-classification). |
| initial_provider | string | Reserved for internal use. |
| vrf_id | string | If the interface is assigned to a VRF, the ID of that VRF, otherwise null. |
| vrf | string | Present only if the interface is assigned to a VRF; see [**VRF Attributes**](/v1/docs/network-assets-apis#vrf-attributes). |

#### secondary_ips Array

The `secondary_ips` array contains one or more objects, each specifying a secondary IP address for the interface.

| JSON name | Type | Description |
| --- | --- | --- |
| address | string | A secondary IP for the interface. |
| netmask | string | The netmask configured for this secondary interface_ip (applies to IPv4 interfaces only). |

#### Top Next Hop ASNs

An array of objects showing ASNs that received the most packets from the interface in the past hour.

| JSON name | Type | Description |
| --- | --- | --- |
| ASN | number | The AS number. |
| packets | number | The number of packets in the hour preceding the call. |

#### VRF Attributes

The `vrf` object, present only if the interface is assigned to a VRF, consists of elements corresponding to each VRF attribute:

| Parameter | Type | Description |
| --- | --- | --- |
| name | string | Name of the VRF entry. |
| description | string | Description of the VRF entry. |
| route_target | string | Route Target Community of the VRF entry. |
| route_distinguisher | string | Route Distinguisher of the VRF entry. |
| ext_route_distinguisher | integer | External Route Distinguisher of the VRF entry. |

  

### Interface List

The Interface List `GET` method retrieves a JSON array of Kentik interfaces for a specified device, with each element representing an individual interface.

> [!NOTE]
> **Note:** The "id" value in each interface object can be used in subsequent calls to retrieve, update, or delete that specific interface.

**HTTP Request**

The following table shows the path and HTTP request for this call:

| URL | https://api.kentik.com/api/v5/device/device_id/interfaces |
| --- | --- |
| Request | GET /api/v5/device/device_id/interfaces HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **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 Interface List method includes:

- Response headers
- HTTP response code
- A JSON response body with an array of interface objects, each representing an interface of the specified device.

> [!NOTE]
> **Note:** For details of the JSON name/value pairs in an interface object, see [**Interface JSON**](/v1/docs/network-assets-apis#interface-json).

### Interface Info

The Interface Info `GET` method fetches details about a single interface, identified by its ID, from the specified device's collection of interfaces.

**HTTP Request**

The following table shows the path and HTTP request for this call:

| **URL** | https://api.kentik.com/api/v5/device/device_id/interface/interface_id |
| --- | --- |
| **Request** | GET /api/v5/device/device_id/interface/interface_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes:**
> 
> - The “interface_id” in the path corresponds to the “id” in each interface object from the [**Interface List**](/v1/docs/network-assets-apis#interface-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 `Interface` Info method includes the following elements:

- Response headers
- HTTP response code
- A single JSON `interface` object with details about the interface specified by `interface_id.`

> [!NOTE]
> **Note:** For details on the JSON name/value pairs in an `interface` object, see [**Interface JSON**](/v1/docs/network-assets-apis#interface-json).

### Interface Create

The Interface Create `POST` method adds a new interface to the specified Kentik-registered device’s collection of interfaces.

HTTP Request

The following table shows the path and HTTP request for this call:

| **URL** | https://api.kentik.com/api/v5/device/device_id/interface |
| --- | --- |
| **Request** | POST /api/v5/device/device_id/interface HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **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:

| Parameter | Type | Description |
| --- | --- | --- |
| device_id | string | Required: The system-assigned ID of the device to which this interface belongs. |
| snmp_id | string | Required: The interface index (ifIndex) as defined in the device and retrieved via SNMP. See [**Getting an Interface Index**](/v1/docs/interfaces#getting-an-interface-index). |
| interface_description | string | Required: User-specified text used by Kentik as the name of the interface. |
| snmp_alias | string | User-specified text used by Kentik as the description of the interface. |
| interface_ip | string | The IP address assigned to the interface. |
| interface_ip_netmask | string | The netmask configured for the interface (applies to IPv4 interfaces only). |
| snmp_speed | number | Required: The capacity of the interface in Mbps. |
| secondary_ips | array | Array of secondary_ip objects; see [**Secondary IPs Array**](/v1/docs/network-assets-apis#secondaryips-array). |
| vrf | object | An object specifying the VRF attributes of the interface; see [**VRF Object**](/v1/docs/network-assets-apis#vrf-object). |

#### Secondary IPs Array

An array of secondary IP objects, each of which must include the address and netmask parameters.

| Parameter | Type | Description |
| --- | --- | --- |
| address | string | In secondary_ip object, a secondary ip for the interface. |
| netmask | string | In secondary_ip object, the netmask configured for this secondary interface_ip (applies to IPv4 interfaces only) |

#### VRF Object

An object specifying the VRF attributes of the interface:

| Parameter | Type | Description |
| --- | --- | --- |
| name | string | Required: Name of the VRF entry. |
| description | string | Required: Description of the VRF entry. |
| route_target | string | Required: Route Target Community of the VRF entry. |
| route_distinguisher | string | Required: Route Distinguisher of the VRF entry. |
| ext_route_distinguisher | integer | External Route Distinguisher of the VRF entry. |

**HTTP Response**

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

- Response headers
- HTTP response code
- A single JSON `interface` object with details about the newly-added interface.

> **Note:** For details of the JSON name/value pairs in an interface object, see [**Interface JSON**](/v1/docs/network-assets-apis#interface-json).

### Interface Update

The Interface Update `PUT` method modifies system data for a specific interface, identified by ID, within the specified device's existing interfaces.

HTTP Request

The following table shows the path and HTTP request for this call:

| URL | https://api.kentik.com/api/v5/device/device_id/interface/interface_id |
| --- | --- |
| Request | PUT /api/v5/device/device_id/interface/interface_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes**:
> 
> - The “interface_id” in the path corresponds to the “id” in each interface object from the [**Interface List**](/v1/docs/network-assets-apis#interface-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

When updating an interface, the JSON object must include the required snmp_id and any fields to be updated (see table under HTTP Request in [**Interface Create**](/v1/docs/network-assets-apis#interface-create)). The following example shows an update to the interface’s description:

```json
{
"snmp_id": "150"
"interface_description": "This is a truly great interface."
 }
```

HTTP Response

A successful response from the Interface Update call includes the following elements:

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

> [!NOTE]
> **Note**: For details of the JSON name/value pairs in an `interface` object, see [**Interface JSON**](/v1/docs/network-assets-apis#interface-json).

### Interface Delete

The Interface Delete method removes a specified interface by ID from a Kentik-registered device’s collection of interfaces.

HTTP Request

The following table shows the path and HTTP request for this call:

| URL | https://api.kentik.com/api/v5/device/device_id/interface/interface_id |
| --- | --- |
| Request | DELETE /api/v5/device/device_id/interface/interface_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes**:
> 
> - The “interface_id” in the path corresponds to the “id” in each `interface` object from the [**Interface List**](/v1/docs/network-assets-apis#interface-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 Interface Delete method includes the following elements:

- Response headers
- The HTTP response code 204 (no content)

## Device Label API

The Device Label API allows for programmatic management of your device labels in Kentik.

> [!NOTE]
> **Notes**:
> 
> - Member-level users whose only have access to the GET methods of this API
> - For information on adding and managing device labels via the Kentik portal, see [**Labels**](/v1/docs/labels).
> - To make calls to this API using cURL, see [**API Access Via cURL**](/v1/docs/apis-overview#api-access-via-curl).

### Device Label JSON

Calls to the Device Label API return an HTTP response body with a JSON device label object, or an array of such objects for the Device Label List call. The object includes fields (name/value pairs) as shown in the following example:

```json
{
"id": 32,
"name": "ISP",
"color": "#f1d5b9",
"user_id": "#####",
"company_id": "####",
"order": 0,
"devices": [
    {
      "id": "#####",
      "device_name": "my_device_1",
      "device_subtype": "router"
    },
  ],
"created_date": "2018-05-16T20:21:10.406Z",
"updated_date": "2018-05-16T20:21:10.406Z"
 }
```

Each device label object contains fields with information about an individual device label. These fields are described in the following tables.

> [!NOTE]
> **Note**: For details of the settings represented by these name/value pairs, see [**Labels**](/v1/docs/labels).

#### Device Label Object

| JSON name | Type | Description |
| --- | --- | --- |
| id | number | The system-assigned ID of the device label. |
| name | string | User-specified text of the device label (e.g. "ISP"). |
| color | string | The color, in hex, associated with this device label (e.g., "#f1d5b9"). |
| user_id | string | The ID of the user who created or last edited the label. |
| company_id | string | The system-assigned ID of the customer in which the label exists. |
| devices | array | See [Devices Array for Labels](/v1/docs/network-assets-apis-1#devices-array-for-labels). |
| created_date | string | Date-time in UTC (ISO 8601) at which the device label was created (e.g., 2015-01-27T01:39:17.186Z). |
| updated_date | string | Date-time at which the label was most-recently edited. |

#### Devices Array for Labels

An array of `device` objects, each containing a subset of elements from the full `device` object (see [**Device JSON**](/v1/docs/network-assets-apis#device-json)), represents devices associated with labels. The table below lists the included elements.

| JSON name | Type | Description |
| --- | --- | --- |
| id | string | The system-assigned ID of the device. |
| device_name | string | Name specified by user when device was last edited. |
| device_subtype | string | See [**Device Subtypes**](/v1/docs/network-assets-apis#device-subtypes). |

  

### Device Label List

The Device Label List `GET` method retrieves a JSON array of device labels that currently existing in your organization, with each element representing an individual device label.

> [!NOTE]
> **Note**: The "id" value in each device label object can be used in subsequent calls to retrieve, update, or delete that specific device label.

HTTP Request

The following table shows the path and HTTP request for this call:

| URL | api.kentik.com/api/v5/deviceLabels |
| --- | --- |
| Request | GET /api/v5/deviceLabels HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **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 Device Label List call includes the following elements:

- Response headers
- HTTP response code
- A response body including a JSON array of device labels. Each element in the array is an object containing information about a device label.

> [!NOTE]
> **Note**: For details of the JSON name/value pairs in a device label object, see [**Device Label JSON**](/v1/docs/network-assets-apis#device-label-json).

### Device Label Info

The Device Label Info `GET` method fetches details of a specific device label by ID from your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call:

| URL | api.kentik.com/api/v5/deviceLabels/label_id |
| --- | --- |
| Request | GET api/v5/deviceLabels/label_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes**:
> 
> - The "label_id" in the path corresponds to the “id” in the device_label object from the [**Device Label List**](/v1/docs/network-assets-apis#device-label-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 Device Label Info method includes the following elements:

- Response headers
- HTTP response code
- A single JSON device label object with details about the device label specified by label_id.

> [!NOTE]
> **Note**: For details of the JSON name/value pairs in a device label object, see [**Device Label JSON**](/v1/docs/network-assets-apis#device-label-json).

### Device Label Create

The Device Label Create `POST` method adds a new device label to your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call:

| URL | api.kentik.com/api/v5/deviceLabels |
| --- | --- |
| Request | POST api/v5/deviceLabels HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **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:

| Parameter | Type | Description |
| --- | --- | --- |
| name | string | Required: A unique name for the device label. - Length: max=100. |
| color | string | Required: A color value expressed in hex (e.g. "#a9c5e0"). |

HTTP Response

A successful response from the Device Label Create method includes the following elements:

- Response headers
- HTTP response code
- A single JSON device label object with details about the newly-added device label.

> [!NOTE]
> **Note**: For details of the JSON name/value pairs in a device label object, see [**Device Label JSON**](/v1/docs/network-assets-apis#device-label-json).

### Device Label Update

The Device Label Update `PUT` method modifies data for a specified device label by ID in your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call:

| URL | api.kentik.com/api/v5/deviceLabels/label_id |
| --- | --- |
| Request | PUT /api/v5/deviceLabels/label_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes**:
> 
> - The "label_id" in the path corresponds to the “id” in the `device_label` object from the [**Device Label List**](/v1/docs/network-assets-apis#device-label-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 changed are passed in a JSON device label object:

- To update the label's name, include the `name` field only.
- To update the label's color, include both the `name` and `color` fields.

Example of a device label object to update the color to dark blue:

```json
{
"name": "Edge"
"color": "#000080"
 }
```

HTTP Response

A successful response from the Device Label Update method includes the following elements:

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

> [!NOTE]
> **Note**: For details on the JSON name/value pairs in a device label object, see [**Device Label JSON**](/v1/docs/network-assets-apis#device-label-json).

### Device Label Delete

The Device Label Delete method removes a device label by ID from your organization's collection.

HTTP Request

The following table shows the path and HTTP request for this call:

| URL | api.kentik.com/api/v5/deviceLabels/label_id |
| --- | --- |
| Request | DELETE /api/v5/deviceLabels/label_id HTTP/1.1 Host: api.kentik.com X-CH-Auth-API-Token: user_api_token X-CH-Auth-Email: user@domain.suffix Content-Type: application/json |

> [!NOTE]
> **Notes**:
> 
> - The "label_id" in the path corresponds to the “id” in the `device_label` object from the [**Device Label List**](/v1/docs/network-assets-apis#device-label-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 Device Label Delete method includes the following elements:

- Response headers
- HTTP response code
- A single JSON object confirming the operation completed successfully:

```json
{
"success": true
 }
```