Documentation

Cradlepoint NetCloud Manager NetCloud API Version 2

Cradlepoint NetCloud Manager (NCM) is an SaaS-type server that enables the remote management of network devices, including routers and access points. This specification describes a RESTful API that can be used by web applications to access the service.

The NetCloud API is Cradlepoint’s first public API available to all NCM account holders. Active documentation is available. The API and documentation are subject to change. To get started with the NetCloud API read this overview.

What is a REST API?

An API, or application programming interface, is a protocol that enables communication between different software systems. It provides the building blocks programmers need to create applications that access the data from a software platform – in this case the data from Cradlepoint NetCloud Manager.

REST, or representational state transfer, is a particular architectural style, common for Web APIs, that leverages existing technologies of the Web (e.g. HTTP, XML) to enable information access on a large scale. The REST architecture was first described by Roy Fielding in his 2000 doctoral dissertation.

A REST API is a hypertext-driven API that uses HTTP methods and follows the REST principles. The Cradlepoint NetCloud Manager REST API uses the following HTTP methods: GET, POST, PUT, and DELETE.

Basics

Base URL: https://www.cradlepointecm.com/api/v2/ (“v2” designates version 2)

Authentication: Authentication is the means by which a request proves who it is coming from. This API uses NCM keys to perform authentication. An NCM key can be generated by a root admin using the NetCloud API application tile.

Authorization: Authorization is the means by which the system determines that the requestor has the right to the access role which is defined by the NetCloud API Key that includes the following roles: Administrator, Full Access User, Read Only User.

Read results are always filtered by what the requestor has permission to read. Create, update, and delete operations fail unless the requestor has the right permissions. Permissions are specific to each account and resource type.

Supported Security

In compliance with PCI 3.1, NetCloud API supports TLS v1.1 and higher. SSL and earlier versions of TLS are not supported. The following ciphers are supported:

TLS 1.2

          TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
          TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
          TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
          TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
          TLS_RSA_WITH_AES_256_GCM_SHA384
          TLS_RSA_WITH_AES_128_GCM_SHA256
          TLS_RSA_WITH_AES_256_CBC_SHA256
          TLS_RSA_WITH_AES_256_CBC_SHA
          TLS_RSA_WITH_AES_128_CBC_SHA256
          TLS_RSA_WITH_AES_128_CBC_SHA

TLS 1.1
        TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
        TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
        TLS_RSA_WITH_AES_256_CBC_SHA
        TLS_RSA_WITH_AES_128_CBC_SHA

This section describes general conventions used by the API.

Format of Examples

The examples of API usage in this document are abbreviated for clarity and to avoid confusing the RESTful API with a particular tool, language or library. The API does not require any particular tool or library: anything that supports the basic HTTP requests will work, and the syntax of how to express the request will vary with the tool or libary. The examples focus on the HTTP method, the path, and the data where it is relevant. They don't show the hostname of the URL or the authentication headers. For example: 

GET https://www.cradlepointecm.com/api/v2/routers/

It's assumed that every request will send an HTTP with the necessary API keys.

