RESTful API

Program Name: cnMaestro

Product Version: 1.6.1 Document Version: 1.0

3/2/18 Cambium Networks Confidential Page 1 of 37

1 Copyright
© 2017 Cambium Networks Limited. All rights reserved.

This document, Cambium products, and 3rd Party software products described in this document may
include or describe copyrighted Cambium and other 3rd Party supplied computer programs stored in
semiconductor memories or other media. Laws in the United States and other countries preserve for
Cambium, its licensors, and other 3rd Party supplied software certain exclusive rights for copyrighted
material, including the exclusive right to copy, reproduce in any form, distribute and make derivative
works of the copyrighted material. Accordingly, any copyrighted material of Cambium, its licensors, or
the 3rd Party software supplied material contained in the Cambium products described in this
document may not be copied, reproduced, reverse engineered, distributed, merged or modified in any
manner without the express written permission of Cambium. Furthermore, the purchase of Cambium
products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any
license under the copyrights, patents or patent applications of Cambium or other 3rd Party supplied
software, except for the normal non-exclusive, royalty free license to use that arises by operation of
law in the sale of a product.

Restrictions

Software and documentation are copyrighted materials. Making unauthorized copies is prohibited by
law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in
a retrieval system, or translated into any language or computer language, in any form or by any
means, without prior written permission of Cambium.

License Agreements

The software described in this document is the property of Cambium and its licensors. It is furnished
by express license agreement only and may be used only in accordance with the terms of such an
agreement.

3/2/18 Cambium Networks Confidential Page 2 of 37

2 Table of Contents
2.1 Contents
1 Copyright ........................................................................................................................................ 2
2 Table of Contents ........................................................................................................................... 3
2.1 Contents................................................................................................................................. 3
3 Introduction ..................................................................................................................................... 5
3.1 Overview ................................................................................................................................ 5
3.2 Architecture ............................................................................................................................ 5
3.2.1 Establish Session .............................................................................................................. 5
3.2.2 API Access ........................................................................................................................ 5
3.2.3 Session Expiration ............................................................................................................. 5
3.2.4 Concurrent Access ............................................................................................................ 6
3.2.5 Rate Limiting...................................................................................................................... 6
4 Client Id and Client Secret Generation ........................................................................................... 6
4.1 cnMaestro User Interface ...................................................................................................... 6
4.2 Step 1: Navigate to Services > API Clients ........................................................................... 6
4.3 Step 2: Create a New API Client ........................................................................................... 6
4.4 Step 3: Download the Client Id and Client Secret ................................................................. 7
5 API Session .................................................................................................................................... 7
5.1 Introduction ............................................................................................................................ 7
5.2 Retrieve Access Token .......................................................................................................... 7
5.2.1 cnMaestro On-Premises .................................................................................................... 7
5.3 Access Resources ................................................................................................................. 9
6 API Details ...................................................................................................................................... 9
6.1 HTTP Protocol ....................................................................................................................... 9
6.1.1 HTTP Response Codes .................................................................................................... 9
6.1.2 HTTP Headers................................................................................................................... 9
6.2 REST Protocol ....................................................................................................................... 9
6.2.1 Resource URLs ................................................................................................................. 9
6.2.2 Responses ....................................................................................................................... 10
6.3 Parameters .......................................................................................................................... 11
6.3.1 Field Selection ................................................................................................................. 11
6.3.2 Filtering ............................................................................................................................ 12
6.3.3 Time Filtering ................................................................................................................... 13
6.3.4 Sorting ............................................................................................................................. 13
6.3.5 Pagination........................................................................................................................ 13
7 Access API ................................................................................................................................... 14
7.1 token (basic request) ........................................................................................................... 14
7.1.1 Request ........................................................................................................................... 15
7.1.2 Response ........................................................................................................................ 15
7.1.3 Example........................................................................................................................... 15
7.2 token (alternate request) ...................................................................................................... 15
7.2.1 Request ........................................................................................................................... 16
7.2.2 Response ........................................................................................................................ 16
7.2.3 Example........................................................................................................................... 16
7.3 validateToken ...................................................................................................................... 16
7.3.1 Request ........................................................................................................................... 16
7.3.2 Response ........................................................................................................................ 17
7.3.3 Example........................................................................................................................... 17
8 Devices API .................................................................................................................................. 17
8.1 Overview .............................................................................................................................. 17
8.1.1 Request ........................................................................................................................... 17
8.1.2 Response ........................................................................................................................ 17
8.1.3 Example........................................................................................................................... 18
8.2 Device Operations ............................................................................................................... 19
8.2.1 Overview.......................................................................................................................... 19
8.2.2 Reboot Device ................................................................................................................. 19

3/2/18 Cambium Networks Confidential Page 3 of 37

 8.3 Sub-Resources .................................................................................................................... 20
9 Networks API ................................................................................................................................ 20
9.1 Overview .............................................................................................................................. 20
9.1.1 Request ........................................................................................................................... 20
9.1.2 Response ........................................................................................................................ 20
9.1.3 Example........................................................................................................................... 21
9.2 Sub-Resources .................................................................................................................... 21
10 Sites API ....................................................................................................................................... 21
10.1 Overview .............................................................................................................................. 21
10.1.1 Request ....................................................................................................................... 21
10.1.2 Response .................................................................................................................... 22
10.2 Sub-Resources .................................................................................................................... 22
11 Towers API ................................................................................................................................... 22
11.1 Overview .............................................................................................................................. 22
11.1.1 Request ....................................................................................................................... 22
11.1.2 Response .................................................................................................................... 23
11.2 Sub-Resources .................................................................................................................... 23
12 Statistics API ................................................................................................................................ 23
12.1.1 Overview ..................................................................................................................... 23
12.1.2 Request ....................................................................................................................... 23
12.1.3 Response .................................................................................................................... 23
13 Performance API .......................................................................................................................... 26
13.1.1 Device ......................................................................................................................... 26
13.1.2 Request ....................................................................................................................... 26
13.1.3 Response .................................................................................................................... 27
14 WiFi APIs ...................................................................................................................................... 28
14.1 WiFi Clients .......................................................................................................................... 28
14.1.1 Request ....................................................................................................................... 28
14.1.2 Response .................................................................................................................... 28
14.2 WiFi Mesh Peers ................................................................................................................. 28
14.2.1 Request ....................................................................................................................... 29
14.2.2 Response .................................................................................................................... 29
14.2.3 Example ...................................................................................................................... 29
14.2.4 Sub-Resources ........................................................................................................... 30
15 Alarms API .................................................................................................................................... 32
15.1 Active Alarms ....................................................................................................................... 32
15.1.1 Request ....................................................................................................................... 32
15.1.2 Response .................................................................................................................... 32
15.2 Alarm History ....................................................................................................................... 32
15.2.1 Request ....................................................................................................................... 32
15.2.2 Response .................................................................................................................... 33
16 Events API .................................................................................................................................... 33
16.1.1 Overview ..................................................................................................................... 33
17 Sessions API ................................................................................................................................ 34
17.1.1 Overview ..................................................................................................................... 34
18 Sample Python Code ................................................................................................................... 34
18.1 API Client ............................................................................................................................. 35
18.2 Code .................................................................................................................................... 35
19 Appendix: API List ........................................................................................................................ 36
20 Contacting Cambium Networks .................................................................................................... 37

3/2/18 Cambium Networks Confidential Page 4 of 37

