Welcome to the Cradlepoint NetCloud Manager API

The NetCloud Manager API is a RESTful API available to Cradlepoint customers for programmatic access to their NetCloud services. The NetCloud Manager API is used to programmatically perform many of the same functions as can be performed in the NetCloud Manager user interface. This allows for integration and automation between NetCloud Manager and customer software systems.

Important: You are currently viewing the API portal as a non-logged in user. If you are a customer, log into the portal using the steps below in ACCESSING THE API PORTAL AS A LOGGED-IN USER.

NetCloud Manager API Use Cases

Managing Users

View, add, delete, and change permissions for your account's users

Reacting to Events on your Routers

Use Webhooks to send alert notifications to your code.

Tracking Mobile Routers

Quickly identify where mobile routers are located, and where they have been.

Checking for Failovers

Review your routers that are in a failover state.

Updates, New Endpoints and Features

Date Description
07/12/2023 Beta release of API v3 endpoints for Private Cellular Networks, Commerce (subscriptions, asset_endpoints), and User Management (users v3).
01/17/2024

When working with the users v3 endpoint (beta), note that the attributes object for collaborator users contains a reduced set of data.

Collaborator users attributes: email, first_name, last_name, and timeout fields.

Users attributes: email, first_name, last_name, is_active, last_login, and pending_email fields.

API Deprecation Notes

Continued evolution of the NetCloud Manager API requires the deprecation of both endpoints and of data fields used in endpoints that no longer return accurate information.

This page lists the NetCloud Manager API endpoints and endpoint fields that have been deprecated.

References to the following endpoints and fields must be removed from your code by their deprecation date. Continuing to reference these endpoints and fields after their deprecation date will result in your code failing.

 

Deprecated Endpoints, Fields and other Functionality

 

Description: NetCloud Manager Web and API traffic is updating to a new Certificate Authority (CA) on August 15, 2024, and the following must be addressed by August 1st, 2024:
Deprecation Date: 08/01/2024
How does this affect me?

  • If you are not using one of the Supported Browsers, you may not be able to login and use NetCloud Manager.
  • API clients must trust the CA Google Trust Services. Most modern API clients will work without issue, but some older clients may need to be updated to continue working.

Additional Detail:

  • NetCloud Manager leverages Cloudflare for protecting the site from potentially malicious traffic. This provider is deprecating support from the current CA in use, DigiCert, so NetCloud Manager is updating to a supported CA, Google Trust Services.
  • To test whether your API client works with this CA ahead of the official migration, you can leverage
    https://validate-gts.cradlepointecm.com
  • API clients that do not trust the new CA would report an "SSL verification error" (or similar).

Endpoint: routers
Deprecation Date: 09/30/2024
Fields: overlay_network_binding
Reason: Deprecated
Actions to take:

If you reference the overlay_network_binding data field in scripts when using the routers endpoint, you must remove those references by September 30, 2024, or your script may encounter unexpected errors.

The endpoint base path for the routers endpoint remains: 

https://www.cradlepointecm.com/api/v2/routers/
given NetCloud API v2.

Endpoint: overlay_network_bindings
Deprecation Date: 09/30/2024
Fields: All
Reason: Deprecated
Actions to take: If you reference the overlay_network_bindings endpoint in your scripts, you must remove those references by September 30, 2024, or your script may encounter unexpected errors.
Endpoint: forwarding_lan_details
Deprecation Date: 09/30/2024
Fields: All
Reason: Deprecated
Actions to take: If you reference the forwarding_lan_details endpoint in your scripts, you must remove those references by September 30, 2024, or your script may encounter unexpected errors.
Endpoint: net_devices
Deprecation Date: 12/31/2023
Fields: is_upgrade_available
Reason: This field no longer returns accurate information.
Actions to take: Remove any references you have to this field in your code. Note that this field still displays in responses but does not contains accurate information.

 

Accessing the API portal as a logged-in user

 

Cradlepoint customers can access the API portal as a logged-in users to view important account information like API keys (API v2) and API usage statistics. Use the following steps to log in to the API portal

  1. Log in to NetCloud Manager
  2. Navigate to the TOOLS page.
  3. Click NetCloud API and then click the API Portal link to access the API Portal.

For other ways to extend and integrate with NetCloud, see the NetCloud Extensibility Solutions page.

NetCloud Manager API Documentation

This section describes the general conventions used by the NetCloud API.

Format of Examples

The NetCloud API does not require the use of any particular software tools or libraries. Any software tools that support the use of HTTP request methods will work. However, the syntax of how to express the request varies with the tool or library. The examples focus on the HTTP method, the path, and the request body (when required). These examples don't show authentication headers. The following example shows a GET request to the routers endpoint: 

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

It's assumed that every request sends an HTTP header with the necessary API keys.

Please 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 examples 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 the examples in this doc, the Content-Type must be 'application/json.'

Note: The term "device" is used in this documentation to mean either a router or access point. It is important to note that endpoint parameters and methods named, or containing, the word “router(s)” might 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 request 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 request 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.

Create a Resource

Create a resource by sending a POST request to the root path for that resource type. The following example creates a new group, specifying the account, a group name, type of product, and the firmware for the devices in the group: 

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 is added to the requestor's account. If the requestor wants to add a resource to a different account, the request must include an 'account' field in the POST data.

Read Resources

Reading is simple, just issue a GET:

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

Or to get a specific object, append the object's ID to the request:

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

Update a Resource

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

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

Delete a Resource

Deleting a resource removes that specific resource and all the data associated with it. In the case of a router deletion, the router is unregistered from NCM and all of its associated data (e.g. alerts, state samples, signal samples, etc) is removed from the system. The delete process is not reversible.

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

Request Parameters

Parameters are appended to the path after a '?' and are used to affect result sets. The examples uses 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 Parameters

Endpoints that return result sets with multiple records can be "paged" through by using the 'offset' and 'limit' parameters.

Note that not all endpoints support the offset parameter. See the list of endpoints that don't support the offset parameter at the end of this section. 

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

The offset parameter specifies the starting index in a result set to return records from for an endpoint call. The limit parameter specifies how many records to return in each endpoint call.

When a result set is returned from an endpoint call, the values used for offset and limit are returned in the meta portion of the response. Note that most resources have a max limit of 500 records per call. To page through the full record set, you must increment the offset. To get the next 25 devices:

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

Alternatively, if the response contains "next" and "previous" URL values in the meta fields they can be used to return the next or previous "page" of records. The "next" field contains a URL with an offset value equal to the next index (and retains the limit value) to return the next page of records. The "previous" field contains a URL with an offset value equal to the previous index (and retains the limit value) to return the previous page of records.

The limit parameter is supported for all endpoints

The offset parameter is supported for ALL endpoints except the following:

  • alert_push_destinations
  • alert_rules
  • historical_locations
  • net_device_signal_samples
  • net_device_usage_samples
  • router_state_samples
  • router_stream_usage_samples

Limit the Fields Returned in a Result Set

If you do not need all the fields returned by an endpoint, use the fields parameter to retrieve a partial result set containing only the fields you want. The fields to return are specified with the fields query param, e.g. ?fields=field1,field2,... The following is a more complete example that returns only the name and is_disabled fields:

GET https://www.cradlepointecm.com/api/v2/accounts/308/?fields=name,is_disabled

Format & Extensions

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

Reply Format

The NetCloud API returns the following HTTP response codes:

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