It is important to note that URLs for endpoints MUST end with a forward slash (trailing 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/accounts/
Incorrect format: https://www.cradlepointecm.com/api/v2/accounts

In cases of PUT or POST the example would show the data being sent as a JSON document below the PUT or POST, like this: 

POST https://www.cradlepointecm.com/api/v2/groups/
{"name": "Test Group", "product":"https://www.cradlepointecm.com/api/v2/products/1/"}

PUT and POST must send a Content-Type header. If using JSON like all the examples in this doc, the Content-Type should be application/json.

Note: Whenever NetCloud Manager endpoint functionality is applicable to both routers and access points the term "device" is used in this documentation to signify that the endpoint applies to both routers and access points. It is important to note that endpoint parameters and methods named, or containing, the word “router(s)” may also apply to access points.

CRUD & HTTP Methods

The API is RESTful, and uses the following HTTP methods to implement the four basic CRUD (Create, Read, Update, and Delete) operations:

Quick reference:

Create POST https://www.cradlepointecm.com/api/v2/{resource-type}/ The body should contain a resource descriptor.
Read GET https://www.cradlepointecm.com/api/v2/{resource-type}/{id}/
Update PUT https://www.cradlepointecm.com/api/v2/{resource-type}/{id}/ The body should contain a partial resource descriptor containing whatever attributes need to be replaced.
Delete DELETE https://www.cradlepointecm.com/api/v2/{resource-type}/{id}/ This process is not reversible.

Creating

Resources will be created by sending a POST to the root path for that resource. For example: 

POST https://www.cradlepointecm.com/api/v2/groups/
{"account": "https://www.cradlepointecm.com/api/v2/accounts/23/", "name": "Group 2", "product": "https://www.cradlepointecm.com/api/v2/products/1/", "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/3771/"}

By default, the resource will be added to the requestor's account. If the requestor wants to add to a different account, the request should include an 'account' field in the POST data.

Reading

Reading is simple, just issue a GET:

GET https://www.cradlepointecm.com/api/v2/routers/

Or to get a specific object, append the ID:

GET https://www.cradlepointecm.com/api/v2/routers/1234/

Updating

Like creating, updating requires you to provide a body. The body need only list the attributes that are changing.

PUT https://www.cradlepointecm.com/api/v2/groups/23243/
{"name": "Renamed Group"}

Deleting

Deleting a resource removes that specific resource along with all of the data associated with it. For example, in the case of a router deletion, the router is unregistered from NCM, all of the alerts, state samples, signal samples, and anything else associated with that specific router are also removed from the system entirely. This process is not reversible.

DELETE https://www.cradlepointecm.com/api/v2/routers/1224/

Parameters

Parameters are appended to the path after a '?'. The examples will use a short-hand notation in '{' brackets '}' to show common parameters that are supported.

Quick reference:

{paging} := offset=<int>&limit=<int>
{fields} := fields=<val>.<val>,<val>

Examples:

GET https://www.cradlepointecm.com/api/v2/routers/?offset=100&limit=50
GET https://www.cradlepointecm.com/api/v2/router_alerts/?type=wan_unplugged&time__gte=today
GET https://www.cradlepointecm.com/api/v2/accounts/?fields=name

{paging}

Note: offset parameter is supported only with routers, net_devices, groups, accounts, products, firmwares, net_device_metrics, configuration_manager endpoint.

When getting a list you can request a slice with the paging parameters: 'offset' and 'limit'. 

GET https://www.cradlepointecm.com/api/v2/routers/?offset=50&limit=25

Any time a list is returned the values used for offset and limit are returned in the meta portion of the reply. Note that most resources have a max limit of 500. To page the whole list you need to increment the offset. So to get the next 25 devices:

GET https://www.cradlepointecm.com/api/v2/routers/?offset=75&limit=25

{fields} aka Partial Returns

If the requestor does not want to get the full body of the reply, they can use the _fields_ param to get a partial result. Example:

GET https://www.cradlepointecm.com/api/v2/users/?fields=username,email

Format & Extensions

The only officially supported format is JSON, which is the default.

Reply Format

The system will usually send HTTP response codes as follows:

GET   : 200 OK
POST  : 201 Created
PUT   : 202 Accepted
DELETE: 204 No Content

307 Found (Redirected)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
409 Conflict
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway

Normal response format

{
    "data": [
        {
            "account": "https://www.cradlepointecm.com/api/v2/accounts/1/",
            "id": "3",
            "is_disabled": false,
            "name": "blue",
            "resource_url": "https://www.cradlepointecm.com/api/v2/accounts/3/"
        },
        {
            "account": "https://www.cradlepointecm.com/api/v2/accounts/3/",
            "id": "4",
            "is_disabled": false,
            "name": "blue_sub",
            "resource_url": "https://www.cradlepointecm.com/api/v2/accounts/4/"
        }
    ],
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null
    }
}

Error response format

{
    "errors": [
        {
            "path": "https://www.cradlepointecm.com/api/v2/groups/"
        },
        {
            "method": "POST"
        }
    ],
    "exception": {
        "message": "method not allowed",
        "type": "error"
    }
}

The exception codes are listed below, as well as the fields which will appear with them in the error response.

unauthorized

{
    "errors": [
        {
            "path": "https://www.cradlepointecm.com/api/v2/groups/"
        }
    ],
    "exception": {
        "message": "unauthorized",
        "type": "error"
    }
}

forbidden

{
    "exception": {
        "message": "forbidden",
        "type": "error"
    },
    "errors": []
}

server_error

{
    "exception": {
        "message": "Expecting ',' delimiter or '}': line 3 column 2 (char 70)",
        "type": "server_error"
    },
    "errors": []
}

validation

{
  "exception": {
    "type": "validation",
    "message": "bad or missing data"
  },
  "errors": [
    {
      "foo": "no such field"
    }
  ]
}
 

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.

Failovers Object

Parameter Data Type Filter Sort Expand Description
account_id int Your account ID number
group_id int The ID of a group to view failover events
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
ended_at datetime _exact=, _gt=, _gte=, _lt=, _lte= Datetime for when a failover event ended
limit int Number of records to return
offset int

