NetCloud API
Cradlepoint provides a robust Application Program Interface (API)
allowing customers and partners powerful means to integrate NCM
data into their applications. The API enables automated data
transfer based on consistent and efficient programmatic methods.
Use the following steps to access the API Portal:
Note: The API Portal link on the Tools page uses your NCM login to automatically
log you into the API Portal.
For other ways to extend and integrate with NetCloud,
see the NetCloud Extensibility Solutions page.
Documentation
Use the failovers endpoint to retrieve data for failover events on individual routers, groups of routers, and across your account.
A failover event represents when a Cradlepoint device (without load balancing enabled) with multiple WAN interfaces changes its primary WAN interface from a higher-priority interface to a lower-priority interface.
Note: The failovers endpoint requires NCOS version 7.1.30 or newer.
Supported methods: GET.
Failovers Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account_id | int | Your account ID number | |||
ended_at | datetime | _exact=, _gt=, _gte=, _lt=, _lte= | Datetime for when a failover event ended | ||
group_id | int | The ID of a group to view failover events | |||
limit | int | Number of records to return | |||
offset | int | ||||
router_id | int | The ID of a router to view failover events | |||
started_at | datetime | _exact=, _gt=, _gte=, _lt=, _lte= | Datetime for when a failover event started |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/device_failover_events/
When using datetime fields (started_at, ended_at) you must provide the time portion in your call. For example, use "2019-08-12T09:29:34" and not "2015-08-12".
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ { "data": [ { "account_id": 55993, "carrier_name": "Verizon", "current_wan_interface": "ethernet-wan", "current_wan_priority": 0.00088295, "data_usage": 65898, "elapsed_time": 32, "ended_at": "2019-10-22T20:26:34.033177+00:00", "group_id": 145242, "group_name": "2200", "percent_data_cap": null, "previous_wan_interface": "mdm-3983dbd5", "previous_wan_priority": 2.25014338, "router_id": 1507274, "router_name": "AER2200-120", "started_at": "2019-10-22T20:26:01.870771+00:00", "tenant_id": "0013800001TB9s1", "updated_at": "2019-10-22T20:27:32.390005+00:00", "uuid": "6a701002-652b-4137-9ead-5847ae338ccd" }, { "account_id": 55993, "carrier_name": "Verizon", "current_wan_interface": "ethernet-wan", "current_wan_priority": 0.00088295, "data_usage": 74607, "elapsed_time": 96, "ended_at": "2019-10-22T20:32:24.293963+00:00", "group_id": 145242, "group_name": "2200", "percent_data_cap": null, "previous_wan_interface": "mdm-3983dbd5", "previous_wan_priority": 1.50014338, "router_id": 1507274, "router_name": "AER2200-120", "started_at": "2019-10-22T20:30:47.578229+00:00", "tenant_id": "0013800001TB9s1", "updated_at": "2019-10-22T20:33:18.376541+00:00", "uuid": "c3636db8-dd82-4974-a245-7ce872674afa" }, { "account_id": 55993, "carrier_name": "AT&T", "current_wan_interface": "ethernet-wan", "current_wan_priority": 0.00088295, "data_usage": 79261, "elapsed_time": 93, "ended_at": "2019-10-22T22:19:29.456995+00:00", "group_id": 145243, "group_name": "ibr900", "percent_data_cap": null, "previous_wan_interface": "mdm-11162acf6", "previous_wan_priority": 0.500773076, "router_id": 1507400, "router_name": "IBR900-40c", "started_at": "2019-10-22T22:17:56.025395+00:00", "tenant_id": "0013800001TB9s1", "updated_at": "2019-10-22T22:20:52.537549+00:00", "uuid": "7083210f-6643-40a2-80ba-7a4c7012ee42" }, { "account_id": 55993, "carrier_name": "AT&T", "current_wan_interface": "ethernet-wan", "current_wan_priority": 0.00088295, "data_usage": 81612, "elapsed_time": 74, "ended_at": "2019-10-23T15:27:28.981281+00:00", "group_id": 145243, "group_name": "ibr900", "percent_data_cap": null, "previous_wan_interface": "mdm-11162acf6", "previous_wan_priority": 0.500773076, "router_id": 1507400, "router_name": "IBR900-40c", "started_at": "2019-10-23T15:26:14.072588+00:00", "tenant_id": "0013800001TB9s1", "updated_at": "2019-10-23T15:28:52.164089+00:00", "uuid": "a25093f5-5359-4b5a-815c-d2916ba80b03" } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Failovers Methods
As an authorized user, you always have access to the account that you belong. This is your “owning” account because it owns your user information. The owning account is the root of the object hierarchy that you have access.
Supported methods: GET, POST, PUT, DELETE.
The Account Object
Parameter | Data Type | Filter | Sort | Expand | Description | Permissions |
account*! | url | =, __in |
![]() |
Parent account | Read/Write | |
id! | int | =, __in | Object ID | Read Only | ||
is_disabled | bool | True if the account is disabled | Read Only | |||
name*! | string | =, __in | Name of the account | Read/Write | ||
resource_url | url | Object URL | Read Only |
Note: * indicates the attribute is required in the request body for PUT and POST requests.
Note: ! indicates the attribute is required for PUT requests.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/accounts/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/308/", "id": "241", "is_disabled": false, "name": "cradlepoint", "resource_url": "https://www.cradlepointecm.com/api/v2/accounts/241/" }, { "account": "https://www.cradlepointecm.com/api/v2/accounts/123/", "id": "308", "is_disabled": false, "name": "root", "resource_url": "https://www.cradlepointecm.com/api/v2/accounts/308/" }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Account Methods
Use the batteries endpoint to retrieve battery information for E100/E100B devices. Note the following when interpreting values returned by this endpoint.
- A battery's "status" field contains a positive value while a battery is charging and a negative value while discharging. A battery is considered charged when its capacity is within 15% of its design capacity.
- A battery's "health" is a ratio of its present capacity and its design capacity.
- The following alerts can be configured for monitoring the state of batteries in a router.
- Battery Health: creates an alert when the remaining battery life reaches 62%
- Battery Over Current: creates an alert when the battery's current reaches 3.2 amps
- Battery Over Temperature: creates an alert when the battery's temperature reaches 50 degrees Celsius
- Battery Over Voltage: creates an alert when the battery's recommended voltage reaches 8.5V (8500 mV)
- Battery System Low Power: creates an alert when the battery's power reaches 20% charge
- Battery System Power Off: creates an alert when the battery's power reaches 7% charge
Supported methods: GET
The Batteries Object
Parameter | Data Type | Filter | Sort | Expand | Description |
type | string | Type of power source | |||
router_id | int | =, __in | ID of the router containing the battery(s) to query | ||
created_at | timestamp | Date/time of battery's initial record in NetCloud | |||
updated_at | timestamp | Battery's most recent update date/time in NetCloud | |||
serial | string | Battery serial number | |||
milliamps | int | Battery current (milliamps, negative indicates discharging) | |||
millivolts | int | Battery voltage (millivolts) | |||
temp | int | Battery temperature | |||
rsoc | int | Relative state of charge | |||
health | int | Ratio of present capacity and design capacity | |||
time_remaining | int | Battery time remaining, in minutes | |||
manufacturer | string | Manufacturer of battery | |||
status | string | State of battery (charging, discharging, idle) |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/batteries/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
HTTP/1.1 200 OK Content-Type: application/vnd.api+json { "data": [ { "type": "battery", "id": "15496", "created_at": "2020-01-01 00:00:00" "updated_at": "2020-01-02 00:00:00" "serial": "12345", "milliamps": -257, "health": 100, "rsoc": 62, "temp": 29, "time_remaining": 1131, "millivolts": 7567, "manufacturer": "GETAC", "status": "Discharging", }, { "type": "battery", "id": "15496", "created_at": "2020-01-01 00:00:00" "updated_at": "2020-01-02 00:00:00" "serial": "45345", "milliamps": -221, "health": 100, "rsoc": 59, "temp": 27, "time_remaining": 1061, "millivolts": 7545, "manufacturer": "GETAC", "status": "Idle", }, { ... } ], } }
Batteries Methods
Use the activity_logs endpoint to view the activities taken in your account.
An activity occurs when an initiator (known as an actor) performs an activity (known as an action) upon an NCM entity (known as an object) within an NCM account.
- actor (actor__type): the initiator of an action (e.g. user, system, etc)
- action (action__type): something an actor did (updated a device configuration, logged in, created a group, etc)
- object (object__type): the NCM entity acted upon by an actor (e.g. sso acount, router, net_device, etc)
For example, 'user [x] registered a router' where user is the actor, registered is the action and router is the object.
Actors | Actions | Objects |
|
|
|
It is important to note that certain activities that are visible in the NCM Activity Logs are not available when calling this endpoint. These activities include the following:
- Changes to account level settings including Session Length, Forced MFA, Enhanced Login Security, and Company Contacts
- Creation/deletion and updates of user authorization within a company
- Creation/deletion and updates of users
- User logins and logouts
Supported methods: GET
The Activity Logs Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account | int | = | The ID of your account | ||
action__id | string | = | ID of the object for the activity | ||
action__timestamp | timestamp | _exact=, _gt=, _gte=, _lt=, _lte= | Timestamp for the action taken | ||
actor__id | string | = | ID (exact) of the actor who took the action | ||
actor__type | string | = | Type of actor who took the action | ||
created_at | timestamp | _exact=, _gt=, _gte=, _lt=, _lte= | Timestamp for the activity that occurred | ||
object__id | string | = | ID (exact) of the action taken | ||
object__type | string | = | Type of object the action was taken upon |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/activity_logs/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
The activity log entry: SSO user "employee@cradlepoint.com" created group "664" translates to the following JSON when this endpoint is called using: action__type: create actor__type: sso_user object__type: group { "action": { "type": "create", ... }, "actor": { ... "type": "sso_user", "email": "employee@cradlepoint.com" }, "object": { "type": "group", "name": "664" ... } }
Activity Logs Methods
NCM provides alert functionality to notify NCM users of the health and status of their account and devices. Alerts must be configured in NCM before they are generated. The default NCM configuration does not create any alerts. After the alerts have been configured, a customer can use the NCM UI or this endpoint to monitor alerts.
Special Notes:
- This endpoint does not have the standard filter limits of 100 values per field (ex. router__in=[1234,4321,...])
- This endpoint will have only one value out of the router field and the account field. The other value will always be "null." You can filter on the value being null or not with the isnull operation. For example, "/alerts/?router__isnull=true" will give you alerts where the router field has a "null" value.
- See the "router_alerts" endpoint on this page for details on alerts specific to routers.
Supported methods: GET
The Alerts Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account | url | =, __in, __isnull | Account this alert is related to, or null if the router field has a value | ||
created_at | timestamp | __gt, __lt | Time the alert record was created in NCM | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte |
![]() |
A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | |
detected_at | timestamp | Time the alert was detected | |||
friendly_info | string | Human-readable description of the alert | |||
info | json | Alert-type specific information | |||
router | url | =, __in, __isnull | Device this alert is related to, or null if the account field has a value | ||
type | string | =, __in | The type of the alert |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/alerts/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
Example query for an account-event alert:
"https://www.cradlepointecm.com/api/v2/alerts/?router__isnull=true"
Example alert for an account event:
{ "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/1234/", "created_at": "2018-07-17T19:49:51.897155+00:00", "created_at_timeuuid": "91fdfe9e-89fa-11e8-a68b-80ee73b5d9ef", "detected_at": "2018-07-17T19:49:51.882000+00:00", "friendly_info": "Verizon data usage alerted at 80 percent of the total monthly data plan.", "info": { "alert_rule": { "threshold": 80 }, "data_plan": { "carrier_name": "Verizon" } }, "router": null, "type": "pdp_account_overage" }, ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/alerts/?limit=1&created_at_timeuuid__lt=91fdfe9e-89fa-11e8-a68b-80ee73b5d9ef" } }
Example query for a router-event alert:
"https://www.cradlepointecm.com/api/v2/alerts/?router__isnull=false"
Example alert for a router event:
{ "data": [ { "account": null, "created_at": "2018-07-17T19:24:10.552143+00:00", "created_at_timeuuid": "fb476918-89f6-11e8-b7ac-80ee73b5d9ef", "detected_at": "2018-07-17T19:24:10.546000+00:00", "friendly_info": "The device entered the \"online\" state.", "info": { "state": "online" }, "router": "https://www.cradlepointecm.com/api/v2/routers/1/", "type": "connection_state" } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/alerts/?limit=1&router__isnull=false&created_at_timeuuid__lt=fb476918-89f6-11e8-b7ac-80ee73b5d9ef" } }
account_locked
info: { account: "root", type: "account_locked", timeout: 30, time: [ "2015-05-13 16:55:19", "UTC" ] }
ethernet_wan_connected
info: { status: "connected", info: { raw_port: "eth1", mac: "00:30:44:00:00:00", type: "ethernet", uid: "wan", port: "Ethernet 1" }, alert_type: "ethernet_wan_connected", time: [ "2015-04-29 21:08:37", "UTC" ], type: "wan_status_change", history: [ ] }
ethernet_wan_unplugged
info: { status: "unplugged", info: { raw_port: "eth1", mac: "00:30:00:00:00:00", type: "ethernet", uid: "wan", port: "Ethernet 1" }, alert_type: "ethernet_wan_unplugged", time: [ "2015-04-29 21:44:08", "UTC" ], type: "wan_status_change", history: [ ] }
wan_status_change
info: { status: "unplugged", info: { raw_port: "eth1", mac: "00:30:44:00:00:00", type: "ethernet", uid: "wan", port: "Ethernet 1" }, alert_type: "ethernet_wan_unplugged", time: [ "2015-04-29 21:07:59", "UTC" ], type: "wan_status_change", history: [ ] }
Alert Type | Description |
account_locked | The account is lock for 30 minutes after six failed attempts to log into the device. |
acs_noncompliant_devices | Indicates account has new non-compliant devices. |
acs_unlicensed_devices | Indicates account has new unlicensed devices. |
acs_expires_in_180_days | Indicates account has subscriptions expiring in 180 days. |
acs_expires_in_90_days | Indicates account has subscriptions expiring in 90 days. |
acs_expires_in_60_days | Indicates account has subscriptions expiring in 60 days. |
acs_expires_in_15_days | Indicates account has subscriptions expiring in 15 days. |
acs_expires_in_5_days | Indicates account has subscriptions expiring in 5 days. |
acs_unlicensed_in_15_days | Indicates account has devices unlicensing in 15 days. |
acs_unlicensed_in_5_days | Indicates account has devices unlicensing in 5 days. |
custom_alert | An alert generated by custom code in an NCOS SDK app. |
ethernet_wan_connected | An Ethernet WAN device is now active. |
ethernet_wan_disconnected | An Ethernet WAN device is no longer active. |
ethernet_wan_standby | An Ethernet WAN device is now in standby mode. |
ethernet_wan_unplugged | An Ethernet WAN device has been removed. |
gateway_added | Indicates that a NetCloud Gateway was added to a router, allowing it be part of an overlay network. |
gateway_removed | Indicates that a NetCloud Gateway was removed from a router, and the router has been disconnected from its overlay network. |
gateway_state_changed | Indicates that the status of a NetCloud Gateway has changed, which may or may not affect its connection to an overlay network. |
pdp_account_overage | Creates an alert when a user-defined usage percentage is met for a pooled data plan. |
pdp_router_overage | Creates an alert when a user-defined usage percentage is met for a single router. |
router_sdk_app_execution_state_changed | Indicates that an NCOS SDK app that is running on a group has entered a different execution state (start, stop, error, etc). |
router_sdk_mismatched_app_action | Indicates that an unexpected NCOS SDK app is found installed, an expected NCOS SDK app is unexpectedly uninstalled, or a that an NCOS app app unknown to the system is found installed. |
Alerts Methods
A device app object represents a Cradlepoint SDK app.
Supported methods: GET, DELETE.
The Device App Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account* | url | =, __in |
![]() |
Account that owns the object | |
created_at | timestamp | Time the device app object was created | |||
description | string | Optional description of the device app | |||
id | int | =, __in | Object ID | ||
name* | string | =, __in | The name of the device app | ||
resource_url | url | Object URL | |||
updated_at | timestamp | Time of last attribute update | |||
uuid* | int | =, __in | UUID of the app |
Note: * attributes are required for GET requests.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/device_apps/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ { "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "name": "hello_world", "description": "Router SDK Hello World Application", "uuid": "814cf62b-6441-45a3-a564-1ad45d5d934a", "created_at": "2015-08-10T16:19:31.784055+00:00", "updated_at": "2015-09-22T10:35:55.182602+00:00" "id": "17", "resource_url": "https://www.cradlepointecm.com/api/v2/device_apps/17/", }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Device Apps Methods
A device app version object represents the version of a Cradlepoint SDK application.
Supported methods: GET, DELETE.
The Device App Version Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account | url | =, __in |
![]() |
Account that owns the object | |
app | url | =, __in | Associated device app | ||
created_at | timestamp | Time the device app object was created | |||
id | int | =, __in | Object ID | ||
resource_url | url | Object URL | |||
state | string | =, __in | State of the app version | ||
state_details | string | Details of the app version state | |||
updated_at | timestamp | Time of last attribute update | |||
version | int | Version |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/device_app_versions/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ { "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "app": "https://www.cradlepointecm.com/api/v2/device_apps/727/", "created_at": "2018-09-07T21:29:36.968617+00:00", "id": "17", "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/17/", "state": "ready", "state_details": "", "updated_at": "2018-09-07T21:29:37.344942+00:00", "version": "1.0.0", }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Device App Versions Methods
A device app binding object represents a Cradlepoint SDK app group binding.
Supported methods: GET, POST, DELETE.
The Device App Binding Object
Parameter | Data Type | Filter | Sort | Expand | Description | Permissions |
account* | url | =, __in |
![]() |
Account that owns the object | Read/Write | |
app_version* | url | =, __in | The app version that will be tied to the group binding | Read/Write | ||
created_at | timestamp | Time the device app object was created | Read Only | |||
group* | url | =, __in | The group in which the binding will be applied | Read/Write | ||
id | int | =, __in | Object ID | Read Only | ||
resource_url | url | Object URL | Read/Write | |||
state | string | =, __in | State of the device app | Read/Write | ||
updated_at | timestamp | Time of last attribute update | Read/Write |
Note:* indicates the attribute is required for PUT and POST requests.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/device_app_bindings/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ { "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "app_version": "https://www.cradlepointecm.com/api/v2/device_app_versions/112/", "group": "https://www.cradlepointecm.com/api/v2/groups/93/", "state": "running", "created_at": "2015-08-10T16:19:31.784055+00:00", "updated_at": "2015-09-22T10:35:55.182602+00:00" "id": "17", "resource_url": "https://www.cradlepointecm.com/api/v2/device_apps/17/", }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Device App Bindings Methods
A device app state object represents the state of a Cradlepoint SDK app.
Supported methods: GET.
The Device App State Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account | url | =, __in |
![]() |
Account that owns the object | |
app_version | url | =, __in | The app version associated with device app | ||
created_at | timestamp | Time the device app object was created | |||
id | int | =, __in | Object ID | ||
resource_url | url | Object URL | |||
router | url | =, __in | The router with the device app | ||
state | string | =, __in | State of the device app | ||
updated_at | timestamp | Time of last attribute update |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/device_app_states/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ { "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "app_version": "https://www.cradlepointecm.com/api/v2/device_app_versions/112/", "state": "started", "router": "https://www.cradlepointecm.com/api/v2/routers/77/" "created_at": "2015-08-10T16:19:31.784055+00:00", "updated_at": "2015-09-22T10:35:55.182602+00:00" "id": "17", "resource_url": "https://www.cradlepointecm.com/api/v2/device_apps/17/", }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Device App States Methods
A router object represents a Cradlepoint device that is registered with NCM.
Supported methods: GET, PUT, DELETE.
The Router Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account | url | =, __in |
![]() |
Account that owns the object | |
actual_firmware | url | Firmware currently on the device, if known | |||
asset_id | string | User defined identifier often used for asset tracking | |||
config_status | string | Status of configuration synch: synched, pending or suspended | |||
created_at | timestamp | Time the device object was created | |||
custom1 | string | User defined custom text field | |||
custom2 | string | User defined custom text field | |||
description | string | Optional description of the device (synched with device) | |||
device_type | string | =, __in | Type of device, e.g. router or access point | ||
full_product_name | string | Device's full product name, e.g. IBR600LP-AT | |||
group | url | =, __in |
![]() |
Optional group this device belongs to | |
id | int | =, __in | Object ID | ||
ipv4_address | string | =, __in | Device's IPv4 address | ||
last_known_location | url |
![]() |
Optional last known location of the device | ||
locality | string | Device's timezone | |||
mac | string | =, __in | Device's MAC address | ||
name | string | =, __in | Device's name (synched with device) | ||
product | url | Device product, e.g. IBR600 or AP22 | |||
reboot_required | boolean | =, __in | Reboot required to enable additional device functionality | ||
resource_url | url | Object URL | |||
serial_number | string | Device's serial number, if known | |||
state | string | =, __in | Device's state: initialized, online or offline | ||
state_updated_at | timestamp | __lt, __gt | Time of last state update | ||
target_firmware | url | Firmware currently assigned to the router’s group | |||
upgrade_pending | boolean | The device has a pending NCOS upgrade | |||
updated_at | timestamp | __lt, __gt | Time of last attribute update |
Note: PUT requests require a (router) id.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/routers/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ { "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "actual_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/309/", "asset_id": null, "config_status": "synched", "created_at": "2015-08-10T16:19:31.784055+00:00", "custom1": null, "custom2": null, "description": null, "device_type": "router", "full_product_name": "2100", "group": null, "id": "20116", "ipv4_address": "216.64.128.1", "locality": "US/Mountain", "last_known_location": "https://www.cradlepointecm.com/api/v2/locations/9/", "mac": "80:08:00:F1:76:DC", "name": "80:08:00:f1:76:dc", "pc_removed": "unknown", "product": "https://www.cradlepointecm.com/api/v2/products/11/", "reboot_required": false, "resource_url": "https://www.cradlepointecm.com/api/v2/routers/20116/", "serial_number": null, "state": "offline", "state_updated_at": "2015-08-11T16:22:04.337310+00:00", "target_firmware": null, "updated_at": "2015-09-22T10:35:55.182602+00:00" }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Routers Methods
Net Devices are the network interfaces currently enabled in the Cradlepoint device. They are categorized as either WAN or LAN devices, as signified by the "mode" attribute, and further broken down by interface type, such as Ethernet, wireless, modem, LTE, etc.
Supported methods: GET.
The Net Device Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account | url | =, __in |
![]() |
Account that owns the object | |
bsid | string | Base Station ID | |||
carrier | string | The connected carrier if available. Otherwise, the carrier the modem is configured to connect to | |||
carrier_id | string | The carrier the modem is currently registered with | |||
channel | int | WiFi channel currently in use, if applicable | |||
connection_state | string | =, __in | Connected, Connecting, Disconnecting, Disconnected, Error, Ready, Configuring | ||
dns0 | string | Primary DNS server | |||
dns1 | string | Secondary DNS server | |||
esn | string | Electronic serial number | |||
gateway | string | Gateway server onto network | |||
gsn | string | Modem's global object identifier | |||
homecarrid | string | Modem's home carrier identifier | |||
hostname | string | Net device's hostname, if available | |||
iccid | string | Modem's SIM card's integrated circuit card identifier | |||
id | int | =, __in | Object ID | ||
imei | string | Modem's international mobile station equipment identity number | |||
imsi | string | Modem's SIM card's unique subscriber identity | |||
ipv4_address | string | =, __in | Device's IPv4 address | ||
is_asset | boolean | = | True for modem net devices | ||
is_gps_supported | boolean | True if the device supports GPS | |||
is_upgrade_available | boolean | True if a new version of modem firmware is available | |||
is_upgrade_supported | boolean | True if the modem firmware is upgradable | |||
ltebandwidth | string | Indicates the frequency width of the LTE Band being used by the modem module | |||
mac | string | MAC address of the net device | |||
manufacturer | string | Manufacturer of the net device | |||
mdn | string | Modem's mobile data number (phone number) | |||
meid | string | Modem's CDMA unique identifier | |||
mfg_model | string | Network device's manufacturing model | |||
mfg_product | string | Product name of the net device | |||
mn_ha_spi | string | Mobile Node Home Agent Security Parameter Index - Indicates the specific security association between the home agent and the mobile device and the algorithm used for security purposes | |||
mn_ha_ss | string | Mobile Node Home Agent Shared Secret - Contains the shared secret used between the home agent and mobile device for security purposes | |||
mode | string | =, __in | Net device's mode, WAN or LAN | ||
model | string | Net device's model | |||
model_fw | string | Modem's current firmware version | |||
mtu | int | Modem's network maximum transmission unit size | |||
nai | string | Modem's Network access identifier | |||
name | string | Network device's name, e.g. 'ethernet-wan', 'lte-1234abcd', 'mdm-dcba4321' | |||
netmask | string | Net device's netmask | |||
pin_status | string | Indicates the status of the SIM PIN. Examples include "READY", "PIN REQUIRED:, etc | |||
port | string | Port identifier on device | |||
prlv | string | Preferred Roaming List Version - Indicates the version of the Preferred Roaming List that is being used by the modem module | |||
profile | string | Indicates the active CDMA profile used by the modem module | |||
resource_url | url | Object URL | |||
rfband | string | Indicates the Radio Frequency Band that is currently being used by the modem module | |||
rfchannel | string | Indicates the Radio Frequency Channel that is currently being used by the modem module | |||
roam | string | Indicates if the modem is roaming outside its home network (0 - Roaming on a non-preferred network, 1 - Home network, 2 - Roaming on a preferred network) | |||
router | url | =, __in | ![]() |
Cradlepoint device the net device is currently connected to | |
rxchannel | string | Indicates the Radio Frequency Channel that is currently being used by for receiving data | |||
serial | string | Serial number of net device | |||
service_type | string | Connection mode: 3G, 4G, etc | |||
ssid | string | Service set identifier or network name | |||
summary | string | Additional net device state details, e.g. suspended, unconfigured, connecting, unplugged | |||
txchannel | string | Indicates the Radio Frequency Channel that is currently being used by for transmitting data | |||
type | string | Device type, e.g. 'mdm', 'modem', 'lte', 'ethernet' | |||
uid | string | A unique identifier used to the net device by the Cradlepoint device | |||
updated_at | timestamp | Time of last update to this object | |||
uptime | float | Time in seconds since the net device established its link | |||
ver_pkg | string | Indicates the firmware package version that is currently loaded on the modem module | |||
version | string | Firmware version of the network device | |||
wimax_realm | string | WiMAX realm string used to connect to a WiMAX network |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/net_devices/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "bsid": null, "carrier": null, "carrier_id": null, "channel": null, "connection_state": null, "dns0": null, "dns1": null, "esn": null, "gateway": null, "gsn": null, "homecarrid": null, "hostname": null, "iccid": null, "id": "83941", "imei": null, "imsi": null, "ipv4_address": null, "is_asset": false, "is_gps_supported": false, "is_upgrade_available": false, "is_upgrade_supported": false, "ltebandwidth": null, "mac": null, "manufacturer": null, "mdn": null, "meid": null, "mfg_model": null, "mn_ha_spi": null, "mn_ha_ss": null, "mode": "lan", "model": null, "modem_fw": null, "mtu": null, "nai": null, "name": "ethernet-lan", "netmask": null, "pin_status": null, "port": null, "prlv": null, "mfg_product": null, "profile": null, "resource_url": "https://www.cradlepointecm.com/api/v2/net_devices/83941/", "rfband": null, "rfchannel": null, "roam": null, "router": "https://www.cradlepointecm.com/api/v2/routers/20116/", "rxchannel": null, "serial": null, "service_type": "Ethernet", "ssid": null, "summary": null, "txchannel": null, "type": "ethernet", "uid": "lan", "updated_at": "2015-08-10T16:19:32.237596+00:00", "uptime": null, "ver_pkg": null, "version": null, "wimax_realm": null }, { ... } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/net_devices/?limit=20&offset=20", "offset": 0, "previous": null } }
Net Device Methods
A group is a list of devices. All the devices in the group must be of the same product type. The group must have a firmware version, and all the devices in the group upgrade to that version. A group may have a configuration, and all the devices in the group will use that configuration.
Supported methods: GET, POST, PUT, DELETE.
The Group Object
Parameter | Data Type | Filter | Sort | Expand | Description | Permissions |
account* | url | =, __in |
![]() |
Account which owns the object | Read/Write | |
configuration | json | Configuration for the group | Read/Write | |||
device_type | string | =, __in | Type of device, e.g. router or access point | Read Only | ||
id | int | =, __in | Object ID | Read/Write | ||
name* | string | =, __in | Name of the group | Read/Write | ||
product* | url | Product type for the group | Read/Write | |||
resource_url | url | Object URL | Read/Write | |||
target_firmware* | url | Firmware version for the group | Read/Write |
Note: * indicates the attribute is required for PUT and POST requests.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/groups/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "configuration" : [ { "system" : { "logging" : { "level" : "debug" } }, "webfilter" : { "proxy" : { "https_filtering" : true } } }, [] ], "id": "1127", "name": "g3", "product": "https://www.cradlepointecm.com/api/v2/products/11/", "resource_url": "https://www.cradlepointecm.com/api/v2/groups/1127/", "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/10/" }, { "account": "https://www.cradlepointecm.com/api/v2/accounts/241/", "configuration" : [ { "system" : { "logging" : { "level" : "debug" } }, "webfilter" : { "proxy" : { "https_filtering" : true } } }, [] ], "id": "1485", "name": "cradlepoint", "product": "https://www.cradlepointecm.com/api/v2/products/11/", "resource_url": "https://www.cradlepointecm.com/api/v2/groups/1485/", "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/10/" }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Group Methods
A product designates the device model. Each device model has unique characteristics.
Supported methods: GET.
The Product Object
Parameter | Data Type | Filter | Sort | Expand | Description |
device_type | string | =, __in | Type of device, e.g. router or access point | ||
id | int | =, __in | Object ID | ||
name | string | Name of the product, e.g. IBR600 | |||
resource_url | url | Object URL | |||
series | int | Series of the product, e.g. 2 or 3 |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/products/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "id": "1", "name": "MBR1400", "resource_url": "https://www.cradlepointecm.com/api/v2/products/1/", "series": 3 }, { "id": "2", "name": "MBR1400v2", "resource_url": "https://www.cradlepointecm.com/api/v2/products/2/", "series": 3 }, { ... } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/products/?limit=20&offset=20", "offset": 0, "previous": null } }
Products Methods
Use the net_device_health endpoint to view the quality and strength of the cellular signal, expressed as device uptime, for your Cradlepoint devices.
The following conditions should be considered when evaluating the uptime information returned by the net_device_health endpoint:
- Uptime data is available for routers with NCOS 6.2 or higher
- Routers must be managed by NCM in order for statistics to be gathered on them.
- Uptime statistics are calculated at the end of each day. A "day" is defined by a 24-hour period beginning at midnight UTC (Coordinate Universal Time).
- Removing a router from NCM, or moving a router to a new group, does not affect the historically-collected, group-uptime data. The history will not change if a router's group membership changes.
Supported methods: GET.
The Net Device Health Object
Parameter | Data Type | Filter | Sort | Expand | Description |
net_device | int | = | The id of the net_device. |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/net_device_health/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{"data": [], "meta": {"limit": 20, "next": null, "offset": 0, "previous": null}}
Net Device Health Methods
The historical_locations endpoint reports a history of the locations a device has traveled. Use this endpoint to obtain the data points that describe where a specific device has been physically located.
Beginning with NCOS version 7.1.30, your location data is stored (for devices with Location Tracking enabled) even if you lose your network connectivity. Location data is stored on your device and then uploaded to NetCloud when your connection resumes. This prevent gaps in your Location Services data and ensures you always have reliable information about the locations of your devices.
The historical_locations endpoint returns 5,000 location records per query by default (most Cradlepoint endpoints return 20 records by default). This ensures you receive enough historical-location data to meet your reporting needs.
Note: A maximum of 360 location data points are stored while your device is in motion but has no network connection.
Supported methods: GET.
Historical Locations Object
Parameter | Data Type | Filter | Sort | Expand | Description |
accuracy | int | Calculated accuracy of coordinates, based on latitude. | |||
carrier_id | string | The carrier the modem is currently registered with | |||
cinr | double | Carrier to Interference plus Noise Ratio (dB) | |||
created_at | timestamp | =, __gt, __lt | Time the sample was created | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte | A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | ||
dbm | int | Strength of received signal (dBm) | |||
ecio | int | Ec/Io, the ratio of average channel power to total signal power (dB) | |||
latitude | int | A device's relative position north or south on the Earth's surface, in degrees from the Equator | |||
longitude | int | A device's relative position east or west on the Earth's surface, in degrees from the prime meridian | |||
mph | float | Speed of the vehicle carrying the device | |||
net_device_name | float | Network device's name, e.g. 'ethernet-wan', 'lte-1234abcd', 'mdm-dcba4321' | |||
rfband | string | Indicates the Radio Frequency Band that is currently being used by the modem module | |||
rfband_5g | string | Indicates the 5G Radio Frequency Band that is currently being used by the modem module | |||
router | URL | = | The ID of the device providing the location information | ||
rsrp | double | LTE reference signal receive power | |||
rsrp_5g | double | 5G reference signal receive power | |||
rsrq | int | LTE reference signal receive quality | |||
rsrq_5g | int | 5G reference signal receive quality | |||
rssi | int | Received Signal Strength Indication (units vary with manufacturer) Note: Only for WiFi as WAN interfaces |
|||
signal_percent | int | Percent signal strength, derived heuristically from other values | |||
sinr | double | Signal to Interference plus Noise Ratio (dB) | |||
sinr_5g | double | 5G Signal to Interference plus Noise Ratio (dB) | |||
summary | string | Connected status of the net device. |
Note: * A router ID (?router=<router id>) is required when calling this endpoint's GET method.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/historical_locations/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
Historical Locations Methods
Net device usage samples are periodic reports of the number of bytes passed in and out of a net device. By default a net device will report its usage on an hourly basis, although this can be configured.
Supported methods: GET.
The Net Device Usage Sample Object
Parameter | Data Type | Filter | Sort | Expand | Description |
bytes_in | bigint | Bytes received to device since last update | |||
bytes_out | bigint | Bytes sent from device since last update | |||
created_at | timestamp | __gt, __lt | Time the sample was created | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte |
![]() |
A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | |
net_device | url | =, __in | Network device that reported the usage sample | ||
period | double | Time in seconds since the last sample was reported | |||
uptime | double | Time in seconds since the net device established its link |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/net_device_usage_samples/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "bytes_in": 76647420, "bytes_out": 74363677, "created_at": "2015-09-07T09:35:52.015531", "created_at_timeuuid": "d4732aae-5543-11e5-bbd2-0a811c6aca07", "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/94195/", "period": 2940, "uptime": 1214375 }, { ... } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/net_device_usage_samples/?created _at_timeuuid__gt=d4732aae-5543-11e5-bbd2-0a811c6aca07&limit=20" } }
Net Device Usage Sample Methods
Net device signal samples are periodic reports of modem signal strength indicators. By default a modem will report its current signal strength to NCM on an hourly basis, although this can be configured.
Supported methods: GET.
The Net Device Signal Sample Object
Parameter | Data Type | Filter | Sort | Expand | Description |
cinr | double | Carrier to Interference plus Noise Ratio (dB) | |||
created_at | timestamp | __gt, __lt | Time the sample was created | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte |
![]() |
A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | |
dbm | int | Strength of received signal (dBm) | |||
ecio | int | Ec/Io, the ratio of average channel power to total signal power (dB) | |||
net_device | url | =, __in | Network device that reported the usage sample | ||
rsrp | double | LTE reference signal receive power | |||
rsrp5g | double | 5G reference signal receive power | |||
rsrq | double | LTE reference signal receive quality | |||
rsrq5g | double | 5G reference signal receive quality | |||
rssi | int | Received Signal Strength Indication (units vary with manufacturer) Note: Only for WiFi as WAN interfaces |
|||
signal_percent | int | Percent signal strength, derived heuristically from other values | |||
sinr | double | Signal to Interference plus Noise Ratio (dB) | |||
sinr5g | double | 5G Signal to Interference plus Noise Ratio (dB) | |||
uptime | double | Time in seconds since the net device established its link |
Endpoint base path:
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "cinr": null, "created_at": "2015-08-12T09:29:34.093808", "created_at_timeuuid": "a473635e-40d4-11e5-b4b1-064520e3840d", "dbm": -59, "ecio": null, "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/84730/", "rsrp": null, "rsrq": null, "rssi": null, "signal_percent": 39, "sinr": 6, "uptime": 80 }, { .... } ], "meta": { "limit": 20, "next": null, "previous": null } }
Net Device Signal Sample Methods
A firmware object represents a build package for a specific product and firmware version.
Supported methods: GET.
The Firmware Object
Parameter | Data Type | Filter | Sort | Expand | Description |
built_at | timestamp | The time when the firmware image was built | |||
default_configuration | json |
![]() |
Default configuration for the firmware version | ||
expires_at | timestamp | The time when the firmware version expires | |||
hash | string | sha1sum hash of the firmware image | |||
id | int | =, __in | Object ID | ||
is_deprecated | boolean | True if this firmware version has been deprecated | |||
product | url | Product this firmware is for | |||
released_at | timestamp | The time when the firmware was released | |||
resource_url | url | Object URL | |||
uploaded_at | timestamp | The time when the firmware image was uploaded to NCM | |||
url | url | URL of the firmware image | |||
version | string | =, __in | Version of this firmware |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/firmwares/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "built_at": "2014-10-17T12:36:56+00:00", "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/1/default_configuration/" "hash": "fe72606c18153bc789c24cfb477059ca4cabfc4b", "id": "1", "is_deprecated": false, "product": "https://www.cradlepointecm.com/api/v2/products/23/", "released_at": "2014-10-17T12:36:56+00:00", "expires_at": "2020-12-13T12:45:16+00:00", "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/1/", "uploaded_at": "2014-11-13T01:26:20.328785+00:00", "url": "https://d1dkzj1agysu0k.cloudfront.net/IBR1100-2014-10-17T12%3A36%3A56.bin", "version": "5.2.4" }, { ... } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/firmwares/?limit=20&offset=20", "offset": 0, "previous": null } }
Firmwares Methods
A Cradlepoint device connects to NCM through the NCM stream server. NCM tracks communication between the device and the server using stream samples. This endpoint can be used to calculate total NCM network traffic. Note that this data only includes NCM management traffic and not general traffic from the router to the Internet.
Supported methods: GET.
The Router Stream Usage Samples Object
Parameter | Data Type | Filter | Sort | Expand | Description |
bytes_in | bigint | Bytes received by the device from NCM since last update | |||
bytes_out | bigint | Bytes sent from the device to NCM since last update | |||
created_at | timestamp | __gt, __lt | Time the sample was created | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte |
![]() |
A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | |
period | double | Time in seconds since the last sample was reported | |||
router | url | =, __in | Device that is connected to NCM | ||
uptime | double | Time in seconds since the net device established its link |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "bytes_in": 2700, "bytes_out": 3796, "created_at": "2015-09-22T09:31:40.712625", "created_at_timeuuid": "badba2ec-610c-11e5-a31d-0a811c6aca07", "period": 3600.29441688, "router": "https://www.cradlepointecm.com/api/v2/routers/22913/", "uptime": 418162.231429 }, { .... } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/?created_at_timeuuid__gt=badba2ec-610c-11e5-a31d-0a811c6aca07&limit=20", "previous": "https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/?limit=20&created_at_timeuuid__lt=f956e498-6063-11e5-8387-064520e3840d" } }
Router Stream Usage Samples Methods
NCM keeps a history of the online/offline state of devices using state samples. A device is considered online when it is connected to NCM. This endpoint can be used to track historical online/offline status.
Supported methods: GET.
The Router State Samples Object
Parameter | Data Type | Filter | Sort | Expand | Description |
created_at | timestamp | __gt, __lt | Time the sample was created | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte |
![]() |
A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | |
period | double | The time in seconds that the device was in this state | |||
router | url | =, __in | Device that is connected to NCM | ||
state | string | The state of the device during this sample's period, e.g. online or offline |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/router_state_samples/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "created_at": "2015-09-21T19:30:04.364662", "created_at_timeuuid": "28b06a9c-6097-11e5-a3f6-0a811c6aca07", "period": 4506.26495695, "router": "https://www.cradlepointecm.com/api/v2/routers/22913/", "state": "offline" }, { ... } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/router_state_samples/?created_at_timeuuid__gt=28b06a9c-6097-11e5-a3f6-0a811c6aca07&limit=20", "previous": "https://www.cradlepointecm.com/api/v2/router_state_samples/?limit=20&created_at_timeuuid__lt=79301852-597b-11e5-a30d-0a811c6aca07" } }
Router State Samples Methods
NCM provides alert functionality to notify NCM administrators of the health and status of their devices. Alerts must be configured in NCM before they are generated. The default NCM configuration does not create any alerts. After the alerts have been configured, a customer can use the NCM UI or this endpoint to monitor alerts.
Supported methods: GET.
The Router Alerts Object
Parameter | Data Type | Filter | Sort | Expand | Description |
created_at | timestamp | __gt, __lt | Time the alert record was created in NCM | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte |
![]() |
A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | |
detected_at | timestamp | Time the alert was detected | |||
friendly_info | string | Human-readable description of the alert | |||
info | json | Alert-type specific information | |||
router | url | =, __in | Device this alert is related to | ||
type | string | The type of the alert |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/router_alerts/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "created_at": "2015-09-21T19:30:04.318471", "created_at_timeuuid": "28a95e46-6097-11e5-bb1b-0a811c6aca07", "detected_at": "2015-09-21T19:30:04.316000", "friendly_info": "The device entered the \"online\" state.", "info": { "state": "online" }, "router": "https://www.cradlepointecm.com/api/v2/routers/22913/", "type": "connection_state" }, { .... } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/router_alerts/?created_at_timeuuid__lt=28a95e46-6097-11e5-bb1b-0a811c6aca07&limit=20", "previous": "https://www.cradlepointecm.com/api/v2/router_alerts/?limit=20&created_at_timeuuid__gt=20711422-6041-11e5-9792-064520e3840d" } }
Alert Type | Description |
adc_event | Occurs on devices with voltage-sensing systems when a voltage limit is reached, and also when the voltage returns to within the accepted range. |
config_changed | Device configuration was changed via the local UI or ssh. |
config_rejected | A configuration change that was sent to the device has been rejected. |
config_unacked | A configuration change that was sent to the device was not acknowledged by the device. |
connection_state | The device loses or regains its connection to NCM. |
cpu_utilization | CPU Utilization crossed threshold |
data_cap_threshold | Device data usage has reached a threshold. |
device_location_unknown | Occurs when no location is reported for 24 hours on a device with Location Services (GPS) enabled. If a manual location is used the alert is not generated. |
duplicate_ssid | Occurs after running a WiFi site survey when a rogue access point not marked as "known" is detected broadcasting the same SSID as the device running the site survey. This helps identify potential access-point hijacking, evil twin, and man-in-the-middle WiFi attacks. |
failover_event | The device has experienced a failover event. |
firmware_upgrade | The device firmware has been upgraded. |
geofence_proximity_change | Occurs whenever a device enters or exits its specified Geo-fence. |
gpio_state_change | Occurs when a device's GPIO pin has changed state*. To view or update the GPIO configuration, open the Device UI and select the System > GPIOs tab. |
ip_banned | The IP address is banned for 30 minutes after failing to log into the device administration pages six times. |
ips_activity | A potential threat was detected by IPS inspection engine. |
ips_eng_failure | In the unlikely event that the Threat Management engine fails, an alert is logged. |
ipsec_tunnel_down | Occurs when a connected IPSec tunnel is disconnected. |
login_failure | Someone tried and failed to login to the device's local UI. |
login_success | A user has logged into the device locally. |
memory_utilization | Memory Utilization crossed threshold. |
modem_wan_connected | A modem WAN device is now active. |
modem_wan_disconnected | A modem WAN device has been removed. |
modem_wan_plugged | A modem WAN device is now attached. |
modem_wan_standby | Indicates that a modem WAN device's default connection state is set to Standby. This means the modem is connected to the carrier, but is not sending data. A modem in Standby will failover faster than a modem not in Standby. Standby is enabled by modifying the Default Connection State from the Device UI's Connection Manager table. |
modem_wan_unplugged | A modem WAN device has been removed. |
msft_iot_disconnect | Connection to Azure IoT Central has gone down. |
reboot_status_change | Device has rebooted. |
sim_door_event | Occurs when the SIM door opens or closes. |
sustained_system_overload | Sustained System Overload |
thermal_exceeds_limit | Occurs on devices with an internal temperature sensor (COR IBR1100 and IBR1150) when a user-defined temperature limit is reached. To set the temperature limits for the COR IBR1100 Series, login to the Device UI, select System > Administration, and then click the Temperature tab. |
tunnel_limit | Occurs when the number of IPSec tunnel connections has met or exceeded either 90% or 100% of the maximum tunnel limit. |
unrecognized_mac_alert | An unrecognized MAC has appeared on the device LAN. |
wan_service_type | A WAN device has changed its service type, such as switching from 3G to 4G. |
wan_status_change | Device WAN has plugged, unplugged, connected, or disconnected. (deprecated) |
wifi_client_state_change | Occurs when a WiFi client changes state. For example, when a client's state changes from connected to disconnected (requires NCOS version 6.6.1 and newer). |
wwan_connected | A WiFi as WAN network is now active. |
wwan_disconnected | A WiFi as WAN network is no longer active. |
wwan_network_available | A WiFi as WAN network is now attached. |
wwan_network_unavailable | A WiFi as WAN network has been removed. |
wwan_standby | Indicates a WiFi as WAN network is in standby. |
zs_tls_tunnel | Zscaler TLS Tunnel State |
Each alert type has its own schema for the info struct.
Example
{ data: [ { account: "https://www.cradlepointecm.com/api/v2/accounts/8/", alert_type: "connection_state", id: "970", info: { state: "online" }, resource_uri: "https://www.cradlepointecm.com/api/v2/alerts/970/", router: "https://www.cradlepointecm.com/api/v2/routers/76/", router_ts: null, router_tz: "UTC", server_ts: "2013-02-27T16:05:48+00:00" }, { ... }, ], meta: { limit: 20, next: "https://www.cradlepointecm.com/api/v2/alerts/?limit=20&offset=20", offset: 0, previous: null, total_count: 3520 }, success: true }
config_change
info: [ { ecm: { server_host: "stream.cradlepointecm.com" }, system: { admin: { product_name: "IBR650P" }, ui_activated: true } }, [] ]
config_rejected
info: { reason: "rejected", patch: null }
config_unacked
info: { reason: "no diff for change", patch: [ { ecm: { config_version: 13 }, system: { system_id: "Cradlepoint" } }, [ ] ] }
connection_state
info: { state: "online" }
data_cap_threshold
info: { info: { cycle_str: "2014-12-21 00:00:00", hostname: "Cradlepoint", rulename: "*(Novatel Wireless HSPA Port:usb1)", capMB: 15000, percentage: "100", cycle: "monthly" }, type: "data_cap_threshold", time: [ "2015-01-14 06:22:06", "UTC" ] }
ethernet_wan_disconnected
info: { status: "disconnected", info: { raw_port: "eth1", mac: "00:30:44:00:00:00", type: "ethernet", uid: "wan", port: "Ethernet 1" }, alert_type: "ethernet_wan_disconnected", time: [ "2015-04-29 21:07:58", "UTC" ], type: "wan_status_change", history: [ ] }
ethernet_wan_plugged
info: { status: "plugged", info: { raw_port: "eth1", mac: "00:30:44:00:00:00", type: "ethernet", uid: "wan", port: "Ethernet 1" }, alert_type: "ethernet_wan_plugged", time: [ "2015-04-29 21:08:36", "UTC" ], type: "wan_status_change", history: [ ] }
firmware_upgrade
info: { state: "complete", target_firmware: { version: "5.3.0", build_timestamp: "2014-11-28T15:37:39+00:00" }, id: 179498, success: true, error: "install_timeout" }
ip_banned
"info": { "ipaddr": "192.168.0.112", "type": "ip_banned", "timeout": 30, "time": [ "2015-05-19 17:08:56", "UTC" ] }
ips_activity
info: { summary_size: 50, start_time: 1431968112.0550628, period: 900, summary: [ { category: "Buffer Overflow", count: 1, category_id: 4, ip_addr: [ { src: "192.168.0.10", dst: "192.168.0.1" } ], description: "SSL OpenSSL GnuTLS Server (CVE-2014-3466)", proto: 6, action: 1, ip_overflow: false, id: 1059596 } ] end_time: 1431969017.7684307, ip_addr_size: 5 }
ips_eng_failure
info: { reason: { errId: 65543, errStr: "Unknown Error Updating Signatures" }, type: "ips_eng_failure", time: [ "2015-05-14 14:16:10", "UTC" ] }
login_failure
info: { msg: "Failed SSH login attempt from 192.168.0.1, user: test", type: "login_failure", user: "ssh_login", time: [ "2015-05-13 16:06:19", "UTC" ] }
login_success
info: { ip: "192.168.0.1", type: "login_success", user: "admin", time: [ "2015-05-13 16:06:19", "UTC" ] }
modem_wan_connected
info: { status: "connected", info: { product: "Internal LPE (SIM1)", uid: "3fcbfe23", raw_port: "int1", model: "Internal LPE (SIM1)", type: "lte", port: "Internal 1", serial: "353547000000000", manufacturer: "CradlePoint Inc." }, alert_type: "modem_wan_connected", time: [ "2015-05-13 16:06:19", "UTC" ], type: "wan_status_change", history: [ ] }
modem_wan_disconnected
info: { status: "disconnected", info: { product: "MC400LPE (SIM2)", uid: "63d3ad9", raw_port: "usb1", model: "MC400LPE (SIM2)", type: "lte", port: "USB Port 1", serial: "353547060000000", manufacturer: "CradlePoint Inc." }, alert_type: "modem_wan_disconnected", time: [ "2015-05-11 20:17:45", "UTC" ], type: "wan_status_change", history: [ ] }
modem_wan_plugged
{ status: "plugged", info: { product: "Internal HSPA+", uid: "595a250", raw_port: "int1", model: "Internal HSPA+", type: "modem", port: "Internal 1", serial: "353567000000000", manufacturer: "CradlePoint Inc." }, alert_type: "modem_wan_plugged", time: [ "2015-04-29 21:07:59", "UTC" ], type: "wan_status_change", history: [ ] }
modem_wan_unplugged
info: { status: "unplugged", info: { product: "MC400LPE (SIM1)", uid: "66b01a2", raw_port: "usb1", model: "MC400LPE (SIM1)", type: "lte", port: "USB Port 1", serial: "353547060000000", manufacturer: "CradlePoint Inc." }, alert_type: "modem_wan_unplugged", time: [ "2015-05-11 18:42:36", "UTC" ], type: "wan_status_change", history: [ ] }
reboot_status_change
{ type: "reboot_status_change", time: [ "2015-05-06 15:03:22", "UTC" ] }
thermal_exceeds_limit
info: { current: 0, limit: 10, modem: false, type: "thermal_exceeds_limit", time: [ "2015-01-14 12:05:08", "UTC" ] }
unrecognized_mac_alert
info: { info: { interface: "Ethernet", mac: "00:30:44:00:00:00", hostname: "MBR1400-c1e", connect_time: "Wed Jan 14 01:16:55 2015" }, type: "unrecognized_mac_alert", time: [ "2015-01-14 06:16:55", "UTC" ] }
wan_service_type
info: { to: "Not Available", interface_name: "lte-6300000", from: "LTE" }
wwan_connected
info: { status: "connected", info: { rssi: -45.75, type: "wwan", ssid: "Cradlepoint", uid: "00:30:44:00:00:00" }, alert_type: "wwan_connected", time: [ "2015-01-14 08:32:43", "UTC" ], type: "wan_status_change", history: [ ] }
wwan_disconnected
info: { status: "disconnected", info: { note: "Disconnected: Failed to Failback to wan", rssi: -48, type: "wwan", ssid: "Cradlepoint", uid: "00:30:44:00:00:00" }, alert_type: "wwan_disconnected", time: [ "2015-01-14 06:15:01", "UTC" ], type: "wan_status_change", history: [ ] }
wwan_network_available
info: { status: "plugged", info: { rssi: -39, type: "wwan", ssid: "Cradlepoint", uid: "00:30:44:00:00:00" }, alert_type: "wwan_network_available", time: [ "2015-01-14 06:24:10", "UTC" ], type: "wan_status_change", history: [ ] }
wwan_network_unavailable
info: { status: "unplugged", info: { rssi: -39, type: "wwan", ssid: "Cradlepoint", uid: "00:30:44:00:00:00" }, alert_type: "wwan_network_unavailable", time: [ "2015-01-14 06:23:10", "UTC" ], type: "wan_status_change", history: [ ] }
Router Alerts Methods
Device logs contain log information sent from the device to NCM. A device must be in an NCM group and the NCM group settings must check ‘Enable Log Reporting’ for log events to be sent from the device. To reduce NCM traffic, device logs are not sent to the NCM server by default.
Supported methods: GET.
The Router Log Object
Parameter | Data Type | Filter | Sort | Expand | Description |
created_at | timestamp | __gt, __lt | Time the log entry was created in NCM | ||
created_at_timeuuid | timeuuid | =, __in, __gt, __gte, __lt, __lte |
![]() |
A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging. | |
exception | string | Contains details of a device exception (optional) | |||
level | string | The level of the log, e.g. DEBUG, INFO, WARNING, ERROR, CRITICAL | |||
message | string | The log message | |||
reported_at | timestamp | Time the log entry was written to the device's log | |||
router | url | = | Device this log is related to | ||
sequence | int | The insertion order for each log events | |||
source | string | The source of the log entry |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/router_logs?router=22630
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data":[ { "exception":"", "sequence":0, "reported_at":"2015-09-24T10:34:31+00:00", "created_at":"2015-09-24T10:34:58+00:00", "level":"INFO", "source":"ecm", "router":"https://www.cradlepointecm.com/api/v2/routers/22630/", "message":"Connecting to ECM", "created_at_timeuuid":"5603d1d2be3c87573aa6e613" }, { ... } ], "meta":{ "next":null, "previous":null, "limit":40, "offset":0 } }
Router Log Methods
This endpoint allows access to the latest signal, usage, and cell-tower data reported by an account’s wireless devices. This endpoint does not query the historical, raw-sample tables. These tables are not optimized for queries that span many wireless devices at once.
The primary key of this endpoint is net_device. The data returned by this endpoint has a one-to-one relationship with the net_devices endpoint. Expansion is supported to the net_devices endpoint. Paging is supported through our standard offset/limit functionality on the relational endpoints.
This endpoint also returns information about the cell towers used by your devices. This information includes cell tower IDs and the PLMN (MCC and MNC), LAC, and TAC codes.
This is a read-only endpoint.
Supported methods: GET.
The Net Device Metrics Object
Parameter | Data Type | Filter | Sort | Expand | Description |
bytes_in | bigint | Last sampled usage value received from net_device (running total since last device reset) | |||
bytes_out | bigint | Last sampled usage value received from net_device (running total since last device reset) | |||
cinr | double | Carrier to Interference plus Noise Ratio (dB) | |||
dbm | int | Strength of received signal (dBm) | |||
ecio | int | Ec/Io, the ratio of average channel power to total signal power (dB) | |||
id | int | Object ID | |||
net_device | url | =, __in | net_device that reported the usage sample | ||
resource_url | url | Object URL | |||
rsrp | double | LTE reference signal receive power | |||
rsrq | double | LTE reference signal receive quality | |||
rssi | int | Received Signal Strength Indication (units vary with manufacturer) Note: Only for WiFi as WAN interfaces |
|||
service_type | string | Last sampled service type value received from net_device | |||
signal_strength | int | Last sampled signal value received from net_device | |||
sinr | double | Signal to Interference plus Noise Ratio (dB) | |||
update_ts | timestamp | __gt, __lt | Last time any field on this record was updated | ||
cell_id | string | Cell Tower ID | |||
mcc | string | Mobile Country Code (PLMN component) | |||
mnc | string | Mobile Network Code (PLMN component) | |||
lac | string | Location Area Code | |||
tac | string | Tracking Area Code |
Endpoint base path:
https://www.cradlepointecm.com/api/v2/net_device_metrics/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "data": [ { "bytes_in": 1284122915, "bytes_out": 1274644165, "cinr": null, "dbm": null, "ecio": null, "id": "134193", "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/134193/", "resource_url": "https://www.cradlepointecm.com/api/v2/net_device_metrics/134193/", "rsrp": null, "rsrq": null, "rssi": null, "service_type": "EVDO", "signal_strength": null, "sinr": null, "update_ts": "2015-12-30T06:40:20.306754+00:00" }, { "bytes_in": 0, "bytes_out": 0, "cinr": null, "dbm": null, "ecio": null, "id": "134194", "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/134194/", "resource_url": "https://www.cradlepointecm.com/api/v2/net_device_metrics/134194/", "rsrp": null, "rsrq": null, "rssi": null, "service_type": "EVDO", "signal_strength": 0, "sinr": null, "update_ts": "2015-12-30T06:40:20.323704+00:00" } ], "meta": { "limit": 20, "next": "https://www.cradlepointecm.com/api/v2/net_device_metrics/?limit=20&offset=20", "offset": 0, "previous": null } }
Net Device Metrics Methods
Individual device configs are managed by the configuration manager endpoint. A configuration manager is an abstract resource for controlling and monitoring config sync on a single device. Each device has its own corresponding configuration manager.
Supported methods: GET, PUT, PATCH.
The Configuration Managers Object
Parameter | Data Type | Filter | Sort | Expand | Description | Permissions |
account | url | =, __in |
![]() |
Account which owns the object | Read/Write | |
actual | json | Diff of device's actual config | Read Only | |||
configuration | json | Diff of device's individual config | Read/Write | |||
id! | int | =, __in | Object ID | Read/Write | ||
pending | json | Diff of pending updates to device | Read Only | |||
resource_url | url | Object url | Read/Write | |||
router | url | =, __in |
![]() |
Router Object | Read/Write | |
suspended | boolean | = | True if device config sync is paused from a configuration issue. After resolving the issue, config sync can be resumed by setting this field to False. | Read/Write | ||
synched | boolean | = | True if device config is synced | Read/Write | ||
target | json | Diff of device's target config | Read Only | |||
version_number | int | Count of config changes | Read Only |
Note: ! indicates the attribute is required for PUT and PATCH requests.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/configuration_managers/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "success": true, "data": { "pending" : [ {}, [] ], "account" : "https://www.cradlepointecm.com/api/v2/accounts/1/", "target" : [ { "system" : { "logging" : { "level" : "debug" } }, "lan" : { "00000000-0d93-319d-8220-4a1fb0372b51" : { "ip_address" : "192.168.30.1", "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51", "name" : "LAN0" } }, "ecm" : { "config_version" : 18 } }, [] ], "actual" : [ { "ecm" : { "config_version" : 18 }, "lan" : { "0" : { "name" : "LAN0", "ip_address" : "192.168.30.1" } }, "system" : { "logging" : { "level" : "debug" } } }, [] ], "resource_url" : "https://www.cradlepointecm.com/api/v2/configuration_managers/1/", "version_number" : 18, "router" : "https://www.cradlepointecm.com/api/v2/routers/1/", "id" : "1", "synched" : true, "suspended" : false, "configuration" : [ { "system" : { "logging" : { "level" : "debug" } }, "lan" : { "00000000-0d93-319d-8220-4a1fb0372b51" : { "name" : "LAN0", "ip_address" : "192.168.30.1", "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51" } } }, [] ] } }
Configuration Managers Methods
The reboot_activity endpoint allows you to reboot a single router or group of routers. The reboot_activity endpoint provides the ability to
- POST a router's URI in the request payload to reboot a router, or
- POST a group's URI in the request payload to reboot a group of routers.
Specifying both a router and a group in the same call is not supported and the resulting behavior should be considered undefined. The caller must choose to reboot a router or reboot a group of router.
On success, POST requests return a "201 Created" code indicating that the request has been submitted without error. This does not necessarily indicate that the router has started to reboot. If the router is online (connected to NCM), the reboot command is sent as soon as possible. If the router is offline, the request will be lost.
Sending an invalid ID for the target router or group results in an HTTP error, typically a "403 Forbidden" error.
Supported methods: POST.
POST payload requirements: router or group URI.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/reboot_activity/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
To reboot the router with id=42, post the payload: {"router":"https://www.cradlepointecm.com/api/v2/routers/42/"} or using a full resource url (e.g., one obtained from the https://www.cradlepointecm.com/api/v2/routers endpoint): {"router":"http://www.cradlepointecm.com/api/v2/routers/42/"} To reboot the group with id=24, post the payload: {"group":"https://www.cradlepointecm.com/api/v2/groups/24/"} or using a full resource url (e.g., one obtained from the https://www.cradlepointecm.com/api/v2/groups endpoint): {"group":"http://www.cradlepointecm.com/api/v2/groups/24/"}
Reboot Activity Methods
NCM supports location functionality which stores the last known location of a device. This requires that the Location Services feature is available on the account and that appropriate devices have been enabled. After Location Services has been enabled, the NCM UI or this endpoint can be used to monitor or modify device locations.
Supported methods: GET, POST, PUT, DELETE.
Locations
Parameter | Data Type | Filter | Sort | Expand | Description | Permissions |
account* | url | Account which owns the object | Read/Write | |||
accuracy* | int | Indicates accuracy range of location coordinates in meters | Read/Write | |||
id | int | =, __in | Unique identifier of a location object. Location object unique identifiers are generated when location objects are created via calls to this endpoint using POST, as well as locations gathered from the device when Location Services are enabled. | Read/Write | ||
latitude* | int | A device's relative position north or south on the Earth's surface, in degrees from the Equator | Read/Write | |||
longitude* | int | A device's relative position east or west on the Earth's surface, in degrees from the prime meridian | Read/Write | |||
method* | string | Method used to determine location (eg. "gps" or "manual") | Read/Write | |||
resource_url | url | Object URL | Read/Write | |||
router* | url | =, __in | Device that the location is associated with | Read/Write | ||
updated_at | timestamp | Time of the last location update | Read/Write |
Note: * indicates the attribute is required for PUT and POST requests.
Endpoint base path:
https://www.cradlepointecm.com/api/v2/locations/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
Example of JSON data for POST to create a location object:
{ "account": "https://www.cradlepointecm.com/api/v2/accounts/<your account number>/", "accuracy": 0, "latitude": 245, "longitude": 300, "method": "manual", "router": "https://www.cradlepointecm.com/api/v2/routers/<ID of router to associate with location object>/", }
Example response body from a GET call made to this endpoint.
{ "data": [ { "account": "https://www.cradlepointecm.com/api/v2/accounts/3/", "accuracy": 0, "id": "1", "latitude": 45, "longitude": -100, "method": "manual", "resource_url": "https://www.cradlepointecm.com/api/v2/locations/1/", "router": "https://www.cradlepointecm.com/api/v2/routers/4/", "updated_at": "2018-01-29T23:10:09.967460+00:00" }, { "account": "https://www.cradlepointecm.com/api/v2/accounts/3/", "accuracy": 10, "id": "2", "latitude": 22, "longitude": -159, "method": "gps", "resource_url": "https://www.cradlepointecm.com/api/v2/locations/2/", "router": "https://www.cradlepointecm.com/api/v2/routers/9/", "updated_at": "2018-02-25T17:11:14.191640+00:00" }, { ... } ], "meta": { "limit": 20, "next": null, "offset": 0, "previous": null } }
Locations Methods
The speed_test endpoint allows users to create speed-test jobs that spawn individual speed tests for a given list of network devices. Users can create and start a speed-test job capable of queueing and running individual speed tests for up to 10k network devices in one POST request. Users can call the HTTP GET method to check the status of a speed-test job and view the results of completed speed tests. The speed_test endpoint displays speed-test results in the same format as speed test results in NCM.
The Speed Test Object
Parameter | Data Type | Filter | Sort | Expand | Description |
account | url | =, __in |
![]() |
Account that owns the object | |
config | json | config object | |||
id | int | Job object ID |
The config object
Parameter | Data Type | Description |
host | url | URL of Speedtest Server |
max_test_concurrency | int | Number of maximum simultaneous tests to server (1-50) |
net_device_ids | int[] | List of net_device IDs (up to 10,000 net_device IDs per request) |
port | int | TCP port for test |
size | int | Number of bytes to transfer |
test_timeout | int | Test Timeout |
test_type | string | TCP Download, TCP Upload, TCP Latency |
time | int | Test Time |
JSON payload example for a speed_test POST request
Note: All attributes for the "config" object in the following JSON payload example are required for a POST request.
https://www.cradlepointecm.com/api/v2/speed_test/
IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format: https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{ "account": "https://www.cradlepointecm.com/api/v2/accounts/1/", "config": { "host": "YOURTESTSERVER.COM", "max_test_concurrency": 5, "net_device_ids": [ 12345678 ], "port": 12865, "size": null, "test_timeout": 10, "test_type": "TCP Download", "time": 10 } }
RESULT:
{ "account": "https://www.cradlepointecm.com/api/v2/accounts/1/", "config": { "host": "YOURTESTSERVER.COM", "max_test_concurrency": 5, "net_device_ids": [ 12345678 ], "port": 12865, "size": null, "test_timeout": 10, "test_type": "TCP Download", "time": 10 }, "created_at": "2019-02-06T15:16:16.240612+00:00", "id": "47535", "progress": null, "resource_uri": "https://www.cradlepointecm.com/api/v2/speed_test/47535/", "results": null, "state": "created", "updated_at": "2019-02-06T15:16:16.240636+00:00" }
Do a GET on the resource_uri to see test results:
{ "account": "https://www.cradlepointecm.com/api/v2/accounts/1/", "config": { "host": "YOURTESTSERVER.COM", "max_test_concurrency": 5, "net_device_ids": [ 12345678 ], "port": 12865, "size": null, "test_timeout": 10, "test_type": "TCP Download", "time": 10 }, "created_at": "2019-02-06T15:16:16.240612+00:00", "id": "47535", "progress": { "completed": 1, "total_count": 1 }, "resource_uri": "https://www.cradlepointecm.com/api/v2/speed_test/47535/", "results": [ { "created_at": "2019-02-06 15:16:16.260749+00:00", "net_device_id": 12345678, "results": "TCP Download Test Timestamp: 2019-02-18 16:14:56 Duration: 10.01 Seconds Client Received: 69.6 MB Client Sent: 0 bytesServer Received: 0 bytes Server Sent: 70.4 MB Download Throughput: 58.34 Mbps", "router_id": 123456, "state": "success", "updated_at": "2019-02-06 15:16:19.573507+00:00" } ], "state": "complete", "updated_at": "2019-02-06T15:17:16.362784+00:00" }
Speed Test Methods
Endpoint support for different device types
The following table lists which endpoints and methods are supported for which devices
Endpoint name | Routers | Access Points |
---|---|---|
accounts | x | x |
alerts | x | |
batteries | x | |
configuration_managers | x | x |
device_apps | x | x |
device_app_versions | x | x |
device_app_bindings | x | x |
device_app_states | x | x |
firmwares | x | x |
groups | x | x |
locations | x | |
net_device_health | x | x |
net_device_metrics | x | x |
net_device_signal_samples | x | |
net_device_usage_samples | x | x |
net_devices | x | x |
products | x | x |
reboot_activity | x | x |
router_alerts | x | x |
router_logs | x | x |
router_state_samples | x | x |
router_stream_usage_samples | x | x |
routers | x | x |
speed_test | x |
The URL data type has the following conventions:
Note: Any API calls done through the examples above will use the NCM account linked to the NetCloud API key. This can affect production devices and data!
Configuration in API V2
This document describes the conventions for using the configuration-related endpoints and how to extend those conventions.
There are two endpoints for working with device configurations. One endpoint is for individual-device configs, the other is for group configs.
Endpoints:
https://www.cradlepointecm.com/api/v2/configuration_managers/
https://www.cradlepointecm.com/api/v2/groups/
Individual Device Configurations
Individual device configs are managed by the configuration_managers endpoint
https://www.cradlepointecm.com/api/v2/configuration_managers/[id/]
A configuration manager is an abstract resource for controlling and monitoring configuration sync on a single device. Each device has its own corresponding configuration manager.
Schema
account # URL to account that owns the config (readonly)
actual # JSON diff of router's actual config (readonly) [1]
pending # JSON diff of pending updates to device (readonly) [1]
target # JSON diff of target config (readonly) [1]
resource_url # URL to this endpoint (readonly)
version_number # integer count of config changes (readonly)
router # URL to device endpoint (readonly, expandable)
id # integer ID of this resource (readonly, sortable)
synched # true if device config is synced (readonly)
suspended # false unless config sync is paused (read/write)
configuration # JSON diff of individual config (read/write) [1]
[1] See the discussion of config diffs in the Appendix of this document.
The account
is a link to the same account that the device links to.
The actual
config shows the last diff received from the router. It is only
valid for Series 3 routers
(see differences between series 2 and series 3 routers). Routers
send diffs when they connect to NetCloud Manager (NCM) and whenever the config changes while they
are connected. This config is always formatted to match the router's current actual firmware.
The pending
config is empty except for unsynced devices, and then it shows
the changes waiting to be synced to the device when it connects or
resumes config sync. If the device's actual firmware and target firmware are
different, the pending field appears empty even if there are pending changes. This is because the changes cannot be comuputed until the device syncs its firmware version. (Comparing configs for different firmware versions is not
well-defined.)
The target
config is the result of layering an individual config over the group
config. It is the final desired configuration of the device. When the target
and actual
fields are the same, the device is in sync. This config is always
formatted to match the device's target firmware. If the device has no target
firmware, it matches the actual firmware.
The resource_url
is a self-referential link to the resource. It is not
generally useful for anything.
The version_number
starts at zero and increments any time the target
config changes. This is used as part of the sync protocol with the device client. The
device stores a copy of the last version_number
it synced to in its own
config, as ecm.config_version
. When the device sends a config diff to NCM,
NCM checks if the device has the latest version_number
. If and only if it
does, then NCM considers the device to be in-sync and accepts any local
changes. If it does not match, NCM ignores and even wipes local changes to force the device to sync. The API shows this number for informational
purposes only. It automatically increments any time a change is made via
the NCM UI, or the NetCloud API, or a local change is accepted, or if the config is
migrated to a different firmware version.
The router
is a reference to the device.
The id
is the identifier for the resource. It sometimes matches the device
id
, but not necessarily, so do not assume they are the same.
The synched
flag is true
if the device is synced and false
if there are pending changes.
The suspended
flag is true
if config sync has been stopped. This happens when the device rejects a configuration change from NCM. If the Configuration
Rejected alert is enabled, this event generates an alert with
information from the device about why it rejected the config. After fixing the
config, sync can be resumed by setting suspended
to false
via the API (or
via the Resume Updates button in the UI).
The configuration
field shows the individual configuration for the
device. The API can be used to change values in the config via PUT or PATCH,
see the examples below. This config is formatted to match the device's target
firmware (or actual, if there is no target). When the device's target firmware
changes, NCM automatically migrates this config to be compatible with the new
firmware.
Allowed HTTP methods are GET, PUT and PATCH. The user must have at least a full-access role for PUT and PATCH. Any attempt to PUT or PATCH the config is validated using static validators. The validator checks the format of the config, verifying that the keys are valid and the values conform to the correct types and ranges.
GET
GET works as described in the the API V2 documentation for all endpoints.
Possible HTTP status codes:
200 Ok # Success
401 Unauthorized # Incorrect or missing X-ECM-API-ID or X-ECM-API-KEY headers
403 Forbidden # Invalid URL or resource not visible
Supported filters:
Field Filters Right-hand side
===== ======= ===============
version_number =,gt,lt any non-negative integer
router =,in device ID
id =,in resource ID
synched = true or false
suspended = true or false
Other supported URL parameters:
offset # first object to return (for paging)
limit # max objects to return (for paging)
fields # list of fields to return (for partial returns)
expand # convert a url field to an embedded object (only supported on some fields)
See here for an explanation of the example format.
GET Example: A Specific Manager
> GET https://www.cradlepointecm.com/api/v2/configuration_manager/123/
< 200 Ok
< {
< "success": true,
< "data": {
< "pending" : [
< {},
< []
< ],
< "account" : "https://www.cradlepointecm.com/api/v2/accounts/1/",
< "target" : [
< {
< "system" : {
< "logging" : {
< "level" : "debug"
< }
< },
< "lan" : {
< "00000000-0d93-319d-8220-4a1fb0372b51" : {
< "ip_address" : "192.168.30.1",
< "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
< "name" : "LAN0"
< }
< },
< "ecm" : {
< "config_version" : 18
< }
< },
< []
< ],
< "actual" : [
< {
< "ecm" : {
< "config_version" : 18
< },
< "lan" : {
< "0" : {
< "name" : "LAN0",
< "ip_address" : "192.168.30.1"
< }
< },
< "system" : {
< "logging" : {
< "level" : "debug"
< }
< }
< },
< []
< ],
< "resource_url" : "https://www.cradlepointecm.com/api/v2/configuration_managers/1/",
< "version_number" : 18,
< "router" : "https://www.cradlepointecm.com/api/v2/routers/1/",
< "id" : "1",
< "synched" : true,
< "suspended" : false,
< "configuration" : [
< {
< "system" : {
< "logging" : {
< "level" : "debug"
< }
< },
< "lan" : {
< "00000000-0d93-319d-8220-4a1fb0372b51" : {
< "name" : "LAN0",
< "ip_address" : "192.168.30.1",
< "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51"
< }
< }
< },
< []
< ]
< }
< }
The device is synced in the previous example. This is indicated by the following:
- the
pending
field is an empty diff ([{}, []]
) - the
actual
andtarget
fields have the same content, and synched
istrue
You may have noticed that the target
and actual
fields do not
look identical. In the lan
section, the target
has this:
< "00000000-0d93-319d-8220-4a1fb0372b51" : {
< "ip_address" : "192.168.30.1",
< "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
< "name" : "LAN0"
< }
But the actual
has this:
< "0" : {
< "name" : "LAN0",
< "ip_address" : "192.168.30.1"
< }
This difference is because the lan
array has an _id_
field, and the device and NCM express these kind of arrays
differently. This is an unfortunate legacy of the way the _id_
fields were first introduced into device firmware. NCM can understand
both representations, and it recognizes that they are saying the same
thing, so it knows the device is actually synced. See the section on
_id_
fields for more details.
PUT
PUT replaces an entire individual config with the given payload. It can also be used to resume the sync on a suspended device.
As indicated in the schema, only two fields are writable: configuration
(the
individual config) and suspended
. It is not necessary to provide both with
PUT. You can PUT just the configuration
to change the indie config, or just
the suspended
field to resume sync. If you include any other field in your
PUT request payload you will get a 409 Conflict.
HTTP status codes:
202 Accepted # Success
401 Unauthorized # Incorrect or missing X-ECM-API-ID or X-ECM-API-KEY headers
403 Forbidden # Invalid URL or resource not visible
405 Method Not Allowed # URL did not include an /<id>/ in the path
409 Conflict # Invalid API or config request
You cannot PUT to more than one configuration manager at a time. This is ok:
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/34365/
These are not, and return a 405 Method Not Allowed:
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/?synched=false
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/56/
A 409 Bad Request can mean that the request is trying to set an invalid config, and the problem is something inside the config body. The response includes the validation error. For example:
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/
> {"configuration": [{"foo": "bar"}, []]}
< 409 Bad Request
< {
< "errors" : [
< {
< "configuration" : {
< "message" : "cannot set foo to bar: invalid path",
< "reason" : "invalid path",
< "value" : "bar",
< "path" : [
< "foo"
< ]
< }
< }
< ],
< "exception" : {
< "message" : "bad or missing data",
< "type" : "validation"
< }
< }
See here for a complete catalog of config validation errors.
Other URL parameters:
fields # list of fields to return (for partial returns)
Because PUT is only supported on one configuration manager at a time, the standard filter and paging options do not apply.
See here for an explanation of the example format.
PUT Example: A Simple Config
This enables GPS in the individual config:
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/17/?fields=configuration
> {
> "configuration": [
> {
> "system": {
> "gps": {
> "enabled": true
> }
> }
> },
> []
> ]
> }
< 202 Accepted
< {
< "configuration": [
< {
< "system": {
< "gps": {
< "enabled": true
< }
< }
< },
< []
< ]
< }
(The fields=configuration
URL option is telling NCM to reply with only the
configuration
field, otherwise it would return the entire config manager
object. For brevity, the PUT examples always use this technique.)
If the request actually changes the config -- which is usually the intent -- the following changes take place:
- the
target
field is updated - the
version_number
field is incremented - the
synched
field is set to false, and - the
pending
field shows the changes that will be (or already have been) sent to sync the device
Since only system.gps.enabled is set, all other individual config settings will be unassigned. That means they will be determined by the group config. If there is no group config, or if the group config also leaves a setting unassigned, then the default value will apply.
It is important to understand that for PUT, not specifying a config value is equivalent to removing it from the individual config, if it was there. PATCH is different, as discussed below.
PUT Example: A Complicated Config
The following example config removes the default Guest LAN and sets up LAN port 4 on a VLAN to pass traffic to the WAN. It does this by performing the following actions:
- Removes the default Guest LAN
- Moves port 4 from the set of normal LAN ports to a new VLAN called "aleph"
- Assigns the aleph VLAN to a new LAN interface called "Aleph LAN"
- Adds a new firewall zone for the Aleph LAN
- Adds a forwarding rule from the aleph zone to the WAN zone
The request:
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=version_number
> {
> "configuration": [
> {
> "lan": {
> "00000001-2a38-3724-a6fa-02dfdfbc129e": {
> "_id_": "00000001-2a38-3724-a6fa-02dfdfbc129e",
> "devices": [
> {
> "type": "ethernet",
> "uid": "aleph"
> }
> ],
> "dhcpcd": {},
> "enabled": true,
> "ip_address": "192.168.20.1",
> "name": "Aleph LAN",
> "netmask": "255.255.255.0"
> }
> },
> "security": {
> "zfw": {
> "forwardings": {
> "00000004-356d-30f0-962f-bb705dfddfc9": {
> "_id_": "00000004-356d-30f0-962f-bb705dfddfc9",
> "dst_zone_id": "00000002-695c-3d87-95cb-d0ee2029d0b5",
> "enabled": true,
> "filter_policy_id": "00000000-77db-3b20-980e-2de482869073",
> "src_zone_id": "00000005-e091-3d73-80d1-9a51d6143759"
> }
> },
> "zones": {
> "00000005-e091-3d73-80d1-9a51d6143759": {
> "_id_": "00000005-e091-3d73-80d1-9a51d6143759",
> "devices": [
> {
> "trigger_field": "config_id",
> "trigger_group": "lan",
> "trigger_neg": false,
> "trigger_predicate": "is",
> "trigger_value": "00000001-2a38-3724-a6fa-02dfdfbc129e"
> }
> ],
> "name": "aleph"
> }
> }
> }
> },
> "vlan": {
> "2": {
> "mode": "lan",
> "ports": [
> {
> "mode": "tagged",
> "port": 4
> }
> ],
> "uid": "aleph",
> "vid": 3
> }
> }
> },
> [
> ["vlan", 1, "ports", 3],
> ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]
> ]
> ]
> }
< 202 Accepted
< {
< "version_number" : 29
< }
The removals are processed by the device first. Removals must refer to elements which exist in the device's default config. Thefollowing elments exist in the default config:
[
["vlan", 1, "ports", 3],
["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]
]
To understand these examples it is necessary to understand what the default
config looks like. In this case the device is an MBR1400 router running 5.4.0
firmware. The default vlan
array looks like this:
[
{
"uid" : "wan",
"mode" : "wan",
"vid" : 1,
"ports" : [
{
"port" : 0,
"mode" : "untagged"
}
]
},
{
"mode" : "lan",
"uid" : "lan",
"ports" : [
{
"mode" : "untagged",
"port" : 1
},
{
"port" : 2,
"mode" : "untagged"
},
{
"port" : 3,
"mode" : "untagged"
},
{ \
"port" : 4, \ This is vlan.1.port.3
"mode" : "untagged" /
} /
],
"vid" : 2
}
]
vlan
is an array, and ["vlan", 1, ...]
refers to the entry at
offset 1. Offsets start at 0, so 1 means the second entry. Within each vlan
entry there is another array for the ports
. So ["vlan", 1, "ports", 3]
means "The port at offset 3 in the vlan at offset 1". In this default config, that is port 4,
and it is "untagged". That is what will be removed first.
The next removal looks very different:
["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]
. It is obviously trying to
remove something from the default lan
array, but it is referring to the LAN
it wants to remove not by its offset in the array, but by it's unique _id_
field value. "00000001-0d93-319d-8220-4a1fb0372b51" is the _id_
for the Guest
LAN, as indicated by the default config, shown here in part:
"lan": [
{
"name": "Primary LAN",
"_id_": 00000000-0d93-319d-8220-4a1fb0372b51"
},
{
"name": "Guest LAN",
"_id_": 00000001-0d93-319d-8220-4a1fb0372b51"
}
]
If an array contains elements with an _id_
field then removals can refer to
them by this instead of using the offset. Whenever a config is generated by the
NCM UI, it uses the _id_
in its removals whenever possible.
After processing the removals, the device applies all the updates in one
operation. This part of the config tells it to add a new entry to the vlan
array at offset 2:
"vlan": {
"2": {
"mode": "lan",
"ports": [
{
"mode": "tagged",
"port": 4
}
],
"uid": "aleph",
"vid": 3
}
}
Notice that the "2" (the key to the dict) is in quotes, like a string, whereas
in the removal ["vlan", 1, "ports", 3]
the offsets are not quoted. This is
not a mistake and is important. If the "2" is not quoted in the updates then it
is not valid JSON and you will get a 400 Bad Request in resonse to your PUT.
Compare adding the vlan
entry to adding the lan
and security
entries. Instead of using a quoted number, these use a UUID as the key. The key
value corresponds exactly to the _id_
values inside the entries:
"lan": {
"00000001-2a38-3724-a6fa-02dfdfbc129e": {
"_id_": "00000001-2a38-3724-a6fa-02dfdfbc129e",
<...etc...>
This may seem like senseless repitition but it is required.
When adding an entry to an array which supports _id_
fields, you must provide
a UUID or the result is a validation error. The _id_
is necessary to
make it clear which entry the update is referring to.
By now it is probably clear that hand-crafting a configuration is not easy. A better approach is to use the NCM UI to create a configuration to serve as a template and then to modify it as necessary for different devices. A typical workflow might be:
- Use the NCM config editor to create a config on one device.
- Call
GET https://www.cradlepointecm.com/api/v2/configuration_managers/123/
to download the config from the device. - Edit the downloaded copy.
- Call
PUT https://www.cradlepointecm.com/api/v2/configuration_managers/456/
to upload the edited config to a different device.
PUT Example: Resume Sync
To restart the sync cycle on a suspended device after fixing its config:
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=suspended
> {
> "suspended": false
> }
< 202 Accepted
< {
< "suspended" : false
< }
This only works if a device is online. If the device is offline, it stays suspended.
PUT Example: Clearing the Config
To wipe the individual config back to defaults, just PUT an empty diff:
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/123/?fields=configuration
> {
> "configuration": [{}, []]
> }
< 202 Accepted
< {
< "configuration": [{}, []]
< }
PUT Example: Manually Suspend Sync
You can force NCM to stop syncing a device via the API. Why would you stop the syncing of a device? You might not want devices to sync until you are done making and testing configuration changes on a test device. Or you might only want to sync devices at certain times.
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=suspended
> {
> "suspended": true
> }
< 202 Accepted
< {
< "suspended" : true
< }
PATCH
PATCH also changes the config. The difference between PUT and PATCH is in how they treat the parts of the config that are not mentioned in the request. PUT replaces anything not mentioned with nothing (ie, resets it back to defaults). PATCH leaves it alone.
For example, the following PUT call resets the entire individual config back to defaults:
PUT https://www.cradlepointecm.com/api/v2/configuration_managers/123/
{"configuration": [{}, []]}
And this will do nothing at all:
PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/123/
{"configuration": [{}, []]}
PATCH is the operation to use when you want to adjust an existing config. PUT is what you should use to replace an existing config.
Note that you can't remove anything with PATCH, you can only add or update changes.
HTTP status codes:
202 Accepted # Success
400 Bad Request # Invalid config request
401 Unauthorized # Incorrect or missing X-ECM-API-ID or X-ECM-API-KEY headers
403 Forbidden # Invalid URL or resource not visible
405 Method Not Allowed # URL did not include an /<id>/ in the path
409 Conflict # Invalid API request
Like PUT, PATCH cannot operate on more than one configuration manager at a time. For this reason it also does not support the URL options for filtering or paging.
Also like PUT, it will return a 400 Bad Request if it detects an invalid config.
Unlike PUT, PATCH never returns a payload in its reply. The fields
URL option
is therefore meaningless to PATCH.
See here for an explanation of the example format.
PATCH Example: Set Primary LAN IP Address
Change the IP address of the Primary LAN to 192.168.30.1, leaving the other parts of the diff the same. Note the reply contains the entire diff; in this example it shows that PUT Example 1 to add a third LAN was already done, and the PATCH is an incremental change on top of that:
> PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
> {
> "configuration": [
> {
> "lan": {
> "00000000-0d93-319d-8220-4a1fb0372b51": {
> "_id_": "00000000-0d93-319d-8220-4a1fb0372b51",
> "ip_address": "192.168.30.1"
> }
> }
> },
> []
> ]
> }
< 202 Accepted
This example uses the Primary LAN's _id_
value as the key, and whenever you
do that you also must include the _id_
field itself as part of the request,
or you will get a strange validation error:
{
"exception" : {
"message" : "invalid literal for int() with base 10: '00000000-0d93-319d-8220-4a1fb0372b51'",
"type" : "error"
},
"errors" : [
{
"path" : "https://www.cradlepointecm.com/api/v2/configuration_managers/2/"
}
]
}
PATCH Example: Insert A LAN
PATCH supports inserting new array elements:
{
"configuration": [
{
"lan": {
"00000002-2a38-3724-a6fa-02dfdfbc129e": {
"_id_": "00000002-2a38-3724-a6fa-02dfdfbc129e",
"ip_address": "192.168.40.1",
"name": "Gamma",
"netmask": "255.255.255.0",
"dhcpd": {
"enabled": true
},
"devices": []
}
}
},
[]
]
}
Group Configurations
A group's config is part of the groups
resource:
> GET https://www.cradlepointecm.com/api/v2/groups/35/?fields=configuration
< 200 Ok
< {
< "configuration" : [
< {
< "system" : {
< "logging" : {
< "level" : "debug"
< }
< },
< "webfilter" : {
< "proxy" : {
< "https_filtering" : true
< }
< }
< },
< []
< ]
< }
GET, PUT and PATCH work the same for groups
as for configuration_managers
.
Use Cases
Below are some ways people have used the API.
Get the pending config on a particular device
If the configuration_manager
ID is known:
GET https://www.cradlepointecm.com/api/v2/configuration_managers/1106/?field=pending
Otherwise query the configuration_managers
by device ID. The result will be a
list of one element, such as:
> GET https://www.cradlepointecm.com/api/v2/configuration_managers/1106/?field=pending
< 200 Ok
< {
< "data" : [
< {
< "pending" : [
< {
< "system" : {
< "logging" : {
< "level" : "debug"
< }
< },
< "ecm" : {
< "config_version" : 9
< }
< },
< []
< ]
< }
< ],
< "meta" : {
< "offset" : 0,
< "previous" : null,
< "next" : null,
< "limit" : 20
< }
< }
Get the actual config on all devices on a nightly basis
Page through the configuration_managers
using limit
and offset
. To
associate each result with its device, ask for some unique identifier such as
the router.id
or router.mac
or router.name
:
GET https://www.cradlepointecm.com/api/v2/configuration_managers/?fields=actual,router.id,router.mac,router.name&limit=200&offset=0
GET https://www.cradlepointecm.com/api/v2/configuration_managers/?fields=actual,router.id,router.mac,router.name&limit=200&offset=201
... etc ...
GET https://www.cradlepointecm.com/api/v2/configuration_managers/?fields=actual,router.id,router.mac,router.name&limit=200&offset=12000
Read/modify/write a "golden" config
GET https://www.cradlepointecm.com/api/v2/groups/123/?fields=configuration
# modify it for group 456
PUT https://www.cradlepointecm.com/api/v2/groups/456/
# modify it for group 789
PUT https://www.cradlepointecm.com/api/v2/groups/789/
... etc ...
Change the WiFi SSID and WPA2/PSK Passkey On Specific Routers
PUT and PATCH require the URL of the configuration_managers ID endpoint and do not support filtering by router.id (or router.mac, router.name, etc):
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
> PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
> {
> "configuration": [
> {
> "wlan": {
> "radio": {
> "0": {
> "bss": {
> "0": {
> "ssid": "MBR1400-8c1",
> "wpapsk": "t311-n00ne"
> }
> }
> }
> }
> }
> },
> []
> ]
> }
< 202 Accepted
Add User
This and the following examples work the same way with PATCH or PUT as all the previous examples. For brevity, only the payload is shown.
{
"configuration": [
{
"system": {
"pci_dss": true,
"users": {
"1": {
"group": "admin",
"password": "SuperDuper1",
"username": "super"
}
}
}
},
[]
]
}
Static IP for Ethernet WAN using WAN rule
Configuring the static IP on the Ethernet WAN device requires setting the
ip_override
section of its corresponding WAN rule. The WAN rules changed
somewhat with firmware version 6.0. The wan.rules
path was replaced with
wan.rules2
, and the _id_
of the rule dealing with Ethernet WAN also changed
as shown in the examples that follow.
5.0 <= Firmware < 6.0
{
"configuration": [
{
"wan": {
"rules": {
"00000001-dea3-3ccd-a78d-e0196084396f": {
"_id_": "00000001-dea3-3ccd-a78d-e0196084396f",
"ip_mode": "static",
"static": {
"dns": {
"0": {
"ip_address": "172.21.21.50"
},
"1": {}
},
"gateway": "172.19.8.1",
"ip_address": "172.19.9.30",
"netmask": "255.255.252.0"
}
}
}
}
},
[]
]
}
Firmware >= 6.0
Change rules
to rules2
and change the _id_
field and key. The dns
section is not required like it is in older versions, which will accept the
config without DNS but may fail to connect, resulting in a
config rollback.
{
"configuration": [
{
"wan": {
"rules2": {
"00000000-a81d-3590-93ca-8b1fcfeb8e14": {
"_id_": "00000000-a81d-3590-93ca-8b1fcfeb8e14",
"ip_mode": "static",
"static": {
"ip_address": "172.19.9.30",
"netmask": "255.255.252.0"
}
}
}
}
},
[]
]
}
Setting the APN for modem using LTE defaults WAN rule
The APN must be set in the WAN rule corresponding to the modem it is for. For
example, to set it for an LTE modem, use the WAN rule with _id_
"00000002-dea3-3ccd-a78d-e0196084396f":
5.0 <= Firmware < 6.0
{
"configuration": [
{
"wan": {
"rules": {
"00000002-dea3-3ccd-a78d-e0196084396f": {
"_id_": "00000002-dea3-3ccd-a78d-e0196084396f",
"modem": {
"apn_mode": "manual",
"manual_apn": "myapn"
}
}
}
}
},
[]
]
}
Firmware >= 6.0
Change rules
to rules2
and change the _id_
field and key.
{
"configuration": [
{
"wan": {
"rules2": {
"00000002-a81d-3590-93ca-8b1fcfeb8e14": {
"_id_": "00000002-a81d-3590-93ca-8b1fcfeb8e14",
"modem": {
"apn_mode": "manual",
"manual_apn": "myapn"
}
}
}
}
},
[]
]
}
Appendix
Format of Examples
There are many Rest API clients available on the web or as browser plugins. They all differ slightly but provide the same common elements of method, headers, URL, payload, and status code. Rather than showing the syntax for a particular tool, this document uses the following format for all examples.
First, examples appear in monospace
font. The first character of each line is
either >
or <
and indicates the direction of travel, either
client-to-server or server-to-client, respectively:
> = client to server
< = server to client
The first line is always the method and URL. If there is data to be sent (as in PUT and PATCH), this appears on the following lines going in the same direction. The reply appears on subsequent lines, beginning with the status code and followed by the reply payload (if any). Here's an annotated example, with lines numbered for discussion:
1 > GET https://www.cradlepointecm.com/api/v2/configuration_managers/1/?fields=version_number
2 < 200 Ok
3 < {
4 < "version_number" : 19,
5 < }
Line 1 shows the method (GET) and full URL
(https://www.cradlepointecm.com/api/v2/configuration_managers/1/?fields=version_number
) sent from
the client to the server to initiate the request. In this example the
URL is asking for a specific object (with ID 1), and specifying that it only
wants to see the version_number
field (this is known as a "partial
result").
Line 2 shows the status code from the server as 200 Ok
.
Lines 3-5 are the payload of the reply from the server. For readability, the examples always show the payloads as JSON formatted with line breaks and indentations. Not all clients format the reply like this (curl won't, for example, and neither will most browsers unless you install a plugin). The payload from the server will actually be all on one line with no indentation. The meaning is the same.
The examples do not show the headers required for authentication or
content-type, but they are necessary. As described in the general API v2
documentation (the Sample
Code section is most succinct), all requests to the API must provide a header
each for X-ECM-API-ID
, X-ECM-API-KEY
, X-CP-API-ID
and X-CP-API-KEY
to
authenticate the client. Also, PUT and PATCH requests require a Content-Type
header.
_id_
Fields
Many parts of the device configuration are composed of arrays. Most of these lists are treated more like sets than like arrays, where the order of the elements does not matter and elements must be unique from one another in some way. Order does not matter; as long as nothing inserts or removes elements the order remains stable.
Some of these arrays are pre-populated with entries by default. For example, if you factory reset most devices (but not all!) you will find that they have two LAN entries and maybe five WAN rules.
In a config diff arrays are always presented as dictionaries. Historically (prior to 5.0) the keys were always string numerals representing the index of the elements. For example:
{
"lan": {
"1" : {
"ip_address" : "192.168.30.1",
"name" : "Office LAN"
}
}
}
This refers to the LAN at index 1 which would be the second LAN. In most devices that would be the Guest LAN. But not necessarily, if the config has changed from the default. This might be a third LAN inserted before the Guest LAN. It might even be the Primary LAN, if the Guest LAN were somehow re-ordered to come first. This is an aliasing problem, where it is sometimes impossible to tell which element a config diff is referring to just by looking at it. The problem becomes worse when NCM begins to layer configs.
The solution, introduced in firmware version 5.0, was to add a unique _id_
field to the elements of lists that have default values. The _id_
is a
UUID. The lists that support them include the lan
, wan.rules
and various
others, depending on the firmware version and product.
The following example diff illustrates this by referring to the primary LAN by
it's _id_
: "00000000-0d93-319d-8220-4a1fb0372b51".
{
"lan": {
"00000000-0d93-319d-8220-4a1fb0372b51" : {
"ip_address" : "192.168.30.1",
"_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
"name" : "LAN0"
}
}
}
For firmware versions 5.0 and greater this is the unambiguous way to refer to these array elements.
For firmware versions prior to 5.0, these UUID fields are not supported by any arrays, so you must use string numerals to reference their position in the array. The first position is always "0".
The default elements of these lists (ie, those which populate the list after a
factory reset) all have pre-assigned _id_
field values. When adding a new
element to such a list, you must provide your own UUID value.
Here's a list of arrays with elements that
use the _id_
field from a recent firmware build (6.1.0) as of this writing:
asavie.tunnels
certmgmt.certs
dns.dnsmasq_options
gre.tunnels
identities.ip
identities.mac
identities.port
lan
openvpn.tunnels
routing.access_list
routing.bgp.access_list
routing.bgp.community_list
routing.prefix_list
routing.route_map
routing.tables
security.app_sets
security.ips.cat_cfg
security.ips.sig_cfg
security.zfw.filter_policies
security.zfw.forwardings
security.zfw.zones
split_dns.domain_lists
split_dns.servers
system.gps.connections
vpn.tunnels
wan.rules
wan.rules2
Firmware Versioning And DTDs
What constitutes a valid configuration? It depends on the firmware version and product. Every version of firmware has a Document Type Definition (DTD) that specifies the configuration-tree structure, the types of the elements, any limits on the range of values of elements, and whether an element must be specified or can be left blank. If a configuration does not conform to the DTD it is invalid.
NCM checks for valid configs in the API by checking them against the DTD. But even if a config conforms to the DTD it can still be invalid. The devices check for dynamic constraints which can't be expressed in the DTD and may reject a config from NCM because one of these checks fails.
For example, currently all devices have a check that
if `firewall.remote_admin.enabled` is `true` then either
`firewall.remote_admin.secure_only` must be `true` or
`firewall.remote_admin.port` must be provided.
So even though this conforms to the DTD and would be accepted by NCM, the device would reject it:
{
"firewall": {
"remote_admin": {
"enabled": true,
"secure_only": false
}
}
}
The DTD can change from one firmware version to another. This changes what constitutes a valid config. When a device's target firmware changes, NCM automatically attempts to migrate its configuration to make it compatible with the new version.
The DTD specifies a default value for many fields, including all required
fields. As noted elsewhere, it also specifies default elements for some
arrays such as lan
, wan.rules
and firewall.zfw.filter_policies
. The default elements can be altered or removed. If they are, a factory reset of the
device restores them. In NCM, clearing configs has a similar effect.
Suspended Sync
If NCM tries to sync a device to an invalid config, the device rejects
it. NCM stops trying to sync the device and marks it as "suspended", as
shown in the config_status field of the device's endpoint (eg,
https://www.cradlepointecm.com/api/v2/routers/<router-id>
).
To understand why a device was suspended due to an invalid config, check the device's Configuration Rejected alert. This alert contains details about why the device rejected the config. The alert information typically references the field(s) that failed their dynamic validation checks. You can access a device's alerts through the NCM ALERTS page or via the alerts endpoint.
Once the problem is ascertained, the configuration should be changed to remove the error.
Finally, to resume sync from the API, do a PUT with the suspended
field set
to False:
PUT https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
{
"suspended": false
}
Supported Products
All currently available products are referred to as Series 3 products. Older series 2 products which are managed by NCM also have configuration_managers. However, their configuration format is different from series 3, and the fields and values are different. Nonetheless, one can still use this API to try and configure series 2 routers managed in NCM.
Diffs
A configuration diff describes how the configuration differs from the default for that firmware version. It is a list of two elements. The first element is called the update dictionary. The second element is called the removal list.
A diff is like a UNIX patch. It can be applied to an existing configuration. When applied, every path in the removals list is removed in the specified order. Then, every key/value pair in the update dictionary is applied. The update will try to maintain existing elements, and only update exactly what is specified.
For example, suppose a configuration looks like this:
{
"a": {
"b": 1,
"c": 2
},
"d": {
"e": "hi",
"f": "there"
}
}
And the diff being applied looks like this:
[
{
"a": {
"d": 4,
"c": 3
}
},
[
["d", "e"]
]
]
When applied, the diff will first remove element d.e, then, in no particular order, it will change element a.c and insert element a.d. Element a.b and d.f will be left as they are:
{
"a": {
"d": 4,
"c": 3,
"b": 1
},
"d": {
"f": "there"
}
}
If a path in the removal list does not exist in the configuration, this is an error. If an element in the update dictionary is not described by the firmware's Document Type Definition (DTD), or if it is of the wrong type, that is also an error.
An empty configuration diff looks like this:
[{}, []]
Group / Indie Layering
Suppose the device is put into a group, and the group has a configuration like this:
# Group config
{
"a": {
"b": 1
"c": 2
}
}
If you GET the device's configuration, it will look exactly like that. Now suppose you PATCH the following to the device's configuration:
# Patch to config
{
"a": {
"b": 3,
"d": 4
}
}
NCM will save this as the device's individual configuration and update the target by layering it over the group. Now if you GET the device's configuration it will look like this:
# Target config
{
"a": {
"b": 3,
"c": 2,
"d": 4
}
}
NCM changed a.b and inserted a.d. It left a.c alone, because the diff didn't mention it.
What would happen if you then changed your mind and PUT with an empty config to the device’s configuration endpoint? NCM would clear the individual configuration, but the group configuration would stay the same, so the device's target configuration would go back to just being the group configuration:
# Target config if indie cleared
{
"a": {
"b": 1
"c": 2
}
}
What if instead you removed the device from the group? Then only the individual configuration would remain:
# Target config if removed from group
{
"a": {
"b": 3,
"d": 4
}
}
NCM removed a.c from the target configuration, because a.c came from the group configuration.
Passwords
If you GET a config that has non-default passwords, the values are not shown. Instead, you see "*":
> GET https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=configuration
< 200 Ok
< {
< "configuration" : [
< {
< "wlan" : {
< "radio" : {
< "0" : {
< "bss" : {
< "0" : {
< "wpapsk" : "*"
< }
< }
< }
< }
< }
< },
< []
< ]
< }
You can still set passwords through the API by sending them as cleartext:
PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/
> {
> "configuration" : [
> {
> "wlan" : {
> "radio" : {
> "0" : {
> "bss" : {
> "0" : {
> "radius0nasid" : null,
> "wpapsk" : "2secret4Usorry"
> }
> }
> }
> }
> }
> },
> []
> ]
> }
< 202 Accepted
They will be automatically encrypted.
Validation Errors
An "invalid path" error is reported anytime a diff refers to something that does not exist in the DTD. It does not matter if the reference is in the updates or the removals. For instance, both updates and removals are invalid here:
[
{
"foo": "bar"
},
[
["baz", 6]
]
]
Other errors are due to a wrong type or value:
empty dict # array can't be an empty dictionary
not a dict # struct must be dictionary
invalid id # _id_ not a UUID
not a string
url must have "http://" or "https://" prefix
invalid url
invalid ip address
invalid ip address or dns name
not a float type
invalid mac address
invalid ipv6 address
too large
negative invalid # ipv6_prefixlen must be >= 0
not an integer
invalid subnet mask
invalid ipv4 address
invalid ip address
invalid option # select value must be from the list
too large (max=n)
number precision exceeded (max bits=n) # u8, s8, u16, etc only allow 8 or 16 bits, etc
too small(min=n)
not a boolean
bad array index
not a list or dict # array must be a dict or list
too short (min length=n)
incorrect padding # encrypted password is corrupted
too long (max length=n)
invalid dns name
Config Rollback
Sometimes the device will validate a config and apply it, but then be unable to connect the WAN with the new settings. To protect against this situation, all firmware versions support a config rollback feature. After applying a config from NCM, if the device cannot contact NCM within 15 minutes it "undoes" the config change and reverts to the previous working version. When it reconnects to NCM after a rollback it informs NCM and config sync on the device is suspended.
Differences From v1
Sample v1 resource:
"account" : "/api/v1/accounts/1/",
"actual" : "/api/v1/configuration_managers/2/actual/",
"configuration" : "/api/v1/configuration_managers/2/configuration/",
"id" : "2",
"lock" : "unlocked",
"pending" : "/api/v1/configuration_managers/2/pending/",
"pending_patch" : null,
"resource_uri" : "/api/v1/configuration_managers/2/",
"router" : "/api/v1/routers/2/",
"suspended" : false,
"synched" : true,
"target" : "/api/v1/configuration_managers/2/target/",
"version_number" : 83
Sample v2 resource:
"account" : "https://www.cradlepointecm.com/api/v2/accounts/1/",
"actual" : [{}, []],
"configuration" : [{}, []],
"id" : "1108",
"pending" : [{}, []],
"resource_url" : "https://www.cradlepointecm.com/api/v2/configuration_managers/1108/",
"router" : "https://www.cradlepointecm.com/api/v2/routers/1108/",
"suspended" : false,
"synched" : true,
"target" : [{}, []],
"version_number" : 0
*Notable differences:
- The fields which contain configuration diffs (
configuration
,actual
,target
andpending
) are no longer URLs. They are contained right in the resource. - The
pending_patch
field has been removed. The same information is available inpending
. resource_uri
has been renamedresource_url
and is a full URL.- The
account
androuter
fields are full URLs. - The
routers
resource does not have a URL link to the correspondingconfiguration_managers
. However, you can still find the correspondingconfiguration_manager
by querying as in "Change the WiFi SSID and WPA2/PSK Passkey On Specific Routers" example
Zscaler Configurations
Zscaler is a cloud-based filtering and security policy application that can be configured on Cradlepoint devices. More details can be found at Zscaler Internet Security
Zscaler example code
###Zscale Username / Password
{
"configuration": [
{
"dns": {"force_redir": true},
"webfilter": {
"cloudservice": "zsis",
"zsis": {
"dyndns": {"password": "password1", "user_name": "username1"}
}
},
[]
]
}
Hardware Requirements
- Cradlepoint AER 2100 or MBR1400v2
- ZScaler service account
Firmware Version
- The firmware version used for the preparation of this document was NCOS 5.0.0.
Cradlepoint NetCloud provides a secure JSON based RESTful API via HTTPS. The API interface is accessed and managed via NetCloud Manager.
Benefits
Accessing the API
Cradlepoint NetCloud API is available to all customers with an active NetCloud Service Plan.*
Active Documentation
- Active documentation
- Code examples
- API usage tracking
- API developer key creation and management
*Threshold limits may apply.
API Usage Examples
- Network management systems
- Security Information & Event Management
Systems (SIEM) - 3rd party applications
- Customized vertical applications
- Network health monitoring