3 Introduction
3.1 Overview
cnMaestro supports a RESTful API as part of its On-Premises deployment. This API allows customers
to read data and perform operations programmatically using their own client applications. The API is
supported over HTTPS, and messages are exchanged in JSON format. Modern programming
languages have rich support for RESTful interfaces.

3.2 Architecture
A basic OAuth2 API session is presented below. The client retrieves an Access Token to start the
session. It sends API requests until the Access Token times out, at which point the token can be
regenerated.

cnMaestro
Application
On-Premises

Request Access Token

Retrieve (client_id, client_secret)
Access Token
Response
(access_token, expires_in)

API Call Using Access Token

(access_token)
API
API Call Using Access Token
Access
(access_token)

API Call Using Access Token

(access_token)

3.2.1 Establish Session

A session is created by sending the Client Id and Client Secret to the cnMaestro server. These are
generated in the cnMaestro UI and stored with the application. The Client Id defines the cnMaestro
account and application, and the Client Secret is a private string mapped to the specific application.
The Client Secret should be stored securely.

If the session is established successfully, an Access Token is returned along with an Expiration
string. The Access Token is used to authenticate the session. The Expiration is the interval, in
seconds, in which the Access Token remains valid. If the Access Token expires, a new session needs
to be created.

3.2.2 API Access

With the Access Token, the application can make cnMaestro API calls. The token is sent in an
Authentication header on each API request. Details are provided later in this document.

3.2.3 Session Expiration

If a token expires, an expiration error message is returned to the client. The client can then generate a
new token using the Client Id and Client Secret. Tokens will expire immediately if the Client API
account that created them is deleted. The default expiration time for a token is 3600 seconds (1 hour).
This is configurable in the UI.

3/2/18 Cambium Networks Confidential Page 5 of 37

3.2.4 Concurrent Access

Each client supports a single Access Token or multiple Access Tokens. Multiple Access Tokens
allows concurrent access.

3.2.4.1 Single Access Token

If only one Access Token is enabled at a time, whenever a new Access Token is generated from the
Client Id and Client Secret, the previous Token will immediately expire.

3.2.4.2 Multiple Access Tokens

If multiple access tokens are supported, then many clients can concurrently access the API. If another
Access Token is created, the previous will remain valid until their original expiration.

3.2.5 Rate Limiting

Request Rate Limiting is not enabled in the On-Premises version of cnMaestro. It is up to the
application owner to make sure requests do not overtax the system.

4 Client Id and Client Secret Generation

4.1 cnMaestro User Interface
The Client Id and Client Secret are created in the cnMaestro user interface by navigating to Services
> API Client. Each client application should be added as an API Client.

4.2 Step 1: Navigate to Services > API Clients

4.3 Step 2: Create a New API Client

Select the button Add API Client to add a client, then fill in the requested details, and click on ‘save’
button.

3/2/18 Cambium Networks Confidential Page 6 of 37

4.4 Step 3: Download the Client Id and Client Secret
Download and store the Client Id and Client Secret by clicking on the ‘Download Credentials’ button.
Both are required to create an API session.

5 API Session
5.1 Introduction
The cnMaestro API leverages the Client Credentials section of the OAuth 2.0 Authorization
Framework (RFC 6749). An API Session can be created using any modern programming language.
The examples below highlight how messages are encoded and responses returned.

5.2 Retrieve Access Token

5.2.1 cnMaestro On-Premises

Note
The steps below are for the On-Premises release of cnMaestro.

5.2.1.1 Access Token Request (RFC 6749, section 4.4.2)

3/2/18 Cambium Networks Confidential Page 7 of 37

In order to generate a session, the client should retrieve an access token from cnMaestro. This is
done by base64 encoding the client_id and client_secret downloaded from the cnMaestro
Web UI and sending them to the cnMaestro server. The Authorization header is created by
base64 encoding these fields as defined below. Note the fields are separated by a colon (:):

Authorization: Basic BASE64(<client_id>:<client_password>)

In the body of the POST the parameter grant_type must be set to client_credentials.

POST /api/v1/access/token HTTP/1.1

Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Alternatively, instead of using the Authorization header, the credentials can be passed within the
body of the POST:

POST /api/v1/access/token HTTP/1.1

Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbn
fVdmIw

5.2.1.2 Access Token Response (RFC 6749, section 4.4.3)

The response returned from cnMaestro includes the access_token that should be used in
subsequent requests. The expires_in field defines how many seconds the token is valid.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"bearer",
"expires_in":3600
}

5.2.1.3 Error Response (RFC 6749, section 5.2)

If there is an error, an HTTP 400 (Bad Request) error code is returned along with one of the following
error messages:

Message Details
invalid_request Required parameter is missing from the request.
invalid_client Client authentication failed.
unauthorized_client The client is not authorized to use the grant type sent.
unsupported_grant_type The grant type is not supported.

An example error response is below.

HTTP/1.1 400 Bad Request

Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"error":"invalid_request"

3/2/18 Cambium Networks Confidential Page 8 of 37

 }

5.3 Access Resources

Once the access_token is retrieved, API requests are sent to cnMaestro server using the format
below. The access_token is sent within the HTTP Authorization header.

GET https://bdo300asdsd3.cloud.cambiumnetworks.com/api/v1/inventory/device
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

6 API Details
6.1 HTTP Protocol
6.1.1 HTTP Response Codes

The following response codes are supported in cnMaestro and may be returned through the HTTP
protocol.

Code Description Use in cnMaestro

200 OK Standard response for successful HTTP requests.
400 Bad Request Status field in request validation related errors.
401 Unauthorized User tried to access a resource without authentication.
403 Forbidden An authenticated user tries to access a non-permitted resource.
404 Not Found Server could not locate the requested resource.
405 Method Not Allowed A method (GET, PUT, POST) is not supported for the resource.
413 Payload Too Large The request is larger than the server is willing to handle
422 Unprocessable Entity The server understands the request but cannot process it.
429 Too Many Requests The client has sent too many requests in a given interval.
431 Request Header Fields
The header fields are too large to be processed.
Too Large
500 Internal Server Error A server-side error happened during processing the request.
501 Not Implemented The request method is not recognized.
502 Bad Gateway Internal server error that may require a reboot.
503 Service Unavailable Internal server error that may require a reboot.

6.1.2 HTTP Headers

6.1.2.1 Request Headers

Header Details
Used in every API request to send the Access Token.
Authorization
Example: Authorization: Bearer <Access-Token>
Accept Set to application/json
Content-Type Set to application/json

6.2 REST Protocol

6.2.1 Resource URLs

The format for cnMaestro path and parameters are the following:

Access a collection of resources:

3/2/18 Cambium Networks Confidential Page 9 of 37

 /api/{version}/{resource}?{parameter}={value}&{parameter}={value}

Access a single resource:

/api/{version}/{resource}/{resource_id}?{parameter}={value}&{parameter}={value}

Access a sub-resource on a collection (this is also possible on single resources):

/api/{version}/{resource}/{sub-resource}?{parameter}={value}&{parameter}={value}

For example – read the statistics for MAC, Type, and IP on all devices:

/api/v1/devices/statistics?fields=mac,type,ip_wan

Version

The version is equal to v1 in this release.

Resource

Resources are the basic objects in the system.

Context Details
alarms Current active alarms.
alarms/history Historical alarms, including active alarms.
devices Devices, including ePMP, PMP, and WiFi.
events Historical events.
networks Configured networks.
sites Configured WiFi sites.
towers Configured Fixed Wireless towers.