Example

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".

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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 the account to which you belong. This is your “owning” account because it owns your user information. The owning account is the root of the object hierarchy to which you have access.

The Account Object

Parameter Data Type Filter Sort Expand Description Permissions
account* url =, __in Parent account Read/Write
id int =, __in Object ID Read/Write
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/Write
Note: * attributes are required for a Post request.
Note: Only params listed as Read/Write can be included in PUT/POST request bodies.

Example

https://www.cradlepointecm.com/api/v2/accounts/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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 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.

ActorsActionsObjects
  • system
  • user
  • api_key
  • router
  • sso_user
  • access_point
  • create
  • delete
  • update
  • request
  • report
  • login
  • logout
  • register
  • unregister
  • activate
  • license
  • account
  • user
  • group
  • router
  • schedule
  • sso_user
  • task
  • api_key
  • net_device
  • notifier
  • feature_binding
  • authorization
  • remote_connection
  • remote_connection_profile
  • remote_lan_management
  • sso_account
  • access_point
  • sso_authorization
  • network
  • data_plan
  • location
  • data_pact
  • production_database_entity
  • production_database_transaction

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

The Activity Logs Object

Parameter Data Type Filter Sort Expand Description
account int The ID of your account
created_at timestamp _exact=, _gt=, _gte=, _lt=, _lte= Timestamp for the activity that occurred
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
object__id string = ID (exact) of the action taken
action__id string = ID of the object for the activity
actor__type string = Type of actor who took the action
action__type string = Type of action taken
object__type string = Type of object the action was taken upon

Example

https://www.cradlepointecm.com/api/v2/activity_logs/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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

Examples

https://www.cradlepointecm.com/api/v2/alerts/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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" }

}

Alerts Methods

A device app object represents a Cradlepoint SDK app.

The Device App Object

Parameter Data Type Filter Sort Expand Description
account url =, __in Account that owns the object
name string =, __in The name of the device app
description string Optional description of the device app
uuid int =, __in UUID of the app
created_at timestamp Time the device app object was created
updated_at timestamp Time of last attribute update
id int =, __in Object ID
resource_url url Object URL

Example

https://www.cradlepointecm.com/api/v2/device_apps/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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 app.

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
version int Version
state string =, __in State of the app version
state_details string Details of the app version state
created_at timestamp Time the device app object was created
updated_at timestamp Time of last attribute update
id int =, __in Object ID
resource_url url Object URL

Example

https://www.cradlepointecm.com/api/v2/device_app_versions/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

The Device App Binding Object

Parameter Data Type Filter Sort Expand Description Permissions
account url =, __in Account that owns the object Read/Write
group url =, __in The group in which the binding will be applied 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/Write
updated_at timestamp Time of last attribute update Read/Write
state string =, __in State of the device app Read/Write
id int =, __in Object ID Read/Write
resource_url url Object URL Read/Write
Note: Only params listed as Read/Write can be included in PUT/POST request bodies.

Example

https://www.cradlepointecm.com/api/v2/device_app_bindings/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

The Device App State Object

Parameter Data Type Filter Sort Expand Description
account url =, __in Account that owns the object
router url =, __in The router with the device app
app_version url =, __in The app version associated with device app
created_at timestamp Time the device app object was created
updated_at timestamp Time of last attribute update
state string =, __in State of the device app
id int =, __in Object ID
resource_url url Object URL

Example

https://www.cradlepointecm.com/api/v2/device_app_states/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

The Router Object

f
Parameter Data Type Filter Sort Expand Description Permissions
account url =, __in Account that owns the object Read/Write
actual_firmware url Firmware currently on the device, if known Read Only
asset_id string User defined identifier often used for asset tracking Read/Write
config_status string Status of configuration synch: synched, pending or suspended Read Only
created_at timestamp Time the device object was created Read Only
custom1 string User defined custom text field Read/Write
custom2 string User defined custom text field Read/Write
description string Optional description of the device (synched with device) Read/Write
device_type string =, __in Type of device, e.g. router or access point Read Only
full_product_name string Device's full product name, e.g. IBR600LP-AT Read Only
group url =, __in Optional group this device belongs to Read/Write
id int =, __in Object ID Read/Write
ipv4_address string =, __in Device's IPv4 address Read Only
last_known_location url Optional last known location of the device Read Only
locality string Device's timezone Read Only
mac string =, __in Device's MAC address Read Only
name string =, __in Device's name (synched with device) Read/Write
product url Device product, e.g. IBR600 or AP22 Read/Write
reboot_required boolean =, __in Reboot required to enable additional device functionality Read Only
resource_url url Object URL Read/Write
serial_number string Device's serial number, if known Read Only
state string =, __in Device's state: initialized, online or offline Read Only
state_updated_at timestamp __lt, __gt Time of last state update Read Only
target_firmware url Firmware currently assigned to the router’s group Read Only
upgrade_pending boolean The device has a pending NCOS upgrade Read Only
updated_at timestamp __lt, __gt Time of last attribute update Read Only
Note: Only params listed as Read/Write can be included in PUT/POST request bodies.