301 Moved Permanently (Redirected)
302 Found (Redirected)
307 Temporary Redirect (Redirected)
308 Permanent Redirect (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 appear with them in the error response.

unauthorized

      {
       "status_code": 401,
       "exception": "unauthorized",
       "message": " Invalid Credentials i.e. missing or invalid keys.",
       "success": false
      }

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

Differences between NetCloud Manager API v2 and v3

Both versions of the NetCloud Manager API are REST-based services. NetCloud Manager API v3 contains architectural improvements designed to improve performance, stability, and usability.

The most important difference between these API versions is their authentication-and-authorization approach. NetCloud Manager API v2 uses two pairs of API keys to authenticate/authorize requests. NetCloud Manager API v3 uses a single bearer token.

It is important to note that while NetCloud Manager API transitions between API v2 and API v3, it will be common to use both versions of the API.

API v2

API v3

Authentication and Authorization

Cradlepoint API Keys and NetCloud Manager API Keys (application identification) 

Single Bearer Token (user identification)

Documentation Specification

Swagger 1.2

OpenAPI 3.0

Pagination

Offset

Cursor

Versioning

N/A

Yes

Expandable Fields

Yes

No

Alpha Testing

No

Yes

Beta Testing

No

Yes

URL

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

If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account

https://api.cradlepointecm.com/api/v3

Note that a trailing slash isn't used when calling API v3 endpoints.

Content Type

application/json

application/vnd.api+json
 

Use the accounts endpoint to retrieve information about your account and any nested subaccounts in your account.

Your primary, or "owning" account, is the account your NetCloud Manager (NCM) administrator places you into when giving you access to NCM. Depending on your account role and permissions, you can view or modify this account's information and the information for any subaccounts nested beneath it.

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 accounts endpoint supports GET, POST, PUT, and DELETE methods.

  • accounts Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples
  • POST Examples
  • PUT Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

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

Note: Activity Log data is retained in NetCloud for 30 days.

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>
Supported methods: GET
  • Actor/Action/Object Table
  • activity_logs Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the alert_push_destinations endpoint to define HTTP destinations that can receive alert notifications. The destination_config_id field in alert_push_destinations records is used in the alert_rules endpoint http_destinations field to link an alert rule configuration to an HTTP destination for notification.

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>
Supported methods: GET, POST, PATCH, DELETE
  • alert_push_destinations Endpoint Fields and Filters
  • Push Alert States
  • Outbound IP Addresses
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • Field Notes
  • GET Examples
  • POST Examples
  • PATCH Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the alert_rules endpoint to configure Alert Rules that monitor the health and status of your NetCloud account and endpoints. Alert rules are groupings of one or more alert types. Alert types specify the NetCloud system events that you want to be notified of. See the Cradlepoint Connect article Alerting and Reporting for more details on the types of alerts available in NetCloud.

The alert_rules endpoint provides the same functionality as available in the NetCloud Manager (NCM) UI on the Alerts & Logs pages. You can create new Alert Rules, view, edit, and delete them using this endpoint. See the List of NetCloud Alerts section below for a listing of the alerts available in NetCloud.

When an alert is triggered, the alert registers in NetCloud and displays in the NetCloud Manager Alert Log. Alert notifications can be sent via email and to HTTP destinations.

  • Email notifications: when creating an Alert Rule to use email notifications, add one or more user IDs to a list in the email_destinations field. The user IDs from this field are resolved by NetCloud into user email addresses and notification of the alert is sent to those email addresses.
  • Push notifications: alert notifications can be pushed to one or more URLs for processing and monitoring in custom applications. To configure an Alert Rule to send push notifications, use the http_destinations field. This field accepts a list of one or more destinations that you define using the alert_push_destinations endpoint. If you do not have any alert destinations configured in NetCloud, you must create at least one destination to use the push notification functionality.

Important: The unique identifier for an alert_push_destinations record is the destination_config_id (timeuuid) field. The value from this field is the value you must use in the http_destinations field list when configuring an Alert Rule to use a push notification.

NOTE: Certain alerts can be configured with thresholds. These thresholds allow you to control when alerts are triggered. See the Cradlepoint Customer Connect Knowledgebase article Alerting and Reporting for details on using alerts that have thresholds.

When configuring an Alert Rule to push to an HTTP destination, the following steps are required.

  1. Configure a destination to push the alert(s) to using the alert_push_destinations endpoint
  2. Test the destination to ensure it was added correctly using the test_alert_push_destination endpoint
  3. Configure an Alert Rule using this endpoint (alert_rules) and specify one or more destinations for the alert to be pushed to in the http_destination field. Only one destination is required.

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>
Supported methods: GET, POST, PATCH, DELETE.
  • alert_rules Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • List of NetCloud Alerts
  • GET Examples
  • POST Examples
  • PATCH Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

NetCloud Manager (NCM) provides alert functionality to notify NCM users of the health and status of their account and devices. Use the alerts endpoint to view alerts that have been generated in your account. Alerts must be configured in NetCloud, using the NCM UI or the alert_rules endpoint, before they are generated. The default NCM configuration does not create any alerts. After the alerts have been configured, use this endpoint or the NCM UI to monitor the alerts.
See the List of NetCloud Alerts section below for a listing of the alerts available in NetCloud.

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.

NOTE: Certain alerts can be configured with thresholds. These thresholds allow you to control when alerts are triggered. See the Cradlepoint Customer Connect Knowledgebase article Alerting and Reporting for details on using alerts that have thresholds.

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>
Supported methods: GET.
  • alerts Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Important Alert/Push Alert Data-Type Differences
  • Paging Parameters
  • List of NetCloud Alerts
  • GET Examples

    • Forms

    Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the batteries endpoint to retrieve battery information for E100 series devices. Note the following when interpreting values returned by this endpoint.

  • A battery's "status" field contains a positive value while a battery is charging and a negative value while discharging. A battery is considered charged when its capacity is within 15% of its design capacity.
  • A battery's "health" is a ratio of its present capacity and its design capacity.

The following alerts can be configured for monitoring the state of batteries in a router.

  • Battery Health (batt_health_alert): creates an alert when the remaining battery life reaches 62%
  • Battery Over Current (batt_over_current_alert): creates an alert when the battery's current reaches 3.2 amps
  • Battery Over Temperature (batt_over_temp_alert): creates an alert when the battery's temperature reaches 50 degrees Celsius
  • Battery Over Voltage (batt_over_voltage_alert): creates an alert when the battery's recommended voltage exceeds 8.5V (8500 mV)
  • Battery System Low Power (batt_sys_low_power_alert): creates an alert when the battery's power reaches 20% charge
  • Battery System Power Off (batt_sys_power_off_alert): creates an alert when the battery's power reaches 7% charge
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>
Supported methods: GET.
  • batteries Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the configuration_managers endpoint to view and edit configurations for your devices.

Note: Device configuration data is retained for 90 days.

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>
Supported methods: GET, PUT, PATCH.
  • configuration_managers Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Updating SCEP via the NetCloud API
  • Paging Parameters
  • GET Examples
  • PUT Examples
  • PATCH Examples

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

A device app binding object represents a Cradlepoint SDK app to NCM group binding.

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>
Supported methods: GET, POST, DELETE.
  • device_app_bindings Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples
  • POST Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

The device_app_states endpoint retrieves the state of a Cradlepoint SDK app.

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>
Supported methods: GET.
  • device_app_states Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the device_app_versions endpoint to retrieve information about the versions of your installed Cradlepoint SDK apps.

IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
Supported methods: GET, DELETE.
  • device_app_versions Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the device_apps endpoint to retrieve information about your installed SDK apps.

IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
Supported methods: GET, DELETE.
  • device_apps Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

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 and an Advanced license.

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>
Supported methods: GET.
  • failovers Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples

Forms

Use the firmwares endpoint to retrive information about NetCloud OS (NCOS) firmware builds.

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>
Supported methods: GET.
  • firmwares Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

A group is a NetCloud object designed to contain endpoints. Groups allow you to manage endpoints together so you can configure them at the same time with the same settings. Groups have the following characteristics.

  • All endpoints in a group must be the same product type.
  • The group has one NCOS version and endpoints are automatically upgraded to that version when they are added to the group.
  • Groups can have configurations and the group configurations are applied to all endpoints in a group.

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>
Supported methods: GET, POST, PUT, PATCH, DELETE.
  • groups Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples
  • POST Examples
  • PUT Examples
  • PATCH Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

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.

Note: Historical location data is retained for one year.

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>
Supported methods: GET.
  • historical_locations Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

NetCloud Manager (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 are enabled, the NCM UI or this endpoint can be used to monitor or modify device locations.

IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
Supported methods: GET, POST, PUT, DELETE.
  • locations Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples
  • POST Examples
  • PUT Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

The net_device_health endpoints returns a cellular health category and corresponding cellular health score.

The cellular_health_category field is a ranking with one of the following values:

  • Excellent
  • Good
  • Fair
  • Poor

The cellular_health_score field is based on the cellular technology of the connection (i.e. LTE, HSPA, CDMS, etc.), the signal quality (SINR, RSRQ, RSRP, EC/lo, RSSI) and signal strength (RSSI) of the connection.

The following conditions should be considered when evaluating the information returned by the net_device_health endpoint:

  • Routers must be managed by NCM in order for statistics to be gathered on them.
  • 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.
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>
Supported methods: GET.
  • net_device_health Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

This endpoint allows access to the latest signal, usage, and cell-tower data reported by an account’s wireless devices. This endpoint does not query the historical, raw-sample tables. These tables are not optimized for queries that span many wireless devices at once.

The primary key of this endpoint is net_device. The data returned by this endpoint has a one-to-one relationship with the net_devices endpoint. Expansion is supported to the net_devices endpoint. Paging is supported through our standard offset/limit functionality on the relational endpoints.

This endpoint also returns information about the cell towers used by your devices. This information includes cell tower IDs and the PLMN (MCC and MNC), LAC, and TAC codes.

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>
Supported methods: GET.
  • net_device_metrics Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Net device signal samples are periodic reports of modem signal strength indicators. By default a modem will report its current signal strength to NetCloud Manager (NCM) on an hourly basis, although this can be configured.

Note: Device signal-sample data is retained in NetCloud for 90 days.

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>
Supported methods: GET.
  • net_device_signal_samples Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

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.

Note: Net device usage sample data is retained in NetCloud for 90 days.

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>
Supported methods: GET.
  • net_device_usage_samples Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the net_devices endpoint to view network interfaces, and information about each interface, currently enabled on a given Cradlepoint device. Net devices are categorized as either WAN or LAN devices, as signified by the "mode" field, and further categorized by interface type, such as Ethernet, wireless, modem, LTE, etc.

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>
Supported methods: GET.
  • net_devices Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the products endpoint to retrieve information about Cradlepoint products, including product names and resource urls.

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>
Supported methods: GET.
  • products Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

The reboot_activity endpoint allows you to reboot a single router or a group of routers. The reboot_activity endpoint provides the ability to

  • POST a router's URI in the request payload to reboot a router, or
  • POST a group's URI in the request payload to reboot a group of routers.

Specifying both a router and a group in the same call is not supported and the resulting behavior should be considered undefined. The caller must choose to reboot a router or reboot a group of router.

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

Sending an invalid ID for the target router or group results in an HTTP error, typically a "403 Forbidden" error.

Supported methods:POST.
POST payload requirements: router or group URI.

Endpoint base path:

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

IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • POST Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

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.
See the List of NetCloud Router Alerts section below for a listing of the alerts available in NetCloud.

NOTE: Certain alerts can be configured with thresholds. These thresholds allow you to control when alerts are triggered. See the Cradlepoint Customer Connect Knowledgebase article Alerting and Reporting for details on using alerts that have thresholds.

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>
  • router_alerts Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • List of NetCloud Router Alerts
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the router_lans endpoint to retrieve information about the layer 3 LANs of your devices, such as IP addresses and netmasks.

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>
Supported methods: GET.
  • router_lans Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples

    • Forms

Use the router_logs endpoint to view a device's logs. Device logs contain log events sent from the device to NetCloud Manager (NCM). The following are required for a device to report log events.

  • A device must be in an NCM group
  • The NCM group's settings must have the ‘Enable Log Reporting’ setting enabled

To reduce NCM traffic, device logs are not sent to the NCM server by default.

Note: Router log data is retained in NetCloud for 30 days.

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>
Supported methods: GET.
  • router_logs Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • Log Levels
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the router_state_samples endpoint to track the online/offline status of your devices. NetCloud Manager (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 of your devices.

It is important to understand that the router_state_samples endpoint is designed only to report on the online/offline status of routers. It is not recommended to use this endpoint to make calculations related to router states, like router uptime and downtime time periods.

Please note the following about how online/offline status is calculated.

  • Online/offline state is not reported by the router itself but is a function of when the router connects/disconnects to an NCM server. NCM makes online/offline time calculations based on the router being connected to NCM.
  • To account for cases where routers briefly disconnect and reconnect from NCM servers, NCM only counts a device as being offline when it is disconnected from NCM for two minutes or longer.

Note: Router state sample data is retained in NetCloud for 90 days.

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>
Supported methods: GET.
  • router_state_samples Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Cradlepoint devices connect to NetCloud Manager (NCM) through the NCM stream server. NCM tracks communication between devices and the server using stream samples from the stream server. Use the router_stream_usage_samples endpoint to gather stream samples and calculate total NCM network traffic. Note that this data only includes NCM management traffic and not general traffic from the router to the Internet.

Note: Device stream-usage sample data is retained in NetCloud for 90 days.

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>
Supported methods: GET.
  • router_stream_usage_samples Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the form below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the routers endpoint to view information about the devices in your account. This endpoint retrieves information that includes a device's state, location, MAC address, firmware version and other information to help you refer to a device or check its status.

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>
Supported methods: GET, PUT, DELETE.
  • routers Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples
  • PUT Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

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 state 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 NetCloud Manager (NCM).

A speed_test object contains two nested objects; one object for configuration ("config" field) and one object containing the speed test(s) results ("results" field).

IMPORTANT: A netperf server is required for running speed tests via the NetCloud Manager API. No particular netperf server is required. See the Ericsson Enterprise documentation portal article Using Cradlepoint Speedtest for more information on using your own netperf server.

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>
Supported methods: GET, POST, DELETE.
  • speed_test Endpoint Fields and Filters
  • Tips for Using the NetCloud Manager API
  • Paging Parameters
  • GET Examples
  • POST Examples
  • DELETE Example

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Use the test_alert_push_destinations endpoint to test a destination created with the alert_push_destinations endpoint. This endpoint accepts only POST requests containing the destination_config_id of the alert destination to test. Successful POST requests to this endpoint return a 201 Created response with empty response body to indicate an alert push destination is reachable and the secret passed in is valid.

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>
Supported methods:POST.
  • test_alert_push_destinations Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • POST Examples

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

The users endpoint retrieves information about the users in your account including user IDs, names, and email addresses.

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>
Supported methods: GET.
  • users Endpoint Fields and Filters
  • Tips for Using the NetCloud API
  • Paging Parameters
  • GET Examples

Forms

Use the forms below to call the endpoint from this page. The results of your API calls made with these forms are displayed beneath the form.

Endpoint support for different device types

The following table lists which endpoints and methods are supported for which devices

Endpoint name Routers Access Points
accounts x x
alerts x
alert_rules x
alert_push_destinations x
batteries x
configuration_managers x x
device_apps x x
device_app_versions x x
device_app_bindings x x
device_app_states x x
firmwares x x
groups x x
locations x  
net_device_health x x
net_device_metrics x x
net_device_signal_samples x  
net_device_usage_samples x x
net_devices x x
products x x
reboot_activity x x
router_alerts x x
router_lans x x
router_logs x x
router_state_samples x x
router_stream_usage_samples x x
routers x x
speed_test x
test_alert_push_destination x
users x

The URL data type has the following conventions:

  • Request: URI, Example: https://www.cradlepointecm.com/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 Manager API key. This can affect production devices and data!

    Please note that when calling any NetCloud Manager API v3 endpoints, you must provide a Content-Type in the request header. See the GET/POST/PUT Curl examples for each endpoint to see the required Content-Type values.

    Commerce Endpoints

    Use the Cradlepoint Commerce subscriptions endpoint to manage the subscriptions in your account.

    subscriptions

    Subscription required: Essentials

    The subscriptions endpoint returns information about the subscriptions in your account. Subscriptions define the features available to you in NetCloud Manager.

    New! Swagger UI for subscriptions.

    Show more...

    regrades

    Use the regrades endpoint to upgrade, downgrade, license or unlicense devices in bulk operations. The regrades endpoint allows you to specify multiple devices (using MAC addresses) and perform licensing operations on them with one API call.

    IMPORTANT: GET calls to this endpoint only retrieve regrade information for regrades done using this endpoint.
    If a regrade was done using the NetCloud Manager user interface, the regrade information is not available with GET calls to this endpoint.

    The following actions can be performed through the regrades API:

    • License
      • Assign an Essentials license to a device that is currently unlicensed.
      • Does not require subscription_type
    • Unlicense
      • Remove all licenses (Essentials and any Add-ons) from a device.
      • Does not require subscription_type
    • Upgrade
      • Add an Advanced or other Add-on license to a device that already has a compatible Essentials license.
      • Requires subscription_type to assign specific add-on
    • Downgrade
      • Remove an Advanced or other Add-on license from a device, while keeping the Essentials license intact.
      • Requires subscription_type to remove specific add-on

    New! Swagger UI for regrades.

    Show more...

    Account Management Endpoints

    Use the Account Management endpoints to manage your account's users, assets, and related tenants.

    users

    The users endpoint allows you to get, add, modify and delete information about the users in your account including user names and email addresses.

    New! Swagger UI for users.

    Show more...

    asset_endpoints

    Use the asset_endpoints endpoint to obtain a list of all routers and adapters in an account.

    New! Swagger UI for asset_endpoints.

    Show more...

    tenant_authorizations beta

    The tenant_authorizations endpoint lists all the authorizations for all of the users and collaborators in the account tenant and whether they have a 'user' or 'admin' permission. The 'admin' role is the 'Add/Edit User (User Administrator)' permission displayed in the NetCloud web interface. All other users have the 'user' permission.

    New! Swagger UI for tenant_authorizations.

    Show more...

    account_authorizations beta

    Use the account_authorizations endpoint to view and modify the NetCloud Manager roles for the users in your account. User roles specify the level of access to features and functionality for NetCloud Manager users.

    New! Swagger UI for account_authorizations.

    Show more...

    unmasked_wifi_passwords beta

    Use the unmasked_wifi_passwords endpoint to unmask and view Wi-Fi password of a device. Passwords for multiple devices can be unmasked by using the IDs of the devices as query params. Up to 100 device IDs can be passed in each call to this endpoint.

    Note that administrator privileges are required to call the unmasked_wifi_passwords endpoint.

    New! Swagger UI for unmasked_wifi_passwords.

    Show more...

    NetCloud Exchange Endpoints

    Use the NetCloud Exchange (NCX) endpoints for managing your NCX networks.

    exchange_sites beta

    Use the exchange_sites endpoint to create, read, and update NetCloud Exchange resources.

    New! Swagger UI for exchange_sites.

    Show more...

    exchange_resources beta

    Use the exchange_resources endpoint to create, read, and update NetCloud Exchange resources.

    New! Swagger UI for exchange_resources.

    Show more...

    Modem Software Endpoints

    Use the modem software endpoints to manage the modems in your devices.

    modem_software_versions beta

    The modem_software_versions endpoint returns relevant information from modem firmware packages that can be used for updating other groups. This information includes package name, carrier and minimum NetCloud OS version that supports the reported modem firmware.

    The information returned by this endpoint is for the latest package version.

    New! Swagger UI for modem_software_versions.

    Show more...

    modem_upgrades beta

    The modem_upgrades endpoint allows you to create, preview and cancel modem firmware upgrade jobs for groups. You can also retrieve information about completed modem firmware upgrade jobs using this endpoint.

    PUT and POST requests to the modem_upgrades endpoint require that the operational state of the resource is specified in the request body. The following states can be set for POST requests:

    preview:This does not perfrom an upgrade, but allows you to view the estimated number of devices that could be affected when the "upgrade" operation is specified.
    upgrade:Creates a modem_upgrades resource.
    cancel:Cancels a modem_upgrades PUT or POST request

     

    PUT requests support upgrade and cancel, only.

    These states are set in the request body in the attributes -> operation field.

    New! Swagger UI for modem_upgrades.

    Show more...

    Private Cellular Networks Endpoints

    Cradlepoint's Private Cellular Network (PCN) API allows you to manage your Cradlepoint Private Cellular Networks. This includes creating new private cellular networks and managing the cores, radios, and SIM cards associated with the network.

    The PCN endpoints are grouped by functionality.
    PCN Management REST APIs

    The PCN Management REST APIs in this section provide the following functionality:

    • Viewing cellular core information.
    • Viewing, creating, modifying, and deleting cellular networks
    • Viewing, creating, modifying, and deleting radio groups.
    • Viewing and modifying cellular SIMs.

    private_cellular_cores beta

    Use the private_cellular_cores endpoint to get information about the core of a private cellular network.

    New! Swagger UI for private_cellular_cores.

    Show more...

     

    private_cellular_networks beta

    Use the private_cellular_networks endpoint to get, add, modify and delete information about your private cellular networks.

    New! Swagger UI for private_cellular_networks.

    Show more...

    private_cellular_radio_groups beta

    Use the private_cellular_radio_groups endpoint to get, modify, create, and delete private cellular radio groups information.

    New! Swagger UI for private_cellular_radio_groups.

    Show more...

    private_cellular_sims beta

    Use the private_cellular_sims endpoint to get, modify, create, and delete private cellular sims information.

    New! Swagger UI for private_cellular_sims.

    Show more...

    private_cellular_traffic_classes beta

    Use the private_cellular_traffic_classes endpoint to view private_cellular_traffic_classes resources in your account.

    New! Swagger UI for private_cellular_traffic_classes.

    Show more...

    private_cellular_lan_profiles beta

    Use the private_cellular_lan_profiles endpoint to create, view, and modify private_cellular_lan_profiles resources in your account.

    New! Swagger UI for private_cellular_lan_profiles.

    Show more...

    private_cellular_sim_groups beta

    Use the private_cellular_sim_groups endpoint to view, modify, and delete private cellular SIM groups resources.

    New! Swagger UI for private_cellular_sim_groups.

    Show more...
    PCN Radio Management REST APIs

    The PCN Radio Management REST APIs in this section provide the following functionality:

    • Viewing and modifying information about radios used in devices on Private Cellular Networks.
    • Viewing status information about radios.

    private_cellular_radio_statuses beta

    Use the private_cellular_radio_statuses endpoint to get a variety of status information about your private cellular radios.

    New! Swagger UI for private_cellular_radio_statuses.

    Show more...

    private_cellular_radios beta

    Use the private_cellular_radios endpoint to get or modify private cellular radios information.

    New! Swagger UI for private_cellular_radios.

    Show more...

    private_cellular_radios/logs beta

    Use the private_cellular_radios/logs endpoint to get or add private cellular radios log information.

    New! Swagger UI for private_cellular_radios/logs.

    Show more...
    PCN Visibility REST APIs

    The PCN Visibility REST APIs in this section provide a means for viewing PCN core status information and metrics for cores and radios .

    private_cellular_core_metrics beta

    Use the private_cellular_core_metrics endpoint to get metrics information (bits uploaded, bits downloaded, connected clients, timestamps) about a cellular core.

    New! Swagger UI for private_cellular_core_metrics.

    Show more...

    private_cellular_core_statuses beta

    Use the private_cellular_core_statuses endpoint to get status information about a cellular core.

    New! Swagger UI for private_cellular_core_statuses.

    Show more...

    private_cellular_radio_metrics beta

    Use the private_cellular_radio_metrics endpoint to get metric information (bits uploads and downloaded) about a radio in a private cellular device.

    New! Swagger UI for private_cellular_radio_metrics.

    Show more...

    private_cellular_sim_group_metrics beta

    Use the private_cellular_sim_group_metrics endpoint to get information about SIM groups used across devices on a Cradlepoint private cellular network. This includes upload and download amounts across a SIM.

    New! Swagger UI for private_cellular_sim_group_metrics.

    Show more...

    private_cellular_sim_metrics beta

    Use the private_cellular_sim_metrics endpoint to get time-series data for SIMs used in your private cellular networks. This data includes bits uploaded and download via the SIMs.

    New! Swagger UI for private_cellular_sim_metrics.

    Show more...

    Code Samples

    The following code samples demonstrate how to query the NetCloud Manager API using examples in Python, Java, PHP, and shell scripts.

    Python Code Sample

    The following Python code sample shows how to access the routers endpoint of NetCloud Manager API v2 using the Python requests module with paging. It makes use of the NetCloud Manager 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']

    Regrades (API v3)

    Use this Python code sample to perform regrade operations. Note that this script is intended to be modifed for specific uses cases and environments. See the run() function in the script for the variables (action/action_id, mac_address, etc) that you can set for your specific needs. 

        
import json
import time
from datetime import datetime
from enum import Enum
from typing import List, Union

import requests


class RegradeAction(Enum):
    """
    Enum that contains the supported regrade actions
    """
    UPGRADE = "UPGRADE"
    DOWNGRADE = "DOWNGRADE"
    LICENSE = "LICENSE"
    UNLICENSE = "UNLICENSE"


class RegradeStatus(Enum):
    """
    Enum that contains the supported regrade statuses
    """
    RUNNING = "RUNNING"
    COMPLETED = "COMPLETED"
    FAILED = "FAILED"


class RegradePayload:
    @staticmethod
    def __generate_regrade(action: RegradeAction, mac_address: str, subscription_type: str = None):
        regrade = {
            "op": "add",
            "data": {
                "type": "regrades",
                "attributes": {
                    "action": action.value,
                    "mac_address": mac_address
                }
            }
        }

        if subscription_type is not None:
            regrade["data"]["attributes"]["subscription_type"] = subscription_type

        return regrade

    def generate_regrade_payload(self, action: RegradeAction, mac_addresses: List[str], subscription_type: str = None):
        return {
            "atomic:operations": [self.__generate_regrade(action, mac_address, subscription_type) for mac_address in mac_addresses]
        }


class RegradeOperations:
    def __init__(self):
        self.regrade_url = "https://api.cradlepointecm.com/api/v3/asset_endpoints/regrades"

    @staticmethod
    def __save_file(file_name, data):
        """
        Saves data to a file
        Args:
            file_name: Name of file
            data: Data to be saved
        """
        with open(file_name, "w") as f:
            json.dump(data, f, ensure_ascii=False, indent=2)

    @staticmethod
    def __generate_client(token):
        """
        Generate the request client to perform GET and POST actions
        Args:
            token: API token
        Returns:
            A session with the supplied api token
        """
        # Validate the token is not None and not empty
        if token is None or not token:
            raise ValueError(f"Token is required. '{token}' is not a valid token.")

        session = requests.Session()
        session.headers.update({"Authorization": f"Bearer {token}", "Content-Type": "application/vnd.api+json"})

        return session

    def __get_regrade_by_id(self, token, regrade_id):
        """
        Get a single regrade by id
        Args:
            token: API token
            regrade_id: Regrade id
        Returns:
            The regrade for the given id
        """
        url = f"{self.regrade_url}/{regrade_id}"

        client = self.__generate_client(token)
        t0 = time.time()
        response = client.get(url)
        response.raise_for_status()
        t1 = time.time()
        print(f"GET:  {url}  time:  {round((t1 - t0) * 1000)}ms")
        client.close()

        return response

    def get_regrades_by_ids(self, token, regrades: Union[List, str] = None):
        """
        Fetches regrades by a list of regrade Ids or the file path to the json output from posting regrades
        Args:
            token: API token
            regrades: List of regrade ids or the file path to the json response created from posting a regrade
        Returns:
            Creates a json file with the output of fetching regrades with the given regrade ids
        """
        if regrades is None or len(regrades) == 0:
            raise ValueError("A list of regrade ids or the file path to the json response from a previous post must be provided to perform a GET")

        regrade_id_list: List = []
        if isinstance(regrades, str):
            json_file = open(regrades)
            data = json.load(json_file)
            for regrade in data['atomic:results']:
                regrade_id_list.append(regrade["data"]["id"])
            json_file.close()
        elif isinstance(regrades, List):
            regrade_id_list = regrades

        regrades = []
        for regrade_id in regrade_id_list:
            response = self.__get_regrade_by_id(token, regrade_id)
            if response is not None and len(response.json()['data']) > 0:
                regrades.append(response.json()["data"])

        # Save the fetched regrades to a json file
        self.__save_file(f"{datetime.now().strftime('%Y%m%d%H%M%S')}_GET_BY_IDS_RESPONSE.json", regrades)

    def get_regrades(self, token: str, **kwargs):
        """
        Get a collection of regrades by query params
        Args:
            token: API token
            **kwargs: Keyword arguments used as query parameters
        Returns:
            A collection of regrades filtered by the given query params
        """
        query_params = []
        for key, value in kwargs.items():
            if value is not None:
                if key in ["page", "size"]:
                    query_params.append(f"{key}={value}")
                else:
                    if isinstance(value, RegradeAction) or isinstance(value, RegradeStatus):
                        value = value.value
                    query_params.append(f"filter[{key}]={value}")

        url = f"{self.regrade_url}"
        for i in range(len(query_params)):
            if i == 0:
                url += f"?{query_params[i]}"
            else:
                url += f"&{query_params[i]}"

        client = self.__generate_client(token)
        t0 = time.time()
        response = client.get(url)
        response.raise_for_status()
        t1 = time.time()
        print(f"GET:  {url}  time:  {round((t1 - t0) * 1000)}ms")
        client.close()

        # Save the fetched regrades to a json file
        self.__save_file(f"{datetime.now().strftime('%Y%m%d%H%M%S')}_GET_BY_FILTER_PARAMS_RESPONSE.json",
                         response.json())

    def __post_regrades(self, token, regrade_payload):
        """
        Posts regrade via the supplied json blob
        Args:
            token: API token
            regrade_payload: Regrade payload
        Returns:
            The response from posting the regrade payload
        """
        client = self.__generate_client(token)
        t0 = time.time()
        response = client.post(self.regrade_url, json=regrade_payload)
        t1 = time.time()
        response.raise_for_status()
        print(
            f"POST:  {self.regrade_url}  Device_Count:  {len(regrade_payload['atomic:operations'])}  time:  {round((t1 - t0) * 1000)}ms")
        client.close()

        return response

    def post_regrades_via_csv(self, token: str, action: RegradeAction, csv_file_path: str, subscription_type: str = None):
        """
        Post regrades using a csv file that contains the mac addresses of the devices to be regraded. If the file has more than 1000 macs, the macs will be chunked into groups of 1000. Each chunk will be posted separately and will have its own file created with an appended number at the end of the file name.
        Args:
            token: API token
            action: Regrade action, i.e. RegradeAction.UPGRADE, RegradeAction.DOWNGRADE
            csv_file_path: CSV file path
            subscription_type: Subscription type if wanting to specify which subscription to upgrade to or downgrade
            from. Does not work with LICENSE or UNLICENSE.
        Returns:
            Creates a json file with the response from the POST
        """
        if csv_file_path is None or len(csv_file_path) == 0:
            raise ValueError("The csv file path must be specified to perform a POST.")

        mac_addresses = []
        with open(csv_file_path, 'r') as file:
            for line in file:
                line = line.strip()
                mac_addresses.append(line)

        # API supports up to 1000 macs when performing a POST. If there are more than 1000 macs in the CSV then they
        # will be grouped in chunks of 1000 and each chunk will be posted in separate calls.
        mac_addresses_chunks = [mac_addresses[x:x + 1000] for x in range(0, len(mac_addresses), 1000)]
        base_file_name = f"{datetime.now().strftime('%Y%m%d%H%M%S')}_POST_{action.value}_RESPONSE"
        for index, val in enumerate(mac_addresses_chunks):
            regrade_payload = RegradePayload().generate_regrade_payload(action, val, subscription_type)
            response = self.__post_regrades(token, regrade_payload)

            # Save each chunk of 1000 regrades as a csv
            self.__save_file(f"{base_file_name}_{index}.json", response.json())

def run():
    # API token is required when performing the GET and POST operations. Read only tokens can only GET while Admin
    # tokens can GET and POST.
    api_token = None

    # Are you performing a GET or POST?
    operation = "GET"

    # If performing a GET operation, there are two options:
    # Option 1 - Fill in a list of regrade Ids, i.e. ["3ZMHRpcb6OJBtVO", "Sa8MUaAN21mCGQn"] or the file path for the
    # json response from a previous regrade POST. If you want to use option 2 then leave regrade_ids set to None.
    regrade_ids: Union[List, str] = None

    # Option 2 - Fill in the values below to return filtered regrades based on the values populated.
    mac_address: str = None
    action: RegradeAction = None
    action_id: str = None
    get_subscription_type: str = None
    status: RegradeStatus = None
    page: int = None
    size: int = None

    # If performing a POST, fill in fill your csv path containing the mac addresses to be regraded and the desired
    # regrade action, i.e. RegradeAction.UPGRADE. This csv only needs the MACs to be listed in the first column without
    # a header
    post_csv_path = None
    regrade_action = None
    post_subscription_type = None

    if operation.lower() == "get":
        if regrade_ids is not None:
            RegradeOperations().get_regrades_by_ids(api_token, regrade_ids)
        else:
            RegradeOperations().get_regrades(
                api_token,
                mac_address=mac_address,
                action=action,
                action_id=action_id,
                subscription_type=get_subscription_type,
                status=status,
                page=page,
                size=size
            )
    elif operation.lower() == "post":
        RegradeOperations().post_regrades_via_csv(api_token, regrade_action, post_csv_path,
                                                  subscription_type=post_subscription_type)
    else:
        raise ValueError(f"Operation '{operation}' is not supported. Must be GET or POST.")


if __name__ == "__main__":
    # Be sure to enter your values into the run() operation before executing the script
    run()

    Subscriptions (API v3)

    The following Python code sample shows how to access the subscriptions endpoint of the NetCloud Manager API v3 using the Python requests module with paging. It makes use of a bearer token to authenticate and access an account's subscription data. The data is returned as a JSON encoded object. 

    import json
import requests

url = 'https://api.cradlepointecm.com/api/v3/subscriptions'

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/vnd.api+json"
}

# Get subscriptions
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 NetCloud Manager 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 NetCloud accounts endpoint.

    Note that the "-L" option, shown in the example below, 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);
?>

    NetCloud Webhooks

    Webhooks provide a simplified messaging standard (RFC8030) for communication between remote applications. Application inter-messaging is often accomplished using a message queueing and subscribing approach. Webhooks use a simpler, direct-messaging approach that requires less overhead and includes the capability to authenticate messages between remote applications.

    The webhooks model follows this process.

    1. An event occurs in a remote application.
    2. The remote application is configured to call a URL you provide when the event occurs. This URL will typically be routed to a function in your application, or webhook. The event-providing, remote application sends a message that, by design, your application can understand. The convention is to use messages that are JSON objects. These messages describe state changes in the remote application that your application wants to know.
    3. Your application can take some action based on the message contents. The action your application takes could be anything from updating a database to sending an email.

    The NetCloud webhook implementation is used to notify your application of when NetCloud alerts have occurred. This process uses the following steps.

    1. Tell NetCloud where to send, or "push", the message.
      2. a. Configure an Alert Push Destination using the alert_push_destination endpoint. Use a URL in the endpoint field that points to your function for processing the message, and add a "secret" value in the authentication field to enable the message to be validated by your webhook.
    2. Test the Alert Push Destination by using the test_alert_push_destination endpoint.
    3. Configure an Alert Rule and reference the Alert Push Destination. This is done by adding the value from the Alert Push Destination's destination_config_id field to the http_destinations field in the Alert Rule. This links the Alert Push Destination to the Alert Rule.

    NOTE: Certain alerts can be configured with thresholds. These thresholds allow you to control when alerts are triggered. See the Cradlepoint Customer Connect Knowledgebase article Alerting and Reporting for details on using alerts that have thresholds.

     

    Webhooks Alert Overview

     

    Troubleshooting Webhooks in a Suspended State

    The following issues can cause Webhooks to go into a Suspended state. Each issue is followed by an action to take for resolving the Suspended state.

    • The destination isn't receiving valid authentication to allow the Webhook payload to be accepted and processed. Check the Webhook configuration in NCM and verify the correct secret is being sent.
    • NCM can't connect to the URL of the Webhook destination. Check the Webhook URL in the NCM configuration and verify it is correct.
    • The destination endpoint's SSL environment may have vulnerabilities. Check the SSL libraries used by the destination endpoint and verify they are up-to-date.

     

    Webhook Response Payload Examples

    The following examples show the payloads sent from NetCloud to your Alert Push Destination for various alerts.

    Note: The content in the "info" object varies with the type of alert. The type of alert is identified from the outer "type" field.

    • Example payload for connection_state - offline ("NCM Connection State") alerts
    • Example payload for connection_state - online ("NCM Connection State") alerts
    • Example payload for cpu_utilization ("CPU Utilization") alerts
    • Example payload for data_cap_threshold ("Data Cap Threshold") alerts
    • Example payload for ethernet_wan_connected ("Ethernet WAN Connected") alerts
    • Example payload for ethernet_wan_disconnected ("Ethernet WAN Disconnected") alerts
    • Example payload for ethernet_wan_plugged ("Ethernet WAN Plugged In") alerts
    • Example payload for ethernet_wan_standby ("Ethernet WAN Standby") alerts
    • Example payload for ipsec_tunnel_down ("IPSec VPN Tunnel Down") alerts
    • Example payload for ipsec_tunnel_up ("IPSec VPN Tunnel Up") alerts
    • Example payload for login_success ("Successful Login (Router)") alerts
    • Example payload for memory_utilization ("Memory Utilization") alerts
    • Example payload for modem_wan_connected ("Modem WAN Connected") alerts
    • Example payload for modem_wan_disconnected ("Modem WAN Disconnected") alerts
    • Example payload for modem_wan_plugged ("Modem WAN Device Plugged") alerts
    • Example payload for modem_wan_unplugged ("Modem WAN Device Unplugged") alerts
    • Example payload for reboot_status_change alerts
    • Example payload for sim_door_event ("SIM Door Event") alerts
    • Example payload for sustained_system_overload ("System Overload") alerts
    • Example payload for thermal_exceeds_limit ("Temperature Limit Exceeded") alerts
    • Example payload for wan_service_type ("WAN Service Type") alerts
    • Example payload for wifi_client_state_change ("Wi-Fi Client State Changed") alerts
    • Example payload for wwan_connected ("WiFi as WAN Connected") alerts
    • Example payload for wwan_disconnected ("WiFi as WAN Disconnected") alerts
    • Example payload for wwan_network_available ("WiFi as WAN Network Available") alerts
    • Example payload for wwan_network_unavailable ("WiFi as WAN Network Unavailable") alerts
    • Example payload for wwan_standby ("WiFi as WAN Standby") alerts

    Important: The following examples are not intended for production use and are meant only as guidelines.

    Python Webhook Example

    import hmac
def lambda_handler(event, context):
    body = event["body"] or " "
    headers = event["headers"]
    ret = 200
    secret = "__super secret__"
    h = hmac.new(secret.encode("utf-8"), body.encode("utf-8"), "sha256")
    signature = h.hexdigest()
    if signature != headers["x-cp-signature"]:
        ret = 403
    else:
        ret = 200   
    return {
        'statusCode': ret
    }

    Node JS/Express Webhook Example

    const express = require( 'express' );
const app = express();

const API_SECRET = 'secret';

app.use( express.json( { verify: ( req, res, buffer ) => { req.rawBody = buffer; } } ) );

app.post( '/', ( req, res ) => {
  const signature = _generateSignature( req.method, req.url, req.headers[ 'x-cp-signature' ], req.rawBody );
  const ret = 200;

  if ( signature !== req.headers[ 'x-cp-signature' ] ) {
    ret = 403;
  }
  else {
    ret = 200;
  }
  res.sendStatus(ret);
} );

app.listen( 9000, () => console.log( 'Node.js server started on port 9000.' ) );

function _generateSignature( method, url, timestamp, body ) {
  const hmac = crypto.createHmac( 'SHA256', API_SECRET );

  hmac.update( `${ method.toUpperCase() }${ url }${ timestamp }` );

  if ( body ) {
      hmac.update( body );
  }
  return hmac.digest( 'hex' );
}

    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) When does the Hostname Field in the net_devices Endpoint Update?

    To force the hostname field to update, the router must be rebooted after changing it's name.

    To update the net_device hostname first update the router name. The router name is stored on the device under config/system/system_id. After a reboot, the net_device hostname is updated in status/wan/devices. This is where the interface monitor collects the hostname (e.g. status/wan/devices/*/config/hostname). This can only be updated via a reboot.

    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 NetCloud Manager (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 when 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 , each net_device reports an uptime: 

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

    Q) Can I use PMIP names to identify network interfaces in custom code?

    Using PMIP names to identify network interfaces in custom code is not recommeneded due to those names changing during modem resets. Use the net_devices endpoint to find the modem's UID and use that instead of relying on PMIP names.

    Server Timeouts when using NetCloud API

    The NetCloud API is intended to serve queries that can be fulfilled in a reasonable, synchronous, web-request time frame. A “reasonable” amount of time in this context is up to ~10 seconds per query. When working with large data sets that might take longer than 10 seconds to retrieve, your queries may encounter a 408 (Response Timeout), 504 (Gateway Timeout), or a 524 (Cloudflare Timeout) response that prevents you from receiving the expected response.

    Any v2 query could result in a timeout error due to unknown issues occurring on remote servers. These errors represent a transient, response-time issue. When timeout errors occur, your first response should be to retry the query.

    408 or 504 errors are much more likely to occur on a long-running query than a short query. You can prevent server timeouts for your queries by limiting the scope of your queries, thus reducing the amount of time to execute.

    For example, if a query to the alerts endpoint for a 90-day date/time window is timing out, try 90 individual queries, each for a 1-day time window. If a query across 280,000 routers is timing out, try querying a smaller subset of those routers at a time. If a query potentially scans through millions of alerts records, try restricting the arguments so that the maximum dataset contains substantially less than a million alerts.

    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 which are offline:

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

    Values for datetime and timestamp fields in response bodies may contain plus signs ("+"). These plus signs must be replaced with their html encoding, "%2b", when used as filter values.
    For example, the timestamp value "2015-08-10T16:19:31.784055+00:00" must be changed to "2015-08-10T16:19:31.784055%2b00:00" or the value will not work as expected when used as a filter.

    Partial Result Sets

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

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

    Examples:

    Return only the name, state, group and MAC fields for all devices in an account:

    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.

    Expandable fields are fields that contain objects as values and the object's fields/values can be returned, or "expanded."

    NetCloud API fields which are expandable typically include "account", "router",

    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.

    Device and Group Configuration using NetCloud Manager API

    The following sections describe how to make changes to your device and group configurations using the NetCloud Manager API.

    Use the configuration_managers endpoint to make changes to your device configuration.

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

    Use the groups endpoint to make changes to your group configurations.

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

    IMPORTANT: When creating a new profile using the configuration_managers endpoint, a duplicate profile is created with the same priority.
    This behavior can be prevented by making a PATCH call to configuration_managers and explicitly setting the priority for the profile. Note that negative values can be used for the priority value; the lower the value the higher priority.

    Example PATCH body to set the priority for a profile:

        {
     "wan": {
       "rules2": {
         "00000007-a81d-3590-93ca-8b1fcfeb8e14": {
            "_id_": "00000007-a81d-3590-93ca-8b1fcfeb8e14",
            "ip_mode": "static",
            "priority": 1,
            "static": {
                "dns": {
                "0": {
                       "ip_address": "198.6.1.122"
                      },
                 "1": {
                        "ip_address": "198.6.100.53"
                       }
                     },
                  "gateway": "172.16.4.1",
                  "ip_address": "172.16.4.69",
                  "netmask": "255.255.255.128"
                  } 
                }
              }
            }             
   }, [] }}

    Device Configurations

    A configuration manager is an abstract resource for controlling and monitoring configuration sync on a single device. Each device has its own corresponding configuration manager.

    Configuration Manager Schema

    A configuration_managers object contains the following fields.

    
  account         # URL to account that owns the config (readonly)
  actual          # JSON diff of router's actual config (readonly) [1]
  configuration   # JSON diff of individual config (read/write) [1]
  id              # integer ID of this resource (readonly, sortable)
  pending         # JSON diff of pending updates to device (readonly) [1]
  resource_url    # URL to this endpoint (readonly)
  router          # URL to device endpoint (readonly, expandable)
  suspended       # false unless config sync is paused (read/write)
  synched         # true if device config is synched (readonly)
  target          # JSON diff of target config (readonly) [1]
  version_number  # integer count of config changes (readonly)
  
  [1] See the discussion of config diffs in the Appendix of this document.

    The account field represents the account the device is associated with. This field is formatted as a URL in responses; the last segment of the path contains the ID of the account. When using the account field with PUT, or DELETE requests, or as a filter, only the ID value is required and not the full URL.

    The actual config shows the last diff received from the router. Routers send diffs when they connect to NetCloud Manager and whenever the config changes while they are connected. This config is always formatted to match the router's current actual firmware.

    The configuration field shows the individual configuration for the device. The API can be used to change values in the config through PUT, or PATCH, as shown in the examples below. This configuration is formatted to match the device's target firmware, or it will match the actual firmware if there is no target. When the device's target firmware changes, NetCloud Manager automatically migrates this config to be compatible with the new firmware.

    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 pending field is empty unless a device is unsynched. If a device is unsynched, the pending field shows the changes waiting to be synched to the device when it connects or resumes config sync. If the device's actual firmware and target firmware are different, the pending field displays nothing even if there are pending changes. This is because the changes cannot be computed until the device syncs its firmware version. (Comparing configs for different firmware versions is not well-defined.)

    The resource_url is a self-referential link to a configuration_managers record.

    The router is a reference to the device.

    The suspended flag is true if a config sync has been stopped. This happens when the device rejects a configuration change from NetCloud Manager. If the Configuration Rejected alert is enabled, this event generates an alert with information from the device about why it rejected the config. After fixing the config, sync can be resumed by setting suspended to false through the API or through the Resume Updates button in the UI.

    The synched flag is true if the device is synched and false if there are pending changes.

    The target config is the result of layering an individual config over the group config. It is the final desired configuration of the device. When the target and actual fields are the same, the device is in sync. This config is always formatted to match the device's target firmware. If the device has no target firmware, it matches the actual firmware.

    The 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 synched to in its own config, as ecm.config_version in the device's router tree. When the device sends a config diff to NetCloud Manager, NetCloud Manager checks if the device has the latest version_number. If and only if it does, then NetCloud Manager considers the device to be in sync and accepts any local changes. If the version numbers do not match, NetCloud Manager clears the local changes to force the device to sync. The API shows this number for informational purposes only. It automatically increments any time a change is made through the NetCloud Manager UI, or the NetCloud Manager API, or a local change is accepted, or if the config is migrated to a different firmware version.

    Allowed HTTP methods are GET, PUT and PATCH. The user must have at least a Full Access User role to make PUT and PATCH requests. Any attempt to PUT, or PATCH, the config is validated using static validators. The validator checks the format of the config, verifying that the keys are valid and the values conform to the correct types and ranges.

    GET

    Use the GET method on the configuration_managers endpoint to retrieve a device's configuration.

    Possible HTTP status codes for GET requests:

    
  200 Ok            # Success
  401 Unauthorized  # Incorrect or missing API key headers (X-ECM-API-ID, X-ECM-API-KEY, X-CP-API-ID,         
                      or X-CP-API-KEY)
  403 Forbidden     # Invalid URL or resource not visible

    Supported filters for GET requests:

    
  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  # index of the first record to return in a recordset (for paging)
limit   # max number of records to return (for paging)
fields  # list of fields to return (for partial returns)
expand  # converts a url field to an object and displays the object's fields (only supported on the account and router fields)

    See Format of Examples section for an explanation of the example format.

    GET Example: A Specific Manager

    
  > GET https://www.cradlepointecm.com/api/v2/configuration_manager/123/
  < 200 Ok
  < {
  <     "success": true,
  <     "data": {
  <         "pending" : [
  <            {},
  <            []
  <         ],
  <         "account" : "https://www.cradlepointecm.com/api/v2/accounts/1/",
  <         "target" : [
  <            {
  <               "system" : {
  <                  "logging" : {
  <                     "level" : "debug"
  <                  }
  <               },
  <               "lan" : {
  <                  "00000000-0d93-319d-8220-4a1fb0372b51" : {
  <                     "ip_address" : "192.168.30.1",
  <                     "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
  <                     "name" : "LAN0"
  <                  }
  <               },
  <               "ecm" : {
  <                  "config_version" : 18
  <               }
  <            },
  <            []
  <         ],
  <         "actual" : [
  <            {
  <               "ecm" : {
  <                  "config_version" : 18
  <               },
  <               "lan" : {
  <                  "0" : {
  <                     "name" : "LAN0",
  <                     "ip_address" : "192.168.30.1"
  <                  }
  <               },
  <               "system" : {
  <                  "logging" : {
  <                     "level" : "debug"
  <                  }
  <               }
  <            },
  <            []
  <         ],
  <         "resource_url" : "https://www.cradlepointecm.com/api/v2/configuration_managers/1/",
  <         "version_number" : 18,
  <         "router" : "https://www.cradlepointecm.com/api/v2/routers/1/",
  <         "id" : "1",
  <         "synched" : true,
  <         "suspended" : false,
  <         "configuration" : [
  <            {
  <               "system" : {
  <                  "logging" : {
  <                     "level" : "debug"
  <                  }
  <               },
  <               "lan" : {
  <                  "00000000-0d93-319d-8220-4a1fb0372b51" : {
  <                     "name" : "LAN0",
  <                     "ip_address" : "192.168.30.1",
  <                     "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51"
  <                  }
  <               }
  <            },
  <            []
  <         ]
  <     }
  < }

    The device is synched in the previous example. This is indicated by the following field values:

    • the pending field is an empty diff ([{}, []])
    • the actual and target fields have the same content, and
    • synched is true

    Note that the target and actual fields are not identical. In the lan section, the target has this:

    
  < "00000000-0d93-319d-8220-4a1fb0372b51" : {
  <	"ip_address" : "192.168.30.1",
  <    "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
  <    "name" : "LAN0"
  < }

    But the actual has this:

    
  < "0" : {
  <	"name" : "LAN0",
  <    "ip_address" : "192.168.30.1"
  < }

    This difference is because the lan array has an _id_ field, and the device and NetCloud Manager express these kind of arrays differently. This is due to the way the _id_ fields were first introduced into device firmware. NetCloud Manager can understand both representations, and it recognizes that they are saying the same thing, so it knows the device is actually synched. See the section on _id_ fields for more details.

    Notes on using arrays vs objects when making PATCH requests

    While PATCH requests can use both arrays and objects in their request bodies, there are some notable differences between these data structures that affect how PATCH requests work on data.

    Arrays are ordered based on implicit, zero-based numeric keys where the ordering of data isn't easily ascertained without knowing the ordering in advance. Due to this, when using an array in a PATCH body the entire array is replaced with successful a PATCH request.

    Objects, however, do contain explicit keys. PATCH requests that use objects can specify the index/value pairs to update in the array and thus only update those specified values instead of replacing the entire array.

    For example, PATCHing with a body containing an object like this 

    {
 "0": "value for data at position 0",
 "1": "value for data at position 1"
}

    results in an array like this:

    ["value for data at position 0", "value for data at position 1"]

    Updating certificate values in configurations

    When updating SCEP certificate values in a configuration through the API, remove the line containing""ca_print": "null"," from your HTTP PATCH request if you're not using MS NDES.

    PUT

    PUT replaces an entire individual config with the given payload. It can also be used to resume the sync on a suspended device.

    As indicated in the schema, only two fields are writable: configuration (the individual config) and suspended. It is not necessary to provide both with PUT. You can PUT just the configuration to change the individual config, or just the suspended field to resume sync. If you include any other field in your PUT request payload, you get a 409 Conflict.

    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 or config request

    You cannot PUT to more than one configuration manager at a time. This is acceptable:

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/34365/

    These are not acceptable and return a 405 Method Not Allowed:

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/?synched=false
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/56/

    A 409 Conflict can mean that the request is trying to set an invalid config, and the problem is something inside the config body. The response includes the validation error. For example:

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/
  > {"configuration": [{"foo": "bar"}, []]}
  < 409 Bad Request
  < {
  <    "errors" : [
  <       {
  <          "configuration" : {
  <             "message" : "cannot set foo to bar: invalid path",
  <             "reason" : "invalid path",
  <             "value" : "bar",
  <             "path" : [
  <                "foo"
  <             ]
  <          }
  <       }
  <    ],
  <    "exception" : {
  <       "message" : "bad or missing data",
  <       "type" : "validation"
  <    }
  < }

    See here for a complete catalog of config validation errors.

    Other URL parameters:

    
  fields  # list of fields to return (for partial returns)

    Because PUT is only supported on one configuration manager at a time, the standard filter and paging options do not apply.

    See here for an explanation of the example format.

    PUT Example: A Simple Config

    This enables GPS in the individual config:

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/17/?fields=configuration
  > {
  >     "configuration": [
  >         {
  >             "system": {
  >                 "gps": {
  >                     "enabled": true
  >                 }
  >             }
  >         },
  >         []
  >     ]
  > }
  < 202 Accepted
  < {
  <     "configuration": [
  <         {
  <             "system": {
  <                 "gps": {
  <                     "enabled": true
  <                 }
  <             }
  <         },
  <         []
  <     ]
  < }

    (The fields=configuration URL option is telling NetCloud Manager to reply with only the configuration field, otherwise it would return the entire config manager object. For brevity, the PUT examples always use this technique.)

    If the request actually changes the config—which is usually the intent—the following changes take place:

    • the target field is updated
    • the version_number field is incremented
    • the synched field is set to false
    • the pending field shows 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 applies.

    It is important to understand that for PUT, not specifying a config value is equivalent to removing it from the individual config, if it was there. PATCH is different, as discussed below.

    PUT Example: A Complicated Config

    The following example config removes the default Guest LAN and sets up LAN port 4 on a VLAN to pass traffic to the WAN. It does this by performing the following actions:

    1. Removes the default Guest LAN
    2. Moves port 4 from the set of normal LAN ports to a new VLAN named "aleph"
    3. Assigns the aleph VLAN to a new LAN interface named "Aleph LAN"
    4. Adds a new firewall zone for the Aleph LAN
    5. Adds a forwarding rule from the aleph zone to the WAN zone

    The request:

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=version_number
  > {
  >     "configuration": [
  >         {
  >             "lan": {
  >                 "00000001-2a38-3724-a6fa-02dfdfbc129e": {
  >                     "_id_": "00000001-2a38-3724-a6fa-02dfdfbc129e",
  >                     "devices": [
  >                         {
  >                             "type": "ethernet",
  >                             "uid": "aleph"
  >                         }
  >                     ],
  >                     "dhcpcd": {},
  >                     "enabled": true,
  >                     "ip_address": "192.168.20.1",
  >                     "name": "Aleph LAN",
  >                     "netmask": "255.255.255.0"
  >                 }
  >             },
  >             "security": {
  >                 "zfw": {
  >                     "forwardings": {
  >                         "00000004-356d-30f0-962f-bb705dfddfc9": {
  >                             "_id_": "00000004-356d-30f0-962f-bb705dfddfc9",
  >                             "dst_zone_id": "00000002-695c-3d87-95cb-d0ee2029d0b5",
  >                             "enabled": true,
  >                             "filter_policy_id": "00000000-77db-3b20-980e-2de482869073",
  >                             "src_zone_id": "00000005-e091-3d73-80d1-9a51d6143759"
  >                         }
  >                     },
  >                     "zones": {
  >                         "00000005-e091-3d73-80d1-9a51d6143759": {
  >                             "_id_": "00000005-e091-3d73-80d1-9a51d6143759",
  >                             "devices": [
  >                                 {
  >                                     "trigger_field": "config_id",
  >                                     "trigger_group": "lan",
  >                                     "trigger_neg": false,
  >                                     "trigger_predicate": "is",
  >                                     "trigger_value": "00000001-2a38-3724-a6fa-02dfdfbc129e"
  >                                 }
  >                             ],
  >                             "name": "aleph"
  >                         }
  >                     }
  >                 }
  >             },
  >             "vlan": {
  >                 "2": {
  >                     "mode": "lan",
  >                     "ports": [
  >                         {
  >                             "mode": "tagged",
  >                             "port": 4
  >                         }
  >                     ],
  >                     "uid": "aleph",
  >                     "vid": 3
  >                 }
  >             }
  >         },
  >         [
  >             ["vlan", 1, "ports", 3],
  >             ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]
  >         ]
  >     ]
  > }
  < 202 Accepted
  < {
  <    "version_number" : 29
  < }

    The removals are processed by the device first. Removals must refer to elements which exist in the device's default config. The following elements exist in the default configuration:

    
  [
    ["vlan", 1, "ports", 3],
      ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]
  ]

    To understand these examples, it is necessary to understand what the default config looks like. In this case the device is an MBR1400 router running 5.4.0 firmware. The default vlan array looks like this:

    
  [
      {
         "uid" : "wan",
         "mode" : "wan",
         "vid" : 1,
         "ports" : [
            {
               "port" : 0,
               "mode" : "untagged"
            }
         ]
      },
      {
         "mode" : "lan",
         "uid" : "lan",
         "ports" : [
            {
               "mode" : "untagged",
               "port" : 1
            },
            {
               "port" : 2,
               "mode" : "untagged"
            },
            {
               "port" : 3,
               "mode" : "untagged"
            },
            {                          \
               "port" : 4,              \ This is vlan.1.port.3
               "mode" : "untagged"      /
            }                          /
         ],
         "vid" : 2
      }
  ]

    vlan is an array, and ["vlan", 1, ...] refers to the entry at offset 1. Offsets start at 0, so 1 means the second entry. Within each vlan entry, there is another array for the ports. So ["vlan", 1, "ports", 3] means "The port at offset 3 in the vlan at offset 1". In this default config, that is port 4, and it is "untagged". That is what will be removed first.

    The next removal looks very different: ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]. It is obviously trying to remove something from the default lan array, but 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 NetCloud Manager UI, it uses the _id_ in its removals whenever possible.

    After processing the removals, the device applies all the updates in one operation. This part of the config tells it to add a new entry to the vlan array at offset 2:

    
  "vlan": {
      "2": {
          "mode": "lan",
          "ports": [
              {
                  "mode": "tagged",
                  "port": 4
              }
          ],
          "uid": "aleph",
          "vid": 3
      }
  }

    Notice that the "2" (the key to the dict) is in quotes, like a string, whereas in the removal ["vlan", 1, "ports", 3] the offsets are not quoted. This is not a mistake and is important. If the "2" is not quoted in the updates, then it is not valid JSON, and you will get a 400 Bad Request in response to your PUT.

    Compare adding the vlan entry to adding the lan and security entries. Instead of using a quoted number, these use a UUID as the key. The key value corresponds exactly to the _id_ values inside the entries:

    
  "lan": {
          "00000001-2a38-3724-a6fa-02dfdfbc129e": {
              "_id_": "00000001-2a38-3724-a6fa-02dfdfbc129e",
              <...etc...>

    This may seem like senseless repetition but it is required.

    When adding an entry to an array that supports _id_ fields, you must provide a UUID or the result is a validation error. The _id_ is necessary to make it clear which entry the update is referring to.

    By now it is probably clear that manually building a configuration is not easy. A better approach is to use the NetCloud Manager 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 NetCloud Manager config editor to create a config on one device.
    2. Call GET https://www.cradlepointecm.com/api/v2/configuration_managers/123/ to download the config from the device.
    3. Edit the downloaded copy.
    4. Call PUT https://www.cradlepointecm.com/api/v2/configuration_managers/456/ to upload the edited config to a different device.

    PUT Example: Resume Sync

    To restart the sync cycle on a suspended device after fixing its config:

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=suspended
  > {
  >     "suspended": false
  > }
  < 202 Accepted
  < {
  <    "suspended" : false
  < }

    This only works if a device is online. If the device is offline, it stays suspended.

    PUT Example: Clearing the Config

    To wipe the individual config back to defaults, just PUT an empty diff:

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/123/?fields=configuration
  > {
  >     "configuration": [{}, []]
  > }
  < 202 Accepted
  < {
  <     "configuration": [{}, []]
  < }

    PUT Example: Manually Suspend Sync

    You can force NetCloud Manager to stop syncing a device through the API. Why would you stop the syncing of a device? This is useful if you don't want devices to sync until you are done making and testing configuration changes on a test device or you only want to sync devices at certain times.

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=suspended
  > {
  >     "suspended": true
  > }
  < 202 Accepted
  < {
  <     "suspended" : true
  < }

    PATCH

    PATCH also changes the config. The difference between PUT and PATCH is in how they treat the parts of the config that are not mentioned in the request. PUT resets anything not mentioned back to defaults. PATCH leaves it alone.

    For example, the following PUT call resets the entire individual config back to defaults:

    
  PUT https://www.cradlepointecm.com/api/v2/configuration_managers/123/
  {"configuration": [{}, []]}

    And this will do nothing at all:

    
  PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/123/
  {"configuration": [{}, []]}

    PATCH is the operation to use when you want to adjust an existing config. PUT is what you should use to replace an existing config.

    Note that you can't remove anything with PATCH; you can only add or update changes.

    HTTP status codes:

    
  202 Accepted            # Success
  400 Bad Request         # Invalid config request
  401 Unauthorized        # Incorrect or missing X-ECM-API-ID or X-ECM-API-KEY headers
  403 Forbidden           # Invalid URL or resource not visible
  405 Method Not Allowed  # URL did not include an /<id>/ in the path
  409 Conflict            # Invalid API request

    Like PUT, PATCH cannot operate on more than one configuration manager at a time. For this reason it also does not support the URL options for filtering or paging.

    Also like PUT, it returns a 400 Bad Request if it detects an invalid config.

    Unlike PUT, PATCH never returns a payload in its reply. The fields URL option is therefore meaningless to PATCH.

    See the here for an explanation of the example format.

    Notes on using arrays vs objects when making PATCH requests

    While PATCH requests can use both arrays and objects in their request bodies, there are some notable differences between these data structures that affect how PATCH requests work on data.

    Arrays are ordered based on implicit, zero-based numeric keys where the ordering of data isn't easily ascertained without knowing the ordering in advance. Due to this, when using an array in a PATCH body the entire array is replaced with successful a PATCH request.

    Objects, however, do contain explicit keys. PATCH requests that use objects can specify the index/value pairs to update in the array and thus only update those specified values instead of replacing the entire array.

    For example, PATCHing with a body containing an object like this 

    {
 "0": "value for data at position 0",
 "1": "value for data at position 1"
}

    results in an array like this:

    ["value for data at position 0", "value for data at position 1"]

    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. When using this approach, you must include the _id_ field itself as part of the request or you will get a 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

    The following sections contain examples of how to make various configuration changes using the API.

    Get the pending configuration for a particular device

    If the configuration_manager ID is known:

    
  GET https://www.cradlepointecm.com/api/v2/configuration_managers/1106/?field=pending

    If the configuration_manager ID is not known, 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 or modify 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, router.mac, or router.name. 

    
  > PUT https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
  > PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
  > {
  >     "configuration": [
  >         {
  >             "wlan": {
  >                 "radio": {
  >                     "0": {
  >                         "bss": {
  >                              "0": {
  >                                "ssid": "MBR1400-8c1",
  >                                "wpapsk": "t311-n00ne"
  >                               }
  >                          }
  >                      }
  >                  }
  >              }
  >         },
  >         []
  >     ]
  > }
  < 202 Accepted

    Add user

    This and the following examples work the same way with PATCH or PUT as all the previous examples. For brevity, only the payload is shown.

    
  {
      "configuration": [
          {
              "system": {
                  "pci_dss": true,
                  "users": {
                      "1": {
                          "group": "admin",
                          "password": "SuperDuper1",
                          "username": "super"
                      }
                  }
              }
          },
          []
      ]
  }

    Static IP for Ethernet WAN using WAN rule

    Configuring the static IP on the Ethernet WAN device requires setting the ip_override section of its corresponding WAN rule. The WAN rules changed somewhat with firmware version 6.0. The wan.rules path was replaced with wan.rules2, and the _id_ of the rule dealing with Ethernet WAN also changed as shown in the examples that follow.

    5.0 <= Firmware < 6.0

    
  {
      "configuration": [
          {
              "wan": {
                  "rules": {
                      "00000001-dea3-3ccd-a78d-e0196084396f": {
                          "_id_": "00000001-dea3-3ccd-a78d-e0196084396f",
                          "ip_mode": "static",
                          "static": {
                              "dns": {
                                  "0": {
                                      "ip_address": "172.21.21.50"
                                  },
                                  "1": {}
                              },
                              "gateway": "172.19.8.1",
                              "ip_address": "172.19.9.30",
                              "netmask": "255.255.252.0"
                          }
                      }
                  }
              }
          },
          []
      ]
  }

    Firmware >= 6.0

    Change rules to rules2 and change the _id_ field and key. The dns section is not required like it is in older versions, which will accept the config without DNS but may fail to connect, resulting in a config rollback.

    
  {
      "configuration": [
          {
              "wan": {
                  "rules2": {
                      "00000000-a81d-3590-93ca-8b1fcfeb8e14": {
                          "_id_": "00000000-a81d-3590-93ca-8b1fcfeb8e14",
                          "ip_mode": "static",
                          "static": {
                              "ip_address": "172.19.9.30",
                              "netmask": "255.255.252.0"
                          }
                      }
                  }
              }
          },
          []
      ]
  }

    Setting the APN for modem using LTE defaults WAN rule

    The APN must be set in the WAN rule corresponding to the modem it is for. For example, to set it for an LTE modem, use the WAN rule with _id_ "00000002-dea3-3ccd-a78d-e0196084396f":

    5.0 <= Firmware < 6.0

    
  {
      "configuration": [
          {
              "wan": {
                  "rules": {
                      "00000002-dea3-3ccd-a78d-e0196084396f": {
                          "_id_": "00000002-dea3-3ccd-a78d-e0196084396f",
                          "modem": {
                              "apn_mode": "manual",
                              "manual_apn": "myapn"
                          }
                      }
                  }
              }
          },
          []
      ]
  }

    Firmware >= 6.0

    Change rules to rules2 and change the _id_ field and key.

    
  {
      "configuration": [
          {
              "wan": {
                  "rules2": {
                      "00000002-a81d-3590-93ca-8b1fcfeb8e14": {
                          "_id_": "00000002-a81d-3590-93ca-8b1fcfeb8e14",
                          "modem": {
                              "apn_mode": "manual",
                              "manual_apn": "myapn"
                          }
                      }
                  }
              }
          },
          []
      ]
  }

    Appendix

    Format of Examples

    There are many REST API clients available on the web or as browser plugins. They all differ slightly but provide the same common elements of method, headers, URL, payload, and status code. Rather than showing the syntax for a particular tool, this document uses the following format for all examples.

    First, examples appear in monospace font. The first character of each line is either > or < and indicates the direction of travel, either client-to-server or server-to-client, respectively:

    
  > = client to server
  < = server to client

    The first line is always the method and URL. If there is data to be sent (as in PUT and PATCH), this appears on the following lines going in the same direction. The reply appears on subsequent lines, beginning with the status code and followed by the reply payload, if any. Here's an annotated example, with lines numbered for discussion:

    
  1 > GET https://www.cradlepointecm.com/api/v2/configuration_managers/1/?fields=version_number
  2 < 200 Ok
  3 < {
  4 <     "version_number" : 19,
  5 < }

    Line 1 shows the method (GET) and full URL (https://www.cradlepointecm.com/api/v2/configuration_managers/1/?fields=version_number) sent from the client to the server to initiate the request. In this example the URL is asking for a specific object (with ID 1), and specifying that it only wants to see the version_number field. This is known as a "partial result".

    Line 2 shows the status code from the server as 200 Ok.

    Lines 3—5 are the payload of the reply from the server. For readability, the examples always show the payloads as JSON formatted with line breaks and indentations. Not all clients format the reply like this. For example, curl won't, and neither will most browsers unless you install a plugin. The payload from the server will actually be all on one line with no indentation. The meaning is the same.

    The examples do not show the headers required for authentication or content-type, but they are necessary. As described in the general API v2 documentation (the Sample Code section is most succinct), all requests to the API must provide a header each for X-ECM-API-ID, X-ECM-API-KEY, X-CP-API-ID, and X-CP-API-KEY to authenticate the client. Also, PUT and PATCH requests require a Content-Type header.

    _id_ Fields

    Many parts of the device configuration are composed of arrays. Most of these lists are treated more like sets than like arrays, where the order of the elements does not matter and elements must be unique from one another in some way. Order does not matter; as long as nothing inserts or removes elements, the order remains stable.

    Some of these arrays are pre-populated with entries by default. For example, if you factory reset most devices, you will find that they have two LAN entries and up to five WAN rules.

    In a config diff arrays are always presented as dictionaries. Historically (prior to 5.0) the keys were always string numerals representing the index of the elements. For example:

    
  {
      "lan": {
          "1" : {
              "ip_address" : "192.168.30.1",
              "name" : "Office LAN"
          }
      }
  }

    This refers to the LAN at index 1 which is the second LAN. In most devices that is 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 NetCloud Manager 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, such as those that populate the list after a factory reset, all have preassigned _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? A valid configuration depends on the firmware version and product. Every version of firmware has a Document Type Definition (DTD) that specifies the configuration-tree structure, the types of the elements, any limits on the range of values of elements, and whether an element must be specified or can be left blank. If a configuration does not conform to the DTD, it is invalid.

    NetCloud Manager checks for valid configs in the API by checking them against the DTD. However, even if a config conforms to the DTD, it can still be invalid. The devices check for dynamic constraints that can't be expressed in the DTD and may reject a config from NetCloud Manager because one of these checks fails.

    For example, all devices currently have the following check:

    
  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.

    Even though this conforms to the DTD and would be accepted by NetCloud Manager, 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, NetCloud Manager automatically attempts to migrate its configuration to make it compatible with the new version.

    The DTD specifies a default value for many fields, including all required fields. As noted elsewhere it also specifies default elements for some arrays, such as lan, wan.rules and firewall.zfw.filter_policies. The default elements can be altered or removed. If they are, a factory reset of the device restores them. In NetCloud Manager, clearing configs has a similar effect.

    Suspended Sync

    If NetCloud Manager tries to sync a device to an invalid config, the device rejects it. NetCloud Manager stops trying to sync the device and marks it as "suspended", as shown in the config_status field of the device's endpoint. For example, https://www.cradlepointecm.com/api/v2/routers/<router-id>.

    To understand why a device was suspended due to an invalid config, check the device's "Configuration Rejected" alert. This alert contains details about why the device rejected the config. The alert information typically references the field that failed their dynamic validation checks. You can access a device's alerts through the NetCloud Manager ALERTS & LOGS page or through the alerts endpoint.

    Once the problem is identified, 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
  }

    Diffs

    A configuration diff describes how the configuration differs from the default for that firmware version. It is a list of two elements. The first element is called the update dictionary. The second element is called the removal list.

    A diff is like a UNIX patch. It can be applied to an existing configuration. When applied, every path in the removals list is removed in the specified order. Then, every key/value pair in the update dictionary is applied. The update tries to maintain existing elements, and only update exactly what is specified.

    For example if 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. Elements 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 DTD, or if it is of the wrong type, that is also an error.

    An empty configuration diff looks like this:

    
  [{}, []]

    Group/Individual 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
      }
  }

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

    NetCloud Manager 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? If you PUT with an empty config to the device's configuration endpoint, NetCloud Manager would clear the individual configuration, but the group configuration would stay the same. The device's target configuration would go back to just being the group configuration:

    
  # Target config if the individual configuration is cleared
  {
      "a": {
          "b": 1
          "c": 2
      }
  }

    If you removed the device from the group instead, only the individual configuration would remain:

    
  # Target config if removed from group
  {
      "a": {
          "b": 3,
          "d": 4
      }
  }

    NetCloud Manager 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 will 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 validates and applies a config, but it is unable to connect to the WAN with the new settings. To protect against this situation, all firmware versions support a config rollback feature. After applying a config from NetCloud Manager, if the device cannot contact NetCloud Manager within 15 minutes, it "undoes" the config change and reverts to the previous working version. When it reconnects to NetCloud Manager after a rollback, it informs NetCloud Manager and config sync on the device is suspended.

    Differences from verson 1

    Sample version 1.0 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 version 2.0 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 that 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 shown in the "Change. the WiFi SSID and WPA2/PSK Passkey on Specific Routers" example.

    Zscaler Configurations

    Zscaler is a cloud-based filtering and security policy application that can be configured on Cradlepoint devices. More details can be found at Zscaler Internet Security.

    Zscaler example code

      
  ###Zscale Username / Password
  {
     "configuration": [
        {
        "dns": {"force_redir": true},
        "webfilter": {
           "cloudservice": "zsis",
       "zsis": {
       "dyndns": {"password": "password1", "user_name": "username1"}
         }
         },
         []
     ]
  }

    Hardware Requirements

    • Cradlepoint AER 2200
    • ZScaler service account

    Firmware Version

    • The firmware version used for the preparation of this document was NCOS 7.2.70