Sub-Resources

Sub-Resources apply to top-level resources. They provide a different view of the resource data, or a
filtered collection based upon the resource. They include:

Context Details
alarms Alarms mapped to the top-level resource.
alarms/history Historical alarms mapped to the top-level resource.
clients Wireless LAN clients mapped to the top-level resource.
devices Devices mapped to the top-level resource.
events Events mapped to the top-level resource.
mesh/peers Wireless LAN mesh peers mapped to the top-level resource.
operations Operations available to the top-level resource
performance Performance data for the top-level resource.
statistics Statistics for the top-level resource.

6.2.2 Responses

Successful Response

In a successful HTTP 200 response, data is returned using the following structure. The actual payload
is presented in JSON format. The request URL is:
/api/v1/devices?fields=mac,type&limit=5

3/2/18 Cambium Networks Confidential Page 10 of 37

 {
"paging": {
"offset": 0,
"limit": 5,
"total": 540
},
"data": [
{
"mac": "C1:00:0C:00:00:21",
"type": "wifi-home"
},
{
"mac": "C1:00:0C:00:00:18",
"type": "wifi-home"
},
{
"mac": "C1:00:0C:00:00:12",
"type": "wifi-home"
},
{
"mac": "C1:00:0C:00:00:15",
"type": "wifi-home"
},
{
"mac": "C1:00:0C:00:00:06",
"type": "wifi-home"
}
]
}

Error Response

Error responses return a message and an error cause. If the start_time and stop_time are mandatory
query parameters and some once missed to provide them in the url will give the following error
response with message and cause.

{
"error": {
"cause": "Missing required property: stop_time \n Missing required property:
start_time",
"level": "error",
"message": "OBJECT_MISSING_REQUIRED_PROPERTY"
}
}

6.3 Parameters
Most APIs can be modified to filter the data and limit the number of entries returned. The parameter
options are listed below. The specific fields, and the appropriate values, vary for each API.

6.3.1 Field Selection

Field selection is supported through the optional “fields” parameter, which can specify the specific
data to return from the server. If this parameter is missing, all available fields will be returned.

Parameter Details
fields Define exactly what fields should be returned in a request. The names are
provided as a comma-separated list.

Fields can limit which JSON parameters are returned.

Example: To retrieve name, type and location information for all devices.

3/2/18 Cambium Networks Confidential Page 11 of 37

 Request: /api/v1/devices?fields=mac,type
Response:
{
"paging": {
"total": 3,
"limit": 100,
"offset": 0
},
"data": [
{
"mac": "00:44:E6:34:89:48",
"type": "wifi-enterprise"
},
{
"mac": "00:44:16:E5:33:E4",
"type": "wifi-enterprise"
},
{
"mac": "00:44:26:46:32:22",
"type": "wifi-enterprise"
}
]
}

6.3.2 Filtering

A subset of fields support filtering. These are defined as query parameters for a particular resource,
and they are listed along with the API specification. Some of the standard filtering parameters are
below:

Field Details
network (Devices) Configured Network name.
severity (Alarms, Events) Alarm or Event severity (critical, major, minor, notice).
site (Devices) Configured Site name.
state (Alarms) Alarm state (active, cleared).
status (Devices) Device status [online, offline, onboarding]
tower (Devices) Configured Tower name.
(Devices) Device type [epmp, pmp, wifi-enterprise, wifi-home, wifi] (wifi
type
includes wifi-home and wifi-enterprise).

Filters can be used simultaneously for Resources and Sub-Resources.

Example: Retrieve all WiFi devices that are online.

Request: /api/v1/devices?type=wifi&status=online
Response:
{
"paging": {
"total": 1,
"limit": 100,
"offset": 0
},
"data": [
{
"ip": "233.187.212.38",
"location": {
"type": "Point",
"coordinates": [
77.55310127974755,
12.952351523837196
]
},
"mac": "C1:00:0C:00:00:24",
"msn": "SN-C1:00:0C:00:00:24",

3/2/18 Cambium Networks Confidential Page 12 of 37

 "name": "Hattie",
"network": "Bangalore",
"product": "C3VoIP-R201",
"registration_date": "2017-05-23T21:28:37+05:30",
"status": "offline",
"tower": "Bangalore_Industrial",
"type": "wifi-home",
"hardware_version": "V1.1",
"software_version": "2.4.4",
"status_time": 1495560086
}
]
}

6.3.3 Time Filtering

Events, Alarms, and Performance data can be filtered by date and time using ISO 8601 format.

Example: January 12, 2015 UTC would be encoded as 2015-01-12

Example: January 12, 2015 1:00 PM UTC would be encoded as 2015-01-12T13:00:00Z

The parameters are below. If they are not specified, then the start or stop times will be open-ended.

Parameter Details
start_time Inclusive start time of interval.
stop_time Inclusive stop time of interval.

6.3.4 Sorting

Sorting is supported on a selected subset of fields within certain requests. sort is used to specify
sorting columns. The sort order is ascending unless the path name is prefixed with a ‘-‘, in which case
it would be descending.

Parameter Details
sort Used to get the records in the order of the given attribute.

Example: To retrieve devices in sorted (ascending) order by name.

Request: /api/v1/devices?sort=name

Example: To retrieve devices in sorted (descending) order by mac.

Request: /api/v1/devices?sort=-mac

6.3.5 Pagination

The limit and offset query parameters are used to paginate responses.

Parameter Details
limit Maximum number of records to be returned from the server.
offset Starting index to retrieve the data.

Example: To retrieve the first 10 ePMP devices

Request: /api/v1/devices?offset=3&limit=1
Response:
{
"paging": {
"total": 6,
"limit": 1,
"offset": 3

3/2/18 Cambium Networks Confidential Page 13 of 37

 },
"data": [
{
"status": "online",
"product": "cnPilot E400",
"network": "Mumbai",
"software_version": "3.3-b14",
"registration_date": "2017-04-28T08:57:33+00:00",
"site": "Central",
"hardware_version": "Force 200",
"status_time": "3498",
"msn": "W8SF0759MBDH",
"mac": "00:04:36:46:34:AA",
"location": {
"type": "Point",
"coordinates": [
0,
0
]
},
"type": "wifi-enterprise",
"name": "E400-4634AA"
}
]
}

Internal Response Limits

When clients try to access a resource type without pagination, the server will return the first 100
entries that match the filter criteria. The response will always carry a metadata to convey total count
and current offset and limit. Maximum number of results at any point is 100 even though limit provided
as more than 100.

Example: To retrieve all devices.

Request: /api/v1/devices
Response:
{
data: {devices: [ {name: ‘ePMP_5566’, type:’ePMP’, location:’blr’} , {….}… ] },
paging:{
"limit":25,
"offset":50,
"total":100
}
}

The response returns the following values in the paging section:

Parameter Details
limit Current setting for the limit.
offset Starting index for the records returned in the response (begins at 0).
total Total number of records that can be retrieved.

7 Access API
7.1 token (basic request)
POST /api/v1/access/token

Generate an Access Token using the Client Id and Client Password created in the cnMaestro UI. The
token can be leveraged for API calls through the expiration time. Only one token is supported for each
Client Id at any given time.

3/2/18 Cambium Networks Confidential Page 14 of 37

7.1.1 Request

Headers

Header Value
Accept (optional) application/json
Authorization Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type application/x-www-form-urlencoded

The client_id and client_secret are encoded and sent in the Authorization header. The
encoding is:

BASE64(client_id:client_secret)

Body

The body needs to have the grant_type.

grant_type=client_credentials

7.1.2 Response

The response returns credentials for API access.

Body

Name Details
access_token Access token to return with each API request.
expires_in Time in seconds that the API session will remain active.
token_type This will always be bearer.
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"bearer",
"expires_in":3600
}

7.1.3 Example

Request
curl https://10.110.134.12/api/v1/access/token \
-X POST -k \
-u 8YKCxq72qpjnYmXQ:pcX5BmdJ2f4QLM5RfgsS4jOtxAdTRF \
-d grant_type=client_credentials
Response
{"access_token":"d587538f445d30eb2d48e1b7f7a6c9657d32068e","token_type":"
bearer","expires_in":86400}

7.2 token (alternate request)

POST /api/v1/access/token

An alternative form is supported in which the client_id and client_secret are sent in the body,
rather than the Authorization header.

3/2/18 Cambium Networks Confidential Page 15 of 37

7.2.1 Request

Headers

Header Value
Accept (optional) application/json
Content-Type application/x-www-form-urlencoded

Body

grant_type=client_credentials&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbn
fVdmIw

7.2.2 Response

The response to both forms is the same.

Body

Name Details
access_token Access token to return with each API request.
expires_in Time in seconds that the API session will remain active.
token_type This will always be bearer.
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"bearer",
"expires_in":3600
}

7.2.3 Example