Example

https://www.cradlepointecm.com/api/v2/routers/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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
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
mfg_product string Product name of the net device
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

Example

https://www.cradlepointecm.com/api/v2/net_devices/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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: Only params listed as Read/Write can be included in PUT/POST request bodies.
Note: * attributes are required for a Post request

Example

https://www.cradlepointecm.com/api/v2/groups/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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

Example

https://www.cradlepointecm.com/api/v2/products/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

The Net Device Health Object

Parameter Data Type Filter Sort Expand Description
net_device int = The id of the net_device.

Example

https://www.cradlepointecm.com/api/v2/net_device_health/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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
router URL = The ID of the device providing the location information
rsrp double LTE reference signal receive power
rsrq int LTE 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)
summary string Connected status of the net device.

Note: * A router ID (?router=<router id>) is required when calling this endpoint.

Example

https://www.cradlepointecm.com/api/v2/historical_locations/?router=<router id>

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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

Example

https://www.cradlepointecm.com/api/v2/net_device_usage_samples/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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

Example

https://www.cradlepointecm.com/api/v2/net_device_signal_samples/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

The Firmware Object

Parameter Data Type Filter Sort Expand Description
built_at timestamp Time at which the firmware image was built
default_configuration json Default configuration for the firmware version
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 Time at which the firmware was released
expires_at timestamp Time at which the firmware version expires
resource_url url Object URL
uploaded_at timestamp Time at which the firmware image was uploaded to NCM
url url URL of the firmware image
version string =, __in Version of this firmware

Example

https://www.cradlepointecm.com/api/v2/firmwares/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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
    }
}

Firmware 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.

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

Example

https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

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

Example

https://www.cradlepointecm.com/api/v2/router_state_samples/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

The Router Alerts Object

f
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.
friendly_info string Human-readable description of the alert
info json Alert-type specific information
detected_at timestamp Time the alert was detected
router url =, __in Device this alert is related to
type string The type of the alert

Example

https://www.cradlepointecm.com/api/v2/router_alerts/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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
account_locked The account is lock for 30 minutes after six failed attempts to log into the device.
config_change 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.
data_cap_threshold Device data usage has reached a threshold.
ethernet_wan_connected An Ethernet WAN device is now active.
ethernet_wan_disconnected An Ethernet WAN device is no longer active.
ethernet_wan_plugged An Ethernet WAN device is now attached.
ethernet_wan_unplugged An Ethernet WAN device has been removed.
firmware_upgrade The device firmware has been upgraded.
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.
login_failure Someone tried and failed to login to the device's local UI.
login_success A user has logged into the device locally.
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_unplugged A modem WAN device has been removed.
reboot_status_change Device has rebooted.
thermal_exceeds_limit A thermal limit was exceeded on the device.
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)
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.

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
}

account_locked 

 info: {
  account: "root",
  type: "account_locked",
  timeout: 30,
  time: [
    "2015-05-13 16:55:19",
    "UTC"
  ]
}

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_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_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: [ ]
}

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: [ ]
}

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"
}

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: [ ]
}

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.

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

Example

https://www.cradlepointecm.com/api/v2/router_logs?router=22630

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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 is supplied to allow easy access to the latest signal and usage data reported by an account’s net_devices without querying the historical raw sample tables, which are not optimized for a query spanning many net_devices at once.

The primary key of this endpoint is net_device, as the data 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 is a read-only endpoint.

The Net Device Metrics Object

Parameter Data Type Filter Sort Expand Description
id int Object ID
resource_url url Object URL
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)
net_device url =, __in net_device that reported the usage sample
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
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
service_type string Last sampled service type value received from net_device

Example

https://www.cradlepointecm.com/api/v2/net_device_metrics/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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.

The Configuration Managers Object

