Cisco SD-WAN vManage Rest API definitions
These APIs play an important role for clients to consume the features provided by vManage.
vManage REST API access control is based on sessions. All users will be able to get a session after successfully logging in.
Base URI
Every data service API request begins with the following Base URI.
https://{{vmanage}}:{{port}}/dataservice/
SdwanDevice resource type
Provides device resource type metrics information and its properties from the vManage dashboard.
- URI
-
https://{{vmanage}}:{{port}}/dataservice/device/interface?deviceId=<device_id>
- Sample URI
-
https://<IP_address>:8443/dataservice/device/interface?deviceId=10.10.1.17
- Method
- The supported request type.
https GET
- Response
-
The results are returned as JSON data that contains an array of the following fields:
Name Data type Description system-ip
string
IP address of the device number-vsmart-control-connections
number
Number vsmart control connections expectedControlConnections
number
Number of devices that can connect to the Cisco SD_WAN servers. rebootCount
number
Maximum number of restarts allowed. crashCount
number
Maximum number of unrecoverable crashes -
JSON code
{ "header": { "generatedOn": 1634185346348 }, "data": [ { "system-ip": "10.10.1.1", "number-vsmart-control-connections": 1, "expectedControlConnections": 1, "rebootCount": 3, "crashCount": 0 }, { "system-ip": "10.10.1.5", "number-vsmart-control-connections": 0, "expectedControlConnections": 0, "ompPeersUp": 0, "ompPeersDown": 0, "rebootCount": 2, "crashCount": 0 }, ... ] }
-
Interface resource type
Provides interface resource type metrics information and its properties from the vManage
dashboard.
- URI
-
https://{{vmanage}}:{{port}}/dataservice/device/counters
- Sample URI
-
https://<IP_address>:8443/dataservice/device/counters
- Method
- The supported request type
https GET
- URL parameters
-
Name Required Description deviceId
Yes Device ID for which interface metrics are obtained. - Response
-
The results are returned as JSON data that contains an array of the following fields:
Name Data type Description speed-mbps
string
Interface speed mtu
string
Maximum Transmission Unit (MTU) is the largest size in bytes that a certain layer can forward. vdevice-dataKey
string
It identifies the unique key for each record in the output. vpn-id
string
Cisco VPN identification number ifname
string
Interface name if-oper-status
string
Specifies the operator status of the interface if-admin-status
string
Specifies the configured status of the Interface af-type
string
Assured Forwarding type ifindex
string
Interface index vdevice-host-name
string
Device hostname uptime
string
Device uptime ipv6-address
string
IPv6 address hwaddr
string
Hardware address of the ethernet interface also known as MAC address. ip-address
string
IP address port-type
string
Interface type encap-type
string
Encapsulation type rx-drops
string
Total number of packets dropped rx-errors
string
Total number of packets received with error rx-kbps
string
Displays the receiving speed of the monitored device rx-octets
string
Status counters for the incoming and outgoing bytes of the port rx-packets
number
Total number of packets received tx-drops
string
Total number of transmitted packets dropped tx-errors
string
Total number of packets transmitted with error tx-kbps
string
Displays the transmitted speed of the monitored device tx-octets
string
Status counters for the incoming and outgoing bytes of the port tx-packets
string
Total number of packets transmitted tx-pps
string
Total number of transmitted packets per second -
JSON code
{ "header": { "generatedOn": 1631096272594, "viewKeys": { "uniqueKey": [ "vdevice-dataKey" ], "preferenceKey": "grid-CEdgeInterface" }, "columns": [ { "title": "VPN (VRF)", "property": "vpn-id", "width": 50, "dataType": "string" }, { "title": "Interface Name", "property": "ifname", "width": 100, "dataType": "string" }, { "title": "Interface description", "property": "description", "width": 100, "dataType": "string" }, { "title": "Physical Address", "property": "hwaddr", "width": 120, "dataType": "string" }, { "title": "IPv4 Address", "property": "ip-address", "width": 120, "dataType": "string" }, { "title": "IPv4 Subnet Mask", "property": "ipv4-subnet-mask", "width": 120, "dataType": "string" }, { "title": "Admin Status", "property": "if-admin-status", "display": "icon", "iconProperty": "if-admin-status", "icon": [ { "key": "if-state-up", "value": "images/up.png" }, { "key": "if-state-down", "value": "images/down.png" } ], "width": 120, "dataType": "string" }, { "title": "Oper Status", "property": "if-oper-status", "display": "icon", "iconProperty": "if-oper-status", "icon": [ { "key": "if-oper-state-ready", "value": "images/up.png" }, { "key": "if-oper-state-lower-layer-down", "value": "images/down.png" }, { "key": "if-oper-state-no-pass", "value": "images/down.png" } ], "width": 100, "dataType": "string" }, { "title": "Interface Type", "property": "interface-type", "width": 100, "dataType": "string" }, { "title": "BIA Address", "property": "bia-address", "width": 100, "dataType": "string" }, { "title": "IPv6 Address", "property": "ipv6-addrs", "hideable": true, "dataType": "ipv6-address" }, { "title": "ipv4-tcp-adjust-mss", "property": "ipv4-tcp-adjust-mss", "width": 100, "dataType": "string" }, { "title": "ipv6-tcp-adjust-mss", "property": "ipv6-tcp-adjust-mss", "width": 100, "dataType": "string" }, { "title": "If Index", "property": "ifindex", "width": 75, "dataType": "string" }, { "title": "AF Type", "property": "af-type", "width": 100, "dataType": "string" }, { "title": "MTU", "property": "mtu", "width": 60, "dataType": "string" }, { "title": "Speed (mbps)", "property": "speed-mbps", "width": 120, "dataType": "string" }, { "title": "Tx Kbps", "property": "tx-kbps", "width": 100, "dataType": "number" }, { "title": "Rx Kbps", "property": "rx-kbps", "width": 100, "dataType": "number" }, { "title": "Tx PPS", "property": "tx-pps", "width": 100, "dataType": "number" }, { "title": "Rx PPS", "property": "rx-pps", "width": 100, "dataType": "number" }, { "title": "Rx Octets", "property": "rx-octets", "width": 100, "dataType": "number" }, { "title": "Rx unicast Packets", "property": "rx-packets", "width": 100, "dataType": "number" }, { "title": "Tx Octets", "property": "tx-octets", "width": 100, "dataType": "number" }, { "title": "Tx unicast pakcets", "property": "tx-packets", "width": 100, "dataType": "number" }, { "title": "Rx discards", "property": "rx-drops", "width": 100, "dataType": "number" }, { "title": "Tx discards", "property": "tx-drops", "width": 100, "dataType": "number" }, { "title": "Rx Errors", "property": "rx-errors", "width": 100, "dataType": "number" }, { "title": "Tx Errors", "property": "tx-errors", "width": 100, "dataType": "number" }, { "title": "Num Flaps", "property": "num-flaps", "width": 70, "dataType": "string" }, { "title": "Last Updated", "property": "lastupdated", "displayFormat": "DD MMM YYYY h:mm:ss A z", "inputFormat": "unix-time", "hideable": false, "minWidth": 200, "dataType": "date" } ], "fields": [ { "property": "vdevice-name", "dataType": "string" }, { "property": "vdevice-host-name", "dataType": "string" }, { "property": "vpn-id", "dataType": "string" }, { "property": "ifname", "dataType": "string" }, { "property": "description", "dataType": "string" }, { "property": "hwaddr", "dataType": "string" }, { "property": "ip-address", "dataType": "string" }, { "property": "ipv4-subnet-mask", "dataType": "string" }, { "property": "if-admin-status", "dataType": "string", "display": "icon" }, { "property": "if-oper-status", "dataType": "string", "display": "icon" }, { "property": "interface-type", "dataType": "string" }, { "property": "bia-address", "dataType": "string" }, { "property": "ipv6-addrs", "dataType": "ipv6-address" }, { "property": "ipv4-tcp-adjust-mss", "dataType": "string" }, { "property": "ipv6-tcp-adjust-mss", "dataType": "string" }, { "property": "ifindex", "dataType": "string" }, { "property": "af-type", "dataType": "string" }, { "property": "mtu", "dataType": "string" }, { "property": "speed-mbps", "dataType": "string" }, { "property": "tx-kbps", "dataType": "number" }, { "property": "rx-kbps", "dataType": "number" }, { "property": "tx-pps", "dataType": "number" }, { "property": "rx-pps", "dataType": "number" }, { "property": "rx-octets", "dataType": "number" }, { "property": "rx-packets", "dataType": "number" }, { "property": "tx-octets", "dataType": "number" }, { "property": "tx-packets", "dataType": "number" }, { "property": "rx-drops", "dataType": "number" }, { "property": "tx-drops", "dataType": "number" }, { "property": "rx-errors", "dataType": "number" }, { "property": "tx-errors", "dataType": "number" }, { "property": "num-flaps", "dataType": "string" }, { "property": "lastupdated", "dataType": "date" } ] }, "data": [ { "vdevice-name": "10.10.1.11", "rx-errors": 0, "tx-kbps": 0, "if-admin-status": "if-state-up", "ipv6-tcp-adjust-mss": "0", "tx-pps": 0, "tx-errors": 0, "ifname": "Control Plane", "interface-type": "iana-iftype-other", "rx-pps": 0, "if-oper-status": "if-oper-state-ready", "ifindex": "0", "num-flaps": "0", "ipv4-tcp-adjust-mss": "0", "rx-packets": 0, "bia-address": "00:00:00:00:00:00", "vpn-id": "0", "vdevice-host-name": "dc-cedge01", "mtu": "0", "rx-drops": 0, "tx-drops": 0, "hwaddr": "00:00:00:00:00:00", "speed-mbps": "10240000000", "vdevice-dataKey": "10.10.1.11-0-Control Plane--00:00:00:00:00:00", "tx-octets": 0, "tx-packets": 0, "rx-kbps": 0, "rx-octets": 0, "lastupdated": 1631096272557 }, { "vdevice-name": "10.10.1.11", "rx-errors": 0, "tx-kbps": 0, "if-admin-status": "if-state-up", "ipv6-tcp-adjust-mss": "0", "description": "port.sbx-mgmt", "tx-pps": 0, "tx-errors": 0, "ifname": "GigabitEthernet1", "interface-type": "iana-iftype-ethernet-csmacd", "rx-pps": 1, "if-oper-status": "if-oper-state-ready", "ifindex": "1", "num-flaps": "0", "ipv4-tcp-adjust-mss": "0", "rx-packets": 57260, "bia-address": "52:54:00:04:3e:3b", "vpn-id": "512", "vdevice-host-name": "dc-cedge01", "ipv4-subnet-mask": "255.255.255.0", "mtu": "1500", "rx-drops": 0, "tx-drops": 0, "hwaddr": "52:54:00:04:3e:3b", "ip-address": "10.10.20.172", "speed-mbps": "1024000000", "vdevice-dataKey": "10.10.1.11-512-GigabitEthernet1-10.10.20.172-52:54:00:04:3e:3b", "tx-octets": 5816, "tx-packets": 60, "rx-kbps": 2, "rx-octets": 13821998, "lastupdated": 1631096272557 }, ... ] }
-
wanLink resource type
Provides wanLink resource type metrics information from the vManage dashboard.
- URI
-
https://{{vmanage}}:{{port}}/dataservice/statistics/approute/aggregation
- Sample URL
-
https://<IP_address>:8443/dataservice/statistics/approute/aggregation
- Method
- The supported request type
https POST
- URL parameters
-
-
Post query
{ "query":{ "condition":"AND", "rules":[ { "value":[ "1" ], "field":"entry_time", "type":"date", "operator":"last_n_hours" }, { "value":[ "100" ], "field":"loss_percentage", "type":"number", "operator":"less" }, { "value":[ "<replaceIP_String>" ], "field":"vdevice_name", "type":"string", "operator":"in" } ] }, "aggregation":{ "field":[ { "property":"local_color", "order":"asc", "sequence":1 } ], "metrics":[ { "property":"loss_percentage", "type":"avg" }, { "property":"latency", "type":"avg" }, { "property":"jitter", "type":"avg" } ] } }
replaceIP_String
is your device IP address from which the wanLink resource type data must be processed. -
- Response
-
The results are returned as JSON data that contains an array of the following fields:
Name Data type Description entry_time
date
Metric timestamp count
number
Count local_color
string
Configure two tunnel interfaces, one with color silver and the other with color gold. jitter
number
Jitter in your network loss_percentage
number
Percentage of packet loss in your network latency
number
Latency in your network -
JSON code
{ "header": { "generatedOn": 1631097887168, "columns": [ { "property": "entry_time", "title": "Entry_time", "dataType": "date", "isDisplay": true }, { "property": "jitter", "title": "Jitter", "dataType": "number", "isDisplay": true }, { "property": "loss_percentage", "title": "Loss_percentage", "dataType": "number", "isDisplay": true }, { "property": "latency", "title": "Latency", "dataType": "number", "isDisplay": true }, { "property": "local_color", "title": "Local_color", "dataType": "string", "isDisplay": true } ], "fields": [ { "property": "entry_time", "dataType": "date" }, { "property": "jitter", "dataType": "number" }, { "property": "loss_percentage", "dataType": "number" }, { "property": "latency", "dataType": "number" }, { "property": "local_color", "dataType": "string" } ] }, "entryTimeList": [ 1631097600000, 1631097000000, ... ], "data": [ { "entry_time": 1631096400000, "count": 2, "local_color": "mpls", "jitter": 0.5, "loss_percentage": 0.075, "latency": 102.5 }, { "entry_time": 1631096400000, "count": 2, "local_color": "public-internet", "jitter": 0.5, "loss_percentage": 0, "latency": 102 }, ... ] }
-
wanLink properties
Provides properties information for the wanLink resource type from the vManage dashboard.
- URI
-
https://{{vmanage}}:{{port}}/dataservice/device/tloc
- Sample URLs
-
https://<IP_address>:8443/dataservice/device/tloc
- Method
- The supported request type.
https Post
- Response
- The results are returned as JSON data that contains an array of the following
fields:
Name Data type Description color
string system-ip
string bfdSessionsDown
string _id
string controlConnectionsUp
string bfdSessionsUp
string controlConnectionsDown
string -
JSON code
{ "header": { "generatedOn": 1631098152425, "title": "tlocStatus" }, "data": [ { "color": "mpls", "system-ip": "10.10.1.11", "bfdSessionsDown": 0, "_id": 9, "controlConnectionsUp": 2, "bfdSessionsUp": 6, "controlConnectionsDown": 0 }, { "color": "default", "system-ip": "10.10.1.1", "expectedControlConnections": 1, "_id": 174, "controlConnectionsUp": 5, "controlConnectionsToVsmarts": 1, "controlConnectionsDown": 0 }, ... ] }
-
Tunnel resource type
Provides tunnel resource type metrics information and its properties from the vManage dashboard.
- URI
-
https://{{vmanage}}:{{port}}/dataservice/statistics/approute/fec/aggregation
- Sample URLs
-
https://<IP_address>:8443/dataservice/statistics/approute/fec/aggregation
- Method
- The supported request type.
https Post
- URL parameters
-
Post query
{ "query": { "condition": "AND", "rules": [ { "value": [ "1" ], "field": "entry_time", "type": "date", "operator": "last_n_hours" }, { "value": [ "<replaceIP_String>" ], "field": "vdevice_name", "type": "string", "operator": "in" } ] }, "aggregation": { "field": [ { "property": "name", "sequence": 1, "size": 50 }, { "property": "proto", "sequence": 2 } ], "metrics": [ { "property": "loss_percentage", "type": "avg" }, { "property": "vqoe_score", "type": "avg" }, { "property": "latency", "type": "avg" }, { "property": "jitter", "type": "avg" }, { "property": "rx_octets", "type": "sum" }, { "property": "tx_octets", "type": "sum" } ] } }
replaceIP_String
is your device IP address from which the wanLink resource type data must be processed.-
- Response
-
The results are returned as JSON data that contains an array of the following fields:
Name Data type Description loss_percentage
number
Percentage of packet loss in your network latency
number
Latency in your network count
number
Count of ? tx_octets
number
Status counters for the incoming and outgoing bytes of the port jitter
number
Jitter in your network rx_octets
number
Status counters for the incoming and outgoing bytes of the port proto
string
Protocol name
number
fecLossRecovery
number
Forward error correction loss recovery percent vqoe_score
number
Viptela Quality of Experience (vQoE) score -
JSON code
{ "header": { "generatedOn": 1634192530194, "columns": [ { "property": "fec_re", "title": "Fec_re", "dataType": "number", "isDisplay": true }, { "property": "vqoe_score", "title": "Vqoe_score", "dataType": "number", "isDisplay": true }, { "property": "fec_tx", "title": "Fec_tx", "dataType": "number", "isDisplay": true }, { "property": "jitter", "title": "Jitter", "dataType": "number", "isDisplay": true }, { "property": "rx_octets", "title": "Rx_octets", "dataType": "number", "isDisplay": true }, { "property": "loss_percentage", "title": "Loss_percentage", "dataType": "number", "isDisplay": true }, { "property": "proto", "title": "Proto", "dataType": "string", "isDisplay": true }, { "property": "latency", "title": "Latency", "dataType": "number", "isDisplay": true }, { "property": "name", "title": "Name", "dataType": "string", "isDisplay": true }, { "property": "fec_rx", "title": "Fec_rx", "dataType": "number", "isDisplay": true }, { "property": "tx_octets", "title": "Tx_octets", "dataType": "number", "isDisplay": true } ], "fields": [ { "property": "fec_re", "dataType": "number" }, { "property": "vqoe_score", "dataType": "number" }, { "property": "fec_tx", "dataType": "number" }, { "property": "jitter", "dataType": "number" }, { "property": "rx_octets", "dataType": "number" }, { "property": "loss_percentage", "dataType": "number" }, { "property": "proto", "dataType": "string" }, { "property": "latency", "dataType": "number" }, { "property": "name", "dataType": "string" }, { "property": "fec_rx", "dataType": "number" }, { "property": "tx_octets", "dataType": "number" } ] }, "data": [ { "loss_percentage": 0, "latency": 2.75, "count": 4, "tx_octets": 0, "jitter": 1, "rx_octets": 0, "proto": "IPSEC", "name": "10.10.1.13:mpls-10.10.1.17:public-internet", "fecLossRecovery": "-", "vqoe_score": 10 }, ... ] }
-
Application resource type
Provides application resource type metrics information and its properties from the vManage dashboard.
- URI
-
https://{{vmanage}}:{{port}}/dataservice/statistics/dpi/aggregation
- Sample URLs
-
https://10.10.20.90:8443/dataservice/statistics/dpi/aggregation
- Method
- The supported request type.
https Post
- URL parameters
-
-
Post query
{ "query": { "condition": "AND", "rules": [ { "value": [ "1" ], "field": "entry_time", "type": "date", "operator": "last_n_hours" }, { "value": [ "replaceIP_String" ], "field": "vdevice_name", "type": "string", "operator": "in" }, { "value": [ "network-service", "web", "webmail" ], "field": "family", "type": "string", "operator": "in" } ] }, "aggregation": { "field": [ { "property": "family", "sequence": 1, "size": 3 } ], "metrics": [ { "property": "octets", "type": "sum" } ], "histogram": { "property": "entry_time", "type": "minute", "interval": 10, "order": "asc" } } }
-
- Response
-
The results are returned as JSON data that contains an array of the following fields:
Name Data type Description entry_time
date
count
number
family
string
octets
number
-
JSON code
{ "header": { "generatedOn": 1631098307381, "columns": [ { "property": "entry_time", "title": "Entry_time", "dataType": "date", "isDisplay": true }, { "property": "octets", "title": "Octets", "dataType": "number", "isDisplay": true }, { "property": "family", "title": "Family", "dataType": "string", "isDisplay": true } ], "fields": [ { "property": "entry_time", "dataType": "date" }, { "property": "octets", "dataType": "number" }, { "property": "family", "dataType": "string" } ] }, "entryTimeList": [ 1631098200000, 1631097600000, 1631097000000, 1631096400000, 1631095800000, 1631095200000, 1631094600000 ], "data": [ { "entry_time": 1631096400000, "count": 43, "family": "network-service", "octets": 243330 }, { "entry_time": 1631096400000, "count": 14, "family": "web", "octets": 4032 }, { "entry_time": 1631095200000, "count": 67, "family": "network-service", "octets": 342068 }, ... ] }
-
Application Per Tunnel resource type
Provides applicationPerTunnel resource type metrics information and its properties from the
vManage dashboard.
- URI
-
https://{{vmanage}}:{{port}}/dataservice/statistics/dpi
- Sample URL
-
https://<IP_address>:8443/dataservice/statistics/dpi
- Method
- The supported request type.
https GET
- Response
-
The results are returned as JSON data that contains an array of the following fields:
Name Data type Description host_name
string
vmanage_system_ip
string
device_model
string
octets
number
packets
number
application
string
family
string
entry_time
date
vmanage_system_ip
string
local_system_ip
string
local_color
string
remote_system_ip
string
remote_color
string
-
JSON code
{ "header": { "generatedOn": 1631169026088, "viewKeys": { "uniqueKey": [], "preferenceKey": "grid-raw_dpistatistics" }, "columns": [], "fields": [ { "property": "vip_idx", "dataType": "number" }, { "property": "entry_time", "dataType": "date" }, { "property": "vpn_id", "dataType": "number" }, { "property": "source_ip", "dataType": "string" }, { "property": "dest_ip", "dataType": "string" }, { "property": "source_port", "dataType": "number" }, { "property": "dest_port", "dataType": "number" }, { "property": "octets", "dataType": "number" }, { "property": "packets", "dataType": "number" }, { "property": "application", "dataType": "string" }, { "property": "family", "dataType": "string" }, { "property": "create_time", "dataType": "date" }, { "property": "expire_time", "dataType": "date" }, { "property": "ip_proto", "dataType": "number" }, { "property": "tunnel_encap", "dataType": "string" } ], "chart": { "xAxis": [ "entry_time" ], "yAxis": [ "octets", "packets" ], "series": [ "family", "application" ], "title": "DPI", "xAxisLabel": "Time", "yAxisLabel": "" } }, "data": [ { "ip_proto": 17, "remote_color": "public-internet", "device_model": "vedge-CSR-1000v", "pkt_dup_r_pkts": 0, "device_family": "network-service", "fec_d_pkts": 0, "packets": 4, "source_ip": "10.10.21.11", "local_color": "public-internet", "flow_id": 9223372036854775807, "statcycletime": 1631167800160, "source_port": 48818, "octets": 284, "local_system_ip": "10.10.1.13", "tenant": "default", "dest_port": 53, "entry_time": 1631166801245, "tunnel_encap": "IPSEC", "create_time": 1631166785479, "device_application": "dns", "vip_time": 1631166801245, "end_time": 1631166790484, "expire_time": 1631166790484, "vmanage_system_ip": "10.10.1.13", "start_time": 1631166785479, "application": "dns", "remote_system_ip": "10.10.1.11", "vdevice_name": "10.10.1.13", "dest_ip": "10.17.248.11", "vip_idx": 90, "family": "network-service", "fec_r_pkts": 0, "host_name": "site1-cedge01", "vpn_id": 1, "id": "AXvJLWNmag33uAGRiAXu" }, { "ip_proto": 17, "remote_color": "mpls", "device_model": "vedge-CSR-1000v", "pkt_dup_r_pkts": 0, "device_family": "network-service", "fec_d_pkts": 0, "packets": 4, "source_ip": "10.10.22.11", "local_color": "mpls", "flow_id": 9223372036854775807, "statcycletime": 1631167800162, "source_port": 41696, "octets": 284, "local_system_ip": "10.10.1.15", "tenant": "default", "dest_port": 53, "entry_time": 1631166801017, "tunnel_encap": "IPSEC", "create_time": 1631166785791, "device_application": "dns", "vip_time": 1631166801017, "end_time": 1631166790793, "expire_time": 1631166790793, "vmanage_system_ip": "10.10.1.15", "start_time": 1631166785791, "application": "dns", "remote_system_ip": "10.10.1.11", "vdevice_name": "10.10.1.15", "dest_ip": "10.17.248.11", "vip_idx": 93, "family": "network-service", "fec_r_pkts": 0, "host_name": "site2-cedge01", "vpn_id": 1, "id": "AXvJLWNoag33uAGRiAZL" }, ... ], "pageInfo": { "startTime": "1631166801245", "endTime": "1631166185804", "count": 269 } }
-