Request
curl https://10.110.134.12/api/v1/access/token \
-X POST -k \
-d grant_type=client_credentials \
-d client_id=8YKCxq72qpjnYmXQ \
-d client_secret=pcX5BmdJ2f4QLM5RfgsS4jOtxAdTRF
Response
{"access_token":"ee4e077cf457196eb4d27cf6f02686dc07763059","token_type":"
bearer","expires_in":86400}

7.3 validateToken
GET /api/v1/access/validate_token

Verify an Access Token is valid and return the time remaining before it expires.

7.3.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

3/2/18 Cambium Networks Confidential Page 16 of 37

7.3.2 Response

Body

Name Details
expires_in Time in seconds that the API session will remain active.
{
'expires_in': 86399
}

7.3.3 Example

Request
curl https://10.110.134.12/api/v1/access/validate_token \
-X GET -k \
-H "Authorization: Bearer ee4e077cf457196eb4d27cf6f02686dc07763059"
Response
{"expires_in":85643}

8 Devices API
8.1 Overview
GET /api/v1/devices

GET /api/v1/devices/{MAC Address}

Retrieve inventory data from devices.

8.1.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.
network Network filter (text name of the network).
status Device status filter [online, offline, onboarding]
site Site filter (text name of the site).
sort Sort fields [mac, name, registration_date]
tower Tower filter (text name of the tower).
type Type of the device [epmp, pmp, wifi-home, wifi-enterprise, wifi]

8.1.2 Response

Body

Name Details ePMP PMP WiFi cnReach

3/2/18 Cambium Networks Confidential Page 17 of 37

ap_group AP group X X
config.sync_reason Configuration synchronization reason X X X X
config.sync_status Configuration synchronization status X X X X
config.variables Device is mapped to configuration variables X X X X
country Country X X X X
description Description X X X X
hardware_version Hardware version X X X X
ip IP address X X X X
location Location X X X X
mac MAC address X X X X
maximum_range Maximum range X X
msn Manufacturer serial number X X X X
name Device name X X X X
network Network X X X X
product Product name X X X X
registration_date Registration date X X X X
site Site X
software_version Software version X X X X
Status (online, offline,
status X X X X
onboarding).
status_time Uptime/downtime time interval (sec) X X X X
tower Tower X X X
Device type (epmp, pmp, wifi-home, wifi-
type X X X X
enterprise, wifi)

8.1.3 Example

Request
curl https://10.110.134.12/api/v1/devices \
-X GET -k \
-H "Authorization: Bearer ee4e077cf457196eb4d27cf6f02686dc07763059"
Response
{
"paging": {
"offset": 0,
"limit": 100,
"total": 2
},
"data": [
{
"ap_group": "automation1",
"config": {
"sync_reason": "Device's mapped profile updated",
"sync_status": false,
"variables": {
"VLAN_1_MODE": "static",
"VLAN_1_IP": "10.110.212.105",
"VLAN_1_MASK": "255.255.255.0",
"DEFAULT_GW": "10.110.212.254",
"DNS_SERVER_1": "10.110.12.110",
"DNS_SERVER_2": "10.110.12.111",
"DISPLAY_NAME": "400-105"
}
},
"hardware_version": "Dual-Band Indoor Omni 802.11ac",
"ip": "10.110.212.105",
"location": {
"coordinates": [
78.486671,
17.385044
],
"type": "Point"
},
"mac": "00:04:56:AC:42:5A",

3/2/18 Cambium Networks Confidential Page 18 of 37

 "msn": "W8RK238260NF",
"name": "400-105",
"network": "Automation",
"product": "cnPilot E400",
"registration_date": "2017-05-31T09:58:32+00:00",
"site": "Automation-site2",
"software_version": "3.3-r16",
"status": "offline",
"status_time": 10459542,
"type": "wifi-enterprise"
},
{
"ap_group": "automation2",
"config": {
"sync_reason": "Device's mapped profile updated",
"sync_status": false,
"variables": {
"VLAN_1_MODE": "static",
"VLAN_1_IP": "10.110.212.125",
"VLAN_1_MASK": "255.255.255.0",
"DEFAULT_GW": "10.110.212.254",
"DNS_SERVER_1": "10.110.12.110",
"DNS_SERVER_2": "10.110.12.111",
"DISPLAY_NAME": "E500-1256"
}
},
"hardware_version": "Dual-Band Outdoor Omni 802.11ac",
"ip": "10.110.212.125",
"location": {
"coordinates": [
78.486671,
17.385044
],
"type": "Point"
},
"mac": "00:04:56:BB:13:42",
"msn": "W8SG4152XHM0",
"name": "E500-1256",
"network": "Automation",
"product": "cnPilot E500",
"registration_date": "2017-05-31T09:58:32+00:00",
"site": "Automation-site2",
"software_version": "3.3-r16",
"status": "offline",
"status_time": 10459550,
"type": "wifi-enterprise"
}
]
}

8.2 Device Operations

8.2.1 Overview

The table below list all operations currently supported and their device types.

Operation Details ePMP PMP WiFi cnReach

Reboot Device Reboot a single device X X X X

8.2.2 Reboot Device

POST /api/v1/devices/{MAC}/reboot

3/2/18 Cambium Networks Confidential Page 19 of 37

Reboot an individual device.

8.3 Sub-Resources
The following sub-resources can be applied to Devices URLs.

/api/v1/devices/alarms Alarms for all devices in system.

/api/v1/devices/alarms/history Alarm history for all devices in system.
/api/v1/devices/events Events for all devices in system.
/api/v1/devices/performance Performance data for all devices in system.
/api/v1/devices/statistics Statistics for all devices in system.
/api/v1/devices/{MAC}/alarms Alarms for MAC device.
/api/v1/devices/{MAC}/alarms/history Alarm history for MAC device.
/api/v1/devices/{MAC}/clients Wi-Fi Clients
/api/v1/devices/{MAC}/events Events for MAC device.
/api/v1/devices/{MAC}/performance Performance data for MAC device.
/api/v1/devices/{MAC}/statistics Statistics data for MAC device.

9 Networks API
9.1 Overview
GET /api/v1/networks

GET /api/v1/networks/{Network ID}

Retrieve inventory data from networks.

9.1.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.

Note
The Network ID may be replaced with the Network Name as long as the name is unique in the
system. If the name is not unique, an HTTP error code 422 (Unprocessable Entity) will be returned.

9.1.2 Response

Body

Name Details
id Identifier of the network.
name Name of the network.

3/2/18 Cambium Networks Confidential Page 20 of 37

9.1.3 Example

Request
curl https://10.110.134.12/api/v1/networks \
-X GET -k \
-H "Authorization: Bearer ee4e077cf457196eb4d27cf6f02686dc07763059"
Response
{
"paging": {
"offset": 0,
"limit": 100,
"total": 4
},
"data": [
{
"id": "TEST_AUTOMATION_NETWORK",
"name": "TEST_AUTOMATION_NETWORK"
},
{
"id": "default",
"name": "default"
},
{
"id": "Automation",
"name": "Automation"
},
{
"id": "test_net_1",
"name": "test_net_1"
}
]
}

9.2 Sub-Resources
The following sub-resources can be applied to Network URLs.

/api/v1/networks/{NID}/{Devices API} Statistics for devices in network.

10 Sites API
10.1 Overview
GET /api/v1/networks/{NID}/sites

GET /api/v1/networks/{NID}/sites/{Site ID}

Retrieve inventory data from sites.

10.1.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

3/2/18 Cambium Networks Confidential Page 21 of 37

 Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.

Note
The Site ID may be replaced with the Site Name as long as the name is unique in the system. If the
name is not unique, an HTTP error code 422 (Unprocessable Entity) will be returned.

10.1.2 Response

Body

Name Details
id Identifier of the site.
location Location of the site.
name Name of the site.
network Network to which the site belongs.

10.2 Sub-Resources
The following sub-resources can be applied to Site URLs.

/api/v1/networks/{NID}/sites/{SID}/clients Clients for the Site

/api/v1/networks/{NID}/sites/{SID}/{Devices API} Statistics for devices in Site.

11 Towers API
11.1 Overview
GET /api/v1/networks/{NID}/towers

GET /api/v1/networks/{NID}/towers/{Tower ID}

Retrieve inventory data from towers.

11.1.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.

Note
The Tower ID may be replaced with the Tower Name as long as the name is unique in the system.
If the name is not unique, an HTTP error code 422 (Unprocessable Entity) will be returned.

3/2/18 Cambium Networks Confidential Page 22 of 37

11.1.2 Response

Body

Name Details
id Identifier of the tower.
location Location of the tower.
name Name of the tower.
network Network to which the tower belongs.

11.2 Sub-Resources
The following sub-resources can be applied to Tower URLs.

/api/v1/networks/{NID}/towers/{TID}/{Devices API} Statistics for devices on tower.

12 Statistics API
12.1.1 Overview

GET /api/v1/devices/statistics

GET /api/v1/devices/{MAC}/statistics

Retrieve statistics data from a resource (currently only devices are supported). Statistics parameters
can be used in tandem with parameters available for the resource.

12.1.2 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.

12.1.3 Response

Body

Name Details ePMP PMP WiFi cnReach

General
ap_mac AP MAC SM SM
config_version Configuration version AP/SM AP/SM
connected_sms Connected SM count AP AP
distance SM distance (miles) SM SM
gain Antenna gain (dBi) AP/SM AP/SM
gps_sync_state GPS synchronization state AP/SM
last_sync Last synchronization (UTC
AP/SM AP/SM
Unix time milliseconds)

3/2/18 Cambium Networks Confidential Page 23 of 37

mac MAC address AP/SM AP/SM All
Device mode
mode AP/SM AP/SM All
[ap, sm]
name Device name AP/SM AP/SM All
network Network AP/SM AP/SM All
parent_mac Parent MAC All
reboots Reboot count AP/SM
session_drops Session drops AP
site Site name All
Status
status [online, offline,
AP/SM AP/SM All
claimed, waiting,
onboarding]
status_time Uptime/downtime interval (sec) AP/SM AP/SM All
temperature Temperature AP/SM
tower Tower name AP AP
Device type
type [epmp, pmp, wifi-home, All
wifi-enterprise]
vlan VLAN AP/SM
Networks
default_gateway Default gateway AP/SM AP/SM All
ip_dns DNS AP/SM AP/SM All
ip_dns_secondary Secondary DNS AP/SM All
ip_wan WAN IP AP/SM All
LAN mode status
lan_mode_status AP/SM
[no-data, half, full]
lan_mtu MTU size SM
lan_speed_status LAN speed status AP/SM All
LAN status
lan_status AP/SM
[down, up]
netmask Network mask AP/SM AP/SM All
Radios (Fixed Wireless)
radio.auth_mode Authentication mode AP/SM
Authentication type
ePMP
radio.auth_type [open, wpa1, eap-ttls] AP/SM
PMP:
[disabled, enabled]
Channel width
ePMP:
[5 MHz, 10 MHz, 20
radio.channel_width AP/SM AP/SM
MHz, 40 MHz]
PMP:
[…]
radio.color_code Color code AP/SM AP/SM
DFS status
ePMP:
[not-applicable,
channel-availability-
check, in-service,
radio.dfs_status radar-signal-detected, AP/SM AP/SM
alternate-channel-
monitoring, not-in-
service]
PMP:
[Status String]
radio.dl_frame_utilization Downlink frame utilization AP
radio.dl_mcs MCS SM
radio.dl_pkts Usage (packet count) AP/SM AP/SM
radio.dl_retransmits Retransmission AP/SM
radio.dl_retransmits_pct Retransmission percentage AP/SM
radio.dl_rssi RSSI SM SM
radio.dl_rssi_imbalance Downlink RSSI imbalance AP
radio.dl_snr SNR (dB) SM

3/2/18 Cambium Networks Confidential Page 24 of 37

radio.dl_modulation Modulation SM
radio.dl_throughput Downlink throughput AP
radio.frame_period Frame period AP
radio.frequency RF frequency AP/SM AP/SM
radio.mac Wireless MAC AP/SM
Radio mode
[eptp-master, eptp-
radio.mode AP/SM
slave, tdd, tdd-ptp,
wifi]
radio.sessions_dropped Session drops AP AP/SM
radio.ssid SSID AP/SM
radio.sync_source Synchronization source AP
radio.sync_state Synchronization state AP
TDD ratio
ePMP:
[75/25, 50/50, 30/70,
radio.tdd_ratio AP/SM AP/SM
flexible]
PMP:
[…]
radio.tx_capacity SM transmit capacity SM
radio.tx_power Radio transmit power AP/SM AP/SM
radio.tx_quality SM transmit quality SM
radio.ul_frame_utilization Uplink frame utilization AP
radio.ul_mcs Uplink MCS AP/SM
radio.ul_modulation Modulation SM
e.g. [2X MIMO-B)]
radio.ul_pkts Usage (packet count) AP/SM AP/SM
radio.ul_retransmits Retransmission AP/SM
radio.ul_retransmits_pct Retransmission percentage AP/SM
radio.ul_rssi RSSI SM SM
radio.ul_snr SNR (dB) SM
radio.ul_throughput Uplink throughput AP
WLAN status
radio.wlan_status AP/SM
[down, up]
Radios (WiFi)
radio.24ghz.airtime Airtime All
radio.24ghz.channel Channel All
radio.24ghz.multicast_rate Multicast rate All
radio.24ghz.noise_floor Noise floor All
radio.24ghz.num_clients Number of clients All
radio.24ghz.num_wlans Number of WLANs Enterprise
radio.24ghz.power Transmit power All
radio.24ghz.quality RF Quality description Enterprise
radio.24ghz.radio_state Radio state Enterprise
radio.24ghz.rx_bps Receive bits/second Enterprise
radio.24ghz.rx_bytes Receive bytes All
radio.24ghz.tx_bps Transmit bits/second Enterprise
radio.24ghz.tx_bytes Transmit bytes All
radio.24ghz.unicast_rates Unicast rates All
radio.24ghz.utilization Radio utilization Enterprise
radio.5ghz.airtime Airtime All
radio.5ghz.channel Channel Enterprise
radio.5ghz.multicast_rate Multicast rate All
radio.5ghz.noise_floor Noise floor All
radio.5ghz.num_clients Number of clients Enterprise
radio.5ghz.num_wlans Number of WLANs Enterprise
radio.5ghz.power Transmit power All
radio.5ghz.quality RF quality description Enterprise
radio.5ghz.radio_state Radio state Enterprise
radio.5ghz.rx_bps Receive bits/second Enterprise
radio.5ghz.rx_bytes Receive bytes All
radio.5ghz.tx_bps Transmit bits/second Enterprise
radio.5ghz.tx_bytes Transmit bytes All
radio.5ghz.unicast_rates Unicast rates All