Parameter Data Type Filter Sort Expand Description Permissions
account url =, __in Account which owns the object Read/Write
id int =, __in Object ID Read/Write
resource_url url Object url Read/Write
actual json Diff of device's actual config Read Only
pending json Diff of pending updates to device Read Only
target json Diff of device's target config Read Only
version_number int Count of config changes Read Only
router url =, __in Router Object Read/Write
synched boolean = True if device config is synced 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
configuration json Diff of device's individual config Read/Write
Note: Only params listed as Read/Write can be included in PUT/POST request bodies.

Example

https://www.cradlepointecm.com/api/v2/configuration_managers/123/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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

Reboot Activity allows a device or group to be rebooted. POST a device's URI to reboot a device or a group's URI to reboot a group.

Specifying both a device and a group in the same call is not supported and behavior in this case should be considered undefined. The caller must choose one or the other.

On success, the POST will return a "201 Created" code indicating that the request has been submitted without error. This does not necessarily indicate that the device has started to reboot. If the device is online (connected to NCM), it will be sent the command as soon as possible. If the device is offline, the request will be lost.

Sending an invalid ID for the target will result in an HTTP error, generally a "403 Forbidden" error.

Example

https://www.cradlepointecm.com/api/v2/reboot_activity/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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 device 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.

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: Only params listed as Read/Write can be included in PUT/POST request bodies.
Note: * attributes are required for a POST request

 

Example

https://www.cradlepointecm.com/api/v2/locations/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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 Permissions
host url URL of Speedtest Server Read/Write
max_test_concurrency int Number of maximum simultaneous tests to server (1-50) Read/Write
net_device_ids int[] List of net_device IDs (up to 10,000 net_device IDs per request) Read/Write
port int TCP port for test Read/Write
size int Number of bytes to transfer Read/Write
test_timeout int Test Timeout Read/Write
test_type string TCP Download, TCP Upload, TCP Latency Read/Write
time int Test Time Read/Write

 

Note: Only params listed as Read/Write can be included in PUT/POST request bodies.

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/

Endpoint calls made to "cradlepointecm.com" return a 307 status code and are redirected to www.cradlepointecm.com.
If your client code uses "cradlepointecm.com" (without the WWW protocol) you must:

  • change your code to "www.cradlepointecm.com", or
  • handle the returned 307 codes in your code

 

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": "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
configuration_managers 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
alerts x
device_apps x x
device_app_versions x x
device_app_bindings x x
device_app_states x x

The URL data type has the following conventions:

  • Request: URI, Example: /api/v2/accounts/1/
  • Response: URL, Example: https://www.cradlepointecm.com/api/v2/accounts/1/
  • Query Argument: Integer, Example: ?account=1

    • 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!

    Sample Code

    The following code samples demonstrate how to query the NCM REST API.

    Sample Code in Python

    The following Python code sample shows how to access the "routers" endpoint of the NCM REST API using the Python "requests" module with paging. It makes use of the NCM and CP credential headers to authenticate and access the device data. The data is returned as a JSON encoded object. 

    import json
import requests

url = 'https://www.cradlepointecm.com/api/v2/routers/'

headers = {
    'X-CP-API-ID': '…',
    'X-CP-API-KEY': '…',
    'X-ECM-API-ID': '…',
    'X-ECM-API-KEY': '…',
    'Content-Type': 'application/json' 
}

# Get routers
while url:
    req = requests.get(url, headers=headers)
    routers_resp = req.json()
               
    # Get URL for next set of resources
    url = routers_resp['meta']['next']

    Net device usage and signal samples

    The following Python code extends the previous example and can be used to efficiently export the account's net device usage and signal information. It minimizes API requests by using the maximum API_OBJ_REQUEST_SIZE and API_OBJ_RESPONSE_SIZE values. 

    import json
import requests


API_OBJ_REQUEST_SIZE = 100
API_OBJ_RESPONSE_SIZE = 500

START_DATE = '2017-10-19'
END_DATE = '2017-10-20'


# Chunk lists into blocks
def chunker(seq, size):
    return (seq[pos:pos + size] for pos in range(0, len(seq), size))


# Get the next url, at completion return None
def next_url(resp):
    if resp['meta']['next']:
        url = resp['meta']['next']
    else:
        url = None

    return url


# Fill in your API keys here
headers = {
    'X-CP-API-ID': '...',
    'X-CP-API-KEY': '...',
    'X-ECM-API-ID': '...',
    'X-ECM-API-KEY': '...',
    'Content-Type': 'application/json'
}


# Get net_devices
net_device_ids = set()
url = 'https://www.cradlepointecm.com/api/v2/net_devices/?limit={}'. \
    format(API_OBJ_RESPONSE_SIZE)
