WebSocket API Overview
You can use WebSockets in your Juniper Mist network. The WebSocket protocol can open a bidirectional communication session between a client and a server. You can send messages to the server and receive real-time, event-driven responses without having to poll the server for a reply.
The initial client request and server response use the HTTP protocol to establish the WebSocket communication. From then on, the client can subscribe to one or more topics (streaming channels) to stream data.
You and other administrators can use WebSockets in very specific use cases, such as data visualization dashboards or maps that must reflect real-time data values.
Examples
-
Populate a custom dashboard with the live status of Juniper Mist access points (APs) and real-time location data of Bluetooth Low Energy (BLE) assets.
-
Stream device data and statistics (such as transmit and receive packets) on an hourly basis to an external, operational dashboards like Grafana. Although the device statistics are robust, you can easily parse them to abstract the desired data for display.
WebSocket API Endpoint
The API endpoint depends on the global region that your organization is associated with.
Service Type |
Global 01 |
Global 02 |
Global 03 |
Global 04 |
EMEA 01 |
EMEA 02 |
EMEA 03 |
APAC 01 |
---|---|---|---|---|---|---|---|---|
Admin Portal | api-ws.mist.com | api-ws.gc1.mist.com | api-ws.ac2.mist.com | api-ws.gc2.mist.com | api-ws.eu.mist.com | api-ws.gc3.mist.com | api-ws.ac6.mist.com | api-ws.ac5.mist.com |
Websocket API |
api.mist.com |
api.gc1.mist.com |
api.ac2.mist.com |
api.gc2.mist.com |
api.eu.mist.com |
api.gc3.mist.com |
api.ac6.mist.com |
api.ac5.mist.com |
Authentication Options
Juniper Mist requires authentication to establish a connection to the WebSocket API. You can use these methods:
-
HTTP login with Juniper Mist login credentials
-
API call to an external OAuth2 provider
WebSocket Streaming Channels
After Juniper Mist establishes a streaming connection with a client, the client needs to subscribe to at least one channel to send and receive messages. Messages go back and forth through the bidirectional WebSocket protocol. To stop sending and receiving messages from a channel, you can unsubscribe from it.
All channels require that you specify the site ID. To find a site ID in the Juniper Mist portal, select Organization > Site Configuration from the left menu, and then click the site.
Once you are logged in, you can view further information about each WebSocket. Begin by navigating to the web links for WebSocket documentation provided in the next section.
WebSocket Samples and Documentation
As mentioned previously, the WebSocket protocol is used for communication between client and server. You can send messages to the server and receive event-driven responses. The following table contains sample requests and responses as well as links to WebSocket Documentation.
Your documentation link will depend on the region (cloud) you have logged in to. The table below contains links for the Global 01 cloud.
Names | Streaming Channels | Sample Requests/Responses and Documentation |
---|---|---|
Discovery of BLE Assets by Map | /sites/:site_id/stats/maps/:map_id/discovered_assets |
To discover BLE assets on the map, issue the following request: Request: GET /api/v1/sites/:site_id/stats/maps/:map_id/discovered_assets Response: [ { "mac": "6fa474be7xxx", "device_name": "[TV] UN65JU6xxx", "x": 60, "y": 80, "manufacture": "Apple", "last_seen": 1428939600, // optionally populated "ibeacon_uuid": "f3f17139-704a-f03a-2786-0400279e37c3", "ibeacon_major": 13, "ibeacon_minor": 138, "eddystone_uid_namespace": "2818e3868dec25629ede", "eddystone_uid_instance": "5c5b35000001", "eddystone_url_url": "https://www.abc.com", "mfg_company_id": 935, "mfg_data": "648520a1020000", "duration": 120 } ] For more information, see https://api.mist.com/api/v1/docs/Site#assets |
BLE Asset RF Glass Info | /sites/:site_id/assets/:asset_id/diag |
To get RF Glass information for BLE Assets, issue the following request: Request: { "subscribe": "/sites/:site_id/assets/:asset_id/diag" } Response: { "event": "data", "channel": "/sites/4ac1dcf4-9d8b-7211-65c4-057819f0862b/assets/115825352113/diag", "data": { "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5", "grid": { "topleft_x_m": -0.86, "topleft_y_m": 9.2486, "size_m": 0.5, "width": 40, "height": 40, "data": "<base-64 encoded data intended to be interpreted by atob() in JS>", }, "motion": false, "vbles": [ { "type": "device", "id": "00000000-0000-0000-1000-5c5b350e0060", "orientation": 90, "xyz_m": [ 5.79, 4.33, 3.04 ], "rssis": [ -52.32, -53, -55, -57, -60.25, null, null, -62, null ] }, { "type": "beacon", "id": "00000000-0000-0000-1000-e74489000052", "xyz_m": [ 8.79, 10.33, 3.04 ], "rssi": -59.5 } ], "peak": { "vble_id": "00000000-0000-0000-1000-e74489000052", "max_rssi": -53.428, "plf": -73, "ple": -21, "intercept": -52 }, // estimates based on probability surface, we'll always have this "raw_xyz_m": [ 18.7486, 10.13269, 0 ], "smoothed_xyz_m": [ 18.7486, 10.13269, 0 ], "model": "asset", "speed": null, "direction": null, "timestamp": 1501113197.768402, // the loudest mote estimate "closest_mote_xyz_m": [ 8.79, 10.33, 3.04 ], // 3 past consecutive mote estimates "adjusted_mote_xyz_m": [ 8.79, 10.33, 3.04 ], // another algorithm, more sophisticated "vector_mote_xyz_m": [ 8.79, 10.33, 3.04 ] //particle reset flags "pf_reset": false, "pf_hard_reset": false } } For more information, see https://api.mist.com/api/v1/docs/Site#location |
SDK Client RF Glass Info (including SDK Client Location) | /sites/:site_id/sdkclients/:sdkclient_id/diag |
To see RF Glass data for SDK Clients, issue the following request: Request: { "subscribe": "/sites/:site_id/sdkclients/:sdkclient_id/diag" } Response: { "event": "data", "channel": "/sites/4ac1dcf4-9d8b-7211-65c4-057819f0862b/sdkclients/de87bf9d-183f-e383-cc68-6ba43947d403/diag", "data": { "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5", "grid": { "topleft_x_m": -0.86, "topleft_y_m": 9.2486, "size_m": 0.5, "width": 40, "height": 40, "data": "<base-64 encoded data intended to be interpreted by atob() in JS>", }, "motion": true, "avg_duration": 3, "vbles": [ { "type": "device", "id": "00000000-0000-0000-1000-5c5b350e0060", "orientation": 90, "xyz_m": [ 5.79, 4.33, 3.04 ], "rssis": [ -52.32, -53, -55, -57, -60.25, null, null, -62, null ] }, { "type": "beacon", "id": "00000000-0000-0000-1000-e74489000052", "xyz_m": [ 8.79, 10.33, 3.04 ], "rssi": -59.5 } ], "peak": { "vble_id": "00000000-0000-0000-1000-e74489000052", "max_rssi": -53.428, "plf": -73, "ple": -21, "intercept": -52 }, // estimates based on probability surface, we'll always have this "raw_xyz_m": [ 18.7486, 10.13269, 0 ], "smoothed_xyz_m": [ 18.7486, 10.13269, 0 ], // available only if present "app_xyz_m": [18.714, 10.1102, 0], "dead_reckoning_xyz_m": [18.791, 10.1613, 0], "dead_reckoning_raw_xyz_m": [18.157, 10.110, 0], "model": "iPod7", "os": "", "version": "10.2.1", "beams_count": 12, "beams_mean": 4, "missing_beams": 16, "speed": 1, "direction": 235, "timestamp": 1501113999.758902, // the loudest mote estimate "closest_mote_xyz_m": [ 8.79, 10.33, 3.04 ], // 3 past consecutive mote estimates "adjusted_mote_xyz_m": [ 8.79, 10.33, 3.04 ], // another algorithm, more sophisticated "vector_mote_xyz_m": [ 8.79, 10.33, 3.04 ] //particle reset flags "pf_reset": false, "pf_hard_reset": false "latency": 123 } } For more information, see https://api.mist.com/api/v1/docs/Site#location. |
Wi-Fi (Client Location) | /sites/:site_id/stats/maps/:map_id/clients |
To see wireless client locations, issue the following request: Request: GET /api/v1/sites/:site_id/stats/maps/:map_id/clients Response: [ { "mac": "5684dae9ac8b", "last_seen": 1470417522, "username": "david@mist.com", "hostname": "David-Macbook", "os": "OS X 10.10.2", "manufacture": "Apple", "family": "iPhone", "model": "6S", "ip": "192.168.1.8", "ip6": "2001:db8:3333:4444:5555:6666:7777:8888", "ap_mac": "5c5b35000010", "ap_id": "0000000-0000-0000-1000-5c5b35000010", "ssid": "corporate", "wlan_id": "be22bba7-8e22-e1cf-5185-b880816fe2cf", "psk_id": "732daf4e-f51e-8bba-06f9-b25cd0e779ea", "uptime": 3568, "idle_time": 3, "power_saving": true, "band": "24", "proto": "a", "key_mgmt": "WPA2-PSK/CCMP", "dual_band": false, "channel": 7, "vlan_id": "", "airespace_ifname": "", "rssi": -65, "snr": 31, "tx_rate": 65, "rx_rate": 65, "tx_bytes": 175132, "tx_bps": 6, "tx_packets": 1566, "tx_retries": 500, "rx_bytes": 217416, "rx_bps": 12, "rx_packets": 2337, "rx_retries": 5, "map_id": "63eda950-c6da-11e4-a628-60f81dd250cc", "x": 53.5, "y": 173.1, "x_m": 5.35 "y": 17.31 "num_locating_aps": 3, "is_guest": true, "guest": { "authorized": True, "authorized_time": 1428939300, "authorized_expiring_time": 1429109300 "name": "John", "email": "john@abc.com", "company": "ABC", "field1": "whatever", "cross_site": True }, "airwatch": { "authorized": True }, "_ttl": 250 } ] For more information, see https://api.mist.com/api/v1/docs/Site#client-stats. |
Wi-Fi Client Stats | /sites/:site_id/stats/clients |
To get wireless client statistics, issue the following request: Request: GET /api/v1/sites/:site_id/stats/clients Response: [ { "mac": "5684dae9ac8b", "last_seen": 1470417522, "username": "david@mist.com", "hostname": "David-Macbook", "os": "OS X 10.10.2", "manufacture": "Apple", "family": "iPhone", "model": "6S", "ip": "192.168.1.8", "ip6": "2001:db8:3333:4444:5555:6666:7777:8888", "ap_mac": "5c5b35000010", "ap_id": "0000000-0000-0000-1000-5c5b35000010", "ssid": "corporate", "wlan_id": "be22bba7-8e22-e1cf-5185-b880816fe2cf", "psk_id": "732daf4e-f51e-8bba-06f9-b25cd0e779ea", "uptime": 3568, "idle_time": 3, "power_saving": true, "band": "24", "proto": "a", "key_mgmt": "WPA2-PSK/CCMP", "dual_band": false, "channel": 7, "vlan_id": "", "airespace_ifname": "", "rssi": -65, "snr": 31, "tx_rate": 65, "rx_rate": 65, "tx_bytes": 175132, "tx_bps": 6, "tx_packets": 1566, "tx_retries": 500, "rx_bytes": 217416, "rx_bps": 12, "rx_packets": 2337, "rx_retries": 5, "map_id": "63eda950-c6da-11e4-a628-60f81dd250cc", "x": 53.5, "y": 173.1, "x_m": 5.35 "y": 17.31 "num_locating_aps": 3, "is_guest": true, "guest": { "authorized": True, "authorized_time": 1428939300, "authorized_expiring_time": 1429109300 "name": "John", "email": "john@abc.com", "company": "ABC", "field1": "whatever", "cross_site": True }, "airwatch": { "authorized": True }, "_ttl": 250 } ]https://api.mist.com/api/v1/docs/Site#client-stats |
Unconnected Clients | /sites/:site_id/stats/maps/:map_id/unconnected_clients |
To get the location of unconnected clients, issue the following request: Request: GET /api/v1/sites/:site_id/stats/maps/:map_id/unconnected_clients Response: [ { "mac": "5684dae9ac8b", "ap_mac": "5c5b350e0410", "map_id": "ea77be98-ab51-4ff8-a863-ac3c8e1b1c3a", "x": 60, "y": 80, "rssi": -75.0, "manufacture": "Apple", "last_seen": 1428939600 } ] For more information, see https://api.mist.com/api/v1/docs/Site#location. |
Devices | /sites/:site_id/devices |
To get a list of devices for a particular site, issue the following: Request: GET /api/v1/sites/:site_id/devices Response: [ { "model": "AP41", "hw_rev": "0", "map_id": "01b04bbe-9687-11e8-a5a9-346895ed1b7d", "orientation": 0, "org_id": "476057fe-cebb-4be9-9c15-caf1f09d95e0", "site_id": "eaa6b2b7-88cd-41ea-8150-9b46b6779235", "mac": "5c5b350e0001", "modified_time": 1533206823, "created_time": 1533196761, "tag_id": 107, "tag_uuid": "9c557d6a-8a5e-11e6-b1db-0242ac110004", "serial": "1002710010001", "type": "ap", "id": "00000000-0000-0000-1000-5c5b350e0001", "name": "ap-001" } ] For more information, see https://api.mist.com/api/v1/docs/Site#device. |
Device Stats | /sites/:site_id/stats/devices |
To view the current statistics for a particular device, issue the following: Request: GET /api/v1/sites/:site_id/stats/devices Response: [ { # information from manufacturing, immutable "mac": "5c5b35000010", "model": "AP200", "type": "ap", "serial": "FXLH2015170017", "last_seen": 1470417522, # configurations "name": "conference room", "map_id": "63eda950-c6da-11e4-a628-60f81dd250cc", "x": 53.5, "y": 173.1, "radio_config": { "band_24": { "channel": 0, "bandwidth": 20, "power": 0, "dynamic_chaining_enabled": false, "tx_chain": 4, "rx_chain": 4 }, "band_5": { "channel": 0, "bandwidth": 40, "power": 0, "dynamic_chaining_enabled": false, "tx_chain": 1, "rx_chain": 4 }, "band_6": { "channel": 0, "bandwidth": 40, "power": 0, "tx_chain": 1, "rx_chain": 4 }, "scanning_enabled": true }, "ip_config": { "type": "static", "ip": "10.2.1.1", "netmask": "255.255.255.0", "gateway": "10.2.1.254", "dns": [ "8.8.8.8", "4.4.4.4" ], "dns_suffix": [ ".mist.local", ".mist.com" ] }, "ble_config": { "power_mode": "custom", "power": 10, "beacon_rate_model": "custom", "beacon_rate": 3, "beam_disabled": [ 1, 3, 6 ] }, "led": { "enabled": true, "brightness": 255 }, # current stat "status": "connected", "version": "1.0.0", "ip": "10.2.9.159", // first IP "ext_ip": "73.92.124.103", "num_clients": 10, "uptime": 13500, "tx_bps": 634301, "rx_bps": 60003, "tx_bytes": 211217389682, "tx_pkts": 812204062, "rx_bytes": 8515104416, "rx_pkts": 57770567, "locating": false, "radio_stat": { "band_24": { "mac": "5c5b350004a0" "channel": 6, "bandwidth": 20, "power": 19, "num_clients": 6, "tx_bytes": 211166512114, "tx_pkts": 812058566, "rx_bytes": 8504737800, "rx_pkts": 57731964 }, "band_5": { "mac": "5c5b350004b0" "channel": 44, "bandwidth": 80, "power": 15, "num_clients": 4, "tx_bytes": 50877568, "tx_pkts": 145496, "rx_bytes": 10366616, "rx_pkts": 38603 } }, "port_stat": { "eth0": { "up": true, "speed": 1000, "full_duplex": true, "tx_bytes": 2056, "tx_pkts": 670, "rx_bytes": 2056, "rx_pkts": 670, "rx_errors": 0, }, "eth1": { "up": false }, "module": { "up": false } }, # `ports` is like `port_stat` but is an array. # This array can be converted to a dict using (port_id, node) as key. "ports": [ // Each port object is same as `GET /api/v1/sites/:site_id/stats/ports/search` result object, // except that org_id, site_id, mac, timestamp are removed { "port_id": "ge-0/0/1", "node": "node0", // Absent if this device is standalone . . . } ] "ip_stat": { "ip": "10.2.1.1", "netmask": "255.255.255.0", "gateway": "10.2.1.254", "ip6": "2607:f8b0:4005:808::2004", "netmask6": "/32", "gateway6": "2607:f8b0:4005:808::1", "dns": [ "8.8.8.8", "4.4.4.4" ], "dns_suffix": [ ".mist.local", ".mist.com" ], "ips": { "vlan1": "10.2.1.1/24,2607:f8b0:4005:808::1/32", "vlan193": "10.73.1.31/16", "vlan3157": "10.72.11.14/24" } }, "ble_stat": { "power": 10, "beacon_rate": 3, "uuid": "ada72f8f-1643-e5c6-94db-f2a5636f1a64", "major": 12345, "minors": [ 201, 202, 203, 204, 205, 206, 207, 208 ], "tx_pkts": 135135135, "tx_bytes": 5231513353, "tx_resets": 0, "rx_pkts": 135, "rx_bytes": 135, "ibeacon_enabled": true, "ibeacon_uuid": "f3f17139-704a-f03a-2786-0400279e37c3", "ibeacon_major": 13, "ibeacon_minor": 138, "eddystone_uid_enabled": false, "eddystone_uid_namespace": "2818e3868dec25629ede", "eddystone_uid_instance": "5c5b35000001", "eddystone_uid_freq_msec": 200, "eddystone_url_enabled": true, "eddystone_url_url": "https://www.abc.com", "eddystone_url_freq_msec": 100 }, "l2tp_stat": { "7dae216d-7c98-a51b-e068-dd7d477b7216": { "wxtunnel_id": "7dae216d-7c98-a51b-e068-dd7d477b7216", "state": "established_with_sessions", "uptime": 135, "sessions: [ { "remote_id": "vpn1", "state": "established", "remote_sid": 13, "local_sid": 31 } ] } }, "lldp_stat": { "system_name": "TC2-OWL-Stack-01", "system_desc": "HP J9729A 2920-48G-POE+ Switch", "mgmt_addr": "10.1.5.2", "port_desc": "2/26", "chassis_id": "63:68:61:73:73:69", "lldp_med_supported": false, "power_request_count": 3, "power_allocated": 15500, "power_requested": 25500, "power_draw": 15000 }, "power_src": "PoE 802.3af", "power_budget": -12000, "power_constrained": true, "power_opmode": "[20] 6GHz(2x2) 5GHz(4x4) 2.4GHz(2x2).", "switch_redundancy": { "num_redundant_aps": 1, }, // IoT stats "iot_stat": { "DI2": { "value": 0 } }, // Environment stats "env_stat": { "cpu_temp": 51, "ambient_temp": 39, "humidity": 11, "attitude": 0, "pressure": 1015 "accel_x": -0.012, "accel_y": 0.004, "accel_z": -1.012, "magne_x": 0.0, "magne_y": 1.3, "magne_z": 0.0, "vcore_voltage": 0 }, "mount": 'faceup', // ESL Stats "esl_stat": { "up": true, "type": "imagotag", // if up // following are type-dependent "connected": true, "channel": 3, }, // for a base AP "mesh_downlinks": { "00000000-0000-0000-1000-5c5b356be59f": { "site_id": "0e525da3-6033-428c-9a51-9f652f643baf", "band": "24", "proto": "a", "channel": 7, "last_seen": 1470417522, "idle_time": 3, "rssi": -65, "snr": 31, "tx_rate": 65, "rx_rate": 65, "tx_bytes": 175132, "tx_bps": 6, "tx_packets": 1566, "tx_retries": 500, "rx_bytes": 217416, "rx_bps": 12, "rx_packets": 2337, "rx_retries": 5 } }, // for a remote/relay AP "mesh_uplink": { "uplink_ap_id": "00000000-0000-0000-1000-5c5b35000010", "uplink_site_id": "1916d52a-4a90-11e5-8b45-1258369c38a9", "band": "24", "proto": "a", "channel": 7, "last_seen": 1470417522, "idle_time": 3, "rssi": -65, "snr": 31, "tx_rate": 65, "rx_rate": 65, "tx_bytes": 175132, "tx_bps": 6, "tx_packets": 1566, "tx_retries": 500, "rx_bytes": 217416, "rx_bps": 12, "rx_packets": 2337, "rx_retries": 5 }, "fwupdate": { "timestamp": 1428949501, "status": "inprogress", "status_id": 5, "progress": 10 }, "last_trouble": { "code": "03", "timestamp": 1428949501 }, // if RADSec is enabled, device certs will be automatically generated and managed // with the expiration time exposed "cert_expiry": 1534534392 "locked": false, "auto_placement": { "x": 53.5, "y": 173.1, "x_m": 5.35, "y_m": 17.31, "status": "localized", "status_detail": "localized", "use_auto_placement": false, "recommended_anchor": false, "info": { "cluster_number": 0, "orientation_state": 0, "probability_surface": { "radius": 2.1, "x": 5.65, "y": 17.10 } }, "_id": "5c5b35000010" } } ] For more information, see https://api.mist.com/api/v1/docs/Site#device. |
Commands from Devices | /sites/:site_id/devices/:device_id/cmd |
To subscribe to device command outputs, issue the following request: Request: { "subscribe": "/sites/:site_id/devices/:device_id/cmd" } Response: { "event": "data", "channel": "/sites/4ac1dcf4-9d8b-7211-65c4-057819f0862b/devices/00000000-0000-0000-1000-5c5b350e0060/cmd", "data": { "session": "session_id", "raw": "64 bytes from 23.211.0.110: seq=8 ttl=58 time=12.323 ms\n" } } For more information, see https://api.mist.com/api/v1/docs/Site#device. |
Streaming PCAP | /sites/:site_id/pcaps |
To subscribe to streaming Packet Capture (PCAP), issue the following request: Request: { subscribe: "/sites/:site_id/pcaps" } Response: { "event": "data" "channel": "/sites/:site_id/pcaps" "data": { "capture_id": "6b1be4fb-b239-44d9-9d3b-cb1ff3af1721" "pcap_dict": { "channel_frequency": 2412, "channel": "1", "datarate": "1.0 Mbps", "rssi": -75, "dst": "78:bd:bc:ca:0b:0a", "src": "18:b8:1f:4c:91:c0", "bssid": "18:b8:1f:4c:91:c0", "frame_type": "Management", "frame_subtype": "Probe Response", "proto": "802.11", "ap_mac": "d4:20:b0:81:99:2e", "direction": "tx", "timestamp": 1652246543, "length": 416.0, "interface": "radiotap", "info": "1652246544.467733 1683216786us tsft 1.0 Mb/s 2412 MHz 11g -75dBm signal -82dBm noise antenna 0 Probe Response (ATTKmsWiVS) [1.0* 2.0* 5.5* 11.0* 18.0 24.0 36.0 54.0 Mbit] CH: 2, PRIVACY\\n", }, "pcap_raw": "1MOyoQIABAAAAAAAAAAAAP//AAABAAAAEEh7Yh5VBwCgAQAAoAEAAAAAKwBvCADAAQAAAIw7reCS2VNkAAAAABACbAmABLWuAAEAEBgAAwACAABQADoBeL28ygsKGLgfTJHAGLgfTJHAcIZ2WDlBJQAAAGQAERUACkFUVEttc1dpVlMBCIKEi5YkMEhsAwECBwZVUyABCx4gAQAjAhkAKgEEMgQMEhhgMBQBAAAPrAQBAAAPrAQBAAAPrAIMAAsFAQAbAABGBTIIAQAALRqtCR////8AAAAAAAAAAAAAAAAAAAAAAAAAAD0WAggVAAAAAAAAAAAAAAAAAAAAAAAAAH8IBAAIAAAAAEDdkwBQ8gQQSgABEBBEAAECEDsAAQMQRwAQn2481frn3KT+uGod2ERx+RAhAAtBcnJpcywgSW5jLhAjAApCR1cyMTAtNzAwECQACkJHVzIxMC03MDAQQgAKQkdXMjEwLTcwMBBUAAgABgBQ8gQAARARAA5BcnJpcyBXaXJlbGVzcxAIAAIgCBA8AAEBEEkABgA3KgABIN0JABAYAgEQHAAA3RgAUPICAQGEAAOkAAAnpAAAQkNeAGIyLwAzjakr\" } For more information, see https://api.mist.com/api/v1/docs/Site#subscribe-to-streaming-pcap. |