3/2/18 Cambium Networks Confidential Page 25 of 37

radio.5ghz.utilization Radio utilization Enterprise
Radios (cnReach)
radio.radio1.margin Margin Radios
radio.radio1.mode Radio mode
Radios
[ap, ep, rep]
radio.radio1.neighbors Radio neighbors Radios
radio.radio1.noise Average noise (dB) Radios
radio.radio1.power Transmit power Radios
radio.radio1.rssi RSSI value (dB) Radios
radio.radio1.rx_bytes Receive bytes Radios
radio.radio1.software_version Current software version. Radios
radio.radio1.temperature Radio temperature Radios
radio.radio1.tx_bytes Transmit bytes Radios
radio.radio1.type Radio type
Radios
[ptp, pmp]
radio.radio1.vlan Connected VLAN ID. Radios
radio.radio2.margin Margin Radios
radio.radio2.mode Radio mode
Radios
[ap, ep, rep]
radio.radio2.neighbors Radio neighbors Radios
radio.radio2.noise Average noise Radios
radio.radio2.power Transmit power Radios
radio.radio2.rssi RSSI value (dB) Radios
radio.radio2.rx_bytes Receive bytes Radios
radio.radio2.software_version Radio current software
Radios
version.
radio.radio2.temperature Radio temperature Radios
radio.radio2.tx_bytes Transmit bytes Radios
radio.radio2.type Radio type
Radios
[ptp, pmp]
radio.radio2.vlan Connected VLAN id. Radios
Interfaces (cnReach)
interface.default_gateway Interface gateway All
interface.ip Interface IP Address All
interface.ip_dns Interface DNS1 IP address All
interface.mac Interface MAC address All
interface.name Interface name (vlan1, rad1) All
interface.netmask Interface mask All

13 Performance API
13.1.1 Device

GET /api/v1/devices/performance

GET /api/v1/devices/{MAC Address}/performance

Retrieve performance data from a resource (currently only devices are supported). Performance
parameters can be used in tandem with parameters available for the resource.

13.1.2 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

3/2/18 Cambium Networks Confidential Page 26 of 37

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.(These limit and offset are for devices(MACs) and not for
metrics objects count in the response)
start_time Start time for performance data in ISO 8601 format.
stop_time Stop time for performance data in ISO 8601 format.

13.1.3 Response

Body

Name Details ePMP PMP WiFi cnReach

General
mac MAC address AP/SM AP/SM All All
mode Device mode AP/SM AP/SM All All
name Device name AP/SM AP/SM All All
network Network AP/SM AP/SM All All
site Site All All
sm_count Connected SM count AP AP
sm_drops Session drops AP/SM AP
timestamp Timestamp AP/SM AP/SM All All
tower Tower AP AP All
Device type
type [epmp, pmp, wifi-home, AP/SM AP/SM All All
wifi-enterprise]
Radios (Fixed Wireless)
radio.dl_frame_utilization Frame utilization AP
radio.dl_kbits Usage (in kbits on hour or
AP/SM
minute basis)
radio.dl_mcs MCS SM
radio.dl_modulation Modulation SM
radio.dl_pkts Usage (packet count) AP/SM
radio.dl_retransmits_pct Retransmission percentage AP/SM
radio.dl_rssi RSSI SM SM
radio.dl_rssi_imbalance RSSI imbalance SM
radio.dl_snr SNR SM
radio.dl_throughput Throughput (Kbps) AP/SM AP/SM All
radio.ul_frame_utilization Frame utilization AP
radio.ul.kbits Usage (in Kbits on hour or
AP/SM
minute basis)
radio.ul_mcs MCS SM
radio.ul_modulation Modulation SM
radio.ul_pkts Usage (packet count) AP/SM
radio.ul_retransmits_pct Retransmission percentage AP/SM
radio.ul_rssi RSSI SM SM
radio.ul_snr SNR SM
radio.ul_throughput Throughput (Kbps) AP/SM AP/SM All
Radios (WiFi)
radio.24ghz.clients Number of clients All
radio.24ghz.rx_bps Receive bits/second Enterprise
radio.24ghz.throughput Total throughput All
radio.24ghz.tx_bps Transmit bits/second Enterprise
radio.5ghz.clients Number of clients All
radio.5ghz.rx_bps Receive bits/second Enterprise
radio.5ghz.throughput Total throughput All
radio.5ghz.tx_bps Transmit bits/second Enterprise
Radios (cnReach)
radio.radio1.children Number of children Radios
radio.radio1.neighbors Radio neighbors Radios
radio.radio1.noise Average noise Radios
radio.radio1.power Transmit power Radios
radio.radio1.rssi RSSI value Radios

3/2/18 Cambium Networks Confidential Page 27 of 37

radio.radio1.rx_bytes Receive bytes Radios
radio.radio1.throughput Total throughput Radios
radio.radio1.tx_bytes Transmit bytes Radios
radio.radio2.children Number of children Radios
radio.radio2.neighbors Radio neighbors Radios
radio.radio2.noise Average noise Radios
radio.radio2.power Transmit power Radios
radio.radio2.rssi RSSI value Radios
radio.radio2.rx_bytes Receive bytes Radios
radio.radio2.throughput Total throughput Radios
radio.radio2.tx_bytes Transmit bytes Radios

14 WiFi APIs
14.1 WiFi Clients
GET /api/v1/devices/clients

GET /api/v1/devices/{MAC Address}/clients/{Client MAC}

Retrieve data for WiFi Clients. This API only works with cnPilot Enterprise and cnPilot Home.

14.1.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.

14.1.2 Response

Body

Name Details WiFi

ap_mac AP MAC
ip IP address of client
mac Client MAC
manufacturer Manufacturer name
name Client name
radio.band Band (2.4 GHz /5 GHz)
radio.rssi RSSI
radio.rx_bytes Received bytes
radio.snr SNR
radio.ssid SSID
radio.tx_bytes Transmitted bytes

14.2 WiFi Mesh Peers

GET /api/v1/devices/mesh/peers