while url:
    req = requests.get(url, headers=headers)
    resp = req.json()
    for net_device in resp['data']:
        net_device_ids.add(int(net_device['id']))
    url = next_url(resp)


# Get usage samples
print('bytes_in,bytes_out,created_at,created_at_timeuuid,'
      'net_device,period,uptime')
for net_devices in chunker(sorted(net_device_ids), API_OBJ_REQUEST_SIZE):
    url = 'https://www.cradlepointecm.com/api/v2/net_device_usage_samples/' \
        '?limit={}'.format(API_OBJ_RESPONSE_SIZE)
    url += '&net_device__in={}'.format(','.join(map(str, net_devices)))
    url += '&created_at__gt={}&created_at__lt={}'.format(START_DATE, END_DATE)
    url += '&order_by=created_at_timeuuid'

    while url:
        req = requests.get(url, headers=headers)
        resp = req.json()
        if (len(resp['data']) > 0):
            for net_device in resp['data']:
                print('{},{},{},{},{},{},{}'.format(
                    net_device['bytes_in'],
                    net_device['bytes_out'],
                    net_device['created_at'],
                    net_device['created_at_timeuuid'],
                    net_device['net_device'],
                    net_device['period'],
                    net_device['uptime']))
        url = next_url(resp)


# Get signal samples
print('created_at,created_at_timeuuid,ecio,net_device,rssi,'
      'signal_percent,sinr,uptime')
for net_devices in chunker(sorted(net_device_ids), API_OBJ_REQUEST_SIZE):
    url = 'https://www.cradlepointecm.com/api/v2/net_device_signal_samples/' \
        '?limit={}'.format(API_OBJ_RESPONSE_SIZE)
    url += '&net_device__in={}'.format(','.join(map(str, net_devices)))
    url += '&created_at__gt={}&created_at__lt={}'.format(START_DATE, END_DATE)
    url += '&order_by=created_at_timeuuid'

    while url:
        req = requests.get(url, headers=headers)
        resp = req.json()
        if (len(resp['data']) > 0):
            for net_device in resp['data']:
                print('{},{},{},{},{},{},{},{}'.format(
                    net_device['created_at'],
                    net_device['created_at_timeuuid'],
                    net_device['ecio'],
                    net_device['net_device'],
                    net_device['rssi'],
                    net_device['signal_percent'],
                    net_device['sinr'],
                    net_device['uptime']))
        url = next_url(resp)

    Sample Code in Shell Script

    The shell script below shows how to access the NCM REST API to view account data. It makes use of Environment variables to set the NCM and CP credentials and uses the CURL program to access the NCM "accounts" REST endpoint.

    Note that the "-L" option, shown below in the example, must be used with all curl requests to Cradlepoint's API. This allows your curl request to follow any redirects put in place by Cradlepoint. 

    ECM_API_ID="<ECM-API-ID HERE>"
ECM_API_KEY="<ECM-API-KEY HERE>"
CP_API_ID="<CP-API-ID HERE>"
CP_API_KEY="<CP-API-KEY HERE>"
URL="https://www.cradlepointecm.com/api/v2/accounts/"
curl -H "X-ECM-API-ID: $ECM_API_ID" -H "X-ECM-API-KEY: $ECM_API_KEY" 
     -H "X-CP-API-ID: $CP_API_ID" -H "X-CP-API-KEY: $CP_API_KEY" 
     -H "Content-Type: application/json" -L $URL

    Sample Code in JAVA

    import java.util.*;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

import javax.net.ssl.HttpsURLConnection;

public class HttpURLConnectionExample {

	public static void main(String[] args) throws Exception {
		HttpURLConnectionExample http = new HttpURLConnectionExample();
		http.sendGet();
	}

	// HTTP GET request
	private void sendGet() throws Exception {
		String url = "https://www.cradlepointecm.com/api/v2/accounts/";		
		URL obj = new URL(url);
		HttpURLConnection con = (HttpURLConnection) obj.openConnection();

		// optional default is GET
		con.setRequestMethod("GET");

		//add request header
		HttpURLConnectionExample http = new HttpURLConnectionExample();
		http.set_headers(con);
		int responseCode = con.getResponseCode();

		System.out.println("\nSending 'GET' request to URL : " + url);
		System.out.println("Response Code : " + responseCode);

                Scanner s = new Scanner(con.getInputStream());
                System.out.println("Response : " + s.useDelimiter("\0").next());	

	}

        public HttpURLConnection set_headers(HttpURLConnection con)
	{
                con.setRequestProperty("x-ecm-api-id", "...");
                con.setRequestProperty("x-ecm-api-key", "...");
                con.setRequestProperty("x-cp-api-id", "...");
                con.setRequestProperty("x-cp-api-key", "...");
                con.setRequestProperty("Accept", "*/*");
                return con;
	}
}

    Sample Code in PHP

    <?php
$url = 'https://www.cradlepointecm.com/api/v2/routers/';
$headers = array(
    'X-CP-API-ID: ...',
    'X-CP-API-KEY: ...',
    'X-ECM-API-ID: ...',
    'X-ECM-API-KEY: ...', 
    'Content-Type: application/json' 
);

$req = curl_init();
curl_setopt_array($req, array(    
    CURLOPT_URL => $url,
 CURLOPT_HTTPHEADER => $headers, 
));

$result = curl_exec($req);
$res_info = curl_getinfo($req);
echo $res_info['http_code'];
curl_close($req);
?>

    Q&A

    Q) When can a request refer to a nested resource for filtering or field selection?

    A general rule which usually works is this: if a field is NOT a URL by default, then you CANNOT “dive into it” with query parameters. For instance, if you GET https://www.cradlepointecm.com/api/v2/routers/, the “product” field is a URL: 

    "product": "https://www.cradlepointecm.com/api/v2/products/2"

    By way of comparison, if you GET https://www.cradlepointecm.com/api/v2/alerts/, the “info” field is not a URL, it's a literal value (which happens to be a nested dict): 

    "info": { ... stuff ... }

    So filters and field selection cannot “dive into” the internals of info.

    Q) What is the best way to get API results into Excel?

    The best way is to page the results in as JSON and convert them using a script.

    Q) How can I use the API to create an uptime report?

    If by “uptime” you mean “time the device has been connected to NCM,” then this is very close: 

    https://www.cradlepointecm.com/api/v2/routers/?state=online&fields=state_updated_at

    This shows all the devices currently online and the time at which they came online. Again (with a script) one can subtract that time from the current time to get uptime. You can do the same for state=offline to see when devices were detected as offline by NCM.

    As an alternative, (for series 3 products only), each net_device reports an uptime: 

    https://www.cradlepointecm.com/api/v2/net_devices/?connection_state=connected&fields=uptime,name

    Filtering

    Filter Syntax:

    Multiple filters can be provided. Results will match all of the filters.

    Generic Filters

    fieldname=value Exact match
    fieldname__in=[value_1, value_2,..., value_n] Match any from a list

    Examples:

    Return all devices in groups 5, 6 or 7 that are offline:

    GET https://www.cradlepointecm.com/api/v2/routers/?group__in=5,6,7&state=offline

    Sorting

    Partial Results:

    A partial result is when only a subset of the available fields are asked for in a request. The syntax.

    fields=field_1,field_2,...,field_n Return only the fields listed

    Examples:

    Return only the name, state, group and mac for all devices:

    GET https://www.cradlepointecm.com/api/v2/routers/?fields=name,state,group,mac

    Expands

    Expanding is when related objects are asked for in request. Only a subset of related objects allow expands. The syntax.

    expands=field_1,field_2,...,field_n Return related data of the fields listed

    Examples:

    Return all devices, as well as the related objects account and group:

    GET https://www.cradlepointecm.com/api/v2/routers/?expand=account,group

    Paging

    When getting a list you can request a slice with the paging parameters: 'offset' and 'limit'. 

    GET https://www.cradlepointecm.com/api/v2/routers/?offset=count&limit=count

    Any time a list is returned the values used for offset and limit are returned in the meta portion of the reply. Note that most resources have a max limit of 500. To page the whole list you need to increment the offset. So to get the next 50 devices:

    Examples:

    import requests

headers = {
    'X-CP-API-ID': '…',
    'X-CP-API-KEY': '…',
    'X-ECM-API-ID': '…',
    'X-ECM-API-KEY': '…',
    'Content-Type': 'application/json',
    'Accept': '*/*'
}

result = []
#Get next 50 devices
url = 'https://www.cradlepointecm.com/api/v2/routers/?offset=50&limit=50'

    #loop to get all the data
    while url != None:

        req = requests.get(url, headers=headers)
        alert_data = req.json()
        result.append(alert_data)
        meta = alert_data['meta']
        url = meta['next']

    Glossary

    • admin: a user named as admin by an account, and who gains certain automatic privileges thereby.
    • authentication: the act of verifying that a request is really coming from the user it claims to be coming from.
    • authorization: the act of checking that a request's user has permission to do what the request is trying to do.
    • CRUD: acronym for create, read, update and delete; the four basic operations on a data resource.
    • DTD: document type definition; a structured document describing the format of a class of structured documents. A DTD specifies data types, defaults and hierarchical structure.

    Configuration in API V2

    This document describes what is particular to the configuration-related endpoints and how they extend those conventions.

    There are two endpoints for controlling configuration. One is for individual devices and one is for group configs.

    Endpoints:

    https://www.cradlepointecm.com/api/v2/configuration_managers/