GET /api/v1/devices/mesh/peers/{Peer MAC}

3/2/18 Cambium Networks Confidential Page 28 of 37

 GET /api/v1/devices/{MAC Address}/mesh/peers/{Peer MAC}

Retrieve data for WiFi Peers. This API only works with cnPilot Enterprise.

14.2.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.

14.2.2 Response

Body

Name Details
Mesh Base AP
ap.base_mac Mesh Base MAC address
ap.description AP description
ap.last_sync AP last synchronization time
ap.mac AP MAC address
ap.name AP hostname
ap.site Site to which the AP belongs
ap.status Status of AP (online/offline)
ap.status_time Duration since the AP is online or offline
ap.24Ghz.airtime Airtime utilization on 2.4 GHz radio in percentage (%)
ap.24Ghz.noise_floor Noise floor of 2.4 GHz radio
ap.24Ghz.rx_bytes Total received bytes on 2.4 GHz radio
ap.24Ghz.tx_bytes Total transmitted bytes on 2.4 GHz radio
ap.5Ghz.airtime Airtime utilization on 5 GHz radio in percentage (%)
ap.5Ghz.noise_floor Noise floor of 5 GHz radio
ap.5Ghz.rx_bytes Total received bytes on 5 GHz radio
ap.5Ghz.tx_bytes Total transmitted bytes on 5 GHz radio
Mesh Peer
ip Mesh Peer IP address
mac Mesh Peer MAC address
name Mesh Peer hostname
Radio (Mesh Peer)
radio.band Mesh Peer radio band
radio.data_rate Data rate in Mbps
radio.rssi Mesh Peer RSSI
radio.rx_bytes Total received bytes
radio.snr Mesh Peer SNR
radio.ssid Mesh Peer SSID
radio.tx_bytes Total transmitted bytes

14.2.3 Example

Request
curl https://10.110.134.134/api/v1/devices/mesh/peers/BC-62-9F-05-37-61 \
-X GET -k \
-H "Authorization: Bearer 6b2a1954bf8fd13a93a8772247876d6ace65b304"

3/2/18 Cambium Networks Confidential Page 29 of 37

 Response
{
"paging": {
"limit": 100,
"total": 1
},
"data": [
{
"ip": "10.110.235.73",
"mac": "BC-62-9F-05-37-61",
"name": "",
"ap": {
"mac": "00:04:56:B6:74:14",
"base_mac": "00-04-56-B6-86-22",
"name": "E400-B67414",
"description": "Base AP For Demo",
"site": "Central",
"up_time": "0d 5h 38m",
"24Ghz": {
"noise_floor": "-94",
"airtime": "72/4/68/0",
"tx_bytes": 5464,
"rx_bytes": 3360
},
"5Ghz": {
"noise_floor": "-104",
"airtime": "4/0/4/0",
"tx_bytes": 574,
"rx_bytes": 34860
}
},
"radio": {
"band": "2.4GHz",
"rssi": -46,
"snr": 54,
"ssid": "Auto-RF-2G-new",
"tx_bytes": 573464,
"rx_bytes": 349360,
"data_rate": 72.109
}
}
]
}

14.2.4 Sub-Resources
The following sub-resources can be applied to Mesh Peer URLs.

/api/v1/devices/mesh/peers/end_hosts/{End Host MAC} End Host connected to a Mesh Peer.

14.2.4.1 Response

Body

Name Details
Mesh Base AP
ap.base_mac Mesh Base MAC Address
ap.description AP description
ap.ip AP IP address
ap.mac AP MAC address
ap.name AP hostname
ap.site Site to which the AP belongs
ap.24Ghz.airtime Airtime utilization on 2.4 GHz radio in percentage (%)
ap.24Ghz.noise_floor Noise floor of 2.4 GHz radio
ap.24Ghz.rx_bytes Total received bytes on 2.4 GHz radio

3/2/18 Cambium Networks Confidential Page 30 of 37

 ap.24Ghz.tx_bytes Total transmitted bytes on 2.4 GHz radio
ap.5Ghz.airtime Airtime utilization on 5 GHz radio in percentage (%)
ap.5Ghz.noise_floor Noise floor of 5 GHz radio
ap.5Ghz.rx_bytes Total received bytes on 5 GHz radio
ap.5Ghz.tx_bytes Total transmitted bytes on 5 GHz radio
Mesh Peer
ip Mesh Peer IP address
mac Mesh Peer MAC address
name Mesh Peer hostname
Radio (Mesh Peer)
radio.band Mesh Peer radio band
radio.data_rate Data rate in Mbps
radio.rssi Mesh Peer RSSI
radio.rx_bytes Total received bytes
radio.snr Mesh Peer SNR
radio.ssid Mesh Peer SSID
radio.tx_bytes Total transmitted bytes

14.2.4.2 Example

Request
curl https://10.110.134.134/api/v1/devices/mesh/peers/end_hosts/00-04-56-0F-A4-D9 \
-X GET -k \
-H "Authorization: Bearer 6b2a1954bf8fd13a93a8772247876d6ace65b304"
Response
{
"paging": {
"limit": 100,
"total": 1
},
"data": [
{
"ip": "10.110.235.73",
"mac": "BC-62-9F-05-37-61",
"name": "",
"ap": {
"mac": "00:04:56:B6:74:14",
"base_mac": "00-04-56-B6-86-22",
"name": "E400-B67414",
"description": "Base AP For Demo",
"site": "Central",
"up_time": "0d 5h 38m",
"24Ghz": {
"noise_floor": "-94",
"airtime": "72/4/68/0",
"tx_bytes": 5464,
"rx_bytes": 3360
},
"5Ghz": {
"noise_floor": "-104",
"airtime": "4/0/4/0",
"tx_bytes": 574,
"rx_bytes": 34860
}
},
"radio": {
"band": "2.4GHz",
"rssi": -46,
"snr": 54,
"ssid": "Auto-RF-2G-new",
"tx_bytes": 573464,
"rx_bytes": 349360,
"data_rate": 72.109
}
}

3/2/18 Cambium Networks Confidential Page 31 of 37

 ]
}

15 Alarms API
15.1 Active Alarms
GET /api/v1/alarms

Retrieve active alarm data.

15.1.1 Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.
severity Alarm severity [critical, major, minor]

15.1.2 Response

Body

Name Details
acknowledged_by Acknowledged by
code Category code
duration Duration (seconds)
id Alarm Id
mac MAC address
message Message
name Alarm name
network Network
severity Severity
site Site
source Device name
source_type Device type
status Status
time_raised Raised time
tower Tower

15.2 Alarm History

GET /api/v1/alarms/history

Retrieve active and historical alarm data.

15.2.1 Request

HTTP Headers

3/2/18 Cambium Networks Confidential Page 32 of 37

 Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.
severity Alarm severity [critical, major, minor]
start_time Start time of the interval where the alarms are active (ISO 8601 format).
state Alarm state (active, cleared).
stop_time Stop time of the interval where the alarms are active (ISO 8601 format).

15.2.2 Response

Body

Name Details
acknowledged_by Acknowledged by
code Category code
duration Duration (seconds)
id Alarm Id
mac MAC address
message Message
name Alarm name
network Network
severity Severity
site Site
source Device name
source_type Device type
status Status
time_cleared Clear time
time_raised Raised time
tower Tower

16 Events API
16.1.1 Overview

GET /api/v1/events

Retrieve event log.

Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

Header Value
fields Select JSON fields to be returned.

3/2/18 Cambium Networks Confidential Page 33 of 37

 limit, offset Pagination functionality.
severity Alarm severity (critical, major, minor).
start_time Start time of the event generation timestamp (ISO 8601 format).
stop_time Stop time of the event generation timestamp (ISO 8601 format).

Response

Body

Name Details
code Category code
id Unique event Id
mac MAC address
message Message
name Event name
network Network
severity Severity
site Site
source Device name
source_type Device type
time_raised Raised time
tower Tower

17 Sessions API
17.1.1 Overview

GET /api/v1/users/sessions

Retrieve the session information for current administrators.

Request

HTTP Headers

Header Value
Accept (optional) application/json
Authorization Bearer <ACCESS_TOKEN>

Parameters

Header Value
fields Select JSON fields to be returned.
limit, offset Pagination functionality.

Response

Body

Name Details
duration Duration of session in seconds
id Session Id
role Role of the administrator
user User name of the administrator

18 Sample Python Code

3/2/18 Cambium Networks Confidential Page 34 of 37
18.1 API Client
To execute the client, type the command below. The code is for Python 2.7, and may require the
python2.7 command in Linux.

python client.py

18.2 Code
# Copyright (C) 2017 Cambium Networks, LTD. All rights reserved.
#
# API test code for cnMaestro that demonstrates session establishment and API
# calls. The client connects to cnMaestro using the Client Id and Client
# Secret downloaded from the Client API page in the cnMaestro UI. The Client
# receives a URL, Access Token, and Expiration Interval (in seconds)
# defining how long the token is valid. The URL and Access Token are used
# for subsequent API requests.
#
# This example also demonstrates the Token Validation API, which connects to
# cnMaestro directly, and not necessarily the URL returned during session
# establishment (though in On-Premises, they will be identical).
#

import sys
import requests
import json
import base64

HOST = '10.10.10.10'
CLIENT_ID = 'b3hmeraj3Xse24Qj'
CLIENT_SECRET = 'oCrhxTwqQ34O2E6pCLXMq9dEs8tzPL'

# Simple HTTP return function. Exit script on error.

def check_http_return(section, url, code, request):
if int(code) != 200:
print '%s failed with HTTP status %d' % (section, code)
print 'URL: %s' % url
try:
print json.dumps(request.json(), indent=2)
except: pass
sys.exit(1)

# Retrieve access parameters (url, access_token, and expires_in).

def get_access_parameters(host, client_id, client_secret):
token_url = 'https://%s/api/v1/access/token' % host
encoded_credentials = base64.b64encode("%s:%s" % (client_id, client_secret))
headers = {
'Authorization': 'Basic %s' % encoded_credentials,
'Content-Type':'application/x-www-form-urlencoded'
}
body = 'grant_type=client_credentials'
r = requests.post(token_url, body, headers=headers, verify=False)
check_http_return('Access Parameters', token_url, r.status_code, r)
return r.json()['access_token'], r.json()['expires_in']

# Validate the expiration of the access token.

def validate_access_token(host, access_token):
validate_url = 'https://%s/api/v1/access/validate_token' % (host)
headers = {
'Authorization': 'Bearer %s' % access_token,
}
r = requests.get(validate_url, headers=headers, verify=False)
check_http_return('Validate Access Token', validate_url, r.status_code, r)
return r.json()['expires_in']

# Execute API using URL returned in access parameters.

def call_api(host, path, access_token):
api_url = 'https://%s%s' % (host, path)
headers = {
'Authorization': 'Bearer %s' % access_token,
}
r = requests.get(api_url, headers=headers, verify=False)
check_http_return("API", api_url, r.status_code, r)

3/2/18 Cambium Networks Confidential Page 35 of 37

 return r.json()

# Main function.
if __name__== '__main__':
# Retrieve access parameters and generate API session
print '\nRetrieve Access Parameters'
access_token, expires_in = get_access_parameters(HOST, CLIENT_ID, CLIENT_SECRET)
print 'Success: access_token (%s) expires_in (%s)\n' % (access_token, expires_in)

# Validate time remaining for the access token

print 'Validating expiration time'
expires_in_check = validate_access_token(HOST, access_token)
print 'Success: expiresIn (%s)\n' % (expires_in_check)

# Execute a basic API call

print ('Sending an API message')
#data = call_api(HOST, '/api/v1/alarms', access_token)
data = call_api(HOST, '/api/v1/devices', access_token)
#data = call_api(HOST, '/api/v1/devices/statistics', access_token)
#data = call_api(HOST, '/api/v1/events', access_token)
#data = call_api(HOST, '/api/v1/networks', access_token)
#data = call_api(HOST, '/api/v1/sites', access_token)
#data = call_api(HOST, '/api/v1/devices/statistics?fields=mac,type,ip_wan',
access_token)
if data: print json.dumps(data, indent=2)

19 Appendix: API List

This appendix lists the supported APIs.

Path Details
Alarms API
/api/v1/alarms List of all active alarms.
/api/v1/alarms/{Alarm ID} Details on a single active alarm (not supported)
/api/v1/alarms/history List of all historical and active alarms.
Details on a single historical or active alarm. (not
/api/v1/alarms/history/{Alarm ID}
supported)

Devices API
/api/v1/devices System device inventory
/api/v1/devices/{Alarms API} System device alarms
/api/v1/devices/{Clients API} System WiFi clients
/api/v1/devices/{Events API} System device events
/api/v1/devices/{Mesh API} System WiFi mesh peers.
/api/v1/devices/statistics System device statistics
/api/v1/devices/performance System device performance
/api/v1/devices/{MAC} Single device inventory
/api/v1/devices/{MAC}/{Alarms API} Single device alarms
/api/v1/devices/{MAC}/{Clients API} Single device WiFi clients
/api/v1/devices/{MAC}/{Events API} Single device events
/api/v1/devices/{MAC}/{Mesh API} Single device WiFi mesh peers
/api/v1/devices/{MAC}/reboot Single device reboot operation
/api/v1/devices/{MAC}/statistics Single device statistics
/api/v1/devices/{MAC}/performance Single device performance

Events API
/api/v1/events List of all events.

Guest Access Portal API

/api/v1/portals
/api/v1/portals/{Portal ID}

Networks API
/api/v1/networks System network inventory
/api/v1/networks/{NID} Single network inventory

3/2/18 Cambium Networks Confidential Page 36 of 37

/api/v1/networks/{NID}/[Devices API] Single network devices

Sessions API
/api/v1/users/sessions Session information for current administrators.

Sites API
/api/v1/networks/{NID}/sites System site inventory
/api/v1/networks/{NID}/sites/{SID} Single site inventory
/api/v1/networks/{NID}/sites/{SID}/[Devices API] Single site devices

Towers API
/api/v1/networks/{NID}/towers System towers inventory
/api/v1/networks/{NID}/towers/{TID} Single tower inventory
/api/v1/networks/{NID}/towers/{TID}/[Devices API] Single tower devices

20 Contacting Cambium Networks

Support Website http://www.cambiumnetworks.com/support
Main Website http://www.cambiumnetworks.com
Cambium Community http://community.cambiumnetworks.com
Sales Enquiries [email protected]
Support Enquiries [email protected]
Telephone Number List http://www.cambiumnetworks.com/support/contact-support
Cambium Networks Limited,
Address 3800 Golf Road, Suite 360,
Rolling Meadows, IL 60008 USA.

3/2/18 Cambium Networks Confidential Page 37 of 37