https://www.cradlepointecm.com/api/v2/groups/

    Individual Devices Configurations

    Individual device configs are managed by the configuration manager endpoint

    https://www.cradlepointecm.com/api/v2/configuration_managers/[id/]

    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.

    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.

    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 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 which are 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, then even if there are pending changes this field will appear empty, because the changes cannot be computed 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 the individual 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 will match 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 will accept any local changes. If it does not match, NCM will ignore and even wipe local changes in order to force the device to sync. The API shows this number for informational purposes only. It will increment automatically 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 will also generate 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 will be validated using static validators. The validator will check 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"
<                  }
<               }
<            },
<            []
<         ]
<     }
< }

    In the above example the device is synced. You can tell because the pending field is just an empty diff ([{}, []]), the actual and target fields have the same content, and synched is true.

    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 due to the fact that 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 will replace an entire individual config with the given payload. It can also be used to resume 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 will 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/

    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 will include 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 will enable 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 will always use this technique.)

    If the request actually changes the config -- which is usually the intention -- the target field will be updated, the version_number field will be incremented, the synched field will be false and the pending field will show the changes that will be (or already have been) sent to sync the device. If the request does not change the config (meaning it already matches the request payload) then nothing changes.

    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 which will pass traffic to the WAN. It does this by:

    1. Removing the default Guest LAN.
    2. Moving port 4 from the set of normal LAN ports to a new VLAN called "aleph".
    3. Assigning the aleph VLAN to a new LAN interface called "Aleph LAN".
    4. Adding a new firewall zone for the Aleph LAN.
    5. Adding 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 will be processed by the device first. Removals must refer to elements which exist in the device's default config. These do:

    [
	["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" as you can see. 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 will use the _id_ in its removals whenever possible.

    After processing the removals, the device will apply 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 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 will be 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:

    1. Use the NCM config editor to create a config on one device.
    2. GET https://www.cradlepointecm.com/api/v2/configuration_managers/123/ to download it.
    3. Edit the downloaded copy.
    4. PUT https://www.cradlepointecm.com/api/v2/configuration_managers/456/ to upload it 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 will stay 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 tell NCM to stop syncing a device via the API. Why would you? 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 will also change 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 will replace anything not mentioned with nothing (ie, wipes it back to defaults). PATCH will leave it alone.

    For example, this will wipe 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 it.

    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 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: &#39;00000000-0d93-319d-8220-4a1fb0372b51&#39;",
      "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 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 will 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 in some way be unique from one another. Although 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"
        }
    }
}

    Obviously, 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) which 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 does conform to the DTD it can still be invalid. The devices checks 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 will automatically attempt to migrate its configuration to be compatible with the new version.

    The DTD will specify a default value for many fields, including all required fields. As noted elsewhere it will also specify 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 will restore them. In NCM, clearing configs will have a similar effect.

    Suspended Sync

    If NCM tries to sync a device to an invalid config, the device will reject it. NCM will stop trying to sync the device and will mark 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>).

    When a device is suspended the first action of an administrator should be to ascertain why it rejected the config. From NCM, the best way to do this is by examining the Config Sync Rejected Alert. When this alert is enabled, it will contain information from the device itself about why it rejected the config. Usually it will reference some field of the config that failed its dynamic validation checks.

    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 will also have configuration_managers. However, their configuration format is different from series 3, and of course the fields and values are all 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, first every path in the removals list is removed, in the order specified, then every key/value 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 will "undo" the config change, reverting to the previous working version. When it reconnects to NCM after a rollback it informs NCM and config sync on the device will be 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 and pending) are no longer URLs. They are contained right in the resource.
    • The pending_patch field has been removed. The same information is available in pending.
    • resource_uri has been renamed resource_url and is a full URL.
    • The account and router fields are full URLs.
    • The routers resource does not have a URL link to the corresponding configuration_managers. However, you can still find the corresponding configuration_manager by querying as in "Change the WiFi SSID and WPA2/PSK Passkey On Specific Routers" example

    Zscaler Configurations

    Zscaler is the cloud-based filtering and security policy, 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 that was for the preparation of this document was 5.0.0.